--- title: Building a Settings bundle for your app framework: foundation role: article role_heading: Article path: foundation/building-a-settings-bundle-for-your-app --- # Building a Settings bundle for your app Integrate your app’s custom settings into the Settings app in iOS, iPadOS, tvOS, and visionOS, and support a Mac Catalyst settings window. ## Overview Overview In iOS, iPadOS, tvOS, and visionOS, you can display some or all of your app’s settings from the system’s Settings app. The Settings app already displays system-specific settings for each app. For example, if an app supports push notifications, the Settings app displays details about the types of alerts the system uses to deliver those notifications. If you don’t want to display settings from your app’s interface, you can display them in the Settings app instead. Typically, you do so if people modify the settings infrequently. To add custom settings to the system’s Settings app, include a Settings bundle inside your app. A Settings bundle contains static files that describe your app’s settings to the system. The system uses the information in these files to build the content for your app’s settings interface and to save changes to settings back to your app’s defaults database. Your app’s custom settings appear below any system-specific settings. If your iOS app supports Mac Catalyst, the system uses your app’s Settings bundle to create an appropriate settings interface when your app runs in macOS. The system displays and manages this settings interface for you, and automatically adds a menu item to your app’s menus to display that interface. This system-provided settings interface matches the experience that people expect for apps in macOS. note: To determine when to add a Settings bundle to your app, see Settings in Human Interface Guidelines. Add the Settings bundle and initial content to your project Xcode provides a template for a Settings bundle that you can add to your project and modify. To add this bundle to your app: Open your app project in Xcode. Select New > File from Template. Select Settings Bundle from the Resources section. Click Next. Add the Settings bundle to your app target. Save the bundle with the name Settings.bundle. When you add a Settings bundle to your project, Xcode creates the bundle directory and populates it with some initial files. The main file of each Settings bundle is a property list file called Root.plist that describes the contents of the main page of your settings interface. This property list file contains a dictionary with special keys and values that describe your interface. Place the individual elements of your settings interface in the array for the Preference Items key. Use other keys to configure both the page of content and the elements themselves. Remove any elements from the initial Root.plist file that you don’t need, and replace them with elements you do need. The following table lists the types of elements you can include, along with tips for how to use them to display your app’s settings. | | | | | | | | | Localize the content of your settings interface When you build your settings interface, specify the text for interface elements in your development language. To localize that text, add strings files to your Settings bundle for each language you support. When building your settings interface, the Settings app loads the strings file for the appropriate language and makes the relevant substitutions. The following listing shows the structure of a bundle that includes localized strings for English and German. Settings.bundle/ Root.plist en.lproj/ root.strings de.lproj/ root.strings Each property list file in your Settings bundle can have its own dedicated strings file. When building a page of settings, add the Strings Filename key to the page and set its value to the name of the relevant strings file. Omit the filename extension from the name of the strings file. For example, when specifying the strings file for the Root.plist file in the previous listing, set the value of the key to root. Inside each strings file, place a pair of translation strings on its own line and separate the strings with an equal sign (=). Place the original value on the left side of the equal sign, and have your translator place the translated value on the right side. The following listing shows the contents of a strings file that translates a set of strings from English to German. "Group" = "Gruppe"; "Name" = "Name"; "Enabled" = "Aktiviert"; Specify the contents of each settings page Each property list file in your Settings bundle contains top-level keys that describe the contents of that page. Include these keys in the Root.plist file to specify the contents of your main settings page. Also include them in the property list file for any child pages you add to your Settings bundle. The keys tell the Settings app what elements to display on the page and where to find localized resources. The following table lists the supported keys and their purpose. | | | | | | | | Add a child page element If your app’s settings interface includes a large number of elements, organize those elements hierarchically using child page elements. When the Settings app encounters a child page element, it adds a single row to the current page of your settings interface. Tapping or clicking the row transitions to a new page, the contents of which you provide in a separate property list file in your Settings bundle. The following table lists the supported keys and their purpose. | | | | | | | | | | Add a group element Include group elements to separate settings visually on the current page. When the Settings app encounters a group element, it renders the items in the group with a special visual treatment to indicate they’re related to each other, and not to other elements. The group includes the items immediately after the group element. The group ends when there are no more elements in the Preference Items array, or when the Settings app encounters a radio group element or another group element. The following table lists the supported keys and their purpose. | | | | | | Add a multi-value element A multi-value element gives someone a way to choose one value from a mutually exclusive set of values. The Settings app displays a single row for this element on the current page. When someone taps or clicks that row, Settings displays a new page with the available values and places a checkmark next to the selected one. When someone changes the selected value, the system saves the new value to your app’s defaults database. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | Add a radio group element A radio group element displays a group of mutually exclusive values on the current page. This element is similar to a multi-value element but places the items on the current page instead of displaying a new page. Tapping or clicking one row deselects the other rows and saves the new value to your app’s defaults database. Avoid using this option with a large number of possible values. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | | | If a group element appeared previously in the list of items, the presence of this element ends that group and creates a new group exclusively for the radio group values. If you display any items after the radio group, make the first item another group element to create a new group of settings. Add a slider element A slider element displays a row with a slider control that you can use to represent a continuous range of values. The control in this row is equivalent to a Slider, UISlider, or NSSlider control. The slider control spans the entire width of the row, with the slider’s minimum position located at the leading edge of the row. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | | | note: tvOS doesn’t support slider controls in settings interfaces, and the Settings app in tvOS ignores slider elements in your property list files. Add a text-field element A text-field element displays a row with an editable space for typing a text-based value. The title of the element appears on the row’s leading edge and the value appears on the trailing edge. Tapping or clicking the row displays the system keyboard so the person can type. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | | | | | important: Because the Settings app displays and manages your settings interface, your app can’t validate the setting’s text before the system saves it to the database. When you retrieve a value for the associated setting in your code, validate it before you use it. Add a title element A title element displays a read-only version of the setting’s name and its currently configured value, if any. Use this element to display settings that you don’t want people to change. For example, you might use this field to display login information that someone created using your app’s interface. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | Use the Titles and Values keys of this element to provide meaningful descriptions of potentially cryptic settings. If the Values array contains the current setting, the Settings app displays the associated string from the Titles array instead. If the setting contains a value that’s not in the array, the Settings app displays the value without modification. Add a toggle switch element A toggle switch element displays a control with a binary choice and a title describing the meaning behind that choice. This element is equivalent to a Toggle, UISwitch, or NSSwitch control. Typically, you use this element for settings that enable or disable features. The following table lists the supported keys and their purpose. | | | | | | | | | | | | | | | | | | | | In an iOS app running in Mac Catalyst, include the TrueConfirmationPrompt or FalseConfirmationPrompt keys if you want the person to confirm the change before the system updates the setting. When these keys are present, the system displays a prompt with information you provide in the dictionary of the appropriate key. If the person confirms the change, the system writes the new setting to the defaults database. The following table lists the supported keys and values for that dictionary. | | | | | | | | | | | | ## See Also ### Settings interfaces - [Adding a settings interface to your app](foundation/adding-a-settings-interface-to-your-app.md)