Component reference
Select
Single selection with a styled listbox or an explicit native option.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Loading the interactive example?
Width adapts to the available space
"use client";
import { useState } from "react";
import { Select } from "@pimolu/react";
export function SelectExample() {
const [value, setValue] = useState("design");
return (
<div className="space-y-4">
<Select label="Team" name="team" value={value} onValueChange={setValue} fullWidth>
<option value="design">Design</option>
<option value="engineering">Engineering</option>
<option
value="research"
disabled
>
Research (unavailable)
</option>
</Select>
<p role="status">Selected team: {value}.</p>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Sizes
From xs to xxl.
Variants
The semantic tone of the field.
Appearances
Outline, soft, filled and glass.
Usage
Declare literal option and optgroup children so the component can parse the choices. Use onValueChange for the styled path; native onChange belongs to native mode.
Use native when the platform menu is preferable. value/defaultValue are strings, and name enables form submission.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluSelectProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | undefined | "md" | Visual size, not the native HTML size. |
variant | "primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefined | "neutral" | Semantic color. |
appearance | "soft" | "outline" | "glass" | "filled" | undefined | "outline" | Visual appearance. |
label | string | undefined | — | Visible label. |
placeholder | string | undefined | — | Initial empty option. |
helperText | string | undefined | — | Supporting text below the field. |
errorMessage | string | undefined | — | Error text, replacing helper text. |
invalid | boolean | undefined | false | Explicit invalid state. |
fullWidth | boolean | undefined | false | Stretch to parent width. |
native | boolean | undefined | false | Render the native `<select>` instead of the styled listbox. The open menu is then drawn by the platform, which is the right choice on touch devices and in a strongly constrained environment. |
value | string | undefined | — | Controlled selection. |
defaultValue | string | undefined | — | Initial uncontrolled selection. |
onValueChange | ((value: string) => void) | undefined | — | Called with the selected value. This is the callback to use: the styled control reports every selection through it, while the native React `onChange` only fires when the platform menu is the one being used (`native`). |
containerClassName | string | undefined | — | Class applied to the outer container. |
onChange | ChangeEventHandler<HTMLSelectElement, HTMLSelectElement> | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLSelectElement> | undefined | — | Standard React/HTML attribute. |
disabled | boolean | undefined | false | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
required | boolean | undefined | false | Standard React/HTML attribute. |
size"xs" | "sm" | "md" | "lg" | "xl" | "xxl" | undefinedDefault: "md"
Visual size, not the native HTML size.
variant"primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefinedDefault: "neutral"
Semantic color.
appearance"soft" | "outline" | "glass" | "filled" | undefinedDefault: "outline"
Visual appearance.
labelstring | undefinedNo default extracted.
Visible label.
placeholderstring | undefinedNo default extracted.
Initial empty option.
helperTextstring | undefinedNo default extracted.
Supporting text below the field.
errorMessagestring | undefinedNo default extracted.
Error text, replacing helper text.
invalidboolean | undefinedDefault: false
Explicit invalid state.
fullWidthboolean | undefinedDefault: false
Stretch to parent width.
nativeboolean | undefinedDefault: false
Render the native `<select>` instead of the styled listbox. The open menu is then drawn by the platform, which is the right choice on touch devices and in a strongly constrained environment.
valuestring | undefinedNo default extracted.
Controlled selection.
defaultValuestring | undefinedNo default extracted.
Initial uncontrolled selection.
onValueChange((value: string) => void) | undefinedNo default extracted.
Called with the selected value. This is the callback to use: the styled control reports every selection through it, while the native React `onChange` only fires when the platform menu is the one being used (`native`).
containerClassNamestring | undefinedNo default extracted.
Class applied to the outer container.
onChangeChangeEventHandler<HTMLSelectElement, HTMLSelectElement> | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLSelectElement> | undefinedNo default extracted.
Standard React/HTML attribute.
disabledboolean | undefinedDefault: false
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
requiredboolean | undefinedDefault: false
Standard React/HTML attribute.
Accessibility
- Provide label or aria-label and meaningful option labels.
- Check arrow navigation, Enter and Escape. Disabled options stay visible and cannot be chosen.