Collection preferences

Preview

Preferences trigger
With visible content preference

Usage

<cs-collection-preferences
  title="Preferences"
  page-size-preference='{"title":"Page size","options":[{"value":10,"label":"10 items"},{"value":25,"label":"25 items"},{"value":50,"label":"50 items"}]}'
  visible-content-preference='{"title":"Visible columns","options":[{"id":"name","label":"Name","editable":false},{"id":"type","label":"Type"},{"id":"size","label":"Size"}]}'
></cs-collection-preferences>

Properties

cancel-labelstring default: 'Cancel'

Label of the cancel button in the modal footer.

close-aria-labelstring

Adds an aria-label to the close button, for accessibility.

confirm-labelstring default: 'Confirm'

Label of the confirm button in the modal footer.

content-density-preferenceCollectionPreferencesProps.ContentDensityPreference

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.

content-display-preferenceCollectionPreferencesProps.ContentDisplayPreference

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.

custom-preference(customValue: CustomPreferenceType, setCustomValue: (value: CustomPreferenceType) => void) => unknown

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.
disabledboolean default: false

Determines whether the preferences trigger button is disabled.

get-modal-rootPortalProps['getContainer']

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.

page-size-preferenceCollectionPreferencesProps.PageSizePreference

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.

preferencesCollectionPreferencesProps.Preferences<CustomPreferenceType>

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) - (Optional) Specifies the list of content and their visibility. The order of the elements influences the display.
  • visibleContent (ReadonlyArray) - Specifies the list of visible content ids. The order of the ids does not influence the display. If the contentDisplay property is set, this property is ignored.
  • custom (CustomPreferenceType) - Specifies the value for your custom preference.
remove-modal-rootPortalProps['removeContainer']

Use this property when getModalRoot is used to clean up the modal root element after a user closes the dialog. The function receives the return value of the most recent getModalRoot call as an argument.

sticky-columns-preferenceCollectionPreferencesProps.StickyColumnsPreference

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.

striped-rows-preferenceCollectionPreferencesProps.StripedRowsPreference

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.

titlestring default: 'Preferences'

Specifies the title of the preferences modal dialog. It is also used as an aria-label for the trigger button.

visible-content-preferenceCollectionPreferencesProps.VisibleContentPreference

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 ids in the preferences.visibleContent property.

Deprecated in table, replaced by contentDisplayPreference.

wrap-lines-preferenceCollectionPreferencesProps.WrapLinesPreference

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.

Slots

contentBefore

Content displayed before the preferences. Use it to display additional information relating to the preferences.

Events

cancelCustomEvent<void>

Called when the user cancels a preference change using the cancel button in the modal footer or by dismissing the modal.

confirmCustomEvent<CollectionPreferencesProps.Preferences<CustomPreferenceType>>

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) - (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) - (Optional) The list of selected content ids. 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.