MultiSelector

A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Multi Selector

A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.

Usage guidance

• Use for a moderate, finite set of options where multiple choices are needed.
• Enable search filtering when the list exceeds ~15 options.
• Use renderOption for custom option rows; the checkbox affordance remains owned by MultiSelector.
• Enable select-all when most users will want all or nearly all options selected.
• Use inside InputGroup only when the control needs a short prefix or suffix addon as part of one decorated input surface; prefer count or labels trigger display so the group stays single-line.
• Use variant="secondary" when a multi-selector sits beside secondary buttons or segmented controls, and variant="ghost" when it sits beside ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.
• Use presentation="adaptive" when the multi-selector should become a bottom sheet on compact touch screens.
• Avoid: Use for single-value selection; use Selector instead.
• Avoid: Show more than ~20 options without enabling search.
• Avoid: Wrap a disabled MultiSelector in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-multi-selector",
      "visualProps": [
        "variant",
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    },
    {
      "className": "astryx-multi-selector-empty-state"
    },
    {
      "className": "astryx-multi-selector-search"
    },
    {
      "className": "astryx-multi-selector-section-heading"
    },
    {
      "className": "astryx-multi-selector-indicator-icon",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-multi-selector-option",
      "visualProps": [
        "size"
      ],
      "states": [
        "select-all",
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-multi-selector-popup"
    }
  ]
}

Multi Selector

Multi-select dropdown with checkboxes for choosing multiple items.

Anatomy

• Field: Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
• Trigger: Painted control that displays the current selection or placeholder and opens the selection surface when editable.
• Icon-rendered start icon: Optional leading semantic icon or icon component rendered through Icon.
• Caller-rendered start content: Optional arbitrary React content rendered directly at the start of the trigger.
• Trigger clear button: Shared clear action that removes every selected value when hasClear is enabled.
• Status icon: Status glyph shown in place of the disclosure indicator for attached or tooltip status.
• Indicator icon: Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.
• Search row: Panel header with a borderless search input and optional clear action.
• Search icon: Leading magnifier rendered through Icon inside the search row.
• Search clear button: Shared clear action shown in the search row while a query is present.
• Option row: Selectable row for an option or the optional select-all choice.
• Option checkbox indicator: CheckboxInput indicator that presents each row’s selected, unselected, or indeterminate state.
• Option divider: Divider supplied in the public options data to separate adjacent option groups.
• Section heading: Visible heading for a labeled group of option rows.
• Empty state: Message shown when the shared panel content has no options or no search matches.
• Pointer popup: Anchored painted surface that hosts the shared panel content for popover presentation.
• Touch sheet heading: Heading above the shared panel content in bottom-sheet presentation.
• Touch sheet: BottomSheet surface that hosts the same panel content for bottom-sheet presentation.

Examples

• Multi Selector:
• MultiSelector — Bottom Sheet: Keeps a multi-selection list open in a bottom sheet while choices are toggled.
• MultiSelector — Column Visibility: Column visibility toggle with hidden label, search, select-all, and selection count.
• MultiSelector — Form Composition: Two multi-selectors in a form with required/optional states.
• MultiSelector — Ghost Toolbar: Borderless MultiSelector variant composed with ghost buttons in a toolbar.
• MultiSelector — Searchable: Multi-select with search filtering and select-all.
• MultiSelector — Sectioned Permissions: Multi-select with options grouped into labeled sections.