Select

<Select label="Country" name="country">
<option value="">Select a country</option>
<option value="us">United States</option>
<option value="ca">Canada</option>
<option value="mx">Mexico</option>
</Select>

Add

npx @ava-ui/apogee add select

Pulls in Field and utils. Uses @lucide/astro for the chevron and the checkmark.

Usage

---
import Select from '@/components/apogee/Select/Select.astro'
---
<Select label="Country" name="country">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
</Select>

<Select label="Plan" name="plan" placeholder="Pick a plan" options={[
  { value: 'free', label: 'Free', description: 'For trying things out' },
  { value: 'pro', label: 'Pro', description: 'For teams' },
]} />

Anatomy

• Field — the Field wrapper: label, hint/error text.
• <select> — the native control; pass <option>s (and <optgroup>s) in the default slot. With options it is generated from the array and hidden while JS runs, but it is still the form control.
• Trigger (custom mode) — a field-styled <button popovertarget> showing the chosen label or the placeholder.
• Listbox (custom mode) — a role="listbox" popover anchored under the trigger, as wide as it, scrolling past 15rem.
• Start / end — start slot icon inside the control; end slot replaces the decorative chevron.

API

@composable — exposed to Content Editors in AVA. Any other native <select> attribute (e.g. name, autocomplete) passes through to the <select> itself.

Slots: start (icon inside the control), end (replaces the chevron).

Custom listbox

Pass options. The native <select> stays the form control, so the value submits with the form, change fires on it, and required still blocks an empty submit (the message shows under the trigger, which takes focus).

<form>
<Select label="Plan" name="plan" placeholder="Pick a plan" required options={[
  { value: 'free', label: 'Free', description: 'For trying things out' },
  { value: 'pro', label: 'Pro', description: 'For teams' },
  { value: 'business', label: 'Business', description: 'For organisations' },
  { value: 'enterprise', label: 'Enterprise', disabled: true },
]} />
<Button type="submit">Continue</Button>
</form>

Multiple

<Select label="Regions" name="regions" multiple value={['eu']} options={[
{ value: 'na', label: 'North America' },
{ value: 'eu', label: 'Europe' },
{ value: 'apac', label: 'Asia Pacific' },
]} />

Icons and avatars

Each option can lead with a Lucide component or an image; the trigger repeats the chosen one.

Assignee

Ana LimaPersonalALAna Lima

ALAna Lima

Personal

Workspace

ChoosePersonalLarkspur Inc.Ana LimaChoose

Personal

Larkspur Inc.

ALAna Lima

Show codeHide code

<Select label="Workspace" name="ws" options={[
{ value: 'personal', label: 'Personal', icon: Zap },
{ value: 'larkspur', label: 'Larkspur Inc.', icon: Building2 },
{ value: 'ana', label: 'Ana Lima', avatar: 'https://i.pravatar.cc/48?img=5', avatarName: 'Ana Lima' },
]} />

Multiple with search and a footer

A multiple select shows a checkbox on each option, counts the choices in the trigger, and can carry a search box and a footer. The native <select multiple> still submits.

<Select label="Countries" name="countries" multiple search selectAll placeholder="Pick some" options={[
{ value: 'fr', label: 'France' }, { value: 'ca', label: 'Canada' }, { value: 'jp', label: 'Japan' },
{ value: 'de', label: 'Germany' }, { value: 'es', label: 'Spain' }, { value: 'it', label: 'Italy' },
]} />

Placeholder and start icon

placeholder injects an empty first option and greys the text until a value is chosen. The start slot works in both modes.

<Select label="Country" name="ph-native" placeholder="Select a country">
<Globe slot="start" />
<option value="us">United States</option>
<option value="ca">Canada</option>
</Select>
<Select label="Country" name="ph-custom" placeholder="Select a country" options={[
{ value: 'us', label: 'United States' },
{ value: 'ca', label: 'Canada' },
]}>
<Globe slot="start" />
</Select>

Variants

<Select label="Outline" name="v-outline" variant="outline"><option>Option</option></Select>
<Select label="Faded" name="v-faded" variant="faded"><option>Option</option></Select>
<Select label="Ghost" name="v-ghost" variant="ghost"><option>Option</option></Select>
<Select label="Headless" name="v-headless" variant="headless"><option>Option</option></Select>

Sizes

Every size:

<Select label="Small" name="size-sm" size="small"><option>Option</option></Select>
<Select label="Medium" name="size-md"><option>Option</option></Select>
<Select label="Large" name="size-lg" size="large"><option>Option</option></Select>
<Select label="Extra large" name="size-xl" size="xlarge"><option>Option</option></Select>

Option groups and disabled options

<Select label="Timezone" name="tz">
<optgroup label="Europe">
  <option value="lisbon">Lisbon</option>
  <option value="bucharest">Bucharest</option>
</optgroup>
<optgroup label="Americas">
  <option value="toronto">Toronto</option>
  <option value="lima" disabled>Lima (soon)</option>
</optgroup>
</Select>

States

• Hover / focus — a visible focus-visible ring (--border-primary).
• Disabled — dimmed, cursor-not-allowed.
• Error — aria-invalid="true", border switches to the critical colour, Field shows the error text with role="alert".
• Required — the label shows a *.

<Select label="Plan" name="state-required" required>
<option value="free">Free</option>
</Select>
<Select label="Plan" name="state-error" error="Choose a plan">
<option value="">Select a plan</option>
</Select>
<Select label="Plan" name="state-disabled" disabled>
<option value="free">Free</option>
</Select>

Examples

With hint text:

<Select label="Plan" name="plan" hint="You can change this later">
  <option value="free">Free</option>
  <option value="pro">Pro</option>
</Select>

Listening for a choice (both modes fire change on the <select>):

<script>
  document.querySelector('select[name="plan"]').addEventListener('change', (e) => {
    console.log(e.target.value)
  })
</script>

Accessibility

• Native mode: a real <select> — full native keyboard (type-ahead, arrow keys) and mobile picker support for free.
• Custom mode: a <button aria-haspopup="listbox"> labelled by the field label and the shown value, and a role="listbox" of role="option"s with aria-selected (and aria-multiselectable when multiple). Opening focuses the chosen option. An outside click closes the list (native light dismiss) and focus returns to the trigger. Clicking the label focuses the trigger. A required field that submits empty focuses the trigger, marks it aria-invalid and shows the browser’s message as a role="alert".
• label renders a real <label for> via Field.
• hint / error are wired to the control through aria-describedby; error also sets aria-invalid and announces via role="alert".
• The chevron and checkmark are decorative (aria-hidden="true").

Tokens

Do / Don’t

• Do use the native mode by default — the platform picker is the best one on phones.
• Do reach for options when choices need a description, an icon-sized layout or a consistent look across platforms.
• Do set a placeholder when nothing should be pre-selected.
• Don’t use Select for 2–5 always-visible options — SegmentedControl or Radio shows every choice at once.

Content

• label is a short noun naming the field (“Country”, not “Select your country”).
• hint is one short clause, no ending period unless it’s a full sentence.
• error states the problem and, where possible, the fix (“Choose a country”).