Single Select Field – Design

​

Anatomy

The Select Field consists of eight elements that work together to allow users to search and select a single value from a list of options.

1. Placeholder text
2. Popover
3. Option
4. Selected value
5. Selected options overflow
6. Clear button (Optional)
7. Section header
8. Rich content option

​

Options

The Select Field supports the following configurations to accommodate a wide range of selection scenarios.

​

Selection options

​

Search

By default, Select Field provides a searchable text input that filters options as users type.

​

Select-only

When search adds no value — such as with short, well-known option lists — disable it to present a simpler select-only trigger. The select-only mode uses the listbox ARIA pattern instead of combobox.

​

Menu display options

Select Field displays options in a popover by default on desktop and a dialog on mobile. Override this adaptive behavior by setting the display mode explicitly to always use a popover or always use a dialog.

​

In a Popover

​

In a Dialog

​

Sections

Sections divide options into labeled groups, helping users scan and identify related items. Every section requires a label.

​

Pinned sections

Sections can be pinned to the top of the list. Pinned sections are useful for surfacing frequently used options, recent selections, or AI-powered suggestions without requiring the user to search for them.

​

Rich content

Options support rich content including titles, descriptions, avatars, icons, and chips. Rich content helps users distinguish between similarly named items or convey additional metadata at a glance.

​

Lazy loading options

For large datasets, options load on demand as users scroll through the list. Three pagination strategies are supported: page-based, offset-based, and group-based. Results are cached by default to avoid redundant requests.

​

Field Options

​

Sizes

Three sizes are available: small, medium, and large. Choose a size that aligns with the surrounding form layout and density.

​

Prefix and suffix

Add content before or after the input to provide additional context, such as currency symbols or units.

​

Behavior

The Select Field responds to user interaction with search filtering and distinct visual states.

​

Visual states

Select Field supports standard form field states. Disabled prevents all interaction. Read-only allows viewing options without changing the selection. Error highlights validation issues with a message. Required marks the field as mandatory with a visual indicator.

​

Search and filtering

In combobox mode, typing in the input filters options in real time. Results are ranked by match quality so the most relevant options appear first. Search input is automatically debounced to reduce unnecessary requests when loading options asynchronously.

​

Usage Guidelines

​

When to Use

Use the Select Field when you need to:

• Select a single option from a medium-to-large set of options
• Provide typeahead search to help users narrow results
• Load options from a server with pagination support
• Organize options into groups or pinned sections
• Display a simplified, opinionated select experience in a form

​

When not to use

Avoid using the Select Field for:

• There are only a few items to choose from. A radio or checkbox group may be more appropriate.
• When a particularly complex selection interaction is needed, in which case a Listbox in a special layout may be preferred.
• In navigational contexts.

​

Alternatives

​

Select Field vs Combobox

Select Field is the eventual replacement for the Combobox component. Use Select Field when looking for features such as Dialog viewing, standardized content display, secondary actions, sectioning, or lazy loading. Consider using the Combobox if needing a stable component in your application.

​

Select Field vs Select Trigger

Select Field displays options in a built-in Popover or Dialog with integrated search and filtering. Select Trigger opens a custom overlay — typically a Dialog — that the implementor fully controls.

​

How to Use

​

Labels and help

For guidance on labels, placeholders, and help text, refer to the Form pattern.

​

Sorting options

Select Field does not prescribe how options are sorted. Common sorting strategies include alphabetical, time-based, and categorical. Choose a sort order that matches user expectations for the data.

​

Content

Content within the Select Field should clearly communicate available options and help users identify the correct selection.

• Use clear, concise option labels that users recognize immediately
• Add descriptions to rich content options when labels alone are insufficient to distinguish items
• Use pinned sections to surface frequently used or contextually relevant options

For additional content guidance, refer to the Form pattern.

​

Keyboard Interaction

Users can navigate the Select Field using standard keyboard controls. Keyboard behavior differs between combobox mode (search enabled) and select mode (search disabled).

​

Search enabled

​

Text field

​

Popup

​

Search disabled

​

Accessibility

Anvil provides accessibility support for Select Field out of the box. In combobox mode, the component follows the combobox ARIA pattern. In select mode, it follows the listbox ARIA pattern. For more guidance on building accessible form controls, see custom component best practices.