Skip to main content

Customization

SuperSelect is not tied to a UI framework. You can keep the default CSS, add classes and styles to specific parts, or replace rendered pieces with components from your own design system.

Every class generated by the default components uses the super-select namespace, such as super-select__form-select and super-select__list-group. The classNamePrefix customization controls that namespace and defaults to super-select.

There are a few levels of customization:

  1. Use the default structure and CSS.
  2. Pass classes, styles, or replacement components to specific mode slots.
  3. Change classNamePrefix and provide your own CSS for the generated class names.
  4. Map each mode to a UI library.

Changing classNamePrefix changes every generated class name, so the default stylesheet will no longer match those components. Use it when you are intentionally replacing the CSS namespace or mapping the generated classes to an existing class system.

Mental Model​

Customize the narrowest surface that solves the problem. For example, if only native mode needs a class from your app, customize native mode directly:

<SuperSelect
    customization={{
        selectInput: {
            className: "person-select__native",
        },
    }}
>
    <option value="apollo-creed">Apollo Creed</option>
</SuperSelect>

When integrating with a design system, customize each mode at the level where that system needs control:

<SuperSelect
    customization={{
        selectInput: { className: "form-select" },
        toggleButtonInput: {
            /* toggle button custom UI */
        },
        modalSelectButton: {
            /* modal trigger button / selected-content custom UI */
        },
        optionListInput: {
            /* option list custom UI */
        },
        modal: {
            /* modal custom UI */
        },
    }}
>
    <option value="apollo-creed">Apollo Creed</option>
</SuperSelect>

Async UI slots are configured at the top level as pendingIndicator, errorIndicator, emptyIndicator, and moreIndicator (including nested button/content settings). SuperSelect passes those into modal and option-list mode, and also uses them for its own initial async loading/error states. The top-level maxAdditionalPages setting controls how many pages can be loaded after the first page before the overflow indicator is shown.

Content And Text​

Use customization to provide the text your interface needs. See Accessibility for details about language independence and choosing content for assistive technology.

<SuperSelect
    customization={{
        modalSelectButton: {
            selectedContent: { placeholder: "Select an option" },
        },
        searchInput: {
            placeholder: "Search options",
            title: "Search options",
        },
        pendingIndicator: {
            title: "Loading options",
            content: "Loading options...",
        },
        errorIndicator: {
            defaultMessage: "Unable to load options right now.",
            retryButton: { title: "Retry loading options", content: "Try again" },
        },
        emptyIndicator: {
            content: "No options available.",
            retryButton: { title: "Try loading again", content: "Try again" },
        },
        maxAdditionalPages: 2,
        moreIndicator: {
            loadMoreButton: { title: "Load more options", content: "Load more options" },
            overflowIndicator: { title: "More options are available", content: "More options are available" },
        },
        modal: {
            okButton: { title: "Apply selection", content: "Apply" },
            closeButton: { title: "Close dialog", content: "Close" },
        },
    }}
/>

Display Mode

Text And Labels

Search, Empty, And Pagination Copy

No options available.

Always Empty

No options available.

Loading And Error Copy

No options available.
No options available.

For a wrapper built around a framework such as Bootstrap, Mantine, Material UI, Chakra UI, Ant Design, or shadcn/ui, see UI Component Libraries.