@cap-kit/settings

src="https://raw.githubusercontent.com/cap-kit/capacitor-plugins/main/assets/logo.png"
alt="CapKit Logo"
width="128"
/>

Settings

@cap-kit/settings

A Capacitor plugin for opening system and application settings on iOS and Android.

Provides a unified Promise-based API to navigate users to relevant settings screens,
including app settings, notifications, connectivity, and other system sections.

Built following the Cap-Kit architectural standards with strict separation
between JavaScript, bridge, and native implementations (Swift / Kotlin).

Install

``bash
pnpm add @cap-kit/settings
npx cap sync

`

Configuration

Configuration options for the Settings plugin.

| Prop | Type | Description | Default | Since |
| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| verboseLogging | boolean | Enables verbose native logging. When enabled, additional debug information is printed to the native console (Logcat on Android, Xcode on iOS). This option affects native logging behavior only and has no impact on the JavaScript API. | false | 1.0.0 |

$3

In capacitor.config.json:

`json
{
"plugins": {
"Settings": {
"verboseLogging": true
}
}
}
`

In capacitor.config.ts:

`ts
///

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
plugins: {
Settings: {
verboseLogging: true,
},
},
};

export default config;
`

API

* open(...)
* openIOS(...)
* openAndroid(...)
* getPluginVersion()
* Interfaces
* Enums

Public JavaScript API for the Settings Capacitor plugin.

This plugin uses a state-based result model:
- operations never throw
- Promise rejection is not used
- failures are reported via { success, error?, code? }

This design ensures consistent behavior across Android, iOS, and Web.

$3

`typescript
open(options: PlatformOptions) => Promise
`

Opens the specified settings option on the current platform.
On Web, this method is not supported.

| Param | Type | Description |
| ------------- | ----------------------------------------------------------- | ----------------------------------- |
| options | PlatformOptions | Platform-specific settings options. |

Since: 1.0.0

--------------------

$3

`typescript
openIOS(options: IOSOptions) => Promise
`

Opens a specific system settings section. (iOS Only)

| Param | Type | Description |
| ------------- | ------------------------------------------------- | --------------------- |
| options | IOSOptions | iOS settings options. |

Since: 1.0.0

--------------------

$3

`typescript
openAndroid(options: AndroidOptions) => Promise
`

Opens a specific Android Intent. (Android Only)
On Web, this method is not supported.

| Param | Type | Description |
| ------------- | --------------------------------------------------------- | ------------------------- |
| options | AndroidOptions | Android settings options. |

Since: 1.0.0

--------------------

$3

`typescript
getPluginVersion() => Promise
`

Returns the native plugin version.

The returned version corresponds to the native implementation
bundled with the application.

Returns: Promise<PluginVersionResult>

Since: 1.0.0

#### Example

`ts
const { version } = await Settings.getPluginVersion();
`

--------------------

$3


#### PlatformOptions

Platform-specific options for opening system settings.

This interface allows specifying settings options for both
Android and iOS in a single call.

| Prop | Type | Description |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| optionAndroid | AndroidSettings | Android settings option to open. Used only when running on Android. Mapped internally to a system Intent. |
| optionIOS | IOSSettings | iOS settings option to open. Used only when running on iOS. Mapped internally to an iOS settings URL scheme. |


#### IOSOptions

iOS-specific options for opening system settings.

| Prop | Type | Description |
| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| option | IOSSettings | The iOS settings section to open. Most values correspond to internal iOS URL schemes. Availability depends on the iOS version and system configuration. |


#### AndroidOptions

Android-specific options for opening system settings.

| Prop | Type | Description |
| ------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| option | AndroidSettings | The Android settings section to open. Each value maps to a specific Android system Intent. Support varies depending on the device and OS version. |


#### PluginVersionResult

Result object returned by the getPluginVersion() method.

| Prop | Type | Description |
| ------------- | ------------------- | --------------------------------- |
| version | string | The native plugin version string. |

$3


#### AndroidSettings

| Members | Value | Description |
| ---------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Accessibility | 'accessibility' | Opens Accessibility settings. |
| Account | 'account' | Opens the Add Account screen. |
| AirplaneMode | 'airplane_mode' | Opens Airplane Mode settings. |
| Apn | 'apn' | Opens Access Point Name (APN) settings. |
| ApplicationDetails | 'application_details' | Opens the Application Details screen for the current app. |
| ApplicationDevelopment | 'application_development' | Opens Application Development settings. Availability depends on developer options being enabled. |
| Application | 'application' | Opens Application settings. |
| AppNotification | 'app_notification' | Opens app-specific notification settings. |
| BatteryOptimization | 'battery_optimization' | Opens Battery Optimization settings. Allows managing apps excluded from battery optimizations. |
| Bluetooth | 'bluetooth' | Opens Bluetooth settings. |
| Captioning | 'captioning' | Opens Captioning settings. |
| Cast | 'cast' | Opens Cast device settings. |
| DataRoaming | 'data_roaming' | Opens Data Roaming settings. |
| Date | 'date' | Opens Date & Time settings. |
| Display | 'display' | Opens Display settings. |
| Dream | 'dream' | Opens Dream (Daydream / Screensaver) settings. |
| Home | 'home' | Opens Home app selection settings. |
| Keyboard | 'keyboard' | Opens Input Method (Keyboard) settings. |
| KeyboardSubType | 'keyboard_subtype' | Opens Input Method Subtype settings. |
| Locale | 'locale' | Opens Language & Input (Locale) settings. |
| Location | 'location' | Opens Location Services settings. |
| ManageApplications | 'manage_applications' | Opens Manage Applications settings. |
| ManageAllApplications | 'manage_all_applications' | Opens Manage All Applications settings. Availability depends on Android version and OEM. |
| MemoryCard | 'memory_card' | Show settings for memory card storage |
| Network | 'network' | Opens Network Operator settings. |
| Nfc | 'nfc' | Opens NFC settings. |
| NfcSharing | 'nfcsharing' | Opens NFC Sharing settings. |
| NfcPayment | 'nfc_payment' | Opens NFC Payment settings. |
| Print | 'print' | Opens Print settings. |
| Privacy | 'privacy' | Opens Privacy settings. |
| QuickLaunch | 'quick_launch' | Opens Quick Launch settings. |
| Search | 'search' | Opens Search settings. |
| Security | 'security' | Opens Security settings. |
| Settings | 'settings' | Opens the main System Settings screen. |
| ShowRegulatoryInfo | 'show_regulatory_info' | Opens Regulatory Information screen. |
| Sound | 'sound' | Opens Sound & Volume settings. |
| Storage | 'storage' | Opens Internal Storage settings. |
| Sync | 'sync' | Opens Sync settings. |
| TextToSpeech | 'text_to_speech' | Opens Text-to-Speech (TTS) settings. Uses a non-public intent on some devices. |
| Usage | 'usage' | Opens Usage Access settings. Allows managing apps with access to usage data. |
| UserDictionary | 'user_dictionary' | Opens User Dictionary settings. |
| VoiceInput | 'voice_input' | Opens Voice Input settings. |
| VPN | 'vpn' | Opens VPN settings. |
| Wifi | 'wifi' | Opens Wi-Fi settings. |
| WifiIp | 'wifi_ip' | Opens Wi-Fi IP settings. Availability varies by device and Android version. |
| Wireless | 'wireless' | Opens Wireless & Networks settings. |
| ZenMode | 'zen_mode' | Opens Zen Mode (Do Not Disturb) settings. This uses a non-public intent and may not work on all devices. |
| ZenModePriority | 'zen_mode_priority' | Opens Zen Mode Priority settings. |
| ZenModeBlockedEffects | 'zen_mode_blocked_effects' | Opens Zen Mode Blocked Effects settings. |


#### IOSSettings

| Members | Value | Description |
| ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| App | 'app' | Opens the app-specific settings screen. This is the ONLY settings destination officially supported by Apple and is considered App Store safe. |
| AppNotification | 'appNotification' | Opens the app-specific notification settings. - iOS 16+: opens the dedicated notification settings screen - iOS <16: falls back to the app settings screen |
| About | 'about' | Opens iOS "About" settings. |
| AutoLock | 'autoLock' | Opens Auto-Lock settings. |
| Bluetooth | 'bluetooth' | Opens Bluetooth settings. |
| DateTime | 'dateTime' | Opens Date & Time settings. |
| FaceTime | 'facetime' | Opens FaceTime settings. |
| General | 'general' | Opens General settings. |
| Keyboard | 'keyboard' | Opens Keyboard settings. |
| ICloud | 'iCloud' | Opens iCloud settings. |
| ICloudStorageBackup | 'iCloudStorageBackup' | Opens iCloud Storage & Backup settings. |
| International | 'international' | Opens Language & Region (International) settings. |
| LocationServices | 'locationServices' | Opens Location Services settings. |
| Music | 'music' | Opens Music settings. |
| Notes | 'notes' | Opens Notes settings. |
| Notifications | 'notifications' | Opens Notifications settings. Note: this is the global notifications screen, not app-specific notifications. |
| Phone | 'phone' | Opens Phone settings. |
| Photos | 'photos' | Opens Photos settings. |
| ManagedConfigurationList | 'managedConfigurationList' | Opens Managed Configuration profiles list. |
| Reset | 'reset' | Opens Reset settings. |
| Ringtone | 'ringtone' | Opens Ringtone settings. |
| Sounds | 'sounds' | Opens Sounds settings. |
| SoftwareUpdate | 'softwareUpdate' | Opens Software Update settings. |
| Store | 'store' | Opens App Store settings. |
| Tracking | 'tracking' | Opens App Tracking Transparency settings. Available on iOS 14+. |
| Wallpaper | 'wallpaper' | Opens Wallpaper settings. |
| WiFi | 'wifi' | Opens Wi-Fi settings. |
| Tethering | 'tethering' | Opens Personal Hotspot (Tethering) settings. |
| DoNotDisturb | 'doNotDisturb' | Opens Do Not Disturb settings. |
| TouchIdPasscode | 'touchIdPasscode' | Opens Touch ID / Passcode settings. |
| ScreenTime | 'screenTime' | Opens Screen Time settings. |
| Accessibility | 'accessibility' | Opens Accessibility settings. |
| VPN | 'vpn' | Opens VPN settings. |

---

Platform limitations

$3

Apple officially supports opening only the app-specific settings screen.
Other settings destinations rely on undocumented URL schemes and may change
or be restricted by future iOS versions or App Store review policies.

$3

Some Android system settings are not guaranteed to be available on all devices.

Certain options (such as Zen Mode / Do Not Disturb related settings) rely on
device-specific or undocumented system intents. Availability may vary depending on:

- Android version
- device manufacturer (OEM)
- system configuration or user restrictions

When a requested settings screen is not supported on the current device,
the plugin rejects the Promise with the error code:

- UNAVAILABLE

Consumers are expected to handle this case using standard try / catch`
error handling.

This behavior is intentional and aligns with real-world Android platform constraints.

For historical context on Android intent limitations, see the discussion in the
original implementation:
https://github.com/RaphaelWoude/capacitor-native-settings/pull/63
Note that this plugin does not use the state-based result model found in that implementation.

---

Contributing

Contributions are welcome! Please read the contributing guide before submitting a pull request.

---

Credits

This plugin is based on prior work from the Community and
has been refactored and modernized for Capacitor v8 and
Swift Package Manager compatibility.

Original inspiration:

- https://github.com/RaphaelWoude/capacitor-native-settings

---

License

MIT