@redis-ui/components 42.8.0 → 43.2.1

package/skills/redis-ui-components/references/MultiSelect.md

@@ -0,0 +1,558 @@
+# MultiSelect
+
+A multi-select dropdown built on the Select primitives. Supports chip-based multi-value selection, searchable lists, virtualized rendering, select-all actions, and compound composition for custom trigger, content, and option layouts.
+
+## Import
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| options | `TOption[]` (extends `SelectOption`) | *required* | Array of selectable options. |
+| disabled | `boolean` | `false` | Disables the select. |
+| defaultOpen | `boolean` | - | Uncontrolled initial open state. |
+| open | `boolean` | - | Controlled open state. |
+| onOpenChange | `(open: boolean) => void` | - | Called when the dropdown open state changes. |
+| defaultValue | `TValue[]` | - | Uncontrolled initial selected values. |
+| value | `TValue[]` | - | Controlled selected values. |
+| onChange | `(value: TValue[]) => void` | - | Called when selected values change. |
+| customCompare | `SelectCompareHandler<TOption>` | - | Custom search comparison handler for filtering options. |
+| error | `string \| ReactElement` | - | Error message or element. Enables error state and tooltip content. |
+| valid | `boolean` | - | Enables valid status. |
+| placeholder | `ReactNode` | `'Select...'` | Placeholder text shown in the trigger when nothing is selected. |
+| valueRender | `SelectValueRender<TOption>` | - | Custom render function for trigger chips and dropdown option values. |
+| searchable | `boolean` | `false` | Enables the search input in the dropdown content. |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Dropdown placement relative to the trigger. |
+| maxVisibleItems | `number` | - | Maximum visible items before scrolling. |
+| virtualized | `boolean` | `false` | Enables virtualized rendering for long lists. |
+| contentWidth | `string` | - | Custom width for the dropdown content. |
+| allowSelectAll | `boolean` | `false` | Adds the select/unselect-all footer action. |
+| allowReset | `boolean` | `true` | Shows the trigger reset button. |
+| loading | `boolean` | `false` | Shows the loading indicator in the trigger. |
+| id | `string` | - | Custom trigger id for label and accessibility wiring. |
+| className | `string` | - | Class name passed through to the trigger wrapper. |
+
+The component also extends Radix UI `SelectTriggerProps` through `RestSelectTriggerComposeProps` (excluding `children`, `placeholder`, `asChild`, and `onChange`).
+
+### SelectOption Type
+
+| Field | Type | Description |
+|-------|------|-------------|
+| value | `string` | *required* - Unique option value. |
+| label | `string` | Optional display label. |
+| icon | `IconType \| ComponentType` | Optional icon component. |
+| disabled | `boolean` | Whether the option is disabled. |
+| hidden | `boolean` | Whether the option is hidden. |
+
+## Sub-components
+
+- `MultiSelect.Compose` - Context provider that wires up selection state, validation state, and the trigger/content pair. Use this when building custom layouts or when you need `allowResetDisabledItems`.
+- `MultiSelect.Trigger` - Default trigger that renders selected values as chips, plus reset, status, loading, and arrow indicators.
+- `MultiSelect.Trigger.Compose` - Composable trigger wrapper for custom trigger UI. Use `customContainer` when you need to replace the default combobox-style button.
+- `MultiSelect.Trigger.MultiValue` - Renders selected values as chips and the placeholder when nothing is selected. Accepts `allowRemove` to hide chip remove controls.
+- `MultiSelect.Trigger.ResetButton` - Clears the current selection.
+- `MultiSelect.Trigger.StatusIndicator` - Shows the validation state indicator.
+- `MultiSelect.Trigger.LoadingIndicator` - Shows the loading indicator.
+- `MultiSelect.Trigger.Arrow` - Dropdown arrow indicator.
+- `MultiSelect.Trigger.ErrorIcon` - Deprecated alias for `MultiSelect.Trigger.StatusIndicator`.
+- `MultiSelect.Content` - Default dropdown content with optional search, option list, custom `optionValueRender` / `optionComponent`, and select-all footer.
+- `MultiSelect.Content.Compose` - Composable content wrapper for custom dropdown layouts and static elements.
+- `MultiSelect.Content.Search` - Search input for filtering options.
+- `MultiSelect.Content.OptionList` - Renders the list of options.
+- `MultiSelect.Content.Footer` - Footer container used for select-all and custom footer content.
+- `MultiSelect.Content.SelectAll` - Toggle button that selects or unselects all options. Accepts `selectAllTitle` and `unselectAllTitle`.
+- `MultiSelect.Option` - Default multi-select option row.
+- `MultiSelect.Option.Compose` - Composable option wrapper for custom option rendering. This is the required root for custom option components.
+- `MultiSelect.Option.Content` - Content area inside an option row.
+- `MultiSelect.Option.Indicator` - Selection indicator rendered for each option.
+
+## Hooks
+
+- `useMultiSelectContext` - Reads multi-select state inside custom trigger, content, or option components. The context exposes `getSelectAllApi(inSearchResults?)` for select/unselect-all flows, and the returned API should be memoized before reuse. `selectAll()` is deprecated.
+
+## Examples
+
+### MultiSelect
+
+#### Playground
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect
+  options={options}
+  searchable
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+#### WithLabel
+
+> Component doesn't have internal label or any other external decoration elements.
+> For these purposes, use `FormField`.
+> If a custom id is specified, `FormField` inherits it; otherwise the label is auto-connected to the select with a generated id.
+> Custom ids must start with a letter to work correctly.
+
+```tsx
+import { FormField, MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<FormField label="FormField Label with custom id" additionalText="Additional text">
+  <MultiSelect
+    options={options}
+    placeholder="MultiSelect placeholder"
+    id="custom-id"
+    onChange={(value) => console.log(value)}
+    onOpenChange={(open) => console.log(open)}
+  />
+</FormField>
+```
+
+#### Status
+
+> Adding `valid` enables valid status.
+> Adding text to `error` enables error state and shows the tooltip on hover.
+> Error status overrides valid status.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<>
+  Valid status
+  <MultiSelect options={options} valid onChange={(value) => console.log(value)} onOpenChange={(open) => console.log(open)} />
+  Error status
+  <MultiSelect options={options} error="Error message" onChange={(value) => console.log(value)} onOpenChange={(open) => console.log(open)} />
+</>
+```
+
+#### ResetButton
+
+> The reset button appears only when something is selected.
+> Set `allowReset` to `false` to hide it.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect
+  options={options}
+  defaultValue={['orange']}
+  allowReset={false}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+#### Loading
+
+> Adding `loading` enables the loading indicator.
+> It can be used together with other indicators and states.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<>
+  Loading indicator
+  <MultiSelect options={options} loading onChange={(value) => console.log(value)} onOpenChange={(open) => console.log(open)} />
+  With other elements
+  <MultiSelect
+    options={options}
+    defaultValue={['banana']}
+    valid
+    allowReset
+    loading
+    onChange={(value) => console.log(value)}
+    onOpenChange={(open) => console.log(open)}
+  />
+</>
+```
+
+#### Disabled
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<>
+  Default
+  <MultiSelect options={options} disabled onChange={() => {}} onOpenChange={() => {}} />
+  With selected items
+  <MultiSelect options={options} disabled value={['orange']} onChange={() => {}} onOpenChange={() => {}} />
+  With error message
+  <MultiSelect
+    options={options}
+    disabled
+    value={['banana']}
+    error="Error message"
+    loading
+    onChange={() => {}}
+    onOpenChange={() => {}}
+  />
+</>
+```
+
+#### ValueRender
+
+> `valueRender` customizes both trigger chips and dropdown option values.
+> The handler receives the current `option`, `isSelected`, and `isOptionValue` flags.
+> Returning `undefined` or `null` falls back to the default rendering.
+> When `isOptionValue` is falsy, plain text is extracted from the rendered result for the trigger chip.
+
+```tsx
+import { MultiSelect, SelectValueRender } from '@redislabsdev/redis-ui-components';
+
+const customValueRender: SelectValueRender = ({ option, isSelected, isOptionValue }) => {
+  const color = !isOptionValue ? 'green' : (isSelected && 'blueviolet') || 'orange';
+  const stateLabel = isOptionValue ? `${isSelected ? 'Selected Option' : 'Option'}` : 'Value';
+
+  return (
+    <div>
+      <span style={{ fontSize: '0.7em', color }}>{stateLabel}: </span>
+      {option.label}
+    </div>
+  );
+};
+
+<MultiSelect
+  options={options}
+  defaultValue={['orange']}
+  valueRender={customValueRender}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+#### SelectAll
+
+> `allowSelectAll` adds a footer action to select or unselect all options.
+> When search is active, only search results are affected.
+> Disabled options are ignored by default.
+> Use `Ctrl+A` or `Cmd+A` while focus is on the list to toggle select-all.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect
+  options={usStates}
+  defaultValue={['Arizona', 'California']}
+  searchable
+  allowSelectAll
+  maxVisibleItems={6}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+#### CustomSearch
+
+> `customCompare` replaces the default label search.
+> The handler receives an option and a lowercase search string.
+> Include the label in your custom comparison if you still want label matches.
+
+```tsx
+import {
+  MultiSelect,
+  SelectCompareHandler,
+  SelectOption,
+  SelectValueRender
+} from '@redislabsdev/redis-ui-components';
+
+const customCompare: SelectCompareHandler<SelectOption> = (option, searchValue) => {
+  const fieldsForSearch = [option.label, option.state as string];
+  return fieldsForSearch.some((field) => field?.toLowerCase().includes(searchValue));
+};
+
+const valueRender: SelectValueRender = ({ option }) => {
+  return (
+    <>
+      <span>{option.label}</span>
+      &nbsp;
+      <span style={{ fontSize: '0.8em' }}>{`(${option.state})`}</span>
+    </>
+  );
+};
+
+<MultiSelect
+  options={usStates}
+  searchable
+  customCompare={customCompare}
+  valueRender={valueRender}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+#### VirtualList
+
+> List of options can be virtualized by adding `virtualized`.
+> It helps with long lists without performance drops.
+
+```tsx
+import { FormField, MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<FormField label="Countries">
+  <MultiSelect
+    virtualized
+    searchable
+    options={countryOptions}
+    allowReset
+    defaultValue={['ua', 'us']}
+    maxVisibleItems={6}
+    onChange={(value) => console.log(value)}
+    onOpenChange={(open) => console.log(open)}
+  />
+</FormField>
+```
+
+### MultiSelect.Trigger
+
+#### Playground
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose options={options} onChange={(value) => console.log(value)} onOpenChange={(open) => console.log(open)}>
+  <MultiSelect.Trigger placeholder="MultiSelect fruit..." allowReset={false} />
+  <MultiSelect.Content />
+</MultiSelect.Compose>
+```
+
+#### ValueRender
+
+> Trigger value rendering can be customized by specifying `valueRender` on `MultiSelect.Trigger`.
+> The handler receives the current `option`.
+> When `isOptionValue` is falsy, plain text is extracted for the trigger chip.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+const valueRender = ({ option }) => {
+  return (
+    <div>
+      <span style={{ fontSize: '0.7em', color: 'green' }}> Option: </span> {option.label}
+    </div>
+  );
+};
+
+<MultiSelect.Compose
+  options={options}
+  defaultValue={['orange']}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger valueRender={valueRender} />
+  <MultiSelect.Content />
+</MultiSelect.Compose>
+```
+
+#### CustomContainer
+
+> `customContainer` replaces the default combobox-style button container.
+> Wrap the custom container in a `span` or `div` if you need to avoid attribute conflicts.
+
+```tsx
+import { useState } from 'react';
+import { MultiSelect, ToggleButton, useSelectContext } from '@redislabsdev/redis-ui-components';
+
+function Render() {
+  const CustomTriggerValue = () => {
+    const { hasSelection, isOptionSelected, options } = useSelectContext();
+
+    if (!hasSelection) {
+      return <>No selection</>;
+    }
+
+    return <>Selected {options.filter(isOptionSelected).length} item(s)</>;
+  };
+
+  const [open, setOpen] = useState(false);
+
+  return (
+    <MultiSelect.Compose
+      options={options}
+      defaultValue={['orange']}
+      open={open}
+      onOpenChange={setOpen}
+      onChange={(value) => console.log(value)}
+    >
+      <MultiSelect.Trigger.Compose customContainer>
+        <span>
+          <ToggleButton pressed={open}>
+            <CustomTriggerValue />
+            <MultiSelect.Trigger.Arrow />
+          </ToggleButton>
+        </span>
+      </MultiSelect.Trigger.Compose>
+      <MultiSelect.Content />
+    </MultiSelect.Compose>
+  );
+}
+```
+
+#### TriggerComposition
+
+> Default composition example includes all parts of `MultiSelect.Trigger`.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose
+  options={options}
+  defaultValue={['orange']}
+  error="error message"
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger.Compose>
+    <MultiSelect.Trigger.MultiValue placeholder="Placeholder" />
+    <MultiSelect.Trigger.ResetButton />
+    <MultiSelect.Trigger.StatusIndicator />
+    <MultiSelect.Trigger.LoadingIndicator loading />
+    <MultiSelect.Trigger.Arrow />
+  </MultiSelect.Trigger.Compose>
+
+  <MultiSelect.Content />
+</MultiSelect.Compose>
+```
+
+### MultiSelect.Content
+
+#### Playground
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose options={options} onChange={(value) => console.log(value)} onOpenChange={(open) => console.log(open)}>
+  <MultiSelect.Trigger />
+  <MultiSelect.Content />
+</MultiSelect.Compose>
+```
+
+#### OptionValueRender
+
+> `optionValueRender` customizes option values separately from trigger values.
+> The handler receives the current `option` and `isSelected` flag.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose
+  options={options}
+  defaultValue={['orange']}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger />
+  <MultiSelect.Content
+    optionValueRender={({ option, isSelected }) => {
+      return (
+        <div>
+          <span
+            style={{
+              fontSize: '0.7em',
+              color: (isSelected && 'blueviolet') || 'orange'
+            }}
+          >
+            {isSelected ? 'Selected Option' : 'Option'}:
+          </span>{' '}
+          {option.label}
+        </div>
+      );
+    }}
+  />
+</MultiSelect.Compose>
+```
+
+#### OptionComponent
+
+> `optionComponent` renders the entire option, including the multi-selection indicator.
+> If it is not specified, `MultiSelect` renders options using the default `MultiSelect.Option`.
+> A custom option component can still be used together with `optionValueRender`.
+> The custom option component must use `MultiSelect.Option.Compose` as the root element.
+
+```tsx
+import { MultiSelect, SelectOptionComponent } from '@redislabsdev/redis-ui-components';
+
+const CustomOption: SelectOptionComponent = ({ option, content, ...restProps }) => (
+  <MultiSelect.Option.Compose option={option} {...restProps}>
+    <MultiSelect.Option.Content>{content}</MultiSelect.Option.Content>
+    <MultiSelect.Option.Indicator option={option} />
+  </MultiSelect.Option.Compose>
+);
+
+<MultiSelect.Compose
+  options={options}
+  defaultValue={['orange']}
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger />
+  <MultiSelect.Content optionComponent={CustomOption} />
+</MultiSelect.Compose>
+```
+
+#### ContentComposition
+
+> This example includes all parts of `MultiSelect.Content` and shows how to place static elements inside the composed content.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose
+  options={options}
+  allowResetDisabledItems
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger />
+  <MultiSelect.Content.Compose>
+    <div style={{ textAlign: 'center' }}>Top static element</div>
+    <MultiSelect.Content.Search />
+    <div style={{ textAlign: 'center' }}>Middle static element</div>
+    <MultiSelect.Content.OptionList style={{ maxHeight: 100 }} />
+    <div style={{ textAlign: 'center' }}>Bottom static element</div>
+    <MultiSelect.Content.Footer>
+      <div style={{ textAlign: 'center' }}>Custom element in Footer</div>
+      <MultiSelect.Content.SelectAll selectAllTitle="Select all fruits" unselectAllTitle="Select none" />
+    </MultiSelect.Content.Footer>
+  </MultiSelect.Content.Compose>
+</MultiSelect.Compose>
+```
+
+#### ContentListComposition
+
+> Adding an extra list container lets static elements scroll with the options.
+
+```tsx
+import { MultiSelect } from '@redislabsdev/redis-ui-components';
+
+<MultiSelect.Compose
+  options={options}
+  allowResetDisabledItems
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+>
+  <MultiSelect.Trigger />
+  <MultiSelect.Content.Compose>
+    <MultiSelect.Content.Search />
+    <div style={{ overflowY: 'auto', maxHeight: 200 }}>
+      <div style={{ textAlign: 'center' }}>Top scrollable element</div>
+      <MultiSelect.Content.OptionList />
+      <div style={{ textAlign: 'center' }}>Bottom scrollable element</div>
+    </div>
+  </MultiSelect.Content.Compose>
+</MultiSelect.Compose>
+```
+
+## Notes
+
+- `FormField` is the recommended way to add an external label or additional text.
+- `error` overrides `valid`, and the error indicator tooltip shows the error text.
+- `valueRender` customizes both trigger chips and dropdown option values; return `undefined` or `null` to fall back to the default rendering.
+- Use `MultiSelect.Content` or `MultiSelect.Compose` directly when you need `optionValueRender` or `optionComponent`; the top-level wrapper only exposes `valueRender`.
+- `allowSelectAll` affects only the current search results when search is active.
+- `MultiSelect.Trigger.ErrorIcon` is deprecated; use `StatusIndicator`.
+- `allowResetDisabledItems` is available on `MultiSelect.Compose`, not on the top-level `MultiSelect` wrapper.
+- `useMultiSelectContext` is exported for custom trigger and option components.