Skip to content
WebJs
Menu

Native Select

A styled native HTML select element with consistent design system integration.

import { html } from '@webjsdev/core';
import {
  nativeSelectWrapperClass, nativeSelectClass, nativeSelectIconClass,
} from '#components/ui/native-select.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

export default function NativeSelectDemo() {
  return html`
    <div data-slot="native-select-wrapper" data-size="default" class=${nativeSelectWrapperClass()}>
      <select data-slot="native-select" data-size="default" aria-label="Status" class=${nativeSelectClass()}>
        <option data-slot="native-select-option" value="">Select status</option>
        <option data-slot="native-select-option" value="todo">Todo</option>
        <option data-slot="native-select-option" value="in-progress">In Progress</option>
        <option data-slot="native-select-option" value="done">Done</option>
        <option data-slot="native-select-option" value="cancelled">Cancelled</option>
      </select>
      ${ChevronDownIcon(nativeSelectIconClass())}
    </div>
  `;
}
View Code

For a styled select component, see the Select component.

Installation

pnpm dlx @webjsdev/ui add native-select

Usage

import {
  nativeSelectWrapperClass,
  nativeSelectClass,
  nativeSelectIconClass,
} from '#components/ui/native-select.ts';
<div class=${nativeSelectWrapperClass()}>
  <select class=${nativeSelectClass()} aria-label="Fruit">
    <option value="">Select a fruit</option>
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="blueberry">Blueberry</option>
    <option value="pineapple">Pineapple</option>
  </select>
  <svg class=${nativeSelectIconClass()} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
</div>

Composition

Simple

Options placed directly under the <select> (no <optgroup>).

nativeSelectWrapperClass()
├── nativeSelectClass() on <select>
│   ├── <option>
│   ├── <option>
│   ├── <option>
│   └── <option>
└── nativeSelectIconClass() on the chevron

With groups

Use a native <optgroup> to organize options into categories.

nativeSelectWrapperClass()
├── nativeSelectClass() on <select>
│   ├── <optgroup>
│   │   ├── <option>
│   │   └── <option>
│   └── <optgroup>
│       ├── <option>
│       └── <option>
└── nativeSelectIconClass() on the chevron

Groups

Use a native <optgroup> to organize options into categories.

import { html } from '@webjsdev/core';
import {
  nativeSelectWrapperClass, nativeSelectClass, nativeSelectIconClass,
} from '#components/ui/native-select.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

export default function NativeSelectGroups() {
  return html`
    <div data-slot="native-select-wrapper" data-size="default" class=${nativeSelectWrapperClass()}>
      <select data-slot="native-select" data-size="default" aria-label="Department" class=${nativeSelectClass()}>
        <option data-slot="native-select-option" value="">Select department</option>
        <optgroup data-slot="native-select-optgroup" label="Engineering">
          <option data-slot="native-select-option" value="frontend">Frontend</option>
          <option data-slot="native-select-option" value="backend">Backend</option>
          <option data-slot="native-select-option" value="devops">DevOps</option>
        </optgroup>
        <optgroup data-slot="native-select-optgroup" label="Sales">
          <option data-slot="native-select-option" value="sales-rep">Sales Rep</option>
          <option data-slot="native-select-option" value="account-manager">Account Manager</option>
          <option data-slot="native-select-option" value="sales-director">Sales Director</option>
        </optgroup>
        <optgroup data-slot="native-select-optgroup" label="Operations">
          <option data-slot="native-select-option" value="support">Customer Support</option>
          <option data-slot="native-select-option" value="product-manager">Product Manager</option>
          <option data-slot="native-select-option" value="ops-manager">Operations Manager</option>
        </optgroup>
      </select>
      ${ChevronDownIcon(nativeSelectIconClass())}
    </div>
  `;
}
View Code

Disabled

Add the disabled attribute to the <select> to disable it. The wrapper dims itself while its select is disabled.

import { html } from '@webjsdev/core';
import {
  nativeSelectWrapperClass, nativeSelectClass, nativeSelectIconClass,
} from '#components/ui/native-select.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

export default function NativeSelectDisabled() {
  return html`
    <div data-slot="native-select-wrapper" data-size="default" class=${nativeSelectWrapperClass()}>
      <select data-slot="native-select" data-size="default" aria-label="Fruit" disabled class=${nativeSelectClass()}>
        <option data-slot="native-select-option" value="">Disabled</option>
        <option data-slot="native-select-option" value="apple">Apple</option>
        <option data-slot="native-select-option" value="banana">Banana</option>
        <option data-slot="native-select-option" value="blueberry">Blueberry</option>
      </select>
      ${ChevronDownIcon(nativeSelectIconClass())}
    </div>
  `;
}
View Code

Invalid

Use aria-invalid to show validation errors and the data-invalid attribute on the Field wrapper for styling.

import { html } from '@webjsdev/core';
import {
  nativeSelectWrapperClass, nativeSelectClass, nativeSelectIconClass,
} from '#components/ui/native-select.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

export default function NativeSelectInvalid() {
  return html`
    <div data-slot="native-select-wrapper" data-size="default" class=${nativeSelectWrapperClass()}>
      <select data-slot="native-select" data-size="default" aria-label="Fruit" aria-invalid="true" class=${nativeSelectClass()}>
        <option data-slot="native-select-option" value="">Error state</option>
        <option data-slot="native-select-option" value="apple">Apple</option>
        <option data-slot="native-select-option" value="banana">Banana</option>
        <option data-slot="native-select-option" value="blueberry">Blueberry</option>
      </select>
      ${ChevronDownIcon(nativeSelectIconClass())}
    </div>
  `;
}
View Code

Native Select vs Select

  • Use Native Select for native browser behavior, better performance, or mobile-optimized dropdowns.
  • Use Select for custom styling, animations, or complex interactions.

RTL

To enable RTL support, see the RTL configuration guide.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  nativeSelectWrapperClass, nativeSelectClass, nativeSelectIconClass,
} from '#components/ui/native-select.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

// shadcn's demo switches language with a selector; the page shows its
// default, Arabic. Its RTL build turns the style's physical padding and
// chevron position into logical ones, so the rtl: classes do that here.
const translations = {
  en: {
    dir: 'ltr',
    values: { placeholder: 'Select status', todo: 'Todo', inProgress: 'In Progress', done: 'Done', cancelled: 'Cancelled' },
  },
  ar: {
    dir: 'rtl',
    values: { placeholder: 'اختر الحالة', todo: 'مهام', inProgress: 'قيد التنفيذ', done: 'منجز', cancelled: 'ملغي' },
  },
  he: {
    dir: 'rtl',
    values: { placeholder: 'בחר סטטוס', todo: 'לעשות', inProgress: 'בתהליך', done: 'הושלם', cancelled: 'בוטל' },
  },
};

export default function NativeSelectRtl() {
  const { dir, values: t } = translations.ar;
  return html`
    <div data-slot="native-select-wrapper" data-size="default" class=${nativeSelectWrapperClass()}>
      <select data-slot="native-select" data-size="default" dir=${dir} aria-label=${t.placeholder} class=${cn(nativeSelectClass(), 'rtl:pr-2.5 rtl:pl-8')}>
        <option data-slot="native-select-option" value="">${t.placeholder}</option>
        <option data-slot="native-select-option" value="todo">${t.todo}</option>
        <option data-slot="native-select-option" value="in-progress">${t.inProgress}</option>
        <option data-slot="native-select-option" value="done">${t.done}</option>
        <option data-slot="native-select-option" value="cancelled">${t.cancelled}</option>
      </select>
      ${ChevronDownIcon(cn(nativeSelectIconClass(), 'rtl:right-auto rtl:left-2.5'))}
    </div>
  `;
}
View Code

API Reference

nativeSelectClass

The classes for the native <select> element. It hides the platform chevron, so wrap the select in an element with nativeSelectWrapperClass() and put the chevron icon after it with nativeSelectIconClass(). The chevron is decorative, so keep aria-hidden="true" on it. Every native attribute (name, required, disabled, multiple) works as usual, and the select submits with its form with no script.

HelperApplies to
nativeSelectWrapperClass()The wrapper around the select and its chevron. Set data-size="sm" on the wrapper and the select for the small size.
nativeSelectClass()The <select> element.
nativeSelectIconClass()The chevron icon.
<div class=${nativeSelectWrapperClass()}>
  <select class=${nativeSelectClass()} aria-label="Option">
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
  </select>
  <svg class=${nativeSelectIconClass()} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
</div>

nativeSelectOptionClass

An individual option is a native <option>. The theme stylesheet already gives every option the themed colours, so a bare <option> needs no class; nativeSelectOptionClass() applies the same colours explicitly.

AttributeTypeDefault
valuestring
disabledbooleanfalse

nativeSelectOptGroupClass

Groups related options together with a native <optgroup>. Its label is announced, so it is real structure rather than only a visual break. Like options, it takes the themed colours with no class; nativeSelectOptGroupClass() applies them explicitly.

AttributeTypeDefault
labelstring
disabledbooleanfalse
<optgroup label="Fruits">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
</optgroup>