{
  "name": "Select",
  "source": "src/components/Select.tsx",
  "propsType": "SelectProps",
  "description": "Select wraps a native `<select>` rather than rebuilding one.\n\nReact Aria's `useSelect` builds a listbox in a popover, which is the right\nanswer when the menu needs custom rows — but Figma models only the trigger\nhere, and the dropdown list is a separate component on the Menu page. Until\nthat is built, the native control is the honest match: it brings keyboard\nhandling, type-ahead and the platform picker on mobile for free, and it is\naccessible without any of it being reimplemented.\n\nFigma's six states map the same way Input's do — Hover and Focus from\ninteraction, Filled from whether a value is set, the rest from props.",
  "import": "import { Select } from 'ionbase-ui';",
  "status": "stable",
  "summary": "A dropdown over a native <select>, with the same label and error wiring as Input.",
  "useWhen": [
    "the user picks exactly one value from a known, modest list",
    "the native platform picker is acceptable — and on mobile it usually is the best option"
  ],
  "useInstead": [
    {
      "when": "the list is long enough to need search or type-ahead beyond the native behaviour",
      "use": "Combobox",
      "why": "a native <select> list is the browser's, and cannot be filtered"
    },
    {
      "when": "the rows need icons, avatars or two lines of text",
      "use": "Menu",
      "why": "Select wraps a native <select>, whose options can only be text"
    },
    {
      "when": "there are two or three mutually exclusive choices worth showing at once",
      "use": "RadioGroup"
    },
    {
      "when": "the user may pick more than one",
      "use": "MultiSelect",
      "why": "a native <select multiple> needs Ctrl or Cmd for a second pick and cannot filter; for a handful of options use CheckboxGroup"
    }
  ],
  "variants": {
    "size": {
      "sm": {
        "use": "dense forms, table filters"
      },
      "md": {
        "use": "the default"
      },
      "lg": {
        "use": "prominent single-field forms"
      }
    }
  },
  "a11y": {
    "guarantees": [
      "keyboard handling, type-ahead and the mobile platform picker come from the native <select> rather than being reimplemented",
      "label, helper and error wiring match Input"
    ],
    "requires": [
      "`label`, or `aria-label` when no visible label is rendered"
    ]
  },
  "antiPatterns": [
    {
      "dont": "passing rich React nodes as option content",
      "why": "this renders a native <select>; options are text only"
    },
    {
      "dont": "using a Select with two options for an on/off setting",
      "do": "Toggle",
      "why": "a two-item dropdown costs two interactions to do what one control does in one"
    }
  ],
  "deprecated": [
    {
      "prop": "disabled",
      "replacement": "isDisabled"
    }
  ],
  "stylesheet": "src/styles/select.css",
  "tokens": [
    "--border-default",
    "--border-disabled",
    "--border-error-strong",
    "--border-focus",
    "--border-strong",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-regular",
    "--icon-disabled",
    "--icon-size-md",
    "--icon-size-sm",
    "--icon-tertiary",
    "--ion-duration-base",
    "--ion-ease-out",
    "--ion-select-border-width",
    "--ion-select-font-size",
    "--ion-select-gap",
    "--ion-select-height",
    "--ion-select-icon-size",
    "--ion-select-line-height",
    "--ion-select-padding-x",
    "--ion-select-radius",
    "--radius-md",
    "--radius-sm",
    "--spacing-12",
    "--spacing-16",
    "--spacing-32",
    "--spacing-40",
    "--spacing-48",
    "--spacing-6",
    "--spacing-8",
    "--surface-default",
    "--surface-disabled",
    "--text-disabled",
    "--text-secondary",
    "--text-tertiary",
    "--type-body",
    "--type-body-line-height",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "size": {
      "type": "SelectSize | undefined",
      "required": false,
      "origin": "own",
      "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
      "values": [
        "sm",
        "md",
        "lg"
      ],
      "default": "md"
    },
    "options": {
      "type": "readonly SelectOption[] | undefined",
      "required": false,
      "origin": "own",
      "description": "The options to render. Omit and pass `children` for grouped options.\n\n`readonly` because an options list is almost always a module-level constant,\nand `as const` on one produces a readonly array that a mutable parameter\nrejects. The component only ever maps over it, so demanding a mutable array\nbought nothing and cost callers a spread or a cast."
    },
    "placeholder": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Text shown when nothing is selected. Renders as a disabled option so the\nfield can start empty without that being a valid choice."
    },
    "label": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Field label. Renders the Figma `Form Field` wrapper around the control."
    },
    "description": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Helper text below the field."
    },
    "errorMessage": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Replaces the helper text when `isInvalid` is set."
    },
    "isInvalid": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own"
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own"
    },
    "disabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "tags": {
        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
      }
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Class names for the control box (`.ion-select`). Always lands here —\nnever on the form-field wrapper. Use `wrapperClassName` for that."
    },
    "wrapperClassName": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
    }
  },
  "propCounts": {
    "own": 11,
    "aria": 0,
    "dom": 283,
    "other": 0
  }
}