# Single Select Menu > Input control allowing for choosing single option from searchable options menu. `SingleSelectMenu` is built on top of [Select Menu](/components/forms/select-menu/select-menu) parts which provide core functionality of the component. It is interchangeable with the [native Select component](/components/forms/select), but prettier and more powerful. ## Import ```js import { SingleSelectMenu } from '@gemini-suite/vera-react'; ``` Single Select Menu is a compound component that consists of multiple parts: - `SingleSelectMenu.Root`: The wrapper that contains all the parts of a select menu and provides context for its children. - `SingleSelectMenu.Trigger`: The button that toggles the select menu. - `SingleSelectMenu.Content`: A wrapper for the content to be rendered when the select menu is open. It positions itself by aligning over `SingleSelectMenu.Trigger`. - `SingleSelectMenu.Clear`: The button that clears the value of select menu. - `SingleSelectMenu.Item`: A container for select menu's item of choice. - `SingleSelectMenu.ItemText`: A wrapper around textual part of `SingleSelectMenu.Item`. - `SingleSelectMenu.ItemIndicator`: A visual cue in form of an icon that is displayed when the item is selected. - `SingleSelectMenu.Group`: A wrapper for the group of select menu items. - `SingleSelectMenu.Label`: The component that renders an accessible label of `SingleSelectMenu.Group`. - `SingleSelectMenu.Separator`: The component that renders a horizontal divider between menu items and groups. ## Examples ### Basic Provide `placeholder` prop when the select input does not have an initial value. `SingleSelectMenu` has built in typeahead behavior, meaning pressing the letter B will jump to and highlight the word "Banana" in the example below. ```jsx {'Apple'} {'Banana'} {'Orange'} ``` ### With a default value When using `SingleSelectMenu` in "uncontrolled" mode, you can specify the default selected option with `defaultValue` property. ```jsx {'White'} {'Red'} {'Green'} {'Purple'} ``` ### Controlled You can easily make the `SingleSelectMenu` controlled, by passing your own state to `value` prop. `onValueChange` handler is called when the selected value changes, allowing you to sync state. ```jsx () => { const [value, setValue] = React.useState('apple'); return ( {'Apple'} {'Banana'} {'Orange'} Selected value: {value} ); }; ``` ### With a clear button Use `SingleSelectMenu.Clear` part to render a button that clears the value of the select menu. Focus will automatically move back to the select menu trigger after the value is cleared. ```jsx } /> {'White'} {'Red'} {'Green'} {'Purple'} ``` ### Disabled The component can use `isDisabled` prop to prevent user from interacting, but also single items can be disabled to limit user's choice. ```jsx () => { const items = ['Carrot', 'Corn', 'Broccoli', 'Tomato', 'Paprika']; return ( {items.map(item => ( {item} ))} {items.map((item, index) => ( = 3} > {item} ))} ); }; ``` ### With Form Field Use [Form Field component](/components/forms/form-field) to enhance `SingleSelectMenu` with: an accessible label, an optional helper text, a feedback message or to show required indicator. It is recommended to wrap select inputs with [Form Field](/components/forms/form-field) to create a consistent set of accessible form fields. The [Form Field](/components/forms/form-field) automatically generates a unique id that links the `SingleSelectMenu` with the `FormField.Label`. When using `SingleSelectMenu` without [Form Field](/components/forms/form-field), be mindful to provide `aria-label` for `SingleSelectMenu.Trigger`. ```jsx () => { const [value, setValue] = React.useState(''); return ( {'Season'} } /> {'Winter'} {'Spring'} {'Summer'} {'Fall'} {'Choosing season is required.'} ); }; ``` ### Sizes `SingleSelectMenu` comes in two size variants: `medium` and `small`, with the `medium` size used by default. All sizes are aligned with sizes of other related components like [Text Input](/components/forms/text-input). ```jsx {'Timespan'} {'Quarter'} {'Half hour'} {'Hour'} {'Timespan'} {'Quarter'} {'Half hour'} {'Hour'} ``` ### Customized appearance `SingleSelectMenu.Trigger` and `SingleSelectMenu.Item` can be decorated with supporting icons or elements using `startElement` and `endElement` props. ```jsx () => { const [value, setValue] = React.useState(''); const minutes = { quarter: 15, halfHour: 30, hour: 60 }; return ( {'Timespan'} } endElement={ minutes[value] && ( ) } /> {'0.25 h'} } > {'Quarter'} {'0.5 h'} } > {'Half hour'} } endElement={ } > {'Hour'} ); }; ``` ### Active indicators When item inside the Single Select Menu is selected its text content is highlighted in bold. For additional emphasis you may include `SingleSelectMenu.ItemIndicator` to add a visual indicator rendered when the item is selected. ```jsx () => { const [value, setValue] = React.useState('buysell'); return ( } /> } > {'Buy'} } > {'Sell'} } > {'Buy & Sell'} } > {'None'} ); }; ``` ### Custom render value By default, `SingleSelectMenu.Trigger` will automatically display the selected item text content. However you can take control over the rendering by providing a function to the `renderValue` prop. The function receives getter for the selected item. The element returned by this function will be rendered inside the trigger. ```jsx ( {'Sort by'} {getSelectedItem().textValue} )} /> {'Newest update'} {'Oldest update'} {'Name A-Z'} {'Name Z-A'} ``` ### Groups Related options can be grouped together using `SingleSelectMenu.Group` with `SingleSelectMenu.Label` as a label for the group. Notice how overflowing content behaves when there is a long list of select menu items. ```jsx () => { const group = { Land: ['Cat', 'Dog', 'Tiger', 'Reindeer', 'Raccoon', 'Armadillo'], Water: ['Dolphin', 'Flounder', 'Eel'], Air: [ 'Falcon', 'Winged Horse', 'Owl', 'Raven', 'Parrot', 'Blue jay', 'Sparrow', 'Magpie', 'Pigeon', 'Canary', 'Kingfisher', 'Blackbird', 'Bald eagle', 'Hawk', 'Woodpecker' ] }; return ( {'Your favorite animal'} } /> {Object.entries(group).map(([name, animals], index) => ( {index !== 0 && } {name} {`(${animals.length})`} {animals.map(animal => ( {animal} ))} ))} ); }; ``` ### HTML Form integration `SingleSelectMenu` automatically uses hidden select part from [Select Menu](/components/forms/select-menu/select-menu) when it's used in the context of an HTML form. You just need to provide `name` property that will be used when submitting the form. ```jsx () => { const handleSubmit = event => { event.preventDefault(); const formData = new FormData(event.currentTarget); const formJson = Object.fromEntries(formData.entries()); alert(JSON.stringify(formJson)); }; return (
{'Name'} {'Country'} {'Norway'} {'Germany'} {'Poland'}
); }; ``` --- ## Accessibility features