Preferences dialog
A preferences dialog allows you to display, group and navigate application preferences within a responsive modal dialog window. This pattern introduces guidelines to make the preferences dialog consistent and usable.
You should place any preference settings in your platform or application within a single centralized preferences dialog. These settings could be global, application-wide settings or settings local to a specific window or widget (such as a grid or comments feed). If accessing from a specific window, immediately display the relevant settings when the preferences dialog opens.
Furthermore, we recommend implementing consistent behavior around applying preferences, whether applying changes immediately or requiring the user to confirm any changes using the button bar actions.
A preferences dialog comprises four key features:
- Dialog: a window with a content area that opens over the application content, focusing the user’s attention on a particular task or piece of information
- Navigation item: a link that allows users to navigate to distinct panel of content
- Button bar: displays possible actions for users to take when they reach the end of a task. Use the button bar pattern to understand how to implement actionable interactions within dialogs across your applications
- Parent-child layout: positions the navigation and content within a preference dialog
In the parent-child layout, the parent container (containing the navigation) typically remains fixed in width when the user resizes the browser. You can apply an independent layout grid to align the content with the child container. This enables it to adapt responsively based on the viewport size.
To implement a responsive experience for preferences dialogs, refer to the layout guidance in the Navigation pattern.
You can use navigation items to switch between pages of grouped preferences.
Limit nesting to no more than two levels, if possible. A deep hierarchy can make it difficult for users to discover or locate specific preferences.
We recommend that scrolling affordance should only take effect if content in the parent-child layout exceeds the visible content area.
The visual indicators are the two separator lines above and below the parent-child layout. Apply the shadow-scroll token for the container shadow.
Display scrolling affordance when the content or navigation (or both) exceeds the visible area of the parent-child layout.
Cancel and Save button bar actions allow the user to manually apply preferences in the application. We recommend this when the user wants to:
- Make multiple changes with ease and apply them simultaneously.
- Easily cancel any unwanted changes.
It's preferable for affected components in your application to listen for live changes in the preferences dialog and dynamically update themselves.
Display core actions to the right of a dialog. Refer to the button bar pattern for further guidance on how to display user actions within dialogs.
If your application can listen for changes and take immediate effect, you don't need to display a button bar across a preferences dialog. A close button in the top-right corner of the dialog should be on display instead to allow the user to close the dialog after editing any preferences.
We recommend configuring the button bar to display secondary actions to the left such as Import and Export if you need to enable other actions.
The preferences dialog is responsive to the width of the application viewport and responds dynamically to the Salt breakpoints.
Once a preference dialog hits a certain breakpoint, you can configure the layout to either:
- Collapse to allow more room for content.
- Change the orientation to stack the button bar.
When the navigation collapses, the preferences content spans the entire width of the dialog. To select and view alternative preference types, users should use the back chevron button to navigate back to the vertical navigation. The vertical navigation view also spans the dialog width. A collapsed layout ensures improved usability of dialog content in smaller screen sizes or application resolutions.
For smaller viewports (i.e. devices with limited screen sizes), it's preferable to configure buttons to stack horizontally at the XS breakpoint. This ensures longer button labels accommodate mobile devices that may not fit within the horizontal layout. They also remain an adequate size for touch interactions.
View the stacked button bar guidance to understand how to order and build a stacked button bar.
If you need to expand the pattern or share feedback with us, please contact the team.