Organize your settings   Part of Android Jetpack.

Large and complex settings screens can make it difficult for a user to find a specific setting they want to change. The Preference library offers the following ways to better organize your settings screens.

Preference categories

If you have several related Preference objects on a single screen, you can group them using a PreferenceCategory. A PreferenceCategory displays a category title and visually separates the category.

To define a PreferenceCategory in XML, wrap the Preference tags with a PreferenceCategory, as follows:

<PreferenceScreen
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <PreferenceCategory
        app:key="notifications_category"
        app:title="Notifications">

        <SwitchPreferenceCompat
            app:key="notifications"
            app:title="Enable message notifications"/>

    </PreferenceCategory>

    <PreferenceCategory
        app:key="help_category"
        app:title="Help">

        <Preference
            app:key="feedback"
            app:summary="Report technical issues or suggest new features"
            app:title="Send feedback"/>

    </PreferenceCategory>

</PreferenceScreen>

The result looks like the following:

An image showing preferences with categories
Figure 1. Preferences within categories.

Split your hierarchy into multiple screens

If you have a large number of Preference objects or distinct categories, you can display them on separate screens. Each screen is a PreferenceFragmentCompat with its own separate hierarchy. Preference objects on your initial screen can then link to subscreens that contain related preferences.

Figure 2 shows a simple hierarchy that contains two categories: Messages and Sync.

An image showing a preference screen with hierarchies
Figure 2. A simple hierarchy with two categories.

Figure 3 shows the same set of preferences split into multiple screens:

An image showing a hierarchy split into multiple screens
Figure 3. A hierarchy split into multiple screens.

To link screens with a Preference, you can declare an app:fragment in XML or you can use Preference.setFragment(). Launch the full package name of the PreferenceFragmentCompat when the Preference is tapped, as shown in the following example:

<Preference
        app:fragment="com.example.SyncFragment"
        .../>

When a user taps a Preference with an associated Fragment, the interface method PreferenceFragmentCompat.OnPreferenceStartFragmentCallback.onPreferenceStartFragment() is called. This method is where you handle displaying the new screen and where the screen is implemented in the surrounding Activity.

A typical implementation looks similar to the following:

Kotlin

class MyActivity : AppCompatActivity(),
    PreferenceFragmentCompat.OnPreferenceStartFragmentCallback {
    ...
    override fun onPreferenceStartFragment(caller: PreferenceFragmentCompat, pref: Preference): Boolean {
        // Instantiate the new Fragment.
        val args = pref.extras
        val fragment = supportFragmentManager.fragmentFactory.instantiate(
                classLoader,
                pref.fragment)
        fragment.arguments = args
        fragment.setTargetFragment(caller, 0)
        // Replace the existing Fragment with the new Fragment.
        supportFragmentManager.beginTransaction()
                .replace(R.id.settings_container, fragment)
                .addToBackStack(null)
                .commit()
        return true
    }
}

Java

public class MyActivity extends AppCompatActivity implements
        PreferenceFragmentCompat.OnPreferenceStartFragmentCallback {
    ...
    @Override
    public boolean onPreferenceStartFragment(PreferenceFragmentCompat caller, Preference pref) {
        // Instantiate the new Fragment.
        final Bundle args = pref.getExtras();
        final Fragment fragment = getSupportFragmentManager().getFragmentFactory().instantiate(
                getClassLoader(),
                pref.getFragment());
        fragment.setArguments(args);
        fragment.setTargetFragment(caller, 0);
        // Replace the existing Fragment with the new Fragment.
        getSupportFragmentManager().beginTransaction()
                .replace(R.id.settings_container, fragment)
                .addToBackStack(null)
                .commit();
        return true;
    }
}

PreferenceScreens

Declaring nested hierarchies within the same XML resource using a nested &lt;PreferenceScreen&gt; is no longer supported. Use nested Fragment objects instead.

Use separate Activities

Alternatively, if you need to heavily customize each screen, or if you want full Activity transitions between screens, you can use a separate Activity for each PreferenceFragmentCompat. By doing this, you can fully customize each Activity and its corresponding settings screen. For most apps, we don't recommended this; instead, use Fragments as previously described.

For more information about launching an Activity from a Preference, see Preference actions.