Multiple Selector

https://shadcnui-expansions.typeart.cc/docs/multiple-selector
Admin
A fast, composable, and fully-featured multiple selector component for React, built as an expansion...
Tokens:24,084
Snippets:70
Trust Score:5.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Radix UI Progress Package

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/progress-with-value

Installs the `@radix-ui/react-progress` package, a foundational dependency for the `ProgressWithValue` component, using npm.

```bash
npm i @radix-ui/react-progress
```

--------------------------------

### Install shadcn/ui command and badge components

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/multiple-selector

Installs the necessary 'command' and 'badge' components from shadcn/ui, which are prerequisites for the Multiple Selector component. This step ensures the foundational UI elements are available.

```shell
npx shadcn@latest add command badge
```

--------------------------------

### Install shadcn/ui dependencies for Datetime Picker

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/datetime-picker

This command installs the necessary shadcn/ui components (calendar, select, input, popover) required for the Datetime Picker to function.

```Shell
npx shadcn@latest add calendar select input popover
```

--------------------------------

### Install Shadcn UI Label and Input Components

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/floating-label-input

This command installs the `label` and `input` components from Shadcn UI, which are essential dependencies for building the Floating Label Input. It uses `npx` to execute the latest Shadcn UI CLI tool.

```bash
npx shadcn@latest add label input
```

--------------------------------

### Install Loading Button Dependencies

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/loading-button

Installs the necessary npm packages, `class-variance-authority` and `@radix-ui/react-slot`, which are required dependencies for the `LoadingButton` component to function correctly.

```bash
npm i class-variance-authority @radix-ui/react-slot
```

--------------------------------

### Install Shadcn UI Button Component

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/magic-back-button

This command installs the `button` component from shadcn/ui using their CLI tool. It's a prerequisite for the Magic Back Button component, providing the base UI for the smart back button.

```Shell
npx shadcn@latest add button
```

--------------------------------

### Install React Page Tracker Package

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/magic-back-button

This command installs the `react-page-tracker` npm package. This package is a crucial dependency for the `MagicBackButton` component, enabling it to track user visits and determine if they are first-time visitors.

```Shell
npm i react-page-tracker
```

--------------------------------

### Install React Markdown Package

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/typewriter

Installs the `react-markdown` package, which is a required dependency for the Typewriter component to render Markdown content.

```bash
npm install react-markdown
```

--------------------------------

### Install Core Dependencies for Heading With Anchor

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/heading-with-anchor

This command installs the foundational packages required for the 'Heading With Anchor' component and other `shadcn/ui` expansions. It includes `@radix-ui/react-slot` for flexible component composition and `class-variance-authority` for managing Tailwind CSS class variations.

```bash
npm i @radix-ui/react-slot class-variance-authority
```

--------------------------------

### Install Radix UI Slider Package

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/dual-range-slider

This command installs the `@radix-ui/react-slider` package, which is a foundational dependency required for the Dual Range Slider component to function correctly.

```npm
npm i @radix-ui/react-slider
```

--------------------------------

### Install Blockquote React Component

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/blockquote

Provides the React and TypeScript code for the Blockquote and BlockquoteAuthor components, including their styling and structure, ready for integration into a shadcn/ui project. It uses `cn` for utility class merging.

```TypeScript
import React from 'react';
import { cn } from '@/lib/utils';

type BlockquoteProps = {
  children?: React.ReactNode;
  className?: string;
};

const Blockquote = ({ children, className }: BlockquoteProps) => {
  return (
    <div
      className={cn(
        "relative rounded-lg border-l-8 border-l-gray-700 bg-gray-100 py-5 pl-16 pr-5 font-sans text-lg italic leading-relaxed text-gray-500 before:absolute before:left-3 before:top-3 before:font-serif before:text-6xl before:text-gray-700 before:content-['“']",
        className,
      )}
    >
      {children}
    </div>
  );
};

const BlockquoteAuthor = ({ children, className }: BlockquoteProps) => {
  return (
    <p className={cn('mt-5 pr-4 text-right font-bold not-italic text-gray-700', className)}>
      {children}
    </p>
  );
};

export { Blockquote, BlockquoteAuthor };

```

--------------------------------

### Install React Spinner Component

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/spinner

This code snippet provides the core React component for a simple spinner. It includes styling variants utilizing `class-variance-authority` for flexible styling and `lucide-react` for the loader icon, enabling a customizable loading indicator.

```tsx
import React from 'react';
import { cn } from '@/lib/utils';
import { VariantProps, cva } from 'class-variance-authority';
import { Loader2 } from 'lucide-react';

const spinnerVariants = cva('flex-col items-center justify-center', {
  variants: {
    show: {
      true: 'flex',
      false: 'hidden',
    },
  },
  defaultVariants: {
    show: true,
  },
});

const loaderVariants = cva('animate-spin text-primary', {
  variants: {
    size: {
      small: 'size-6',
      medium: 'size-8',
      large: 'size-12',
    },
  },
  defaultVariants: {
    size: 'medium',
  },
});

interface SpinnerContentProps
  extends VariantProps<typeof spinnerVariants>,
    VariantProps<typeof loaderVariants> {
  className?: string;
  children?: React.ReactNode;
}

export function Spinner({ size, show, children, className }: SpinnerContentProps) {
  return (
    <span className={spinnerVariants({ show })}>
      <Loader2 className={cn(loaderVariants({ size }), className)} />
      {children}
    </span>
  );
}
```

--------------------------------

### React/TypeScript Custom Heading Component Implementation

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/heading-with-anchor

This code defines the `Anchor` and `BaseHeading` React components, along with helper types and `cva` variants for styling. The `BaseHeading` component dynamically renders as an HTML heading element (h1-h6, p) or a Radix UI `Slot`, incorporating an optional anchor link. The anchor link allows users to copy the URL with the heading's ID to the clipboard. The component supports various configurations for anchor visibility and alignment. Remember to adjust `scroll-m-20` based on your header height and change `Link` to `a` if not using Next.js. Also, ensure import paths match your project setup.

```typescript
'use client';
import React from 'react';
import { cn } from '@/lib/utils';
import { Slot } from '@radix-ui/react-slot';
import { cva, type VariantProps } from 'class-variance-authority';
import { LinkIcon } from 'lucide-react';
import Link from 'next/link';

type AnchorProps = {
  anchor?: string;
  anchorVisibility?: 'hover' | 'always' | 'never';
  disableCopyToClipboard?: boolean;
};

const Anchor = ({
  anchor,
  disableCopyToClipboard = false,
  anchorVisibility = 'always',
}: AnchorProps) => {
  function copyToClipboard() {
    if (disableCopyToClipboard) return;
    const currentUrl = window.location.href.replace(/#.*$/, '');
    const urlWithId = `${currentUrl}#${anchor}`;

    void navigator.clipboard.writeText(urlWithId);
  }

  return (
    <div
      className={cn(
        'ms-2 pt-1',
        anchorVisibility === 'always' && 'visible',
        anchorVisibility === 'never' && 'hidden',
        anchorVisibility === 'hover' && 'invisible group-hover:visible',
      )}
    >
      {/* modify `Link` to `a` if you are not using Next.js */}
      <Link href={`#${anchor}`} onClick={copyToClipboard}>
        <LinkIcon className="text-gray-600 hover:text-gray-400" />
      </Link>
    </div>
  );
};

const headingVariants = cva('font-bold text-primary', {
  variants: {
    variant: {
      h1: 'leading-14 text-4xl lg:text-5xl',
      h2: 'leading-14 text-3xl lg:text-4xl',
      h3: 'leading-10 text-2xl lg:text-3xl',
      h4: 'leading-8 text-xl lg:text-2xl',
      h5: 'leading-8 text-lg lg:text-xl',
      h6: 'leading-7 text-sm lg:text-base',
      p: 'leading-5 text-lg lg:text-xl font-normal',
    },
  },
  defaultVariants: {
    variant: 'h6',
  },
});

type BaseHeadingProps = {
  children?: React.ReactNode;
  variant?: string;
  className?: string;
  asChild?: boolean;
  anchor?: string;
  anchorAlignment?: 'close' | 'spaced';
  anchorVisibility?: 'hover' | 'always' | 'never';
  disableCopyToClipboard?: boolean;
} & React.HTMLAttributes<HTMLHeadingElement> &
  VariantProps<typeof headingVariants>;

const BaseHeading = ({
  children,
  className,
  variant = 'h6',
  asChild = false,
  anchor,
  anchorAlignment = 'spaced',
  anchorVisibility = 'always',
  disableCopyToClipboard = false,
  , ...props
}: BaseHeadingProps) => {
  const Comp = asChild ? Slot : variant;
  return (
    <>
      <Comp
        id={anchor}
        {...props}
        className={cn(
          anchor && 'flex scroll-m-20 items-center gap-1', // modify `scroll-m-20` according to your header height.
          anchorAlignment === 'spaced' && 'justify-between',
          anchorVisibility === 'hover' && 'group',
          headingVariants({ variant, className }),
        )}
      >
        {children}
        {anchor && (
          <Anchor
            anchor={anchor}
            anchorVisibility={anchorVisibility}
            disableCopyToClipboard={disableCopyToClipboard}
          />
        )}
      </Comp>
    </>
  );
};

type TypographyProps = Omit<BaseHeadingProps, 'variant' | 'asChild'>;

const H1 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h1" />;
};

const H2 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h2" />;
};

const H3 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h3" />;
};

const H4 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h4" />;
};

const H5 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h5" />;
};

const H6 = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="h6" />;
};

const P = (props: TypographyProps) => {
  return <BaseHeading {...props} variant="p" />;
};

export { H1, H2, H3, H4, H5, H6, P };

```

--------------------------------

### LoadingButton Component API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/loading-button

Detailed API documentation for the `LoadingButton` component, outlining its `ButtonProps` interface, available variants, sizes, and the `loading` and `asChild` properties.

```APIDOC
LoadingButton Component API:

  ButtonProps Interface:
    Extends:
      - React.ButtonHTMLAttributes<HTMLButtonElement>
      - VariantProps<typeof buttonVariants>
    Properties:
      - asChild: boolean (Optional)
          Description: If true, the component will be rendered as a child of the `Slot` component, preserving its styling and behavior.
      - loading: boolean (Optional, default: false)
          Description: If true, a loading spinner is displayed within the button, and the button is automatically disabled.

  LoadingButton Component:
    Type: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>
    Usage: <LoadingButton {...props}>{children}</LoadingButton>
    Props:
      - className: string (Optional)
          Description: Additional CSS classes to apply to the button.
      - loading: boolean (Optional, default: false)
          Description: Controls the display of the loading spinner and button disabled state.
      - children: React.ReactNode
          Description: The content to be rendered inside the button.
      - disabled: boolean (Optional)
          Description: Standard HTML disabled attribute.
      - variant: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link' (Optional, default: 'default')
          Description: Defines the visual style of the button.
      - size: 'default' | 'sm' | 'lg' | 'icon' (Optional, default: 'default')
          Description: Defines the size of the button.
      - asChild: boolean (Optional, default: false)
          Description: If true, renders the component as a child of another component using Radix UI's Slot.
    Returns: JSX.Element
    Exports:
      - LoadingButton: The main React functional component.
      - buttonVariants: A utility function (from `class-variance-authority`) to generate button CSS classes based on `variant` and `size` props.
```

--------------------------------

### ProgressWithValue Component API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/progress-with-value

Documents the `ProgressWithValueProps` interface, detailing the configurable properties for the `ProgressWithValue` React component, including options for value positioning and custom label rendering.

```APIDOC
interface ProgressWithValueProps:
  extends: React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>
  properties:
    position:
      type: 'start' | 'start-outside' | 'follow' | 'end' | 'end-outside'
      description: Controls the position of the progress value label relative to the bar.
      optional: true
      values:
        - 'start': Inside the bar, aligned to the start.
        - 'start-outside': Outside the bar, aligned to the start.
        - 'follow': Inside the indicator, follows the progress.
        - 'end': Inside the bar, aligned to the end.
        - 'end-outside': Outside the bar, aligned to the end.
    label:
      type: (value?: number | null) => React.ReactNode
      description: A function to render a custom label for the progress value. If not provided, defaults to displaying the value as a percentage.
      optional: true
    valueClassName:
      type: string
      description: Additional CSS class names to apply to the progress value label element.
      optional: true
```

--------------------------------

### Implement a Responsive Modal Component with Radix UI and Tailwind CSS

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/responsive-modal

This snippet defines a `ResponsiveModal` component and its sub-components, including `ResponsiveModalOverlay`, `ResponsiveModalContent`, `ResponsiveModalHeader`, `ResponsiveModalFooter`, `ResponsiveModalTitle`, and `ResponsiveModalDescription`. It leverages Radix UI for accessibility and state management, `class-variance-authority` for dynamic styling based on `side` variants (top, bottom, left, right), and Tailwind CSS for utility-first styling. The component provides smooth animations for opening and closing, and handles different screen sizes by adjusting modal behavior.

```tsx
'use client';

import * as React from 'react';
import * as DialogPrimitive from '@radix-ui/react-dialog';
import { cva, type VariantProps } from 'class-variance-authority';
import { X } from 'lucide-react';

import { cn } from '@/lib/utils';

const ResponsiveModal = DialogPrimitive.Root;

const ResponsiveModalTrigger = DialogPrimitive.Trigger;

const ResponsiveModalClose = DialogPrimitive.Close;

const ResponsiveModalPortal = DialogPrimitive.Portal;

const ResponsiveModalOverlay = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Overlay>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Overlay
    className={cn(
      'fixed inset-0 z-50 bg-background/80 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
      className,
    )}
    {...props}
    ref={ref}
  />
));
ResponsiveModalOverlay.displayName = DialogPrimitive.Overlay.displayName;

const ResponsiveModalVariants = cva(
  cn(
    'fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500 overflow-y-auto',
    'lg:left-[50%] lg:top-[50%] lg:w-full lg:max-w-lg lg:translate-x-[-50%] lg:translate-y-[-50%] lg:border lg:duration-200 lg:data-[state=open]:animate-in lg:data-[state=closed]:animate-out lg:data-[state=closed]:fade-out-0 lg:data-[state=open]:fade-in-0 lg:data-[state=closed]:zoom-out-95 lg:data-[state=open]:zoom-in-95 lg:data-[state=closed]:slide-out-to-left-1/2 lg:data-[state=closed]:slide-out-to-top-[48%] lg:data-[state=open]:slide-in-from-left-1/2 lg:data-[state=open]:slide-in-from-top-[48%] lg:rounded-xl',
  ),
  {
    variants: {
      side: {
        top: 'inset-x-0 top-0 border-b rounded-b-xl max-h-[80dvh] lg:h-fit data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top',
        bottom:
          'inset-x-0 bottom-0 border-t lg:h-fit max-h-[80dvh] rounded-t-xl data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom',
        left: 'inset-y-0 left-0 h-full lg:h-fit w-3/4 border-r rounded-r-xl data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm',
        right:
          'inset-y-0 right-0 h-full lg:h-fit w-3/4 border-l rounded-l-xl data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm',
      },
    },
    defaultVariants: {
      side: 'bottom',
    },
  },
);

interface ResponsiveModalContentProps
  extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>,
    VariantProps<typeof ResponsiveModalVariants> {}

const ResponsiveModalContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  ResponsiveModalContentProps
>(({ side = 'bottom', className, children, ...props }, ref) => (
  <ResponsiveModalPortal>
    <ResponsiveModalOverlay />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(ResponsiveModalVariants({ side }), className)}
      {...props}
    >
      {children}
      <ResponsiveModalClose className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary">
        <X className="h-4 w-4" />
        <span className="sr-only">Close</span>
      </ResponsiveModalClose>
    </DialogPrimitive.Content>
  </ResponsiveModalPortal>
));
ResponsiveModalContent.displayName = DialogPrimitive.Content.displayName;

const ResponsiveModalHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
  <div className={cn('flex flex-col space-y-2 text-center sm:text-left', className)} {...props} />
);
ResponsiveModalHeader.displayName = 'ResponsiveModalHeader';

const ResponsiveModalFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
  <div
    className={cn('flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2', className)}
    {...props}
  />
);
ResponsiveModalFooter.displayName = 'ResponsiveModalFooter';

const ResponsiveModalTitle = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Title>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Title
    ref={ref}
    className={cn('text-lg font-semibold text-foreground', className)}
    {...props}
  />
));
ResponsiveModalTitle.displayName = DialogPrimitive.Title.displayName;

const ResponsiveModalDescription = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Description>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Description
    ref={ref}

```

--------------------------------

### Component Properties Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/heading-with-anchor

Detailed list of properties, their data types, and default values for configuring the component's behavior and appearance.

```APIDOC
Properties:
  className:
    Type: string
    Default: ""
  anchor:
    Type: string
    Default: ""
  anchorAlignment:
    Type: 'close' | 'spaced'
    Default: 'spaced'
  anchorVisibility:
    Type: 'hover' | 'always' | 'never'
    Default: 'always'
  disableCopyToClipboard:
    Type: boolean
    Default: false
```

--------------------------------

### Define and Export Shadcn UI Responsive Modal Components

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/responsive-modal

This snippet illustrates the definition of a component (likely a description element within a modal) applying CSS classes using a utility function `cn` and spreading props. It also sets the `displayName` for debugging and exports a comprehensive set of responsive modal components for use throughout an application.

```TypeScript
className={cn('text-sm text-muted-foreground', className)}
    {...props}
  />
));
ResponsiveModalDescription.displayName = DialogPrimitive.Description.displayName;

export {
  ResponsiveModal,
  ResponsiveModalPortal,
  ResponsiveModalOverlay,
  ResponsiveModalTrigger,
  ResponsiveModalClose,
  ResponsiveModalContent,
  ResponsiveModalHeader,
  ResponsiveModalFooter,
  ResponsiveModalTitle,
  ResponsiveModalDescription,
};
```

--------------------------------

### MultipleSelector React Component API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/multiple-selector

Detailed API documentation for the `MultipleSelector` React component, outlining its props, the methods exposed via `useImperativeHandle`, and a summary of its internal state and key functions.

```APIDOC
MultipleSelector Component:
  Type: React.forwardRef<MultipleSelectorRef, MultipleSelectorProps>
  Description: A highly customizable multi-select input component built with React, supporting search, grouping, and dynamic options.

  Props (MultipleSelectorProps):
    value: Option[] (Optional) - The currently selected options. Used for controlled component behavior.
    onChange: (options: Option[]) => void (Optional) - Callback function invoked when the selected options change.
    placeholder: string (Optional) - Text displayed in the input field when no options are selected and the input is empty.
    defaultOptions: Option[] (Default: []) - Initial options displayed in the dropdown before any search is performed.
    options: Option[] (Optional) - Static options to display. This prop is ignored if `onSearch` is provided.
    delay: number (Optional, Default: 500) - The debounce delay in milliseconds applied to the search input.
    onSearch: (searchTerm: string) => Promise<Option[]> (Optional) - An asynchronous function to fetch options based on the search term. Used for server-side filtering.
    onSearchSync: (searchTerm: string) => Option[] (Optional) - A synchronous function to filter options based on the search term. Used for client-side filtering.
    loadingIndicator: React.ReactNode (Optional) - Custom React element to display when search results are being loaded.
    emptyIndicator: React.ReactNode (Optional) - Custom React element to display when no options are found or search yields no results.
    maxSelected: number (Default: Number.MAX_SAFE_INTEGER) - The maximum number of items that can be selected.
    onMaxSelected: () => void (Optional) - Callback function invoked when the `maxSelected` limit is reached.
    hidePlaceholderWhenSelected: boolean (Optional) - If true, the placeholder text will be hidden once any item is selected.
    disabled: boolean (Optional) - If true, the component will be disabled and non-interactive.
    groupBy: string (Optional) - The key in the Option object to group options by in the dropdown.
    className: string (Optional) - Additional CSS class names to apply to the root element of the component.
    badgeClassName: string (Optional) - Additional CSS class names to apply to the selected item badges.
    selectFirstItem: boolean (Default: true) - If true, the first item in the dropdown list will be automatically highlighted for selection.
    creatable: boolean (Optional) - If true, allows users to create new options from the input text if it doesn't match existing options.
    triggerSearchOnFocus: boolean (Optional) - If true, triggers a search operation when the input field gains focus.
    commandProps: object (Optional) - An object of props to be passed directly to the internal Command component (from shadcn/ui).
    inputProps: object (Optional) - An object of props to be passed directly to the internal HTML input element.
    hideClearAllButton: boolean (Optional) - If true, the button to clear all selected items will be hidden.

  Imperative Handle (MultipleSelectorRef):
    selectedValue: Option[] - A read-only array containing the currently selected options.
    input: HTMLInputElement - A direct reference to the underlying HTML input element.
    focus: () => void - A method to programmatically set focus on the input element.
    reset: () => void - A method to clear all currently selected options.

  Internal State & Hooks Summary:
    - `selected`: Manages the array of currently chosen options.
    - `options`: Manages the array of available options displayed in the dropdown, potentially grouped.
    - `inputValue`: Stores the current text content of the search input field.
    - `debouncedSearchTerm`: A debounced version of `inputValue`, used to trigger search queries after a delay.
    - `open`: Boolean state controlling the visibility of the dropdown menu.
    - `isLoading`: Boolean state indicating whether an asynchronous search operation is in progress.

  Key Internal Functions Summary:
    - `handleClickOutside`: An event handler responsible for closing the dropdown when a click occurs outside the component's boundaries.
    - `handleUnselect`: A callback function to remove a specific option from the `selected` array.
    - `handleKeyDown`: Manages keyboard interactions within the input, such as handling 'Backspace'/'Delete' to remove the last selected item and 'Escape' to blur the input.

  Lifecycle Effects (useEffect) Summary:
    - Manages the attachment and detachment of `mousedown` and `touchend` event listeners for `handleClickOutside` based on the `open` state.
    - Synchronizes the internal `selected` state with the external `value` prop, ensuring controlled component behavior.
    - Updates the internal `options` state when the `arrayOptions` prop changes, provided that an `onSearch` function is not being used.
    - Triggers synchronous search operations (`onSearchSync`) based on changes to `debouncedSearchTerm` or when `triggerSearchOnFocus` is active.
    - Initiates asynchronous search operations (`onSearch`) based on changes to `debouncedSearchTerm`.
```

--------------------------------

### LoadingButton React Component Source Code

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/loading-button

The complete TypeScript/React source code for the `LoadingButton` component. It leverages `class-variance-authority` for styling variants and Radix UI's `Slot` for flexible rendering, including a loading spinner when the `loading` prop is true.

```typescript
import * as React from 'react';
import { Slot, Slottable } from '@radix-ui/react-slot';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
import { Loader2 } from 'lucide-react';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline'
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10'
      }
    },
    defaultVariants: {
      variant: 'default',
      size: 'default'
    }
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
  loading?: boolean;
}

const LoadingButton = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    { className, loading = false, children, disabled, variant, size, asChild = false, ...props },
    ref,
  ) => {
    const Comp = asChild ? Slot : 'button';
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        disabled={loading || disabled}
        {...props}
      >
        {loading && <Loader2 className="mr-2 h-5 w-5 animate-spin" />}
        <Slottable>{children}</Slottable>
      </Comp>
    );
  },
);
LoadingButton.displayName = 'LoadingButton';

export { LoadingButton, buttonVariants };
```

--------------------------------

### Typewriter React Component Implementation

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/typewriter

The complete source code for the Typewriter React component. This component manages the typing animation, displays text incrementally, and optionally renders Markdown using `react-markdown`. It includes props for text, typing speed, completion callbacks, and custom class names.

```TypeScript
'use client';
import { cn } from '@/lib/utils';
import { useEffect, useRef, useState } from 'react';
import Markdown, { Components } from 'react-markdown';

type TypewriterProps = {
  text?: string;
  typeSpeed?: number;
  className?: string;
  onComplete?: () => void;
  renderMarkdown?: boolean;
  markdownComponents?: Components;
};

export const Typewriter = ({
  text = '',
  typeSpeed = 33,
  onComplete,
  className,
  renderMarkdown,
  markdownComponents,
}: TypewriterProps) => {
  const [displayedText, setDisplayedText] = useState('');
  const intervalRef = useRef<NodeJS.Timeout | null>(null);
  const onCompleteRef = useRef(onComplete); // Ref to store the latest onComplete

  // Keep onComplete callback reference up-to-date without causing effect re-runs
  useEffect(() => {
    onCompleteRef.current = onComplete;
  }, [onComplete]);
  useEffect(() => {
    /***
     * Each time htmlString changes,
     * only add new characters from the end of the currently displayed text.
     */
    const startTyping = () => {
      let currentIndex = displayedText.length;
      intervalRef.current = setInterval(() => {
        if (currentIndex < text.length) {
          // Only add new characters, do not reset old text
          setDisplayedText(text.slice(0, currentIndex + 1));
          currentIndex++;
        } else {
          if (intervalRef.current) {
            clearInterval(intervalRef.current);
          }
          onCompleteRef.current?.();
        }
      }, typeSpeed);
    };

    // If there is new text, start typing animation
    if (text.length > displayedText.length) {
      // Start typing immediately, no need to wait for delay
      startTyping();
    }
    // If targetText decreases or resets, consider handling it自行處理
    return () => {
      if (intervalRef.current) {
        clearInterval(intervalRef.current);
      }
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [text, typeSpeed]);

  if (renderMarkdown) {
    return (
      <div className={className}>
        <Markdown components={markdownComponents}>{displayedText}</Markdown>
      </div>
    );
  }

  return (
    <span
      className={cn('whitespace-pre-wrap leading-7', className)}
      dangerouslySetInnerHTML={{ __html: displayedText }}
    />
  );
};
```

--------------------------------

### Spinner Component Properties API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/spinner

This section details the available properties (props) for the `Spinner` React component. It specifies each property's type, default value, and a brief description, allowing developers to understand and customize the spinner's appearance and behavior.

```APIDOC
Component: Spinner
  Properties:
    className: string
      Description: Additional CSS classes to apply to the spinner container.
    size: 'small' | 'medium' | 'large'
      Default: medium
      Description: Controls the visual size of the spinner icon.
    show: boolean
      Default: true
      Description: Determines whether the spinner is visible or hidden.
    children: React.ReactNode
      Description: Content to display alongside the spinner, typically text or other React elements.
```

--------------------------------

### Component Properties API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/typewriter

Defines the configurable properties for a component, including their types, default values, and descriptions. These properties control the behavior and appearance of the component.

```APIDOC
Properties:
  text:
    Type: string
    Default: string
    Description: The content to be displayed.
  typeSpeed:
    Type: number
    Default: 33
    Description: The speed of typing animation in milliseconds per character.
  renderMarkdown:
    Type: boolean
    Default: null
    Description: Specifies if the text content should be rendered as Markdown.
  markdownComponents:
    Type: Components
    Default: null
    Description: Custom components to be used for Markdown rendering.
  onComplete:
    Type: () => void
    Default: null
    Description: A callback function executed when the typing animation completes.
  className:
    Type: string
    Default: null
    Description: CSS class name to apply to the component.
```

--------------------------------

### API Reference for Custom Heading Components

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/heading-with-anchor

This section details the properties and types used by the custom heading components (H1-H6, P) and their underlying `Anchor` component. It outlines the configurable options for anchor behavior, styling, and component rendering.

```APIDOC
AnchorProps:
  anchor?: string
    Description: The ID string to be used for the anchor link.
  anchorVisibility?: 'hover' | 'always' | 'never'
    Description: Controls when the anchor icon is visible.
  disableCopyToClipboard?: boolean
    Description: If true, disables the copy-to-clipboard functionality for the anchor URL.

BaseHeadingProps:
  children?: React.ReactNode
    Description: The content to be rendered inside the heading.
  variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p'
    Description: The semantic HTML heading level or 'p' for paragraph.
  className?: string
    Description: Additional CSS classes to apply to the heading.
  asChild?: boolean
    Description: If true, renders the component as a child of Radix UI's Slot component.
  anchor?: string
    Description: The ID string for the anchor link associated with this heading.
  anchorAlignment?: 'close' | 'spaced'
    Description: Controls the alignment of the anchor icon relative to the heading text.
  anchorVisibility?: 'hover' | 'always' | 'never'
    Description: Controls when the anchor icon is visible for this heading.
  disableCopyToClipboard?: boolean
    Description: If true, disables the copy-to-clipboard functionality for this heading's anchor URL.
  ...React.HTMLAttributes<HTMLHeadingElement>
    Description: Standard HTML heading element attributes.
  ...VariantProps<typeof headingVariants>
    Description: Props derived from the `cva` heading variants.

H1, H2, H3, H4, H5, H6, P Components:
  Description: Pre-configured components that render a BaseHeading with a specific 'variant' prop.
  Props: Inherit all props from `BaseHeadingProps` except 'variant' and 'asChild'.
```

--------------------------------

### Memoize Selectable Options

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/multiple-selector

This `useMemo` hook efficiently calculates the `selectables` options by removing already `selected` items from the main `options` list. It recomputes only when `options` or `selected` dependencies change, optimizing performance.

```typescript
    const selectables = React.useMemo<GroupOption>(
      () => removePickedOption(options, selected),
      [options, selected],
    );
```

--------------------------------

### Implement Magic Back Button Component (React/Next.js)

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/magic-back-button

This TypeScript React component, `MagicBackButton`, provides intelligent navigation. It uses `next/navigation` to control routing and `react-page-tracker` to determine if the user is a first-time visitor. If so, it redirects to a specified `backLink` (defaulting to '/'); otherwise, it uses `router.back()` to respect browser history. It's built on shadcn/ui's Button component.

```TypeScript
import * as React from 'react';
import { cn } from '@/lib/utils';
import { Button, ButtonProps } from '@/components/ui/button';
import { useRouter } from 'next/navigation';
import { usePageTrackerStore } from 'react-page-tracker';
import { ChevronLeft } from 'lucide-react';

export const MagicBackButton = React.forwardRef<
  HTMLButtonElement,
  ButtonProps & { backLink?: string }
>(({ className, onClick, children, backLink = '/', ...props }, ref) => {
  const router = useRouter();
  const isFirstPage = usePageTrackerStore((state) => state.isFirstPage);
  return (
    <Button
      className={cn('rounded-full', className)}
      variant="outline"
      size="icon"
      ref={ref}
      onClick={(e) => {
        if (isFirstPage) {
          router.push(backLink);
        } else {
          router.back();
        }
        onClick?.(e);
      }}
      {...props}
    >
      {children ?? <ChevronLeft />}
    </Button>
  );
});
MagicBackButton.displayName = 'MagicBackButton';
```

--------------------------------

### DateTimePicker Component Definition (Partial)

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/datetime-picker

A partial implementation of the `DateTimePicker` React component, demonstrating the use of `React.forwardRef` for ref forwarding, state management for month and display date, and core logic for handling date changes and formatting.

```TypeScript
const DateTimePicker = React.forwardRef<Partial<DateTimePickerRef>, DateTimePickerProps>(
  (
    {
      locale = enUS,
      defaultPopupValue = new Date(new Date().setHours(0, 0, 0, 0)),
      value,
      onChange,
      onMonthChange,
      hourCycle = 24,
      yearRange = 50,
      disabled = false,
      displayFormat,
      granularity = 'second',
      placeholder = 'Pick a date',
      className,
      ...props
    },
    ref,
  ) => {
    const [month, setMonth] = React.useState<Date>(value ?? defaultPopupValue);
    const buttonRef = useRef<HTMLButtonElement>(null);
    const [displayDate, setDisplayDate] = React.useState<Date | undefined>(value ?? undefined);
    onMonthChange ||= onChange;

    /**
     * Makes sure display date updates when value change on
     * parent component
     */
    React.useEffect(() => {
      setDisplayDate(value);
    }, [value]);

    /**
     * carry over the current time when a user clicks a new day
     * instead of resetting to 00:00
     */
    const handleMonthChange = (newDay: Date | undefined) => {
      if (!newDay) {
        return;
      }
      if (!defaultPopupValue) {
        newDay.setHours(month?.getHours() ?? 0, month?.getMinutes() ?? 0, month?.getSeconds() ?? 0);
        onMonthChange?.(newDay);
        setMonth(newDay);
        return;
      }
      const diff = newDay.getTime() - defaultPopupValue.getTime();
      const diffInDays = diff / (1000 * 60 * 60 * 24);
      const newDateFull = add(defaultPopupValue, { days: Math.ceil(diffInDays) });
      newDateFull.setHours(
        month?.getHours() ?? 0,
        month?.getMinutes() ?? 0,
        month?.getSeconds() ?? 0,
      );
      onMonthChange?.(newDateFull);
      setMonth(newDateFull);
    };

    const onSelect = (newDay?: Date) => {
      if (!newDay) {
        return;
      }
      onChange?.(newDay);
      setMonth(newDay);
      setDisplayDate(newDay);
    };

    useImperativeHandle(
      ref,
      () => ({
        ...buttonRef.current,
        value: displayDate,
      }),
      [displayDate],
    );

    const initHourFormat = {
      hour24:
        displayFormat?.hour24 ??
        `PPP HH:mm${!granularity || granularity === 'second' ? ':ss' : ''}`,
      hour12:
        displayFormat?.hour12 ??
        `PP hh:mm${!granularity || granularity === 'second' ? ':ss' : ''} b`,
    };

    let loc = enUS;
    const { options, localize, formatLong } = locale;
    if (options && localize && formatLong) {
      loc = {
        ...enUS,
        options,
        localize,
        formatLong,
      };
    }

    return (
      <Popover>
        <PopoverTrigger asChild disabled={disabled}>
          <Button
            variant="outline"
            className={cn(
              'w-full justify-start text-left font-normal',
              !displayDate && 'text-muted-foreground',
              className,
            )}
            ref={buttonRef}
          >
            <CalendarIcon className="mr-2 h-4 w-4" />
            {displayDate ? (
              format(
                displayDate,
                hourCycle === 24 ? initHourFormat.hour24 : initHourFormat.hour12,
                {
                  locale: loc,
                },
              )
            ) : (
              <span>{placeholder}</span>
            )}
          </Button>
        </PopoverTrigger>
        <PopoverContent className="w-auto p-0">
          <Calendar
            mode="single"
```

--------------------------------

### DateTimePicker Component Properties API Reference

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/datetime-picker

Documents the available properties for the DateTimePicker component, detailing their types, default values, and purpose. This includes properties for value binding, default display, change handling, time format, placeholder, disabled state, year range, display format, and granularity.

```APIDOC
Property: value
  Type: Date | undefined
  Default: 
  Description: The currently selected date value.

Property: defaultPopupValue
  Type: Date | undefined
  Default: 
  Description: The default date value to display when the calendar pops up.

Property: onChange
  Type: (Date) => void
  Default: 
  Description: Callback function triggered when the date value changes.

Property: hourCycle
  Type: 12 | 24
  Default: 24
  Description: Specifies whether to use a 12-hour or 24-hour cycle for time display.

Property: placeholder
  Type: string
  Default: Pick a date
  Description: The placeholder text displayed when no date is selected.

Property: disabled
  Type: boolean
  Default: false
  Description: If true, the date picker will be disabled.

Property: yearRange
  Type: number
  Default: 50
  Description: Defines the range of years available in the year dropdown (e.g., current year +/- yearRange).

Property: displayFormat
  Type: { hour24?: string, hour12?: string }
  Default: { hour24: 'PPP HH:mm:ss', hour12: 'PP hh:mm:ss b' }
  Description: Custom format for displaying the date and time, using date-fns format strings.

Property: granularity
  Type: 'day' | 'hour' | 'minute' | 'second'
  Default: second
  Description: Specifies the smallest unit of time that can be selected (day, hour, minute, or second).
```

--------------------------------

### Integrate PageTracker in Next.js Root Layout

Source: https://shadcnui-expansions.typeart.cc/docs/multiple-selector/docs/magic-back-button

This code snippet shows how to import and embed the `PageTracker` component within your Next.js `RootLayout`. This integration is essential for `react-page-tracker` to initialize and correctly track page visits across your entire application, which the Magic Back Button relies on.

```TypeScript
import { PageTracker } from 'react-page-tracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
+        <PageTracker />
        {children}
      </body>
    </html>)
}
```
Tokens:
Raw