Skip to content

Select

Custom dropdown select with keyboard navigation, option groups, icons, descriptions, clearable state, and validation.

import { Select } from "phoundry-ui";

Basic

Loading interactive example…

View source
basic.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let basic = $state<string | undefined>("apple");
</script>
<div class="max-w-xs">
<Select
options={plainOptions}
value={basic}
onchange={(v: string | undefined) => {
basic = v;
}}
placeholder="Pick a fruit..."
/>
</div>
<p class="mt-2 text-xs text-txt-tertiary">Selected: {basic ?? "none"}</p>

Variants

Loading interactive example…

View source
variants.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let outline = $state<string | undefined>(undefined);
let minimal = $state<string | undefined>(undefined);
let filled = $state<string | undefined>(undefined);
</script>
<div class="flex flex-wrap items-start gap-3">
<div class="w-44">
<span class="mb-1 block text-[10px] text-txt-tertiary">outline</span>
<Select
options={plainOptions}
value={outline}
onchange={(v: string | undefined) => {
outline = v;
}}
variant="outline"
placeholder="Outline..."
/>
</div>
<div class="w-44">
<span class="mb-1 block text-[10px] text-txt-tertiary">ghost (minimal)</span
>
<Select
options={plainOptions}
value={minimal}
onchange={(v: string | undefined) => {
minimal = v;
}}
variant="ghost"
placeholder="Ghost..."
/>
</div>
<div class="w-44">
<span class="mb-1 block text-[10px] text-txt-tertiary"
>filled (default)</span
>
<Select
options={plainOptions}
value={filled}
onchange={(v: string | undefined) => {
filled = v;
}}
variant="filled"
placeholder="Filled..."
/>
</div>
</div>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let basic = $state<string | undefined>("apple");
let sm = $state<string | undefined>(undefined);
</script>
<div class="flex flex-wrap items-end gap-3">
<div class="w-44">
<span class="mb-1 block text-[10px] text-txt-tertiary">sm</span>
<Select
options={plainOptions}
value={sm}
onchange={(v: string | undefined) => {
sm = v;
}}
size="sm"
placeholder="Small..."
/>
</div>
<div class="w-44">
<span class="mb-1 block text-[10px] text-txt-tertiary">md (default)</span>
<Select
options={plainOptions}
value={basic}
onchange={(v: string | undefined) => {
basic = v;
}}
size="md"
placeholder="Medium..."
/>
</div>
</div>

Shrink

Loading interactive example…

View source
shrink.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let shrinkVal = $state<string | undefined>("cherry");
</script>
<p class="mb-2 text-xs text-txt-secondary">
Fits the trigger width to its content instead of stretching full-width.
</p>
<Select
options={plainOptions}
value={shrinkVal}
onchange={(v: string | undefined) => {
shrinkVal = v;
}}
shrink
/>

Clearable

Loading interactive example…

View source
clearable.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let clearable = $state<string | undefined>("cherry");
</script>
<div class="max-w-xs">
<Select
options={plainOptions}
value={clearable}
onchange={(v: string | undefined) => {
clearable = v;
}}
clearable
placeholder="Pick or clear..."
/>
</div>

Searchable

Set searchable to show a search field inside the dropdown. Search is off by default. Filtering matches option labels using a case-insensitive substring, ignores surrounding whitespace, and hides groups with no matches. It does not change the current selection until an option is chosen. The query resets whenever the dropdown closes.

Loading interactive example…

View source
searchable.svelte
<script lang="ts">
import { Select } from 'phoundry-ui';
let value = $state<string | undefined>();
const options = [
{ label: 'Fruit', options: [{ value: 'apple', label: 'Apple' }, { value: 'banana', label: 'Banana' }] },
{ label: 'Vegetables', options: [{ value: 'carrot', label: 'Carrot' }, { value: 'pepper', label: 'Bell pepper' }] }
];
</script>
<Select {options} {value} onchange={(next) => (value = next)} searchable placeholder="Choose produce..." />

The search field receives focus when opened. Use Arrow Up/Down to navigate matching enabled options and Enter to select. Spaces remain editable text; Escape closes the dropdown and returns focus to the trigger. An empty result set displays “No results found”.

Disabled

Loading interactive example…

View source
disabled.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let disabledVal = $state<string | undefined>("apple");
</script>
<div class="max-w-xs">
<Select
options={plainOptions}
value={disabledVal}
onchange={(v: string | undefined) => {
disabledVal = v;
}}
disabled
/>
</div>

Validation

Loading interactive example…

View source
validation.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let errorVal = $state<string | undefined>(undefined);
</script>
<div class="max-w-xs">
<Select
options={plainOptions}
value={errorVal}
onchange={(v: string | undefined) => {
errorVal = v;
}}
invalid
error="Selection required"
placeholder="Required field..."
/>
</div>

Selected indicator

Loading interactive example…

View source
selected-indicator.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const plainOptions: SelectOption[] = [
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "cherry", label: "Cherry" },
{ value: "dragonfruit", label: "Dragonfruit" },
];
let indicatorVal = $state<string | undefined>("apple");
</script>
<p class="mb-2 text-xs text-txt-secondary">
<code>selectedIndicator="check"</code> shows a checkmark instead of tinting the
active row (helpful when accent-on-background is too strong).
</p>
<div class="max-w-xs">
<Select
options={plainOptions}
value={indicatorVal}
onchange={(v: string | undefined) => {
indicatorVal = v;
}}
selectedIndicator="check"
placeholder="Pick…"
/>
</div>

With Icons

Loading interactive example…

View source
with-icons.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const iconOptions: SelectOption[] = [
{ value: "svelte", label: "Svelte", icon: "logos:svelte-icon" },
{ value: "react", label: "React", icon: "logos:react" },
{ value: "vue", label: "Vue", icon: "logos:vue" },
{ value: "angular", label: "Angular", icon: "logos:angular-icon" },
];
let iconVal = $state<string | undefined>(undefined);
</script>
<div class="max-w-xs">
<Select
options={iconOptions}
value={iconVal}
onchange={(v: string | undefined) => {
iconVal = v;
}}
placeholder="Pick a framework..."
/>
</div>
<p class="mt-2 text-xs text-txt-tertiary">Selected: {iconVal ?? "none"}</p>

With Descriptions

Loading interactive example…

View source
with-descriptions.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
const descOptions: SelectOption[] = [
{ value: "sm", label: "Small", description: "640px max width" },
{ value: "md", label: "Medium", description: "768px max width" },
{ value: "lg", label: "Large", description: "1024px max width" },
{ value: "xl", label: "Extra Large", description: "1280px max width" },
];
let sm = $state<string | undefined>(undefined);
let descVal = $state<string | undefined>(undefined);
</script>
<div class="max-w-xs">
<Select
options={descOptions}
value={descVal}
onchange={(v: string | undefined) => {
descVal = v;
}}
placeholder="Pick a breakpoint..."
/>
</div>
<p class="mt-2 text-xs text-txt-tertiary">Selected: {descVal ?? "none"}</p>

Grouped Options

Loading interactive example…

View source
grouped-options.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption, SelectOptionGroup } from "phoundry-ui";
const groupedOptions: (SelectOption | SelectOptionGroup)[] = [
{
label: "Frontend",
options: [
{ value: "svelte", label: "Svelte" },
{ value: "react", label: "React" },
{ value: "vue", label: "Vue" },
],
},
{
label: "Backend",
options: [
{ value: "rust", label: "Rust" },
{ value: "go", label: "Go" },
{ value: "python", label: "Python" },
],
},
];
let groupedVal = $state<string | undefined>(undefined);
</script>
<div class="max-w-xs">
<Select
options={groupedOptions}
value={groupedVal}
onchange={(v: string | undefined) => {
groupedVal = v;
}}
placeholder="Pick a language..."
/>
</div>
<p class="mt-2 text-xs text-txt-tertiary">Selected: {groupedVal ?? "none"}</p>

Custom Snippet

Loading interactive example…

View source
custom-snippet.svelte
<script lang="ts">
import { Select } from "phoundry-ui";
import type { SelectOption } from "phoundry-ui";
import { Badge } from "phoundry-ui";
import { TextInput } from "phoundry-ui";
let sm = $state<string | undefined>(undefined);
let snippetVal = $state<string | undefined>(undefined);
let customStatusText = $state("");
const statusBadgeColors: Record<string, "green" | "yellow" | "red" | "gray"> =
{
online: "green",
away: "yellow",
busy: "red",
offline: "gray",
};
const snippetOptions: SelectOption[] = [
{ value: "online", label: "Online" },
{ value: "away", label: "Away" },
{ value: "busy", label: "Busy" },
{ value: "offline", label: "Offline" },
];
</script>
{#snippet customInputRow()}
<TextInput
value={customStatusText}
oninput={(v: string) => (customStatusText = v)}
placeholder="Custom status..."
size="sm"
variant="fill"
/>
{/snippet}
{#snippet statusRow({
option,
selected,
}: {
option: SelectOption;
selected: boolean;
})}
<span class="flex min-w-0 flex-1 items-center gap-2">
<Badge color={statusBadgeColors[option.value]} dot />
<span class="truncate text-xs" class:font-medium={selected}
>{option.label}</span
>
</span>
{/snippet}
<p class="mb-2 text-xs text-txt-secondary">
Pass a <code>custom</code> object with a <code>snippet</code> for fully custom
rendering in both the dropdown and the trigger. Set
<code>selectable: false</code> to embed interactive content that doesn't trigger
selection.
</p>
<div class="max-w-xs">
<Select
options={[
...snippetOptions.map((o) => ({ ...o, custom: { snippet: statusRow } })),
{
value: "",
label: "",
custom: { snippet: customInputRow, selectable: false },
},
]}
value={snippetVal}
onchange={(v: string | undefined) => {
snippetVal = v;
}}
placeholder="Set status..."
/>
</div>
<p class="mt-2 text-xs text-txt-tertiary">Selected: {snippetVal ?? "none"}</p>

The dropdown shares floating panel and option-row styling with Context Menu. The size prop continues to scale only the trigger; selection, clearing, validation presentation, and form submission remain Select behavior.


API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
optionsrequiredOptionOrGroup[]—Flat options or option groups to display
valuerequiredT | undefined—Currently selected value
onchangerequired(value: T | undefined) => void—Called when selection changes
placeholderstring'Select...'Placeholder text when no value is selected
size"sm" | "md"'md'Trigger height aligned to Button sm / md control scale
disabledbooleanfalseDisables the select
variant"outline" | "ghost" | "filled"'filled'Visual style of the trigger (ghost is the minimal inline style).
shrinkbooleanfalseWhen true, trigger width fits content instead of full width
clearablebooleanfalseShows a clear button when a value is selected
searchablebooleanfalseShow an option-label search field in the dropdown; defaults to false
invalidbooleanfalseApplies error styling to the trigger
errorstring—Error message displayed below the select
idstring—HTML id attribute
selectedIndicator"check" | "background"'background'How the selected option is indicated in the dropdown
namestring—Hidden input name for form submission
elementbindableHTMLButtonElement—Bindable reference to the trigger button
classClassValue—Additive classes on the trigger button.
stylestring—Inline styles on the trigger button.

required: Reserved for HTML semantics - not wired to DOM attributes yet; use invalid / error for validation UX.

SelectOption

From phoundry-ui@0.4.21

NameTypeDefaultDescription
valuerequiredT—The value associated with this option
labelrequiredstring—Display text for the option (also used as accessible fallback)
descriptionstring—Secondary text shown below the label
iconstring—Iconify icon string shown before the label
customSelectOptionCustom<T>—Custom rendering config (see below)

SelectOptionCustom

From phoundry-ui@0.4.21

NameTypeDefaultDescription
snippetrequiredSnippet<[{ option: SelectOption<T>; selected: boolean; }]>—Svelte snippet that replaces the default option content
selectableboolean—When false, the option row is non-selectable (renders as a div for interactive content)

SelectOptionGroup

From phoundry-ui@0.4.21

NameTypeDefaultDescription
labelrequiredstring—Group header text
optionsrequiredSelectOption<T>[]—Options within this group

Usage tips

  • Use variant="ghost" when the select is inline within a toolbar or header.
  • Pass shrink to prevent the trigger from stretching to full width.
  • Combine invalid + error for form validation; the error renders below the trigger.
  • The dropdown renders as a portal-based overlay for correct z-index stacking.
  • Full keyboard navigation: Arrow keys, Enter/Space to select, Escape to close.
  • Pass name to emit a hidden input for plain HTML forms alongside the visible button trigger.

Styling

.ph-select is the stable root identification hook. Styling is component-local vanilla CSS; data-size always identifies the selected size on the trigger. The root wrapper is .ph-select; the trigger button is .ph-select-trigger. Consumer class, style, native attributes, attachments, and bind:element still target the trigger. The trigger emits data-size, data-variant, and data-placeholder, with open and invalid states represented by aria-expanded and aria-invalid. The wrapper emits data-shrink. Trigger heights use --ph-comp-h-sm (1.5rem) and --ph-comp-h-md (1.75rem), with --ph-comp-icon-sm / --ph-comp-icon-md for icons. The shared surface shadow uses --ph-input-shadow; the dropdown retains its fixed option scale. Internal part selectors and --_ph-* properties are implementation details.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.