Cascader

Cuadro de selección en cascada para datos jerárquicos como ubicaciones o categorías.

Importar

import { Cascader } from 'asterui'

Ejemplos

Básico

Selección jerárquica simple.

import { Cascader } from 'asterui'

function App() {
  const options = [
    {
      value: 'usa',
      label: 'United States',
      children: [
        {
          value: 'ca',
          label: 'California',
          children: [
            { value: 'sf', label: 'San Francisco' },
            { value: 'la', label: 'Los Angeles' },
          ],
        },
        {
          value: 'ny',
          label: 'New York',
          children: [
            { value: 'nyc', label: 'New York City' },
            { value: 'buf', label: 'Buffalo' },
          ],
        },
      ],
    },
  ]
  
  return (
      <Cascader options={options} placeholder="Select location" />
    )
}

export default App

Expandir al Pasar

Expandir submenús al pasar el mouse.

import { Cascader } from 'asterui'

function App() {
  const options = [
    {
      value: 'electronics',
      label: 'Electronics',
      children: [
        {
          value: 'phones',
          label: 'Phones',
          children: [
            { value: 'iphone', label: 'iPhone' },
            { value: 'android', label: 'Android' },
          ],
        },
        {
          value: 'computers',
          label: 'Computers',
          children: [
            { value: 'laptop', label: 'Laptop' },
            { value: 'desktop', label: 'Desktop' },
          ],
        },
      ],
    },
  ]
  
  return (
      <Cascader options={options} expandTrigger="hover" placeholder="Select category" />
    )
}

export default App

Tamaños

Diferentes tamaños de cascader.

import { Cascader } from 'asterui'

function App() {
  const options = [
    { value: 'opt1', label: 'Option 1' },
    { value: 'opt2', label: 'Option 2' },
  ]
  
  return (
      <div className="flex flex-col gap-2">
        <Cascader size="xs" options={options} placeholder="Extra small" />
        <Cascader size="sm" options={options} placeholder="Small" />
        <Cascader size="md" options={options} placeholder="Medium" />
        <Cascader size="lg" options={options} placeholder="Large" />
      </div>
    )
}

export default App

Deshabilitado

Estado deshabilitado del cascader.

import { Cascader } from 'asterui'

function App() {
  const options = [
    { value: 'opt1', label: 'Option 1' },
    { value: 'opt2', label: 'Option 2' },
  ]
  
  return (
      <Cascader options={options} disabled value={['opt1']} />
    )
}

export default App

Buscar

Habilitar funcionalidad de búsqueda/filtro.

import { Cascader } from 'asterui'

function App() {
  const options = [
    {
      value: 'usa',
      label: 'United States',
      children: [
        {
          value: 'ca',
          label: 'California',
          children: [
            { value: 'sf', label: 'San Francisco' },
            { value: 'la', label: 'Los Angeles' },
          ],
        },
      ],
    },
  ]
  
  return (
      <Cascader options={options} showSearch placeholder="Search locations" />
    )
}

export default App

Cambiar al Seleccionar

Permitir selección de cualquier nivel, no solo nodos hoja.

Selected: None

import { Cascader } from 'asterui'
import { useState } from 'react'

function App() {
  const [value, setValue] = useState<string[]>([])
  const options = [
    {
      value: 'usa',
      label: 'United States',
      children: [
        { value: 'ca', label: 'California' },
        { value: 'ny', label: 'New York' },
      ],
    },
  ]
  
  return (
      <div>
        <Cascader
          options={options}
          changeOnSelect
          value={value}
          onChange={setValue}
          placeholder="Select any level"
        />
        <p className="mt-2 text-sm">Selected: {value.join(' / ') || 'None'}</p>
      </div>
    )
}

export default App

Carga Asíncrona

Cargar opciones dinámicamente al expandir.

import { Cascader } from 'asterui'
import { useState } from 'react'

function App() {
  const [options, setOptions] = useState<CascaderOption[]>([
    { value: 'region1', label: 'Region 1' },
    { value: 'region2', label: 'Region 2' },
  ])
  
  const loadData = async (selectedOptions: CascaderOption[]) => {
    const targetOption = selectedOptions[selectedOptions.length - 1]
    await new Promise(resolve => setTimeout(resolve, 1000))
  
    setOptions(prev => {
      const update = (opts: CascaderOption[]): CascaderOption[] =>
        opts.map(opt =>
          opt.value === targetOption.value
            ? {
                ...opt,
                children: [
                  { value: `${opt.value}-1`, label: 'Child 1', isLeaf: true },
                  { value: `${opt.value}-2`, label: 'Child 2', isLeaf: true },
                ],
              }
            : { ...opt, children: opt.children ? update(opt.children) : undefined }
        )
      return update(prev)
    })
  }
  
  return (
      <Cascader options={options} loadData={loadData} placeholder="Load on expand" />
    )
}

export default App

Estado de Validación

Mostrar estado de validación de error o advertencia.

import { Cascader } from 'asterui'

function App() {
  const options = [
    { value: 'opt1', label: 'Option 1' },
    { value: 'opt2', label: 'Option 2' },
  ]
  
  return (
      <div className="flex flex-col gap-2">
        <Cascader options={options} status="error" placeholder="Error state" />
        <Cascader options={options} status="warning" placeholder="Warning state" />
      </div>
    )
}

export default App

Selección Múltiple

Seleccionar múltiples valores hoja.

import { Cascader } from 'asterui'

function App() {
  const options = [
    {
      value: 'fruits',
      label: 'Fruits',
      children: [
        { value: 'apple', label: 'Apple' },
        { value: 'banana', label: 'Banana' },
      ],
    },
    {
      value: 'vegetables',
      label: 'Vegetables',
      children: [
        { value: 'carrot', label: 'Carrot' },
        { value: 'lettuce', label: 'Lettuce' },
      ],
    },
  ]
  
  return (
      <Cascader options={options} multiple placeholder="Select multiple" />
    )
}

export default App

API

`Cascader`

Propiedad	Descripción	Tipo	Predeterminado
`options`	Datos de opciones jerárquicas	`CascaderOption[]`	`[]`
`value`	Ruta de valor seleccionado controlado	`string[]`	-
`defaultValue`	Valor seleccionado predeterminado (no controlado)	`string[]`	`[]`
`onChange`	Callback cuando cambia la selección	`(value: string[], selectedOptions: CascaderOption[]) => void`	-
`placeholder`	Texto de marcador de posición de entrada	`string`	`'Please select'`
`disabled`	Deshabilitar el cascader	`boolean`	`false`
`allowClear`	Mostrar botón de limpiar	`boolean`	`true`
`expandTrigger`	Cómo expandir submenús	`'click' \| 'hover'`	`'click'`
`changeOnSelect`	Permitir selección de cualquier nivel, no solo hojas	`boolean`	`false`
`displayRender`	Función de renderizado de visualización personalizada	`(labels: ReactNode[], selectedOptions: CascaderOption[]) => ReactNode`	-
`size`	Tamaño de entrada	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'md'`
`color`	Color del anillo de foco	`'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'`	-
`status`	Estado de validación	`'error' \| 'warning'`	-
`showSearch`	Habilitar funcionalidad de búsqueda	`boolean \| { filter?, render?, matchInputWidth? }`	`false`
`notFoundContent`	Contenido cuando no hay resultados de búsqueda	`ReactNode`	`'No results found'`
`loadData`	Función de carga de datos asíncrona	`(selectedOptions: CascaderOption[]) => Promise<void>`	-
`fieldNames`	Nombres de campo personalizados para mapeo de datos	`{ label?: string; value?: string; children?: string }`	-
`open`	Estado abierto controlado del desplegable	`boolean`	-
`onDropdownVisibleChange`	Callback cuando cambia la visibilidad del desplegable	`(open: boolean) => void`	-
`popupClassName`	Nombre de clase para desplegable	`string`	-
`dropdownRender`	Renderizado personalizado del envoltorio del desplegable	`(menu: ReactNode) => ReactNode`	-
`multiple`	Habilitar modo de selección múltiple	`boolean`	`false`
`maxTagCount`	Máximo de etiquetas a mostrar en modo múltiple	`number \| 'responsive'`	-
`className`	Clases CSS adicionales	`string`	-

`CascaderOption`

Propiedad	Descripción	Tipo	Predeterminado
`value`	Identificador único	`string`	-
`label`	Etiqueta de visualización	`ReactNode`	-
`children`	Opciones hijas	`CascaderOption[]`	-
`disabled`	Deshabilitar esta opción	`boolean`	`false`
`isLeaf`	Forzar como nodo hoja (sin expandir, sin carga asíncrona)	`boolean`	-

Accesibilidad

El componente Cascader sigue el patrón de combobox WAI-ARIA:

Usa role="combobox" en el disparador con aria-expanded, aria-haspopup
aria-activedescendant rastrea la opción enfocada para lectores de pantalla
aria-selected indica el estado seleccionado en las opciones
aria-disabled indica el estado deshabilitado
El botón de limpiar tiene aria-label="Clear selection"

Navegación por Teclado

Tecla	Acción
Abajo	Abrir desplegable o moverse a la siguiente opción
Arriba	Moverse a la opción anterior
Derecha	Moverse a la siguiente columna (expandir)
Izquierda	Moverse a la columna anterior
Enter	Seleccionar opción enfocada o abrir desplegable
Espacio	Alternar desplegable (cuando no está buscando)
Escape	Cerrar desplegable
Inicio	Moverse a la primera opción
Fin	Moverse a la última opción

Testing

El componente incluye atributos de datos para testing:

data-testid="cascader" en el contenedor raíz
data-testid="cascader-dropdown" en el desplegable
data-testid="cascader-option-{value}" en cada opción
data-testid="cascader-clear" en el botón de limpiar
data-state="open|closed" en la raíz indica el estado del desplegable
data-state="selected|hovered" en las opciones indica el estado
data-value="{value}" en las opciones proporciona el valor