Skip to content
WebJs
Menu

Displays a list of options for the user to pick from, triggered by a button.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

export default function SelectDemo() {
  return html`
    <ui-select>
      <select name="fruit" aria-label="Fruit" class=${cn(selectTriggerClass(), 'w-full max-w-48')}>
        <optgroup label="Fruits">
          <option value="" selected>Select a fruit</option>
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="blueberry">Blueberry</option>
          <option value="grapes">Grapes</option>
          <option value="pineapple">Pineapple</option>
        </optgroup>
      </select>
    </ui-select>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add select

Usage

import { selectTriggerClass } from '#components/ui/select.ts';
import { cn } from '#lib/utils/cn.ts';
<ui-select placeholder="Theme">
  <select name="theme" aria-label="Theme" class=${cn(selectTriggerClass(), 'w-[180px]')}>
    <option value="" disabled selected hidden>Theme</option>
    <option value="light">Light</option>
    <option value="dark">Dark</option>
    <option value="system">System</option>
  </select>
</ui-select>

<ui-select> enhances the native <select> inside it. Without JavaScript the native select is what the page shows and what the form submits. With JavaScript the element hides it visually and draws the styled trigger and list in its place, writing every choice back into it.

Composition

Use the following composition to build a select. The options stay native elements, because the HTML parser drops a custom element inside a <select>:

ui-select
└── select (selectTriggerClass)
    ├── option (placeholder, value="" hidden)
    ├── optgroup (label)
    │   ├── option
    │   └── option
    ├── hr
    └── optgroup (label)
        ├── option
        └── option

Align Item With Trigger

Use the position attribute on <ui-select> to control alignment. When position="item-aligned" (default), the list positions so the selected item appears over the trigger. When position="popper", the list aligns to the trigger edge.

Toggle to align the item with the trigger.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  fieldGroupClass, fieldClass, fieldContentClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

// position="item-aligned" (the default) opens the list over the trigger on
// the chosen option; position="popper" opens it below the trigger. The
// switch shows the setting this select renders with.
export default function SelectAlignItem() {
  const alignItemWithTrigger = true;

  return html`
    <div data-slot="field-group" class=${cn(fieldGroupClass(), 'w-full max-w-xs')}>
      <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
        <div data-slot="field-content" class=${fieldContentClass()}>
          <label data-slot="field-label" for="align-item" class=${fieldLabelClass()}>Align Item</label>
          <p data-slot="field-description" class=${fieldDescriptionClass()}>
            Toggle to align the item with the trigger.
          </p>
        </div>
        <ui-switch input-id="align-item" ?checked=${alignItemWithTrigger}></ui-switch>
      </div>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <ui-select position=${alignItemWithTrigger ? 'item-aligned' : 'popper'}>
          <select name="fruit" aria-label="Fruit" class=${cn(selectTriggerClass(), 'w-full')}>
            <option value="apple">Apple</option>
            <option value="banana" selected>Banana</option>
            <option value="blueberry">Blueberry</option>
            <option value="grapes">Grapes</option>
            <option value="pineapple">Pineapple</option>
          </select>
        </ui-select>
      </div>
    </div>
  `;
}
View Code

Groups

Use <optgroup label> and an <hr> between options to organize items. The label becomes the group's heading.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

export default function SelectGroups() {
  return html`
    <ui-select placeholder="Select a fruit">
      <select name="food" aria-label="Food" class=${cn(selectTriggerClass(), 'w-full max-w-48')}>
        <option value="" disabled selected hidden>Select a fruit</option>
        <optgroup label="Fruits">
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="blueberry">Blueberry</option>
        </optgroup>
        <hr>
        <optgroup label="Vegetables">
          <option value="carrot">Carrot</option>
          <option value="broccoli">Broccoli</option>
          <option value="spinach">Spinach</option>
        </optgroup>
      </select>
    </ui-select>
  `;
}
View Code

Scrollable

A select with many items that scrolls.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

const timezones = [
  {
    label: 'North America',
    items: [
      { value: 'est', label: 'Eastern Standard Time' },
      { value: 'cst', label: 'Central Standard Time' },
      { value: 'mst', label: 'Mountain Standard Time' },
      { value: 'pst', label: 'Pacific Standard Time' },
      { value: 'akst', label: 'Alaska Standard Time' },
      { value: 'hst', label: 'Hawaii Standard Time' },
    ],
  },
  {
    label: 'Europe & Africa',
    items: [
      { value: 'gmt', label: 'Greenwich Mean Time' },
      { value: 'cet', label: 'Central European Time' },
      { value: 'eet', label: 'Eastern European Time' },
      { value: 'west', label: 'Western European Summer Time' },
      { value: 'cat', label: 'Central Africa Time' },
      { value: 'eat', label: 'East Africa Time' },
    ],
  },
  {
    label: 'Asia',
    items: [
      { value: 'msk', label: 'Moscow Time' },
      { value: 'ist', label: 'India Standard Time' },
      { value: 'cst_china', label: 'China Standard Time' },
      { value: 'jst', label: 'Japan Standard Time' },
      { value: 'kst', label: 'Korea Standard Time' },
      { value: 'ist_indonesia', label: 'Indonesia Central Standard Time' },
    ],
  },
  {
    label: 'Australia & Pacific',
    items: [
      { value: 'awst', label: 'Australian Western Standard Time' },
      { value: 'acst', label: 'Australian Central Standard Time' },
      { value: 'aest', label: 'Australian Eastern Standard Time' },
      { value: 'nzst', label: 'New Zealand Standard Time' },
      { value: 'fjt', label: 'Fiji Time' },
    ],
  },
  {
    label: 'South America',
    items: [
      { value: 'art', label: 'Argentina Time' },
      { value: 'bot', label: 'Bolivia Time' },
      { value: 'brt', label: 'Brasilia Time' },
      { value: 'clt', label: 'Chile Standard Time' },
    ],
  },
];

export default function SelectScrollable() {
  return html`
    <ui-select placeholder="Select a timezone">
      <select name="timezone" aria-label="Timezone" class=${cn(selectTriggerClass(), 'w-full max-w-64')}>
        <option value="" disabled selected hidden>Select a timezone</option>
        ${timezones.map((group) => html`
          <optgroup label=${group.label}>
            ${group.items.map((item) => html`<option value=${item.value}>${item.label}</option>`)}
          </optgroup>
        `)}
      </select>
    </ui-select>
  `;
}
View Code

Disabled

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

export default function SelectDisabled() {
  return html`
    <ui-select placeholder="Select a fruit">
      <select name="fruit" aria-label="Fruit" disabled class=${cn(selectTriggerClass(), 'w-full max-w-48')}>
        <option value="" disabled selected hidden>Select a fruit</option>
        <optgroup label="Fruits">
          <option value="apple">Apple</option>
          <option value="banana">Banana</option>
          <option value="blueberry">Blueberry</option>
          <option value="grapes" disabled>Grapes</option>
          <option value="pineapple">Pineapple</option>
        </optgroup>
      </select>
    </ui-select>
  `;
}
View Code

Invalid

Add the data-invalid attribute to the field and the aria-invalid attribute to the native <select> to show an error state. The drawn trigger carries the select's aria-invalid.

<div data-slot="field" data-invalid="true" class=${fieldClass()}>
  <label for="fruit" class=${fieldLabelClass()}>Fruit</label>
  <ui-select>
    <select id="fruit" aria-invalid="true" class=${selectTriggerClass()}>
      ...
    </select>
  </ui-select>
</div>
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass, fieldErrorClass } from '#components/ui/field.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

export default function SelectInvalid() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" data-invalid="true" class=${cn(fieldClass(), 'w-full max-w-48')}>
      <label data-slot="field-label" for="select-invalid" class=${fieldLabelClass()}>Fruit</label>
      <ui-select placeholder="Select a fruit">
        <select id="select-invalid" name="fruit" aria-invalid="true" aria-describedby="select-invalid-error" class=${cn(selectTriggerClass(), 'w-full')}>
          <option value="" disabled selected hidden>Select a fruit</option>
          <optgroup label="Fruits">
            <option value="apple">Apple</option>
            <option value="banana">Banana</option>
            <option value="blueberry">Blueberry</option>
          </optgroup>
        </select>
      </ui-select>
      <div role="alert" data-slot="field-error" id="select-invalid-error" class=${fieldErrorClass()}>Please select a fruit.</div>
    </div>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      selectFruit: 'Select a fruit',
      fruits: 'Fruits',
      apple: 'Apple',
      banana: 'Banana',
      blueberry: 'Blueberry',
      grapes: 'Grapes',
      pineapple: 'Pineapple',
      vegetables: 'Vegetables',
      carrot: 'Carrot',
      broccoli: 'Broccoli',
      spinach: 'Spinach',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      selectFruit: 'اختر فاكهة',
      fruits: 'الفواكه',
      apple: 'تفاح',
      banana: 'موز',
      blueberry: 'توت أزرق',
      grapes: 'عنب',
      pineapple: 'أناناس',
      vegetables: 'الخضروات',
      carrot: 'جزر',
      broccoli: 'بروكلي',
      spinach: 'سبانخ',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      selectFruit: 'בחר פרי',
      fruits: 'פירות',
      apple: 'תפוח',
      banana: 'בננה',
      blueberry: 'אוכמניה',
      grapes: 'ענבים',
      pineapple: 'אננס',
      vegetables: 'ירקות',
      carrot: 'גזר',
      broccoli: 'ברוקולי',
      spinach: 'תרד',
    },
  },
};

export default function SelectRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  const fruits = [
    { label: t.apple, value: 'apple' },
    { label: t.banana, value: 'banana' },
    { label: t.blueberry, value: 'blueberry' },
    { label: t.grapes, value: 'grapes' },
    { label: t.pineapple, value: 'pineapple' },
  ];

  const vegetables = [
    { label: t.carrot, value: 'carrot' },
    { label: t.broccoli, value: 'broccoli' },
    { label: t.spinach, value: 'spinach' },
  ];

  return html`
    <ui-select placeholder=${t.selectFruit} dir=${dir} lang=${lang}>
      <select name="food" aria-label=${t.selectFruit} class=${cn(selectTriggerClass(), 'w-32')}>
        <option value="" disabled selected hidden>${t.selectFruit}</option>
        <optgroup label=${t.fruits}>
          ${fruits.map((item) => html`<option value=${item.value}>${item.label}</option>`)}
        </optgroup>
        <hr>
        <optgroup label=${t.vegetables}>
          ${vegetables.map((item) => html`<option value=${item.value}>${item.label}</option>`)}
        </optgroup>
      </select>
    </ui-select>
  `;
}
View Code

API Reference

ui-select

AttributeTypeDefault
placeholderstringthe placeholder option's text
size"default" | "sm""default"
position"item-aligned" | "popper""item-aligned"
openbooleanfalse
EventDetailFired when
ui-value-change{ value: string }The selected value changes.

The native select also fires input and change. The value, disabled, required and each option's disabled are the native select's own attributes. A placeholder option is one with value="" that is hidden or disabled.

The trigger is a role="combobox" button named by the select's <label> or aria-label, and the list a role="listbox". From the keyboard, the arrows, Enter or Space open the list, typing jumps to a matching option, and Escape closes it without a change.

selectTriggerClass

Put selectTriggerClass() on the native select. The drawn trigger takes the classes written there, so cn(selectTriggerClass(), 'w-full') gives a full-width trigger with JavaScript on and off alike.