Skip to content
This repository was archived by the owner on Feb 10, 2025. It is now read-only.

Latest commit

 

History

History
203 lines (160 loc) · 6.83 KB

MultipleSelect.mdx

File metadata and controls

203 lines (160 loc) · 6.83 KB

import { Meta, Story, Controls, Canvas } from "@storybook/blocks";

import * as MultipleSelectStories from "./MultipleSelect.stories";

<Meta of={MultipleSelectStories} parameters={{ layout: "centered", docs: { story: { inline: true, iframeHeight: 200, }, }, }} />

MultipleSelect

A flexible multi-select component with grouped options, exclusive selections, and collapsible sections.

Props

Component Props

  • options: MultipleSelectGroup[] - Array of option groups
  • defaultValue: Record<string, string[]> - Initial selections per group
  • placeholder: string - Text shown when nothing selected if defaultValue then placeholder will be ignored
  • className: string - Popover container CSS classes
  • variants: object - Style customizations with the following options:
    • color: "default" | "grey" - Controls the overall color scheme
    • size: "default" | "sm" - Controls component sizing
    • rounded: "default" - Controls border radius styling
    • itemsPosition: "start" | "end" | "center" - Controls alignment of items in the list
    • headerPosition: "start" | "end" | "center" - Controls alignment of group headers
    • triggerTextColor: "default" | "red" | "green" - Controls the trigger text color
    • itemsColor: "default" | "light-grey" - Controls the color of items and their icons
  • onChange: (values: Record<string, string[]>) => void - Selection change handler

Group Properties (MultipleSelectGroup)

  • groupLabel?: string - Group name (omit for ungrouped items)
  • multiple?: boolean - Allow multiple selections (default: true)
  • collapsible?: boolean - Enable group toggle
  • items: MultipleSelectItem[] - Array of options

Item Properties (MultipleSelectItem)

  • value: string - Unique identifier
  • label: string - Display text
  • exclusive?: boolean - Clear other selections when chosen
  • exclusiveScope?: "group" | "global" - Clear scope for exclusive items
  • iconType?: IconType - Optional icon identifier check @/primitives/Icon story
  • icon?: React.ComponentType - Optional icon component used if no iconType is provided
  • itemClassName?: string - Item-specific CSS classes

Stories

Below are several usage examples showcasing common patterns and advanced features.

1. Basic

Description
A single ungrouped set of items (no group label) with simple placeholder text.

  • Options: 3 items, no exclusivity.
  • onChange logs the selection to console.

2. OrderByExample

Description Demonstrates exclusive items across two single-select groups (“Order by time” and “Order by name”). Each item has exclusive: true, exclusiveScope: 'global', ensuring that if you pick “Recent,” it clears any “A-Z” or “Z-A” selection.

  • defaultValue sets the initial selection to ["Recent"] in the “ORDER BY TIME” group.
  • variants example usage for adjusting text color, alignment, etc.

3. FilterExample

Description A filter scenario with an “All” exclusive item for resetting.

  • “All” is in an ungrouped set with exclusive: true, exclusiveScope: 'global'.
  • Two collapsible groups, “Network” and “Status,” each with multiple: true.
  • defaultValue starts with “All” selected in the ungrouped items.

4. MixedSelectionTypes

Description Shows a combination of:

  • A group with an exclusive item called “Reset All.”
  • Another group that’s multi-select with standard options.

This approach is useful when you have a special action (like “Reset” or “Clear All”) plus normal multi-select items.

5. WithVariants

Description
Showcases using all variant props (triggerTextColor, headerPosition, itemsPosition, etc.) or whatever your MultipleSelect has to customize.

  • You can set text color, alignment, plus a collapsible group.
  • Useful to see how to pass styling variants from tailwind-variants to the component.

Tips & Best Practices

  1. Use defaultValue for initial selections, or manage selections outside if you want it to be “controlled.”
  2. exclusive items are great for “select all,” “select none,” or “reset.”
  3. Collapsible groups let you nest large sets of items without overwhelming the user.

Conclusion

MultipleSelect is highly configurable for your needs: from a simple single group with no advanced logic, to multi-group filters, collapsible sections, exclusive “all” items, or complex order-by pickers.

Check out the source code & stories for additional usage details.