Skip to content
data-slotv1.0.0
Esc
↑↓navigate↵open⌘Jpreview
On this page

Select

A button that opens a list of options with keyboard navigation and typeahead.

@data-slot/selectSource ↗
bun add @data-slot/select
npm install @data-slot/select
pnpm add @data-slot/select

Anatomy

The trigger and content are required. Wrapping each option’s label in select-item-text gives the trigger, typeahead, and item-aligned scrolling an exact text target.

<div data-slot="select" data-placeholder="Choose a fruit...">
  <button data-slot="select-trigger">
    <span data-slot="select-value"></span>
    <!-- Add your own chevron icon -->
  </button>
  <div data-slot="select-content" hidden>
    <div data-slot="select-viewport">
      <div data-slot="select-group">
        <div data-slot="select-label">Fruits</div>
        <div data-slot="select-item" data-value="apple">
          <span data-slot="select-item-text">Apple</span>
        </div>
        <div data-slot="select-item" data-value="banana">
          <span data-slot="select-item-text">Banana</span>
        </div>
        <div data-slot="select-item" data-value="orange">
          <span data-slot="select-item-text">Orange</span>
        </div>
      </div>
      <div data-slot="select-separator"></div>
      <div data-slot="select-item" data-value="other">
        <span data-slot="select-item-text">Other</span>
      </div>
    </div>
  </div>
</div>

Examples

Choose from a list

Preview
Show codeHide code
<label for="select-basic-fruit-select" class="select-field-label">Fruit</label>
<div data-slot="select" data-placeholder="Select a fruit..." class="select-root">
  <button data-slot="select-trigger" id="select-basic-fruit-select" class="select-trigger">
    <span data-slot="select-value"></span>
    <span class="select-icon">▼</span>
  </button>
  <div data-slot="select-content" class="select-content" hidden>
    <div data-slot="select-group">
      <div data-slot="select-label" class="select-label">Fruits</div>
      <div data-slot="select-item" data-value="apple" data-label="Apple" class="select-item">
        <span data-slot="select-item-text">Apple</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="banana" data-label="Banana" class="select-item">
        <span data-slot="select-item-text">Banana</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="orange" data-label="Orange" class="select-item">
        <span data-slot="select-item-text">Orange</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="mango" data-label="Mango" class="select-item">
        <span data-slot="select-item-text">Mango</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="grape" data-label="Grape" class="select-item">
        <span data-slot="select-item-text">Grape</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pear" data-label="Pear" class="select-item">
        <span data-slot="select-item-text">Pear</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="peach" data-label="Peach" class="select-item">
        <span data-slot="select-item-text">Peach</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pineapple" data-label="Pineapple" class="select-item">
        <span data-slot="select-item-text">Pineapple</span><span class="select-check">✓</span>
      </div>
    </div>
    <div data-slot="select-separator" class="select-separator"></div>
    <div data-slot="select-group">
      <div data-slot="select-label" class="select-label">Vegetables</div>
      <div data-slot="select-item" data-value="carrot" data-label="Carrot" class="select-item">
        <span data-slot="select-item-text">Carrot</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="broccoli" data-label="Broccoli" class="select-item">
        <span data-slot="select-item-text">Broccoli</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="cucumber" data-label="Cucumber" class="select-item">
        <span data-slot="select-item-text">Cucumber</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="tomato" data-label="Tomato" class="select-item">
        <span data-slot="select-item-text">Tomato</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pepper" data-label="Bell Pepper" class="select-item">
        <span data-slot="select-item-text">Bell Pepper</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="zucchini" data-label="Zucchini" class="select-item">
        <span data-slot="select-item-text">Zucchini</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="spinach" data-label="Spinach" data-disabled class="select-item disabled">
        <span data-slot="select-item-text">Spinach (out of stock)</span><span class="select-check">✓</span>
      </div>
    </div>
  </div>
</div>

<style>
  .select-root { position: relative; display: inline-block; }
  .select-field-label {
    display: block;
    font-size: 0.875rem;
    font-weight: 500;
    color: var(--text);
    margin-bottom: 0.25rem;
    line-height: 1.25rem;
  }
  .select-trigger {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.5rem 1rem;
    min-width: 12rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    cursor: pointer;
    transition: opacity 0.15s cubic-bezier(0.4, 0, 0.2, 1);
  }
  .select-trigger:hover { opacity: 0.9; }
  .select-trigger[data-placeholder] [data-slot="select-value"] {
    color: inherit;
  }
  .select-icon {
    margin-left: auto;
    font-size: 0.75rem;
    line-height: 1rem;
  }
  .select-content {
    background: var(--surface);
    border: 1px solid var(--border);
    min-width: 12rem;
    max-height: 14rem;
    overflow-y: auto;
    padding: 0.25rem;
    z-index: 50;
    box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
    width: 16rem;
  }
  .select-label {
    padding: 0.375rem 0.5rem;
    font-size: 0.75rem;
    font-weight: 600;
    color: var(--muted);
    line-height: 1rem;
  }
  .select-item {
    display: flex;
    align-items: center;
    width: 100%;
    padding: 0.375rem 0.5rem;
    cursor: pointer;
    font-size: 0.875rem;
    line-height: 1.25rem;
  }
  .select-check {
    margin-left: auto;
    visibility: hidden;
  }
  .select-item[data-selected] .select-check {
    visibility: visible;
  }
  .select-item[data-highlighted] {
    background: var(--code-bg);
  }
  .select-item.disabled {
    color: var(--border);
    cursor: not-allowed;
  }
  .select-separator {
    height: 1px;
    background: var(--border);
    margin: 0.25rem 0;
  }
</style>
<label for="select-basic-fruit-select" class="block mb-1 text-sm font-medium text-[var(--text)]">Fruit</label>
<div data-slot="select" data-placeholder="Select a fruit..." class="inline-block relative">
  <button
    data-slot="select-trigger"
    id="select-basic-fruit-select"
    class="flex items-center gap-2 px-4 py-2 min-w-48 bg-[var(--surface)] text-text
           border border-[var(--border)] cursor-pointer hover:opacity-90 transition-opacity"
  >
    <span data-slot="select-value" class="data-placeholder:text-[var(--muted)]"></span>
    <span class="ml-auto text-xs">▼</span>
  </button>
  <div
    data-slot="select-content"
    class="absolute top-full left-0 bg-[var(--surface)] border border-[var(--border)]
           w-64 max-h-56 overflow-y-auto p-1 z-50 shadow-lg"
    hidden
  >
    <div data-slot="select-group">
      <div data-slot="select-label" class="px-2 py-1.5 text-xs font-semibold text-[var(--muted)]">
        Fruits
      </div>
      <div
        data-slot="select-item"
        data-value="apple"
        data-label="Apple"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Apple</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="banana"
        data-label="Banana"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Banana</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="orange"
        data-label="Orange"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Orange</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="mango"
        data-label="Mango"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Mango</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="grape"
        data-label="Grape"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Grape</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pear"
        data-label="Pear"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Pear</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="peach"
        data-label="Peach"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Peach</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pineapple"
        data-label="Pineapple"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Pineapple</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
    </div>
    <div data-slot="select-separator" class="my-1 h-px bg-[var(--border)]"></div>
    <div data-slot="select-group">
      <div data-slot="select-label" class="px-2 py-1.5 text-xs font-semibold text-[var(--muted)]">
        Vegetables
      </div>
      <div
        data-slot="select-item"
        data-value="carrot"
        data-label="Carrot"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Carrot</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="broccoli"
        data-label="Broccoli"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Broccoli</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="cucumber"
        data-label="Cucumber"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Cucumber</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="tomato"
        data-label="Tomato"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Tomato</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pepper"
        data-label="Bell Pepper"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Bell Pepper</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="zucchini"
        data-label="Zucchini"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Zucchini</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="spinach"
        data-label="Spinach"
        data-disabled
        class="flex items-center px-2 py-1.5 w-full text-sm text-[var(--border)] cursor-not-allowed group"
      >
        <span data-slot="select-item-text">Spinach (out of stock)</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
    </div>
  </div>
</div>

Choose an initial value

data-default-value="banana" preselects an option on load.

Preview
Show codeHide code
<label for="select-extra-fruit-select" class="select-field-label">Fruit</label>
<div data-slot="select" data-default-value="banana" data-placeholder="Select a fruit..." class="select-root">
  <button data-slot="select-trigger" id="select-extra-fruit-select" class="select-trigger">
    <span data-slot="select-value"></span>
    <span class="select-icon">▼</span>
  </button>
  <div data-slot="select-content" class="select-content" hidden>
    <div data-slot="select-group">
      <div data-slot="select-label" class="select-label">Fruits</div>
      <div data-slot="select-item" data-value="apple" data-label="Apple" class="select-item">
        <span data-slot="select-item-text">Apple</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="banana" data-label="Banana" class="select-item">
        <span data-slot="select-item-text">Banana</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="orange" data-label="Orange" class="select-item">
        <span data-slot="select-item-text">Orange</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="mango" data-label="Mango" class="select-item">
        <span data-slot="select-item-text">Mango</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="grape" data-label="Grape" class="select-item">
        <span data-slot="select-item-text">Grape</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pear" data-label="Pear" class="select-item">
        <span data-slot="select-item-text">Pear</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="peach" data-label="Peach" class="select-item">
        <span data-slot="select-item-text">Peach</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pineapple" data-label="Pineapple" class="select-item">
        <span data-slot="select-item-text">Pineapple</span><span class="select-check">✓</span>
      </div>
    </div>
    <div data-slot="select-separator" class="select-separator"></div>
    <div data-slot="select-group">
      <div data-slot="select-label" class="select-label">Vegetables</div>
      <div data-slot="select-item" data-value="carrot" data-label="Carrot" class="select-item">
        <span data-slot="select-item-text">Carrot</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="broccoli" data-label="Broccoli" class="select-item">
        <span data-slot="select-item-text">Broccoli</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="cucumber" data-label="Cucumber" class="select-item">
        <span data-slot="select-item-text">Cucumber</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="tomato" data-label="Tomato" class="select-item">
        <span data-slot="select-item-text">Tomato</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="pepper" data-label="Bell Pepper" class="select-item">
        <span data-slot="select-item-text">Bell Pepper</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="zucchini" data-label="Zucchini" class="select-item">
        <span data-slot="select-item-text">Zucchini</span><span class="select-check">✓</span>
      </div>
      <div data-slot="select-item" data-value="spinach" data-label="Spinach" data-disabled class="select-item disabled">
        <span data-slot="select-item-text">Spinach (out of stock)</span><span class="select-check">✓</span>
      </div>
    </div>
  </div>
</div>

<style>
  .select-root { position: relative; display: inline-block; }
  .select-field-label {
    display: block;
    font-size: 0.875rem;
    font-weight: 500;
    color: var(--text);
    margin-bottom: 0.25rem;
    line-height: 1.25rem;
  }
  .select-trigger {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.5rem 1rem;
    min-width: 12rem;
    background: var(--surface);
    color: var(--text);
    border: 1px solid var(--border);
    cursor: pointer;
    transition: opacity 0.15s cubic-bezier(0.4, 0, 0.2, 1);
  }
  .select-trigger:hover { opacity: 0.9; }
  .select-trigger[data-placeholder] [data-slot="select-value"] {
    color: inherit;
  }
  .select-icon {
    margin-left: auto;
    font-size: 0.75rem;
    line-height: 1rem;
  }
  .select-content {
    background: var(--surface);
    border: 1px solid var(--border);
    min-width: 12rem;
    max-height: 14rem;
    overflow-y: auto;
    padding: 0.25rem;
    z-index: 50;
    box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
    width: 16rem;
  }
  .select-label {
    padding: 0.375rem 0.5rem;
    font-size: 0.75rem;
    font-weight: 600;
    color: var(--muted);
    line-height: 1rem;
  }
  .select-item {
    display: flex;
    align-items: center;
    width: 100%;
    padding: 0.375rem 0.5rem;
    cursor: pointer;
    font-size: 0.875rem;
    line-height: 1.25rem;
  }
  .select-check {
    margin-left: auto;
    visibility: hidden;
  }
  .select-item[data-selected] .select-check {
    visibility: visible;
  }
  .select-item[data-highlighted] {
    background: var(--code-bg);
  }
  .select-item.disabled {
    color: var(--border);
    cursor: not-allowed;
  }
  .select-separator {
    height: 1px;
    background: var(--border);
    margin: 0.25rem 0;
  }
</style>
<label for="select-extra-fruit-select" class="block mb-1 text-sm font-medium text-[var(--text)]">Fruit</label>
<div data-slot="select" data-default-value="banana" data-placeholder="Select a fruit..." class="inline-block relative">
  <button
    data-slot="select-trigger"
    id="select-extra-fruit-select"
    class="flex items-center gap-2 px-4 py-2 min-w-48 bg-[var(--surface)] text-text
           border border-[var(--border)] cursor-pointer hover:opacity-90 transition-opacity"
  >
    <span data-slot="select-value" class="data-placeholder:text-[var(--muted)]"></span>
    <span class="ml-auto text-xs">▼</span>
  </button>
  <div
    data-slot="select-content"
    class="absolute top-full left-0 bg-[var(--surface)] border border-[var(--border)]
           w-64 max-h-56 overflow-y-auto p-1 z-50 shadow-lg"
    hidden
  >
    <div data-slot="select-group">
      <div data-slot="select-label" class="px-2 py-1.5 text-xs font-semibold text-[var(--muted)]">
        Fruits
      </div>
      <div
        data-slot="select-item"
        data-value="apple"
        data-label="Apple"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Apple</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="banana"
        data-label="Banana"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Banana</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="orange"
        data-label="Orange"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Orange</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="mango"
        data-label="Mango"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Mango</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="grape"
        data-label="Grape"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Grape</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pear"
        data-label="Pear"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Pear</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="peach"
        data-label="Peach"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Peach</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pineapple"
        data-label="Pineapple"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Pineapple</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
    </div>
    <div data-slot="select-separator" class="my-1 h-px bg-[var(--border)]"></div>
    <div data-slot="select-group">
      <div data-slot="select-label" class="px-2 py-1.5 text-xs font-semibold text-[var(--muted)]">
        Vegetables
      </div>
      <div
        data-slot="select-item"
        data-value="carrot"
        data-label="Carrot"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Carrot</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="broccoli"
        data-label="Broccoli"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Broccoli</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="cucumber"
        data-label="Cucumber"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Cucumber</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="tomato"
        data-label="Tomato"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Tomato</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="pepper"
        data-label="Bell Pepper"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Bell Pepper</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="zucchini"
        data-label="Zucchini"
        class="group flex items-center w-full px-2 py-1.5 text-sm cursor-pointer
               data-highlighted:bg-[var(--code-bg)]"
      >
        <span data-slot="select-item-text">Zucchini</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
      <div
        data-slot="select-item"
        data-value="spinach"
        data-label="Spinach"
        data-disabled
        class="flex items-center px-2 py-1.5 w-full text-sm text-[var(--border)] cursor-not-allowed group"
      >
        <span data-slot="select-item-text">Spinach (out of stock)</span><span class="ml-auto invisible group-data-selected:visible">✓</span>
      </div>
    </div>
  </div>
</div>

API reference

Initialization

create(scope?)

Find and bind uninitialized [data-slot="select"] descendants of scope (defaults to document). Returns SelectController[] for newly bound roots. To initialize the scope element itself, use createSelect.

import { create } from "@data-slot/select";

const controllers = create();

createSelect(root, options?)

Create a SelectController for one root element. JavaScript options take precedence over the corresponding data attributes. Calling this again for a bound root returns its existing controller; destroy it before rebinding with new options.

import { createSelect } from "@data-slot/select";

const controller = createSelect(element, {});

Slots

Runtime Slots

  • select - Root container.
  • select-trigger - Required button that opens the popup and anchors its position.
  • select-value - Optional text target inside the trigger; displays the selected label or placeholder.
  • select-content - Required popup container for options.
  • select-viewport - Optional scroll container inside select-content; used for item-aligned scrolling when present.
  • select-item - Individual selectable option.
  • select-item-text - Optional text anchor inside select-item; preferred for exact item-aligned parity with Base/shadcn styles.
  • select-group - Groups related items.
  • select-label - Group label (inside a select-group).
  • select-positioner - Optional authored positioning wrapper (reused instead of generated wrapper).
  • select-portal - Optional authored portal wrapper that can contain select-positioner.

Style-only Slots

  • select-separator - Visual divider between items/groups.

Item labels resolve from authored data-label, then select-item-text, then the item’s text content. data-label is an input attribute, not generated state.

Composed Portal Markup (Optional)

<div data-slot="select">
  <button data-slot="select-trigger">
    <span data-slot="select-value"></span>
  </button>
  <div data-slot="select-portal">
    <div data-slot="select-positioner">
      <div data-slot="select-content" hidden>...</div>
    </div>
  </div>
</div>

Native Label Support

Use a standard HTML <label for="..."> element to label the select. The for attribute should match the id on the trigger button. Clicking the label opens the select, and aria-labelledby is set automatically.

<label for="fruit-select">Choose a fruit</label>
<div data-slot="select">
  <button data-slot="select-trigger" id="fruit-select">
    <span data-slot="select-value"></span>
  </button>
  <div data-slot="select-content" hidden>
    <div data-slot="select-group">
      <div data-slot="select-label">Fruits</div>          <!-- group label -->
      <div data-slot="select-item" data-value="apple">Apple</div>
    </div>
  </div>
</div>

Data Attributes

The component sets these attributes to reflect state:

Attribute Element Values Description
data-state root, trigger, content "open" | "closed" Open state
data-position content, viewport "item-aligned" | "popper" Resolved positioning mode authored by the controller
data-align-trigger content "true" | "false" Whether the current mode aligns the selected item to the trigger
data-value root string Current selected value
data-selected item (presence) Selected item
data-highlighted item (presence) Focused/highlighted item
data-placeholder trigger (presence) When showing placeholder

Options

Options can be passed via JavaScript or data attributes (JS takes precedence). Placement attributes (position, side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding) resolve in this order:

  1. JavaScript option
  2. select-content
  3. select-positioner
  4. select root (fallback)
Option Data Attribute Type Default Description
defaultValue data-default-value string null Initial selected value
defaultOpen data-default-open boolean false Initial popup open state
mountStrategy Root data-mount-strategy "lazy" | "eager" "lazy" Detach closed content, or keep it connected and hidden
placeholder data-placeholder string "" Text when no value selected
disabled data-disabled boolean false Disable interaction
required data-required boolean false Form validation required
name data-name string - Form field name (creates an internal form control)
position data-position "item-aligned" | "popper" "item-aligned" Positioning mode (see below)
avoidCollisions data-avoid-collisions boolean true Adjust to stay in viewport
collisionPadding data-collision-padding number 8 Viewport edge padding (px)
lockScroll data-lock-scroll boolean true Lock page scroll while the popup is open
highlightItemOnHover data-highlight-item-on-hover boolean true Highlight and focus items on pointer hover

Positioning Modes

item-aligned (default): The popup positions itself so the selected item aligns with the trigger, similar to native <select> elements. The popup width matches the trigger width.

For the closest Base/shadcn visual parity, wrap the visible label inside each item with data-slot="select-item-text". When absent, the controller falls back to the whole select-item box for alignment, trigger display, and typeahead.

popper: The popup appears below or above the trigger like a dropdown menu. Additional options apply:

Option Data Attribute Type Default Description
side data-side "top" | "bottom" "bottom" Popup placement
align data-align "start" | "center" | "end" "start" Popup alignment
sideOffset data-side-offset number 4 Distance from trigger (px)
alignOffset data-align-offset number 0 Offset from alignment edge (px)

Both positioning modes set --transform-origin on the positioned element (select-positioner, or select-content when no positioner is used), so content animations can use transform-origin: var(--transform-origin, center).

The controller also mirrors the resolved positioning mode onto the DOM for styling:

  • data-position="item-aligned" | "popper" on select-content
  • data-position="item-aligned" | "popper" on select-viewport when present
  • data-align-trigger="true" | "false" on select-content

Consumers can style against these attributes directly and do not need to author them manually.

Callbacks

Callback Type Description
onValueChange (value: string | null) => void Called when selection changes
onOpenChange (open: boolean) => void Called when popup opens/closes

Content mounting and server rendering

By default, Select removes its closed dropdown from the page’s DOM. This keeps pages with many selects smaller after initialization. The select button and selected value remain visible, and forms continue to work normally.

Opening the dropdown puts the same options back into the page. Their state and event listeners are preserved. Closing waits for any exit animation to finish, except when choosing an option, which closes the dropdown immediately.

Most applications can use this default without any changes.

If your code needs to find or update options while the dropdown is closed—for example, using querySelector—use eager mode to keep them in the DOM:

createSelect(root, { mountStrategy: "eager" });

You can also add data-mount-strategy="eager" to the Select root. A JavaScript option takes precedence over the HTML attribute.

With the default lazy mode, DOM queries won’t find closed options. You can still use the Select controller to change the selected value while closed; the displayed label and form value will update as usual.

Server rendering and pages without JavaScript

Lazy mounting does not reduce the HTML sent to the browser. Options are still included in your HTML; Select removes them from the DOM after JavaScript initializes.

Keep the dropdown’s initial markup hidden to prevent it briefly appearing before initialization. If the form must work without JavaScript, provide a native <select> fallback. Neither lazy nor eager mode provides that fallback automatically.

Controller

interface SelectController {
  readonly value: string | null;   // Current selected value
  readonly isOpen: boolean;        // Current open state
  select(value: string): void;     // Select a value
  open(): void;                    // Open the popup
  close(): void;                   // Close the popup
  destroy(): void;                 // Cleanup
}

Controller Destruction

destroy() permanently disposes the controller and hides any open surface without emitting an additional change event. Repeated destruction is safe; methods on the old controller become no-ops. Create a new controller on the same root to rebind it.

Focus restoration already queued by a close survives destruction. Closing with Tab still skips focus restoration to preserve normal Tab navigation.

Events

Outbound Events

root.addEventListener('select:change', (e) => {
  console.log('Value changed:', e.detail.value);
});

root.addEventListener('select:open-change', (e) => {
  console.log('Open state:', e.detail.open);
});

Inbound Events

select:set accepts { value?: string | null, open?: boolean }. Use value: null to clear the selection. When both fields are supplied, the value is applied before the open state. Programmatic selection works while disabled, but opening is blocked.

// Set value
root.dispatchEvent(new CustomEvent('select:set', {
  detail: { value: 'apple' }
}));

// Set open state
root.dispatchEvent(new CustomEvent('select:set', {
  detail: { open: true }
}));

Keyboard Navigation

Key Action
Enter, Space, ArrowDown, ArrowUp Open popup (when trigger focused)
ArrowDown Move to next item
ArrowUp Move to previous item
Home Move to first item
End Move to last item
Enter, Space Select highlighted item
Escape Close popup
Tab Close popup and move focus
Type characters Jump to matching item

Accessibility

  • Trigger: role="combobox", aria-haspopup="listbox", aria-expanded, and aria-controls while open
  • Content: role="listbox", aria-labelledby
  • Item: role="option", aria-selected, aria-disabled
  • Group: role="group", aria-labelledby
  • Disabled items are skipped during keyboard navigation

Form Integration

When name is provided, an internal control is automatically created for form submission and kept out of the visual and keyboard flow:

<form>
  <div data-slot="select" data-name="fruit">
    <!-- ... -->
  </div>
  <button type="submit">Submit</button>
</form>

With required / data-required, this control participates in native validation. An empty required select blocks form submission and focuses the visible trigger. Disabled selects are excluded from validation and submission. Selected values are preserved exactly, including line breaks.

Resetting the form restores defaultValue and its displayed selection without emitting a value-change event, including when the select has no name. Synchronization happens on the next event-loop task, after the browser resets native controls. Calling preventDefault() on the reset event preserves the current state.