Select

The <Select> is a form component that allows you to select one or more elements from a list of predefined options. It should be used with other form components in a <Form>.

Anatomy

A select contains a pressable button element with a down arrow. The lists of options opens per default below the button, if there is no space for it, it will open above. An option represent a possible choice the user can select.

Optional you have the choice to add a section to the options which helps divide the content of options in categories. You can have the possibility to add a supporting text as short description and/ or error message to the select itself. The description will be relplaced with the error message when an error throws. Also you can have a description for the options in the list.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

The select should be used within a form. It supports an optional description which can be used to provide more context about the field.

As with all form components, the label should always describe what the user expects to achieve. If additional informations is required you can use the description to give a short information for displaying these, or you can provide a placeholder which should represent what is to select.

Number of options

If there are very few options (e.g., 1-4), consider using a radio group instead. These can be easier for users to scan and select.

A select is typically suitable for a moderate number of options (e.g., 5-15). This keeps the list manageable and quick to navigate.

When there are too many options (e.g., more than 15-20), usability can suffer. Users might find it cumbersome to scroll through a long list. In such cases, consider alternative approaches like a autocomplete or combobox.

Do

Use a around 5-15 options for the select.

Don't

Don't use a select if there are less than 4 or more than 15 options to choose from.

With sections

When related options are present, organizing them into sections enhances clarity and usability. Grouping options provides additional context and helps users navigate choices more easily. This approach reduces complexity and allows for additional guidance when needed, ensuring a more intuitive experience.

This can be achieved by wrapping the options in the <Select.Section> component. A header is required for each section, which is set using the header prop.

import { Select } from '@marigold/components';export default () => (  <Select label="Genres" width="fit">    {options.map(item => (      <Select.Section key={item.category} header={item.category}>        {item.genres.map(genre => (          <Select.Option key={genre}>{genre}</Select.Option>        ))}      </Select.Section>    ))}  </Select>);const options = [  {    category: 'Pop and Dance',    genres: ['Pop', 'Electropop', 'Dance-pop', 'Teen pop', 'Disco'],  },  {    category: 'Rock and Alternative',    genres: [      'Hard rock',      'Punk rock',      'Alternative rock',      'Indie rock',      'Grunge',    ],  },  {    category: 'Hip-Hop and R&B',    genres: ['Hip-Hop', 'Rap', 'Trap', 'R&B'],  },];

Item description

If you need to have primary and secondary content shown within an option, you can use our text component with the slot property and set it for the label and description to add a short description for secondary content, which provides more context for the certain selectable option.

import { Select, Text } from '@marigold/components';export default () => (  <Select label="Permissions" width="fit">    <Select.Option id="read" textValue="Read">      <Text slot="label">Read</Text>      <Text slot="description" fontSize="xs">        Read only      </Text>    </Select.Option>    <Select.Option id="write" textValue="Write">      <Text slot="label">Write</Text>      <Text slot="description" fontSize="xs">        Read and write only      </Text>    </Select.Option>    <Select.Option id="admin" textValue="Admin">      <Text slot="label">Admin</Text>      <Text slot="description" fontSize="xs">        Full access      </Text>    </Select.Option>  </Select>);

Disabled keys

Sometimes depending on other settings it can be that a select needs to have disabled options to show up. For this case you can set keys disabled through the disabledKeys property.

Keep in mind that you always should write information why a certain option is disabled near the disabled option.

import { Select } from '@marigold/components';export default () => (  <Select    label="Shipping direction"    disabledKeys={['germany', 'elsalvador', 'poland']}    description="Please select the shipping direction, not every country can be available."    width="fit"  >    <Select.Option id="czechrepublic">Czech Republic</Select.Option>    <Select.Option id="egypt">Egypt</Select.Option>    <Select.Option id="elsalvador">El Salvador</Select.Option>    <Select.Option id="germany">Germany</Select.Option>    <Select.Option id="hungary">Hungary</Select.Option>    <Select.Option id="india">India</Select.Option>    <Select.Option id="nigeria">Nigeria</Select.Option>    <Select.Option id="poland">Poland</Select.Option>    <Select.Option id="portugal">Portugal</Select.Option>    <Select.Option id="ukraine">Ukraine</Select.Option>  </Select>);

Multiselection

Sometimes you need to offer a way for users to select multiple options from a list, but you don't have much room in your layout. In these situations, enabling multiselection (selectionMode="multiple") on the <Select> is an effective approach. A common use case for this is when filtering a list of products. For instance, a user could select both a specific brand and a particular feature, and the dropdown would neatly contain both selections.

However, be mindful of the user experience when offering multiple selections. As more options are chosen, the display text will likely be truncated, hiding the full list of what's been selected. Note that for use cases requiring all selected options to be clearly visible, a dedicated Multiselect component might be a better choice.

import { amenitiesOptions } from '@/lib/data/venues';import { Select } from '@marigold/components';export default () => (  <Select label="Amenities" width={72} selectionMode="multiple">    {amenitiesOptions.map(option => (      <Select.Option key={option} id={option}>        {option}      </Select.Option>    ))}  </Select>);

Additional visuals

Icons or images can be added to options to provide immediate visual context and help users differentiate between items at a glance. Use these visual elements when they add meaningful value, such as representing different categories, user profiles, or status indicators.

Visual elements are processed faster than text, reducing cognitive load and helping users make selections more quickly. However, ensure that options remain understandable even without the visuals for accessibility purposes.

import { people } from '@/lib/data/people';import { Inline, Select, Text } from '@marigold/components';export default () => (  <Select label="Assign to User" placeholder="Select a user" width={80}>    {people.map(person => (      <Select.Option key={person.id} id={person.id}>        <Inline space={2} alignY="center">          <img            src={person.avatar}            alt={person.name}            className="size-6 rounded-full object-cover"          />          <Text slot="label">{person.name}</Text>        </Inline>        <Text slot="description">{person.position}</Text>      </Select.Option>    ))}  </Select>);

Props

Select

Select.Option

Select.Section

Alternative components

• Autocomplete: A searchfield that displays a dynamic list of suggestions. Useful when there are more than 15 options and you need to search for a specific value.

• Combobox: A text field that allows the user to select values from a provided items array. Useful when there are mote than 15 options.

• Radio: Component which allows to select only one option from a list. Use it if you have less than 5 options.

Related