{"id":13461782,"url":"https://github.com/jevonmao/PermissionsSwiftUI","last_synced_at":"2025-03-24T22:34:57.122Z","repository":{"id":37892438,"uuid":"334487502","full_name":"jevonmao/PermissionsSwiftUI","owner":"jevonmao","description":"A SwiftUI package to beautifully display and handle permissions.","archived":false,"fork":false,"pushed_at":"2024-04-06T10:15:25.000Z","size":20172,"stargazers_count":1493,"open_issues_count":15,"forks_count":87,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-24T18:11:25.189Z","etag":null,"topics":["coding","developer","github","ios","ios-swift","learn-swift","library","macos","package","programming","swift","swiftpackage","swiftui","swiftui-learning","ui-design","ux"],"latest_commit_sha":null,"homepage":"https://jevonmao.github.io/PermissionsSwiftUI/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jevonmao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-30T18:50:24.000Z","updated_at":"2025-03-22T21:41:24.000Z","dependencies_parsed_at":"2022-07-09T10:30:19.889Z","dependency_job_id":"4ff59725-61c9-4023-92aa-533bad94cee6","html_url":"https://github.com/jevonmao/PermissionsSwiftUI","commit_stats":{"total_commits":227,"total_committers":7,"mean_commits":32.42857142857143,"dds":"0.026431718061673992","last_synced_commit":"5395d233b21d190950ed254700961bcd9298f5f0"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jevonmao%2FPermissionsSwiftUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jevonmao%2FPermissionsSwiftUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jevonmao%2FPermissionsSwiftUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jevonmao%2FPermissionsSwiftUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jevonmao","download_url":"https://codeload.github.com/jevonmao/PermissionsSwiftUI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245366204,"owners_count":20603438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding","developer","github","ios","ios-swift","learn-swift","library","macos","package","programming","swift","swiftpackage","swiftui","swiftui-learning","ui-design","ux"],"created_at":"2024-07-31T11:00:57.475Z","updated_at":"2025-03-24T22:34:57.066Z","avatar_url":"https://github.com/jevonmao.png","language":"Swift","readme":"\u003cspan align=\"center\"\u003e\n  \u003cbr\u003e\n\u003cimg src=\"https://developer.apple.com/assets/elements/icons/swiftui/swiftui-96x96_2x.png\" width=\"100\"\u003e\n  \u003cbr\u003e\n\u003c/span\u003e\n\n# PermissionsSwiftUI: A SwiftUI package to handle permissions\n\u003cimg src=\"https://img.shields.io/github/workflow/status/jevonmao/PermissionsSwiftUI/Swift?label=CI%20Build\"\u003e \u003cimg src=\"https://img.shields.io/github/contributors/jevonmao/PermissionsSwiftUI\"\u003e \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e \u003cimg src=\"https://img.shields.io/github/issues/jevonmao/PermissionsSwiftUI?color=orange\"\u003e \u003cimg src=\"https://img.shields.io/github/commit-activity/w/jevonmao/PermissionsSwiftUI?color=yellowgreen\u0026logoColor=yellowgreen\"\u003e \u003cimg src=\"https://camo.githubusercontent.com/86f8561418bbd6240d5c39dbf80b83a3dc1e85e69fe58da808f0168194dcc0d3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5377696674504d2d436f6d70617469626c652d627269676874677265656e2e737667\"\u003e \u003cimg src=\"https://img.shields.io/github/v/release/jevonmao/PermissionsSwiftUI?include_prereleases\u0026style=plastic\"\u003e\n\n`PermissionsSwiftUI` displays and handles permissions in SwiftUI. It is largely inspired by [SPPermissions](https://github.com/varabeis/SPPermissions).\nThe UI is highly customizable and resembles an **Apple style**. If you like the project, please `star ★`. \u003cbr /\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/Main-screenshot.png?raw=true\" style=\"display: block; margin: auto;\"/\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e PermissionsSwiftUI looks equally gorgeous on both ☀️light and 🌑 dark mode. \u003c/p\u003e\n\n## 🧭 Navigation\n-  [Installation](#-installation)\n-  [Quickstart](#-quickstart) \n\u003cdetails\u003e\n  \u003csummary\u003eUsage\u003c/summary\u003e\n  \n-  [Usage](#-usage)\n    -  [Customize Permission Texts](#customize-permission-texts)\n    -  [Customize header texts](#customize-header-texts)\n    -  [`onAppear` and `onDisappear` Override](#onappear-and-ondisappear-override)\n    -  [Auto Check Authorization](#auto-check-authorization)\n    -  [Auto Dismiss](#auto-dismiss)\n    -  [Customize Colors](#customize-colors)\n    -  [Restrict Dismissal](#restrict-dismissal)\n    -  [Configuring Health Permissions](#configuring-health-permissions)\n\u003c/details\u003e\n\n-  [Cheatsheet](#-cheatsheat)\n-  [Supported Permissions](#-supported-permissions)\n-  [Contribute](#-contribute)\n\n\u003cdetails\u003e\n  \u003csummary\u003eAdditional Information\u003c/summary\u003e\n  \n-  [Additional Information](#additional-information)\n    -  [Acknowledgement](#acknowledgement)\n    -  [License](#license)\n    \n\u003c/details\u003e\n\n## 🖥️ Installation\n### Requirements\n* iOS 11 (SwiftUI require iOS 13.0) or iPadOS 13\n* Xcode 12 and Swift 5.3\n* tvOS support coming soon\n* No MacOS, and WatchOS support for now\n\n### Install\n#### Swift Package Manager (Recommended)\nYou can install PermissionsSwiftUI into your Xcode project via SPM. \nTo learn more about SPM, click [here](https://swift.org/package-manager/)\n1. In Xcode 12, open your project and navigate to **File** → **Swift Packages** → **Add Package Dependency...**\n\nFor Xcode 13, navigate to **Files** → **Add Package**\n\n2. Paste the repository URL (`https://github.com/jevonmao/PermissionsSwiftUI`) and click **Next**.\n3. For **Version**, verify it's **Up to next major**.\n4. Click **Next** and ONLY SELECT PERMISSIONS NEEDED else Apple will reject your app \n\n(You don't need to add CorePermissionsSwiftUI or PermissionsSwiftUI)\n\n\u003cimg width=\"716\" alt=\"image\" src=\"https://user-images.githubusercontent.com/64660730/121824314-313dea00-cc60-11eb-8553-40012b27f88e.png\"\u003e\n\n5. Click **Finish**\n6. You are all set, thank you for using PermissionsSwiftUI!\n\n\n#### Cocoapods (Deprecated)\nYou can also install PermissionsSwiftUI with Cocoapods. Add `pod 'PermissionsSwiftUI'` in your podfile:\n```Ruby\nplatform :ios, '14.0'\n\ntarget 'test abstract' do\n  use_frameworks!\n  pod 'PermissionsSwiftUI'\n\nend\n```\n## 🚀 Quickstart\n\u003e Before you start, please `star ★` this repository. Your star is my biggest motivation to pull all-nighters and maintain this open-source project.\n\n### ⚠️ v1.4.0 Migration Guide\n`v1.4` is here! If you encounter any issues, please check out the [migration guide](https://github.com/jevonmao/PermissionsSwiftUI/wiki/Migrating-to-v1.4.0) designed to help developers resolve any deprecations and API updates.\n\n### Modal Style\nTo use PermissionsSwiftUI, simply add the `JMModal` modifier to any view:\n```Swift\n.JMModal(showModal: $showModal, for: [.locationAlways, .photo, .microphone])`\n```\nPass in a `Binding\u003cBool\u003e` to show the modal view, and add whatever permissions you want to show. For example:\n```Swift\n   struct ContentView: View {\n       @State var showModal = false\n       var body: some View {\n           Button(action: {\n               showModal=true\n           }, label: {\n               Text(\"Ask user for permissions\")\n           })\n           .JMModal(showModal: $showModal, for: [.locationAlways, .photo, .microphone])\n       }\n   }\n ```\n### Alert Style\n\u003cimg src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/alert_view_screenshot.png?raw=true\" height=\"300\" align=\"left\" /\u003e\nThe alert style is equally gorgeous, and allows for more versatile use. It is recommended when you have less than 3 permissions.  \u003cbr /\u003e\nTo show a permission pop up alert, use: \n\n```Swift\n.JMAlert(showModal: $showModal, for: [.locationAlways, .photo])\n```\nSimilar to the previous `JMPermissions`, you need to pass in a `Binding\u003cBool\u003e` to show the view, and add whatever permissions you want to show.\nTo quickly glance at all of PermissionsSwiftUI's customization and configurations, check out the [cheatsheet](#cheatsheat)!\n\u003cbr /\u003e \u003cbr /\u003e \u003cbr /\u003e \u003cbr /\u003e \u003cbr /\u003e \u003cbr /\u003e\n\n## 🛠️ Usage\n### Customize Permission Texts\n\nTo customize permission texts, use the modifier `setPermissionComponent()`\nFor example, you can change title, description, and image icon:\n```Swift\n.setPermissionComponent(for: .camera, \n                        image: AnyView(Image(systemName: \"camera.fill\")), \n                        title: \"Camcorder\",\n                        description: \"App needs to record videos\")\n```\nand the result:\n\u003cdiv style=\"text-align:center\"\u003e\n\u003cimg src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/Screenshot-camera.png\" height=\"70\"\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\nOr only change 1 of title and description:\n\n```Swift\nsetPermissionComponent(for: .tracking, title: \"Trackers\")\n```\n```Swift\nsetPermissionComponent(for: .tracking, description: \"Tracking description\")\n```\n\n**Note:** \n* The parameters you don't provide will show the default text\n* Add the `setPermissionComponent` modifier on your root level view, after `JMPermissions` modifier\n\nThe `image` parameter accepts **AnyView**, so feel free to use [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols/overview/) or your custom asset:\n```Swift\n.setPermissionComponent(for: .camera, \n                        image: AnyView(Image(\"Your-cool-image\"))\n```\nEven full SwiftUI views will work😱:\n```Swift\n.setPermissionComponent(for: .camera, \n                        image: AnyView(YourCoolView())\n```\nYou can use custom text and icons for all the supported permissions, with a single line of code.\n### Customize Header Texts\nTo customize the header title, use the modifier `changeHeaderTo`:\n\u003cimg align=\"right\" src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/Header%20annotation.png?raw=true\" alt=\"Annotated for headers screen\" height=\"400\" /\u003e\n```Swift\n.JMPermissions(showModal: $showModal, for: [.camera, .location, .calendar])\n.changeHeaderTo(\"App Permissions\")\n```\nTo customize the header description, use the modifier `changeHeaderDescriptionTo`:\n```Swift\n.JMPermissions(showModal: $showModal, for: [.camera, .location, .photo])\n.changeHeaderDescriptionTo(\"Instagram need certain permissions in order for all the features to work.\")\n```\nTo customize the bottom description, use the modifier `changeBottomDescriptionTo`:\n```Swift\n.JMPermissions(showModal: $showModal, for: [.camera, .location, .photo])\n.changeBottomDescriptionTo(\"If not allowed, you have to enable permissions in settings\")\n```\n### `onAppear` and `onDisappear` Override\nYou might find it incredibly useful to execute your code, or perform some update action when a PermissionsSwiftUI view appears and disappears. \u003cbr /\u003e\nYou can perform some action when PermissionsSwiftUI view appears or disappears by:\n```Swift\n.JMPermissions(showModal: $showModal, for: [.locationAlways, .photo, .microphone], onAppear: {}, onDisappear: {})\n```\nThe `onAppear` and `onDisappear` **closure parameters will be executed** everytime PermissionsSwiftUI view **appears and disappears.** \u003cbr /\u003e\nThe same view modifier closure for state changes are available for the `JMAlert` modifier:\n```Swift\n.JMAlert(showModal: $showModal,\n                     for: [.locationAlways, .photo],\n                     onAppear: {print(\"Appeared\")},\n                     onDisappear: {print(\"Disappeared\")})\n```\n### Auto Check Authorization\nPermissionsSwiftUI by default will automatically check for authorization status. It will only show permissions that are currently `notDetermined` status. (the iOS system prevents developers from asking for denied permissions. Allowed permissions will also be ignored by PermissionsSwiftUI). If all permissions are allowed or denied, PermissionsSwiftUI will not show the modal or alert at all.\nTo set auto check authorization, use the `autoCheckAuthorization` parameter:\n```Swift\n.JMModal(showModal: $showModal, for: [.camera], autoCheckAuthorization: false)\n```\nsame applies for JMAlert\n```Swift\n.JMAlert(showModal: $showModal, for: [.camera], autoCheckAuthorization: false)\n```\n### Auto Dismiss\nPermissionsSwiftUI by default will not have any auto dismiss behavior. You can override this behavior to make it automatically dismiss the modal or alert after the user allows the last permission item. (All permissions must be ALLOWED, if any is DENIED, it will not auto dismiss).\n```Swift\n.JMModal(... autoDismiss: Bool) -\u003e some View\n```\nPass in `true` or `false` to select whether to automatically dismiss the view.\n\n### Customize Colors\nUsing PermissionSwiftUI's capabilities, developers and designers can customize all the UI colors with incredible flexibility. You can fully configure all color at all states with your custom colors. \u003cbr /\u003e\nTo easily change the accent color:\n```Swift\n.setAccentColor(to: Color(.sRGB, red: 56/255, green: 173/255,\n                                  blue: 169/255, opacity: 1))\n```\nTo change the primary (default Apple blue) and tertiary (default Apple red) colors:\n```Swift\n.setAccentColor(toPrimary: Color(.sRGB, red: 56/255, green: 173/255,\n                                  blue: 169/255, opacity: 1),\n                toTertiary: Color(.systemPink))\n```\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/Color-custom-screenshot.png?raw=true\" height=\"250\" style=\"display: block; margin: auto;\"/\u003e\n\u003c/p\u003e\n\n\u003e ⚠️ `.setAccentColor()` and `.setAllowButtonColor()` should never be used at the same time.\n\nTo unleash the full customization of all button colors under all states, you need to pass in the `AllButtonColors` struct:\n```Swift\n.setAllowButtonColor(to: .init(buttonIdle: ButtonColor(foregroundColor: Color,\n                                                               backgroundColor: Color),\n                                       buttonAllowed: ButtonColor(foregroundColor: Color,\n                                                                  backgroundColor: Color),\n                                       buttonDenied: ButtonColor(foregroundColor: Color,\n                                                                 backgroundColor: Color)))\n```\nFor more information regarding the above method, reference the [official documentation](https://jevonmao.github.io/PermissionsSwiftUI/Structs/AllButtonColors.html).\n\n### Restrict Dismissal\nPermissionsSwiftUI will by default, prevent the user from dismissing the modal and alert before all permissions have been interacted with. This means if the user has not explicitly denied or allowed EVERY permission shown, they will not be able to dismiss the PermissionsSwiftUI view. This restricts dismissal behavior can be overridden by the `var restrictModalDismissal: Bool` or `var restrictAlertDismissal: Bool` properties.\nTo disable the default restrict dismiss behavior:\n```Swift\n.JMModal(showModal: $show, for permissions: [.camera], restrictDismissal: false)\n```\nYou can also configure with the model:\n```Swift\nlet model: PermissionStore = {\n        var model = PermissionStore()\n        model.permissions = [.camera]\n        model.restrictModalDismissal = false\n        model.restrictAlertDismissal = false\n        return model\n    }\n    ......\n\n    .JMModal(showModal: $showModal, forModel: model)\n```\n### Configuring Health Permissions\nUnlike all the other permissions, the configuration for health permission is a little different. Because Apple requires developers to explicitly set read and write types, PermissionsSwiftUI greatly simplifies the process.\n#### `HKAccess`\nThe structure HKAccess is required when initializing health permission’s enum associated values. It encapsulates the read and write type permissions for the health permission.\n\nTo set read and write health types (`activeEnergyBurned` is used as example here):\n```Swift\nlet healthTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])\n.JMModal(showModal: $show, for: [.health(categories: .init(readAndWrite: healthTypes))])\n\n//Same exact syntax for JMAlert styles\n.JMAlert(showModal: $show, for: [.health(categories: .init(readAndWrite: healthTypes))])\n\n```\nTo set read or write individually:\n```Swift\nlet readTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])\nlet writeTypes = Set([HKSampleType.quantityType(forIdentifier: .appleStandTime)!])\n.JMModal(showModal: $showModal, for: [.health(categories: .init(read: readTypes, write: writeTypes))])\n```\nYou may also set only read or write type:\n```Swift\nlet readTypes = Set([HKSampleType.quantityType(forIdentifier: .activeEnergyBurned)!])\n.JMModal(showModal: $showModal, for: [.health(categories: .init(read: readTypes))])\n\n```\n## 📖 Cheatsheet \n\n### Modifiers\n**Customize overall accent color:**\n```Swift\nsetAccentColor(to:)\nsetAccentColor(toPrimary:toTertiary:)\n```\n**Customize title:**\n```Swift\nchangeHeaderTo(_:)\n```\n**Customize top description:**\n```Swift\nchangeHeaderDescriptionTo(_:)\n```\n**Customize bottom description:**\n```Swift\nchangeBottomDescriptionTo(_:)\n```\n**Customize each permission's displayed text \u0026 image:**\n```Swift\nsetPermissionComponent(for:image:title:description:)\n\nsetPermissionComponent(for:title:)\n\nsetPermissionComponent(for:description:)\n```\n**Customize `allow` button's colors:**\n```Swift\nsetAllowButtonColor(to:)\n```\n**Automatically dismiss after last**\n```Swift\nautoDismiss: Bool\n```\n### Parameters of `JMModal` and `JMAlert`\n**Check authorization before showing modal or alert**\n```Swift\nautoCheckAuthorization: Bool\n```\n**Prevent dismissing before all permissions interacted**\n```Swift\nrestrictDismissal: Bool\n```\n**Do something right before view appear**\n```Swift\nonAppear: () -\u003e Void\n```\n**Do something right before view disappear**\n```Swift\nonDisappear: (() -\u003e Void\n```\n## 🧰 Supported Permissions\nHere is a list of all the permissions PermissionsSwiftUI supports. Yup, even the newest `tracking` permission for iOS 14 so you can stay on top of your game. All permissions in PermissionsSwiftUI come with a default name, description, and a stunning Apple native SF Symbols icon.\n\nSupport for FaceID permission is work in progress and coming soon! If you don't find a permission you need, open an issue. Even better, build it yourself and open a pull request, you can follow [this](docs/New_Permission_Guide.md) step-by-step guide on adding new permissions.\n\u003cbr /\u003e \u003cbr /\u003e \u003cbr /\u003e\n\u003cimg align=\"center\" src=\"https://github.com/jevonmao/PermissionsSwiftUI/blob/main/Resources/All-permissions-card-new.png\" alt=\"A card of all the permissions\" width=\"100%\"\u003e\n\n## 💪 Contribute\nContributions are welcome here for coders and non-coders alike. No matter what your skill level is, you can for certain contribute to PermissionSwiftUI's open source community. Please read [contributing.md](CONTRIBUTING.md) before starting, and if you are looking to contributing a new type of iOS permission, be sure to read this step-by-step [guide](docs/New_Permission_Guide.md).\n\n**If you encounter ANY issue, have ANY concerns, or ANY comments, please do NOT hesitate to let me know. Open a discussion, issue, or email me.** As a developer, I feel you when you don't understand something in the codebase. I try to comment and document as best as I can, but if you happen to encounter any issues, I will be happy to assist in any way I can.\n\n## Additional Information\n\n### Acknowledgement\nSPPermissions is in large a SwiftUI remake of the famous Swift library **[SPPermissions](https://github.com/varabeis/SPPermissions)** by @verabeis. SPPermissions was initially created in 2017, and today on GitHub has over 4000 stars. PermissionsSwiftUI aims to deliver a just as beautiful and powerful library in SwiftUI. If you `star ★` my project PermissionsSwiftUI, be sure to check out the original project SPPermissions where I borrowed the UI Design, some parts of README.md page, and important source code references along the way.\n### License\nPermissionsSwiftUI is created by Jingwen (Jevon) Mao and licensed under the [MIT License](https://jingwen-mao.mit-license.org)\n\n","funding_links":[],"categories":["Swift","iOS","Permission","ux"],"sub_categories":["Android samples","Content"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevonmao%2FPermissionsSwiftUI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjevonmao%2FPermissionsSwiftUI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevonmao%2FPermissionsSwiftUI/lists"}