Select
Selects allow users to choose a single option from a predefined list.
Quick Start
Use a Select when users need to choose one option from a list.
1import { 2Select, 3SelectContent, 4SelectItem, 5SelectTrigger, 6SelectValue 7} from "@ecos/ui"; 8 9<Select 10 label="Country" 11> 12 <SelectTrigger> 13 <SelectValue /> 14 </SelectTrigger> 15 16 <SelectContent> 17 <SelectItem value="uk">United Kingdom</SelectItem> 18 <SelectItem value="fr">France</SelectItem> 19 <SelectItem value="de">Germany</SelectItem> 20 </SelectContent> 21</Select>
Variants
Variants provide different visual treatments for the select control.
Outlined | Filled | Custom |
|---|---|---|
1<Select 2 label="Country" 3 variant="outlined" 4> 5 ... 6</Select> 7 8<Select 9 label="Country" 10 variant="filled" 11> 12 ... 13</Select> 14 15<Select 16 label="Country" 17 variant="custom" 18> 19 ... 20</Select>
Floating Labels
Labels automatically float when the select receives focus or contains a selected value.
1<Select 2 label="Country" 3 defaultValue="uk" 4> 5 <SelectTrigger> 6 <SelectValue /> 7 </SelectTrigger> 8 9 <SelectContent> 10 <SelectItem value="uk">United Kingdom</SelectItem> 11 <SelectItem value="fr">France</SelectItem> 12 </SelectContent> 13</Select>
Placeholders
Placeholders provide guidance before a value has been selected.
Country | Language | Time Zone |
|---|---|---|
1<Select 2 label="Country" 3 placeholder="Select a country" 4> 5 ... 6</Select> 7 8<Select 9 label="Language" 10 placeholder="Choose a language" 11> 12 ... 13</Select> 14 15<Select 16 label="Time Zone" 17 placeholder="Select a timezone" 18> 19 ... 20</Select>
Help Text
Use help text to provide additional context or instructions.
Select your country of residence.
1<Select 2 label="Country" 3 helpText="Select your country of residence." 4> 5 ... 6</Select>
Required Fields
Use the required prop to indicate a mandatory selection.
1<Select 2 label="Country" 3 required 4> 5 ... 6</Select>
Select States
Use the state prop to communicate validation feedback.
Please select a country.
Country selected successfully.
1<Select 2 label="Country" 3 state="default" 4> 5 ... 6</Select> 7 8<Select 9 label="Country" 10 state="error" 11 helpText="Please select a country." 12> 13 ... 14</Select> 15 16<Select 17 label="Country" 18 state="success" 19 helpText="Country selected successfully." 20 defaultValue="uk" 21> 22 ... 23</Select>
Disabled State
Disable a select when interaction is unavailable.
1<Select 2 label="Country" 3 defaultValue="uk" 4 disabled 5> 6 ... 7</Select>
Controlled Usage
Manage the selected value externally using React state.
1const [value, setValue] = useState(""); 2 3<Select 4 label="Country" 5 value={value} 6 onValueChange={setValue} 7> 8 <SelectTrigger> 9 <SelectValue /> 10 </SelectTrigger> 11 12 <SelectContent> 13 <SelectItem value="uk">United Kingdom</SelectItem> 14 <SelectItem value="fr">France</SelectItem> 15 </SelectContent> 16</Select>
Option Groups
Use groups and labels to organise related options.
1<Select label="Country"> 2 <SelectTrigger> 3 <SelectValue /> 4 </SelectTrigger> 5 6 <SelectContent> 7 <SelectGroup> 8 <SelectLabel>Europe</SelectLabel> 9 <SelectItem value="uk">United Kingdom</SelectItem> 10 <SelectItem value="fr">France</SelectItem> 11 </SelectGroup> 12 13 <SelectSeparator /> 14 15 <SelectGroup> 16 <SelectLabel>North America</SelectLabel> 17 <SelectItem value="us">United States</SelectItem> 18 <SelectItem value="ca">Canada</SelectItem> 19 </SelectGroup> 20 </SelectContent> 21</Select>
API Reference
Select
Property | Type | Default | Description |
|---|---|---|---|
| label | string | - | Floating label displayed for the select. |
| placeholder | string | - | Placeholder text displayed when no value is selected. |
| helpText | string | - | Supporting text displayed beneath the select. |
| variant | "outlined" | "filled" | "custom" | "outlined" | Controls the visual appearance of the select. |
| state | "default" | "error" | "success" | "default" | Displays validation and status styling. |
| required | boolean | false | Marks the field as required. |
| disabled | boolean | false | Prevents user interaction. |
| value | string | - | The controlled selected value. |
| defaultValue | string | - | The initial selected value. |
| onValueChange | (value: string) => void | - | Callback fired when the selected value changes. |
Select Trigger
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the trigger. |
| children | ReactNode | - | Typically contains a SelectValue component. |
Select Content
Property | Type | Default | Description |
|---|---|---|---|
| position | "popper" | "item-aligned" | "popper" | Controls how the dropdown is positioned relative to the trigger. |
| align | "start" | "center" | "end" | "center" | Aligns the dropdown content relative to the trigger. |
| className | string | - | Additional classes applied to the dropdown container. |
Select Item
Property | Type | Default | Description |
|---|---|---|---|
| value | string | - | Unique value associated with the item. |
| disabled | boolean | false | Prevents the item from being selected. |
| children | ReactNode | - | Content displayed for the option. |
Select Group
Property | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | - | Contains related select items and labels. |
Select Label
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the group label. |
Select Separator
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the separator. |
Visual Reference
Configuration | Preview |
|---|---|
| Outlined | |
| Filled | |
| Custom | |
| Required | |
| Error | Please select a country. |
| Success | Country selected successfully. |
| Disabled |