# Preference components and attributes
Part of [Android Jetpack](https://developer.android.com/jetpack).

This topic describes some of the most commonly-used `Preference` components and
attributes used when building a settings screen.

## Preference components

This section describes common `Preference` components. For more information, see
the corresponding reference pages for each component.

### Preference infrastructure

[`PreferenceFragmentCompat`](https://developer.android.com/reference/androidx/preference/PreferenceFragmentCompat) -
a [`Fragment`](https://developer.android.com/reference/kotlin/androidx/fragment/app/Fragment) that handles
displaying an interactive hierarchy of `Preference` objects.

### Preference containers

[`PreferenceScreen`](https://developer.android.com/reference/androidx/preference/PreferenceScreen) -
a top-level container that represents a settings screen. This is the root
component of your `Preference` hierarchy.

[`PreferenceCategory`](https://developer.android.com/reference/androidx/preference/PreferenceCategory) -
a container that is used to group similar `Preferences`. A `PreferenceCategory`
displays a category title and visually separates groups of `Preferences`.

### Individual Preferences

[`Preference`](https://developer.android.com/reference/androidx/preference/Preference) - the basic
building block that represents an individual setting. If a `Preference` is set
to persist, it has a corresponding key-value pair that holds the user's choice
for the setting that can be accessed elsewhere in the application.

[`EditTextPreference`](https://developer.android.com/reference/androidx/preference/EditTextPreference) -
a `Preference` that persists a `String` value. Users can tap on the `Preference`
to launch a dialog containing the text field that allows the user to change the
persisted value.

[`ListPreference`](https://developer.android.com/reference/androidx/preference/ListPreference) - a
`Preference` that persists a String value. Users can change this value in a
dialog that contains a list of radio buttons with corresponding labels.

[`MultiSelectListPreference`](https://developer.android.com/reference/androidx/preference/MultiSelectListPreference) -
a `Preference` that persists a set of Strings. Users can change these values in
a dialog that contains a list of checkboxes with corresponding labels.

[`SeekBarPreference`](https://developer.android.com/reference/androidx/preference/SeekBarPreference) -
a `Preference` that persists an integer value. This value can be changed by
dragging a corresponding seekbar that is displayed in the `Preference` layout.

[`SwitchPreferenceCompat`](https://developer.android.com/reference/androidx/preference/SwitchPreferenceCompat) -
a `Preference` that persists a boolean value. This value can be changed by
interacting with the corresponding switch widget or by tapping on the
`Preference` layout.

[`CheckBoxPreference`](https://developer.android.com/reference/androidx/preference/CheckBoxPreference) -
a `Preference` that persists a boolean value. This value can be changed by
interacting with the corresponding checkbox or by tapping on the `Preference`
layout.
| **Note:** Although `SwitchPreferenceCompat` and `CheckBoxPreference` store a boolean value and function in similar ways, we recommend using a `SwitchPreferenceCompat` where possible. For more information, see the [Android Settings Design Guidelines](https://source.android.com/devices/tech/settings/settings-guidelines#checkbox).

## Preference attributes

Listed below are some of the most commonly-used attributes that configure
`Preference` appearance and behavior.
| **Note:** Each attribute listed below has a corresponding getter and setter. For mostly static hierarchies, however, we recommend configuring these attributes via the `Preference` XML resource.

### Generic attributes


`title`

:   A `String` value that represents the title of the
    `Preference`.

    **Example:** `app:title="Title"`


`summary`

:   A `String` value that represents the `Preference`
    summary.

    **Example:** `app:summary="Summary"`


`icon`

:   A `Drawable` that represents the `Preference`
    icon.

    **Example:** `app:icon="@drawable/ic_camera"`


`key`

:   A `String` value that represents the key that is used to
    persist the value for the associated `Preference`. A key allows
    you to further customize the `Preference` during runtime.
    You should set a key for each `Preference` in your
    hierarchy.


    **Example:** `app:key="key"`


`enabled`

:   A boolean value that indicates whether users can interact with the
    `Preference`. When this value is `false`, the
    `Preference` appears grayed out, and users cannot interact with
    it. The default value is `true`.

    **Example:** `app:enabled="false"`


`selectable`

:   A boolean value that indicates whether users can interact with the
    `Preference`. The default value is `true`.

    **Example:** `app:selectable="false"`


`isPreferenceVisible`

:   A boolean value that indicates whether a `Preference` or
    `Preference` category is visible. This is equivalent to calling
    [`setVisible()`](https://developer.android.com/reference/androidx/preference/Preference#setVisible(boolean)).

    **Example:** `app:isPreferenceVisible="false"`


`defaultValue`

:   Represents the default value for a `Preference`. This value is
    set and persisted when no other persisted value for this
    `Preference` is found. The value type depends on the associated
    `Preference`.

    **Example:** `app:defaultValue="true"`


`dependency`

:   Represents the key of a `SwitchPreferenceCompat` that controls
    the state of this `Preference`. When the corresponding switch
    is turned off, this `Preference` is disabled and is unable to
    be modified.

    **Example:** `app:dependency="parent"`

### PreferenceCategory attributes


`initialExpandedChildrenCount`

:   An integer value that enables expandable `Preference`
    behavior. This value represents the maximum number of children to show in
    the `PreferenceGroup`. Any extra children are collapsed and can
    be shown by tapping the expand button. By default, this value is
    `Integer.MAX_VALUE`, and all children are shown.

    **Warning:** Ensure that you set a key on the
    `PreferenceCategory` if using this attribute so that the state
    is correctly saved and restored when the configuration changes (such as
    when rotating the screen).


    **Example:** `app:initialExpandedChildrenCount="0"`

### ListPreference / MultiSelectListPreference attributes


`entries`

:   An array of Strings that corresponds to the list entries to be displayed
    to the user. Each of these values correspond by index to the array of
    values that are internally persisted. For example, when a user selects the
    first list entry, the first element in the corresponding array of values
    is persisted.


    **Example:** `app:entries="@array/entries"`

    **Warning:** Ensure the length of both arrays are the
    same, and the indexes of each array match the correct entry / value
    pair.


`entryValues`

:   The array of entries to be persisted. Each of these values correspond by
    index to the array of list entries that are displayed to the user.


    **Example:** `app:entryValues="@array/values"`