Multi Select

Overview

The Multi Select component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Selecting multiple values from a list is a common pattern for filters, tags, and assignments. A multi-select shows selected values as removable pills.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { useState } from 'react';
import { MultiSelect } from '@byteion/react';

const skills = [
  { value: 'react',  label: 'React' },
  { value: 'vue',    label: 'Vue' },
  { value: 'svelte', label: 'Svelte' },
  { value: 'solid',  label: 'SolidJS' },
];

export default function MultiSelectDemo() {
  const [picked, setPicked] = useState<string[]>(['react', 'vue']);
  return (
    <div className="grid max-w-md gap-4 p-6">
      <MultiSelect label="Skills" options={skills} value={picked} onChange={setPicked} />
      <MultiSelect label="Empty" placeholder="Pick frameworks" options={skills} />
    </div>
  );
}

<script setup lang="ts">
import { ref } from 'vue';
import { MultiSelect } from '@byteion/vue';

const picked = ref<string[]>(['react', 'vue']);
const skills = [
  { value: 'react',  label: 'React' },
  { value: 'vue',    label: 'Vue' },
  { value: 'svelte', label: 'Svelte' },
  { value: 'solid',  label: 'SolidJS' },
];
</script>

<template>
  <div class="grid max-w-md gap-4 p-6">
    <MultiSelect v-model="picked" label="Skills" :options="skills" />
    <MultiSelect label="Empty" placeholder="Pick frameworks" :options="skills" />
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• default — Resting appearance before interaction.
• hover — Pointer is over the element — visual feedback via color or shadow.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.
• loading — Action in progress — spinner replaces icon, button is disabled.
• invalid — Input value does not match expected format.
• error — Validation failed — red border and error message.
• success — Validation passed — green indicator.

Anatomy

Usage guidelines

• Show selected items as removable pills.
• Filter out already-selected items from the dropdown.
• Set a reasonable max selection limit.

Do and Don't

Accessibility

Each tag pill is focusable and removable via Backspace or click.

Customization

Tag pills use badge tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myMultiSelect = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myMultiSelect>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myMultiSelect = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myMultiSelect({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Requires JS module for tag management.

export interface MultiSelectProps {
  options: MultiSelectOption[];
  /** Controlled list of selected values. */
  value?: string[];
  defaultValue?: string[];
  onValueChange?: (value: string[]) => void;
  /** Visible label rendered above the field. */
  label?: ReactNode;
  helperText?: ReactNode;
  error?: ReactNode;
  /** Placeholder shown when nothing is selected. */
  placeholder?: string;
  /** Maximum number of selections. */
  max?: number;
  disabled?: boolean;
  /** Optional id for the input element. */
  id?: string;
  className?: string;
}

export interface MultiSelectProps {
  modelValue?: string[];
  defaultValue?: string[];
  options: MultiSelectOption[];
  placeholder?: string;
  label?: string;
  helperText?: string;
  error?: string;
  disabled?: boolean;
  max?: number;
  id?: string;
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Combobox
• Tags Input
• Checkbox
• Badge