Install

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 | 8.0.0 |

Examples

In capacitor.config.json:

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

In capacitor.config.ts:

/// <reference types="@cap-kit/settings" />

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

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

export default config;

API

The plugin provides a generic open() method for cross-platform usage, and platform-specific aliases (openIOS(), openAndroid()) for direct invocation. While openIOS() and openAndroid() can be used, it's generally recommended to use open() with PlatformOptions for a more unified approach.

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

Public JavaScript API for the Settings Capacitor plugin.

This plugin uses a standard Promise rejection model for errors.

All methods return a Promise that:

• resolves when the operation is successful
• rejects when the operation fails or is not supported

When rejected, the error object contains a machine-readable code from SettingsErrorCode.

open(...)

open(options: PlatformOptions) => Promise<void>

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

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

Since: 8.0.0

openIOS(...)

openIOS(options: IOSOptions) => Promise<void>

Opens a specific system settings section. (iOS Only)

This method is a platform-specific helper. For cross-platform usage, prefer the generic open() method with PlatformOptions.

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

Since: 8.0.0

openAndroid(...)

openAndroid(options: AndroidOptions) => Promise<void>

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

This method is a platform-specific helper. For cross-platform usage, prefer the generic open() method with PlatformOptions.

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

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native plugin version.

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

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Example

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

Interfaces

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. If running on Android and this option is missing or empty, the promise will be rejected with SettingsErrorCode.INVALID_INPUT. | | optionIOS | IOSSettings | iOS settings option to open. Used only when running on iOS. Mapped internally to an iOS settings URL scheme. If running on iOS and this option is missing or empty, the promise will be rejected with SettingsErrorCode.INVALID_INPUT. |

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. |

Enums

AndroidSettings

| Members | Value | Description | | --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Accessibility | 'accessibility' | Opens Accessibility settings. | | 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. | | 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. | | Cast | 'cast' | Opens Cast device settings. | | DataRoaming | 'data_roaming' | Opens Data Roaming settings. | | Date | 'date' | Opens Date & Time settings. | | Display | 'display' | Opens Display settings. | | Home | 'home' | Opens Home app selection settings. | | Location | 'location' | Opens Location Services settings. | | Nfc | 'nfc' | Opens NFC settings. | | NfcSharing | 'nfcsharing' | Opens NFC Sharing settings. | | NfcPayment | 'nfc_payment' | Opens NFC Payment settings. | | Print | 'print' | Opens Print settings. | | Security | 'security' | Opens Security settings. | | Settings | 'settings' | Opens the main System Settings screen. | | Sound | 'sound' | Opens Sound & Volume settings. | | Storage | 'storage' | Opens Internal Storage 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. | | VPN | 'vpn' | Opens VPN settings. | | Wifi | 'wifi' | Opens Wi-Fi 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

iOS

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.

Android

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