XDSSelectorOption@xds/core · Selector
Preview coming soon

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

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

Anatomy

ElementDescription
LabelText label displayed above the selector.
PlaceholderHint text shown when no value is selected.
DescriptionHelper text providing additional context.
Left IconIcon displayed to the left of the selected value.
ValuerequiredThe currently selected item displayed in the selector.
ListrequiredThe dropdown list of selectable options.

Import

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

Props

PropTypeDescription
labelrequired
ReactNodePrimary label text for the item.
icon
XDSIconTypeIcon displayed before the label. See `npx xds docs icons` for valid semantic names.
description
ReactNodeSecondary 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>
  );
}