XDS — Design System

XDSSelectorOption@xds/core · Selector

Usage

A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.

Best practices

Guidance	Practices
Do	Provide a visible label so users understand what they are selecting.
Do	Use sections and dividers to organize options when the list exceeds ~8 items.
Do	Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select...").
Don't	Use for action menus — use Dropdown Menu for triggering commands or navigation.
Don't	Use when there are only two options — use a SegmentedControl or radio buttons instead.
Don't	Use Selector for navigation — links should be links, not dropdown options.
Don't	Use for yes/no or on/off choices — use Switch or CheckboxInput instead.
Don't	Put more than ~20 options without sections — consider Typeahead for large lists.

Anatomy

Element		Description
Label		Text label displayed above the selector.
Placeholder		Hint text shown when no value is selected.
Description		Helper text providing additional context.
Left Icon		Icon displayed to the left of the selected value.
Value	required	The currently selected item displayed in the selector.
List	required	The dropdown list of selectable options.

Import

ts
import {XDSSelectorOption} from '@xds/core/Selector'

Props

Prop	Type	Description
labelrequired	ReactNode	Primary label text for the item.
icon	XDSIconType	Icon displayed before the label. See `npx xds docs icons` for valid semantic names.
description	ReactNode	Secondary description text displayed below the label.

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';
import {XDSCenter} from '@xds/core/Center';
const UserIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" {...props}>
    <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" />
    <circle cx="12" cy="7" r="4" />
  </svg>
);
const descriptions: Record<string, string> = {
  admin: 'Full access to all resources',
  editor: 'Can edit and publish content',
  viewer: 'Read-only access',
  billing: 'Manage plans and payments',
};
const roles = [
  {value: 'admin', label: 'Admin'},
  {value: 'editor', label: 'Editor'},
  {value: 'viewer', label: 'Viewer'},
  {value: 'billing', label: 'Billing'},
];
export default function SelectorOptionShowcase() {
  const [value, setValue] = useState<string | undefined>('editor');
  return (
    <XDSCenter width={280}>
      <XDSSelector
        label="Role"
        options={roles}
        value={value}
        onChange={setValue}
        placeholder="Assign a role...">
        {option => (
          <XDSSelectorOption
            icon={UserIcon}
            label={option.label}
            description={descriptions[option.value]}
          />
        )}
      </XDSSelector>
    </XDSCenter>
  );
}