Select

Guidelines
React API Reference
Blazor API Reference

Select components allow users to choose a single option from a dropdown list, providing a space-efficient way to present multiple options without cluttering the interface.

Guidance

Aspect	Best Practice
Usage	Use select components for single-choice selections from lists with more than 5-7 options. For fewer options, consider radio buttons for better visibility.
Content	Provide clear option labels. Group related options when the list is long. Include a meaningful default selection or placeholder.
Behavior	Display selected option when collapsed. Support keyboard navigation. Close on selection, escape key, or outside click.
States	Clearly indicate focus, hover, selected, disabled, and error states. Show loading state when options are fetched asynchronously.
Feedback	Provide immediate visual feedback when an option is selected. Clearly indicate when the dropdown is open or closed.
Examples	Country selection, category filters, preference settings, or any single-selection from a predefined list.

Best Practices

Clear Default State: Provide a meaningful default selection or descriptive placeholder text.
Logical Organization: Group related options and consider alphabetical ordering for long lists.
Keyboard Accessibility: Ensure users can navigate and select options using arrow keys, Enter, and Escape.
Visual Distinction: Make the currently selected option clearly visible in both open and closed states.
Error Handling: Provide clear validation messages when an invalid or required selection is not made.

Do’s and Don’ts

Do

Provide clear, descriptive option labels.
Group related options in long lists.
Ensure keyboard accessibility.
Show a meaningful default or placeholder.

Don't

Use for fewer than 5 options (consider radio buttons).
Create overly long lists without grouping or search.
Hide or disable options without explanation.
Rely solely on color to indicate selection.

Additional Guidance

Psychological Impact:
- Choice Architecture: Select dropdowns help manage complexity by hiding options until needed.
- Decision Fatigue: Well-organized options reduce the cognitive load of making selections.
- Familiarity: Select components leverage a widely understood interaction pattern that feels familiar to users.

Import

import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem
} from '@strongtie/design-system/select';

Usage

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Option 1</SelectItem>
    <SelectItem value="option2">Option 2</SelectItem>
    <SelectItem value="option3">Option 3</SelectItem>
  </SelectContent>
</Select>

`<Select>` Props

defaultValue

string

The default value of the select.

value

string

The controlled value of the select.

onValueChange

function

Callback function that is called when the value changes.

defaultOpen

boolean

default:"false"

If true, the select will be open by default.

open

boolean

If true, the select will be open.

onOpenChange

function

Callback function that is called when the open state changes.

dir

"ltr" | "rtl"

default:"ltr"

The direction of the select.

name

string

The name of the select.

disabled

boolean

default:"false"

If true, the select will be disabled.

required

boolean

default:"false"

If true, the select is required.

`<SelectContent>` Props

asChild

boolean

default:"false"

If true, the select content will render as a child component.

onCloseAutoFocus

function

Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.

onEscapeKeyDown

function

Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.

onPointerDownOutside

function

Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.

position

"item-aligned" | "popper"

default:"item-aligned"

The positioning mode to use, item-aligned is the default and behaves similarly to a native MacOS menu by positioning content relative to the active item.

side

"top" | "right" | "bottom" | "left"

default:"bottom"

The side of the trigger to position the content.

sideOffset

number

default:"0"

The distance in pixels from the anchor. Only available when position is set to popper.

align

"start" | "center" | "end"

default:"start"

The alignment of the content when side is set to “right” or “left”.

alignOffset

number

default:"0"

An offset in pixels from the “start” or “end” alignment options. Only available when position is set to popper.

avoidCollisions

boolean

default:"true"

When true, overrides the side andalign preferences to prevent collisions with boundary edges.

collisionBoundary

Boundary

The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. Only available when position is set to popper.

collisionPadding

number | Padding

default:"10"

The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. Only available when position is set to popper.

arrowPadding

number

default:"0"

The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. Only available when position is set to popper.

sticky

"partial" | "always"

default:"partial"

The sticky behavior on the align axis. “partial” will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst “always” will keep the content in the boundary regardless. Only available when position is set to popper.

hideWhenDetached

boolean

default:"false"

Whether to hide the content when the trigger becomes fully occluded. Only available when position is set to popper.

`<SelectValue>` Props

asChild

boolean

default:"false"

If true, the select value will render as a child component.

placeholder

string

The placeholder text for the select value.

`<SelectItem>` Props

asChild

boolean

default:"false"

If true, the select item will render as a child component.

value

string

required

The value of the select item.

disabled

boolean

default:"false"

If true, the select item will be disabled.

textValue

string

Optional text used for typeahead purposes.

`<SelectSeparator>`, `<SelectScrollUpButton>`, `<SelectScrollDownButton>`, `<SelectGroup>`, `<SelectLabel>`, `<SelectTrigger>` Props

asChild

boolean

default:"false"

If true, the select separator will render as a child component.

Styling Classes

The following CSS classes are applied by the Select components:

select-trigger – Select trigger button
select-icon – Dropdown arrow icon
select-content – Dropdown content container
select-content-popper – Popper-positioned content modifier
select-viewport – Content viewport wrapper
select-viewport-popper – Popper-positioned viewport modifier
select-scroll-button – Scroll up/down buttons
select-label – Option group label
select-item – Individual select option
select-item-indicator – Selected item indicator wrapper
select-separator – Option separator line

For more examples, visit the Storybook.

Example

<StudsSelect TValue="string" Value="@value" Data="@companyNames" />

@code {
    string value = "CompanyName";
    IEnumerable<string> companyNames = new List<string>();

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();

        companyNames = new List<string>
        {
            "CompanyName 1",
            "CompanyName 2"
        };
    }
}

Parameters

InputAttributes

IReadOnlyDictionary<string, Object>

Additional attributes to be added to the input element.

ReadOnly

bool

default:"false"

Gets or sets a value indicating whether is read only.

ValueTemplate

RenderFragment<Object>

The template to render the selected value.

EmptyTemplate

RenderFragment

The template to render when the dropdown is empty.

OpenOnFocus

bool

default:"false"

If true, the dropdown will open when the input is focused.

ItemRender

Action<DropDownItemRenderEventArgs<TValue>>

Gets or sets the row render callback. Use it to set row attributes.

Gets or sets the Popup height.

Open

EventCallback

Callback for when a dropdown is opened.

EventCallback

Callback for when a dropdown is closed.

AllowVirtualization

bool

default:"false"

Specifies wether virtualization is enabled.

VirtualizationOverscanCount

int

default:"10"

Gets or sets a value that determines how many additional items will be rendered before and after the visible region.

Count

int

Specifies the total number of items in the data source.

Data

IEnumerable

The data source.

DisabledProperty

string

The property name that indicates if an item is disabled.

EmptyAriaLabel

string

The aria label for the empty dropdown.

HasValue

bool

Gets or sets a value indicating whether the dropdown has a value.

HeaderTemplate

RenderFragment

The template to render the header.

ItemComparer

IEqualityComparer<object>

For lists of objects, an IEqualityComparer to control how selected items are determined

Items

IEnumerable<object>

Gets the items.

Gets the popup identifier.

SelectedItem

object

Gets or sets the selected item.

SelectedItemChanged

EventCallback<object>

Gets or sets the selected item changed.

Template

RenderFragment<dynamic>

Gets or sets the template.

ValueProperty

string

Gets or sets the value property.

Virtualize

Microsoft.AspNetCore.Components.Web.Virtualization.Virtualize<object>

The Virtualize instance.

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

Styling Classes

The following CSS classes are applied by the Select component:

select-panel – Single-select dropdown panel
select-label – Selected value display area
select-trigger – Dropdown trigger button
select-clear-icon – Clear selection icon
select-filter-container – Filter input container
select-filter – Filter input field
select-filter-icon – Filter search icon
select-items-wrapper – Items list container
select-items – Items list element

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<Select>` Props

`<SelectContent>` Props

`<SelectValue>` Props

`<SelectItem>` Props

`<SelectSeparator>`, `<SelectScrollUpButton>`, `<SelectScrollDownButton>`, `<SelectGroup>`, `<SelectLabel>`, `<SelectTrigger>` Props

Styling Classes

Parameters

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Select> Props

​<SelectContent> Props

​<SelectValue> Props

​<SelectItem> Props

​<SelectSeparator>, <SelectScrollUpButton>, <SelectScrollDownButton>, <SelectGroup>, <SelectLabel>, <SelectTrigger> Props

​Styling Classes

​Parameters

​Styling Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<Select>` Props

`<SelectContent>` Props

`<SelectValue>` Props

`<SelectItem>` Props

`<SelectSeparator>`, `<SelectScrollUpButton>`, `<SelectScrollDownButton>`, `<SelectGroup>`, `<SelectLabel>`, `<SelectTrigger>` Props

Styling Classes

Parameters

Styling Classes