Preference

Build interactive settings screens without needing to interact with device storage or manage the UI.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
July 26, 2023 1.2.1 - - -

Declaring dependencies

To add a dependency on Preference, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Kotlin

dependencies {
    val preference_version = "1.2.1"

    // Java language implementation
    implementation("androidx.preference:preference:$preference_version")
    // Kotlin
    implementation("androidx.preference:preference-ktx:$preference_version")
}

For more information about dependencies, see Add Build Dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.2

Version 1.2.1

July 26, 2023

androidx.preference:preference:1.2.1 is released. Version 1.2.1 contains these commits.

Bug Fixes

  • PreferenceHeaderFragmentCompat now correctly handles the system back button when used within a ComponentDialog or when using libraries like Hilt's @AndroidEntryPoint that wrap the Fragment's Context.
  • Preference now depends on Activity 1.5.1. (Ie5d22)
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment now propagates header.extras as the Fragment arguments.

Version 1.2.0

January 26, 2022

androidx.preference:preference:1.2.0 and androidx.preference:preference-ktx:1.2.0 are released. Version 1.2.0 contains these commits.

Important changes since 1.1.0

  • Added PreferenceHeaderFragmentCompat for two-pane preference that automatically adapts based on size of the device used, making it suitable for use on phones, foldables, and tablets. The header pane is provided by overriding the onCreatePreferenceHeader() method on PreferenceHeaderFragmentCompat. Any <Preference> in the header PreferenceFragmentCompat that uses app:fragment will cause that fragment to appear in the second detail pane. The initial detail fragment that should be displayed before any preference is manually selected can be customized by overriding onCreateInitialDetailFragment(). The default implementation returns the first preference that has a fragment defined on it.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Added nullability annotations to many of the APIs that previously did not specify @NonNull or @Nullable. This is a potentially Kotlin source breaking change if the nullability you had chosen in your Kotlin code did not match the nullability that is now defined.

  • PreferenceFragmentCompat’s now looks for implementations of the OnPreferenceStartFragmentCallback, OnNavigateToScreenListener, and OnDisplayPreferenceDialogListener interface on parent fragments before looking to see if the hosting Context or Activity implement these interfaces.

Version 1.2.0-rc01

December 15, 2021

androidx.preference:preference:1.2.0-rc01 and androidx.preference:preference-ktx:1.2.0-rc01 are released with no changes since 1.2.0-beta01. Version 1.2.0-rc01 contains these commits.

Version 1.2.0-beta01

November 17, 2021

androidx.preference:preference:1.2.0-beta01 and androidx.preference:preference-ktx:1.2.0-beta01 are released with no changes from Preference 1.2.0-alpha02. Version 1.2.0-beta01 contains these commits.

Version 1.2.0-alpha02

November 3, 2021

androidx.preference:preference:1.2.0-alpha02 and androidx.preference:preference-ktx:1.2.0-alpha02 are released. Version 1.2.0-alpha02 contains these commits.

API Changes

  • Added nullability annotations to many of the APIs that previously did not specify @NonNull or @Nullable. (I04252, Ie2cc0)
  • Removed the openPreference() API from PreferenceHeaderFragmentCompat - this method is called for you and should not be called manually. (Ia6989)

Behavior Changes

  • PreferenceFragmentCompat callbacks for OnNavigateToScreenListener, and OnDisplayPreferenceDialogListener now follow the same pattern as OnPreferenceTreeClickListener and look up the parent fragment hierarchy for valid listeners before looking to see if the hosting Context or Activity implement these interfaces. (I7ae6c)

Version 1.2.0-alpha01

October 27, 2021

androidx.preference:preference:1.2.0-alpha01 and androidx.preference:preference-ktx:1.2.0-alpha01 are released. Version 1.2.0-alpha01 contains these commits.

New Features

  • Added PreferenceHeaderFragmentCompat for two-pane preference (I9a2d8)

Behavior Changes

  • Preference callbacks for OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback, and OnPreferenceStartFragmentCallback can now be implemented in a non-Activity Context. getContext() is checked to see if it implements these callbacks before checking getActivity(). If getContext() returns an Activity (the common case), then there is no behavior change.

  • PreferenceFragmentCompat’s call to onPreferenceTreeClick now looks for implementations of the OnPreferenceStartFragmentCallback interface on parent fragments before considering the Activity’s implementation. (c64eed)

Version 1.1

Version 1.1.1

April 15, 2020

androidx.preference:preference:1.1.1 and androidx.preference:preference-ktx:1.1.1 are released. Version 1.1.1 contains these commits.

Bug Fixes

  • PreferenceDialogFragmentCompat will no longer throw an IllegalStateException when inflating a FragmentContainerView from xml. (b/150051716)

Dependency updates

  • Preference now depends on Fragment 1.2.4. (aosp/1277317)
  • The preference-ktx dependency now depends on androidx.core:core-ktx:1.1.0 and androidx.fragment:fragment-ktx:1.2.4, mirroring the dependencies of the main preference artifact and ensuring that upgrading preference-ktx updates both the main and -ktx artifacts of transitive dependencies. (aosp/1277319)

Version 1.1.0

September 5, 2019

androidx.preference:preference:1.1.0 and androidx.preference:preference-ktx:1.1.0 are released. The commits included in this version can be found here.

If this is the first 1.1.* release you are updating to, here is a concise list of larger changes since the last stable release, 1.0.0. You may also find the Settings guide, sample app, and Android Dev Summit talk useful.

Important changes since 1.0.0

  • PreferenceFragment and other classes using framework Fragments have been deprecated; you should use PreferenceFragmentCompat and other *compat classes instead.
  • You can now set a SummaryProvider on a Preference to dynamically configure its summary whenever the Preference is updated, or becomes visible to the user. See the guide for more information.
  • Added EditTextPreference.OnBindEditTextListener interface. This allows customizing the EditText displayed in the corresponding dialog after the dialog has been bound. This is a direct replacement for using attributes such as android:inputType directly on the EditTextPreference, which is not supported in the AndroidX library. See the guide for more information.
  • Added Preference.setCopyingEnabled() When set, long pressing on the Preference will show a context menu that allows copying the summary of the Preference.
  • Updated SeekBarPreference styling to match Material specifications. See the detailed changelog for other changes to SeekBarPreference.
  • A large amount of bug fixes, style updates, API level compatibility fixes, and general QOL improvements.

Version 1.1.0-rc01

July 2, 2019

androidx.preference:preference:1.1.0-rc01 and androidx.preference:preference-ktx:1.1.0-rc01 are released. The commits included in this version can be found here.

API changes

  • Deprecate Preference#onInitializeAccessibilityNodeInfo
  • This method proxied accessibility node info for a specific Preference - but this is the wrong layer for this customization. If you would like to adjust accessibility information, you should instead override onBindViewHolder, and add accessibility information to the view directly.

Version 1.1.0-beta01

June 5, 2019

androidx.preference:preference:1.1.0-beta01 and androidx.preference:preference-ktx:1.1.0-beta01 are released. The commits included in this version can be found here.

Important changes since 1.1.0

If this is the first 1.1.* release you are updating to, here is a concise list of larger changes since the last stable release, 1.1.0. You may also find the Settings guide, sample app, and Android Dev Summit talk useful.

  • PreferenceFragment and other classes using framework Fragments have been deprecated - you should use PreferenceFragmentCompat and other *compat classes instead.
  • You can now set a SummaryProvider on a Preference to dynamically configure its summary whenever the Preference is updated, or becomes visible to the user. See the guide for more information.
  • Added EditTextPreference.OnBindEditTextListener interface. This allows customizing the EditText displayed in the corresponding dialog after the dialog has been bound. This is a direct replacement for using attributes such as android:inputType directly on the EditTextPreference, which is not supported in the AndroidX library. See the guide for more information.
  • Added Preference.setCopyingEnabled() When set, long pressing on the Preference will show a context menu that allows copying the summary of the Preference.
  • Updated SeekBarPreference styling to match Material specifications. See the detailed changelog for other changes to SeekBarPreference.
  • A large amount of bug fixes, style updates, API level compatibility fixes, and general QOL improvements.

API changes since 1.1.0-alpha05

  • Removes getOnBindEditTextListener from public API, you should only need to use setOnBindEditTextListener when interacting with this API.

Please file bugs here if you run into any issues, or if you have suggestions for new features!

Version 1.1.0-alpha05

May 7, 2019

androidx.preference:preference:1.1.0-alpha05 and androidx.preference:preference-ktx:1.1.0-alpha05 are released. The commits included in this version can be found here.

New features

  • Updated the styling for unselectable Preferences - the title and summary now share the same color to make it clear that they cannot be interacted with, and are only used for displaying information.
  • Note: you may want to consider adding enableCopying="true" to your unselectable Preferences, so you can long press to copy the summary.

Bug fixes

  • Fixed a regression where PreferenceCategory and other unselectable Preferences would have a ripple effect when selected
  • Fixed an accessibility issue where TalkBack did not see DropDownPreference as clickable
  • Fixed some RTL layout issues
  • Updated some nullable annotations in PreferenceFragmentCompat to match Fragment

Version 1.1.0-alpha04

March 13, 2019

androidx.preference:preference:1.1.0-alpha04 and androidx.preference:preference-ktx:1.1.0-alpha04 are released. The full list of commits included in this version can be found here.

New features

The SeekBarPreference update!

  • Styling updated to match Material Specifications
    • The value label is now hidden by default although it can still be shown with app:showSeekBarValue="true" or setShowSeekBarValue(true). This label is not part of Material spec, but we understand that it is heavily used so we will continue to support it - even though we don’t recommend using it.
    • The value label now updates while the SeekBar is being dragged, instead of when it is released. Note that this does not mean that the value internally is updated, see below for a new API that enables that functionality.
    • Note: Although it is supported, you should avoid setting a summary on a SeekBarPreference, as it is not intended and not part of the Material spec.
  • Adds support for continuous updates, allowing the SeekBar to update its saved value while the SeekBar is being dragged. This can be enabled from XML or programmatically, with app:updatesContinuously="true" or setUpdatesContinuously(true). This will fire whenever the SeekBar’s position on screen changes.

API changes

  • Adds missing nullability annotations to findPreference()

Bug fixes

  • Fixed a bug where context menu listeners were not being correctly removed if copying is not enabled

Version 1.1.0-alpha03

February 7, 2019

androidx.preference:preference 1.1.0-alpha03

androidx.preference:preference 1.1.0-alpha03 and androidx.preference:preference-ktx 1.1.0-alpha03 are released with the following changes.

Bug fixes

  • Fixed an issue where the copy/paste popup would sometimes not show in EditTextPreference’s dialog
  • Fixed an issue where the underlying adapter was not unregistered properly, causing memory leaks under specific conditions (b/121006469)
  • Fixed some dialog related crashes that occurred during configuration change (b/122167543)
  • Fixed SummaryProvider not working for MultiSelectListPreference (b/123022772)

Version 1.1.0-alpha02

December 17, 2018

Please also check out the recently updated Settings guide and sample app.

New features

  • Added EditTextPreference.OnBindEditTextListener interface This allows customizing the EditText displayed in the corresponding dialog after the dialog has been bound. For example, setting a custom input type / length or adding a TextWatcher.

  • Added Preference.setCopyingEnabled() When set, long pressing on the Preference will show a context menu that allows copying the summary of the Preference. This can be used to allow copying of static information such as user-specific IDs / application version information.

  • preferenceTheme is now applied to the activity theme This means that when creating a Preference from code, you no longer need to use the context from PreferenceManager#getContext() - you can just use your Fragment/Activity context.

API changes

  • Refactored findPreference() to return <T extends Preference> This means that you do not need to explicitly cast Preferences when using findPreference(). For example, EditTextPreference preference = findPreference(“edit_text”) is now valid code.

Version 1.1.0-alpha01

November 5, 2018

New features

  • You can now set a SummaryProvider on a Preference to dynamically configure its summary whenever the Preference is updated, or becomes visible to the user.
  • Added default SummaryProvider implementations for ListPreference and EditTextPreference, which when set will automatically update the summary of the Preference to reflect its saved value, or ‘Not Set’ if no value has been saved. These can be set with app:useSimpleSummaryProvider=”true”
  • Added PreferenceGroup#removePreferenceRecursively which recursively finds and removes a Preference from the group, or a nested group lower down in the hierarchy.

API changes

  • PreferenceFragment and other classes using framework Fragments have been deprecated - you should use PreferenceFragmentCompat and other compat classes instead.

Bug fixes

  • Fixed iconSpaceReserved not working correctly with PreferenceCategories.
  • Fixed PreferenceCategories not using colorAccent for their title’s color below API 21.
  • Fixed some SeekBarPreference layout inconsistencies below API 21.