---
title: "Collection preferences - Cloudscape Design System"
source: "https://cloudscape.design/components/collection-preferences/?tabId=api"
created: 2025-11-21
description: "With collection preferences, users can manage their display preferences within a collection."
tags:
- "clippings"
---
- [Playground](https://cloudscape.design/components/collection-preferences/?tabId=playground)
- [API](https://cloudscape.design/components/collection-preferences/?tabId=api)
- [Testing](https://cloudscape.design/components/collection-preferences/?tabId=testing)
- [Usage](https://cloudscape.design/components/collection-preferences/?tabId=usage)
## Development guidelines
#### State management
The collection preferences component is controlled. Set the `preferences` property and the `onConfirm` listener to store its value in the state of your application. Learn more about the [state management](https://cloudscape.design/get-started/dev-guides/state-management/) of Cloudscape components.
## Properties
| Name | Type | Description | Accepted values | Default | Required |
| --- | --- | --- | --- | --- | --- |
| cancelLabel | ``` string ``` | Label of the cancel button in the modal footer. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| className (deprecated) | ``` string ``` | Adds the specified classes to the root element of the component. **Deprecated**. Custom CSS is not supported. For testing and other use cases, use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). | \- | \- | ``` false ``` |
| closeAriaLabel | ``` string ``` | Adds an aria-label to the close button, for accessibility. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| confirmLabel | ``` string ``` | Label of the confirm button in the modal footer. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| contentDensityPreference | ``` CollectionPreferencesProps.ContentDensityPreference { description?: string label?: string } ``` | Configures the content density preference (Comfortable / Compact). If you set it, the component displays this preference in the modal. It contains the following: - `label` (string) - Specifies the label for the option checkbox. - `description` (string) - Specifies the text displayed below the checkbox label. You must set the current value in the `preferences.contentDensity` property. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| contentDisplayPreference | ``` CollectionPreferencesProps.ContentDisplayPreference { description?: string dragHandleAriaDescription?: string dragHandleAriaLabel?: string enableColumnFiltering?: boolean i18nStrings?: CollectionPreferencesProps.ContentDisplayPreferenceI18nStrings liveAnnouncementDndDiscarded?: string liveAnnouncementDndItemCommitted?: ( initialPosition: number, finalPosition: number, total: number ) => string liveAnnouncementDndItemReordered?: ( initialPosition: number, currentPosition: number, total: number ) => string liveAnnouncementDndStarted?: ( position: number, total: number ) => string options: ReadonlyArray<CollectionPreferencesProps.ContentDisplayOption> title?: string } ``` | Configures the built-in content display preference for order and visibility of the table columns. Recommended for table and not applicable for cards. Cannot be used together with `visibleContentPreference`. If you set it, the component displays this preference in the modal. It contains the following: - `title` (string) - Specifies the text displayed at the top of the preference. - `description` (string) - Specifies the description displayed below the title. - `options` - Specifies an array of options for reordering and visible content selection. - `enableColumnFiltering` (boolean) - Adds a columns filter. - `liveAnnouncementDndStarted` ((position: number, total: number) => string) - (Optional) Adds a message to be announced by screen readers when an option is picked. - `liveAnnouncementDndDiscarded` (string) - (Optional) Adds a message to be announced by screen readers when a reordering action is canceled. - `liveAnnouncementDndItemReordered` ((initialPosition: number, currentPosition: number, total: number) => string) - (Optional) Adds a message to be announced by screen readers when an item is being moved. - `liveAnnouncementDndItemCommitted` ((initialPosition: number, finalPosition: number, total: number) => string) - (Optional) Adds a message to be announced by screen readers when a reordering action is committed. - `dragHandleAriaDescription` (string) - (Optional) Adds an ARIA description for the drag handle. - `dragHandleAriaLabel` (string) - (Optional) Adds an ARIA label for the drag handle. Each option contains the following: - `id` (string) - Corresponds to a table column `id`. - `label` (string) - Specifies a short description of the content. - `alwaysVisible` (boolean) - (Optional) Determines whether the visibility is always on and therefore cannot be toggled. This is set to `false` by default. You must provide an ordered list of the items to display in the `preferences.contentDisplay` property. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| customPreference | ``` ( customValue: CustomPreferenceType, setCustomValue: React.Dispatch<CustomPreferenceType> ) => React.ReactNode ``` | Configures custom preferences. The function receives two parameters: - `customValue` (CustomPreferenceType) - Current value for your custom preference. It is initialized using the value you provide in `preferences.custom`. - `setCustomValue` - A function that is called to notify a state update. It should return the content of your custom preference, for example: ``` (customValue, setCustomValue) => ( <Checkbox checked={customValue} onChange={({ detail }) => setCustomValue(detail.checked)} /> ) ``` When the user confirms the changes, the new value is passed in the `detail.custom` property of the `onConfirm` listener.When the user cancels the changes, the `customValue` is reset to the one present in `preferences.custom` property. **Display** - If any of the built-in preferences (`pageSizePreference`, `wrapLinesPreference`, or `visibleContentPreference`) are displayed,the custom content is displayed at the bottom of the left column within the modal. - If no built-in preference is displayed, the custom content occupies the whole modal. | \- | \- | ``` false ``` |
| disabled | ``` boolean ``` | Determines whether the preferences trigger button is disabled. | \- | ``` false ``` | ``` false ``` |
| getModalRoot | ``` (options: { abortSignal: AbortSignal }) => Promise<HTMLElement> ``` | Use this property to specify a different dynamic modal root for the dialog.The function will be called when a user clicks on the trigger button. | \- | \- | ``` false ``` |
| id (deprecated) | ``` string ``` | Adds the specified ID to the root element of the component. **Deprecated**. The usage of the `id` attribute is reserved for internal use cases. For testing and other use cases,use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). If you mustuse the `id` attribute, consider setting it on a parent element instead. | \- | \- | ``` false ``` |
| pageSizePreference | ``` CollectionPreferencesProps.PageSizePreference { options: ReadonlyArray<CollectionPreferencesProps.PageSizeOption> title?: string } ``` | Configures the built-in "page size selection" preference. If you set it, the component displays this preference in the modal. It contains the following: - `title` (string) - Specifies the text displayed at the top of the preference. - `options` - Specifies an array of options for page size selection. Each entry contains: - `value` (number) - The value for the radio button (that is, the number of items per page). - `label` (string) - A label for the radio button (for example, "10 resources"). You must set the current value in the `preferences.pageSize` property. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| preferences | ``` CollectionPreferencesProps.Preferences<CustomPreferenceType> { contentDensity?: string contentDisplay?: ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem> custom?: NonNullable<CustomPreferenceType> pageSize?: number stickyColumns?: StickyColumns stripedRows?: boolean visibleContent?: ReadonlyArray<string> wrapLines?: boolean } ``` | Specifies the current preference values. This includes both built-in and custom preferences. It contains the following: - `pageSize` (number) - (Optional) - `wrapLines` (boolean) - (Optional) - `contentDisplay` (ReadonlyArray<ContentDisplayItem>) - (Optional) Specifies the list of content and their visibility. The order of the elements influences the display. - `visibleContent` (ReadonlyArray<string>) - Specifies the list of visible content `id` s. The order of the `id` s does not influence the display. If the `contentDisplay` property is set, this property is ignored. - `custom` (CustomPreferenceType) - Specifies the value for your custom preference. | \- | \- | ``` false ``` |
| removeModalRoot | ``` (container: HTMLElement \| null) => void ``` | Use this property when `getModalRoot` is used to clean up the modal rootelement after a user closes the dialog. The function receives the return valueof the most recent getModalRoot call as an argument. | \- | \- | ``` false ``` |
| stickyColumnsPreference | ``` CollectionPreferencesProps.StickyColumnsPreference { firstColumns?: StickyColumnPreference lastColumns?: StickyColumnPreference } ``` | Configures the sticky columns preference that can be set for both left and right columns. If you set it, the component displays this preference in the modal. It contains the following: - `label` (string) - Specifies the label for each radio group. - `description` (string) - Specifies the text displayed below each radio group label. You must set the current value in the `preferences.stickyColumns` property. | \- | \- | ``` false ``` |
| stripedRowsPreference | ``` CollectionPreferencesProps.StripedRowsPreference { description?: string label?: string } ``` | Configures the built-in "striped rows" preference. If you set it, the component displays this preference in the modal. It contains the following: - `label` (string) - Specifies the label for the option checkbox. - `description` (string) - Specifies the text displayed below the checkbox label. You must set the current value in the `preferences.stripedRows` property. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| title | ``` string ``` | Specifies the title of the preferences modal dialog. It is also used as an `aria-label` for the trigger button. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
| visibleContentPreference | ``` CollectionPreferencesProps.VisibleContentPreference { options: ReadonlyArray<CollectionPreferencesProps.VisibleContentOptionsGroup> title: string } ``` | Configures the built-in visible sections preference for cards or visible columns for table. Recommended for cards. For table use `contentDisplayPreference` instead. Cannot be used together with `contentDisplayPreference`. If you set it, the component displays this preference in the modal. It contains the following: - `title` (string) - Specifies the text displayed at the top of the preference. - `options` - Specifies an array of groups of options for visible content selection. Each group of options contains the following: - `label` (string) - The text to display as a title for the options group. - `options` - Specifies an array of options in the group. Each option contains the following: - `id` (string) - Corresponds to a column `id` for tables or to a section `id` for cards. - `label` (string) - Specifies a short description of the content. - `editable` (boolean) - (Optional) Determines whether the user is able to toggle its visibility. This is `true` by default. You must set the current list of visible content `id` s in the `preferences.visibleContent` property. **Deprecated** in table, replaced by `contentDisplayPreference`. | \- | \- | ``` false ``` |
| wrapLinesPreference | ``` CollectionPreferencesProps.WrapLinesPreference { description?: string label?: string } ``` | Configures the built-in "wrap lines" preference. If you set it, the component displays this preference in the modal. It contains the following: - `label` (string) - Specifies the label for the option checkbox. - `description` (string) - Specifies the text displayed below the checkbox label. You must set the current value in the `preferences.wrapLines` property. **Note:** The property is part of [built-in internationalization](https://cloudscape.design/get-started/for-developers/internationalization/).This property is automatically provided if the application uses Cloudscape's I18nProvider. | \- | \- | ``` false ``` |
## Slots
| Name | Description |
| --- | --- |
| contentBefore | Content displayed before the preferences. Use it to display additional information relating to the preferences. |
## Events
| Name | Detail | Description | Cancelable |
| --- | --- | --- | --- |
| onCancel | | Called when the user cancels a preference change using the cancel button in the modal footer or by dismissing the modal. | ``` false ``` |
| onConfirm | ``` CollectionPreferencesProps.Preferences<CustomPreferenceType> { contentDensity?: string contentDisplay?: ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem> custom?: NonNullable<CustomPreferenceType> pageSize?: number stickyColumns?: StickyColumns stripedRows?: boolean visibleContent?: ReadonlyArray<string> wrapLines?: boolean } ``` | Called when the user confirms a preference change using the confirm button in the modal footer. The event `detail` contains the following: - `contentDensity` (boolean) - (Optional) The current content density preference value. Available only if you specify the `contentDensityPreference` property. - `contentDisplay` (ReadonlyArray<ContentDisplayItem>) - (Optional) The ordered list of table columns and their visibility. Available only if you specify the `contentDisplayPreference` property. - `custom` (CustomPreferenceType) - (Optional) The selected value for your custom preference. - `pageSize` (number) - (Optional) The selected page size value. Available only if you specify the `pageSizePreference` property. - `stickyColumns` (CollectionPreferencesProps.StickyColumns) - (Optional) The current sticky columns preference value. Available only if you specify the `stickyColumnsPreference` property. - `stripedRows` (boolean) - (Optional) The current striped rows preference value. Available only if you specify the `stripedRowsPreference` property. - `visibleContent` (ReadonlyArray<string>) - (Optional) The list of selected content `id` s. Available only if you specify the `visibleContentPreference` property. - `wrapLines` (boolean) - (Optional) The current line wrapping preference value. Available only if you specify the `wrapLinesPreference` property. The values for all configured preferences are present even if the user didn't change their values. | ``` false ``` |
