# CountryPicker

> Un país de la lista ISO, con su bandera y el nombre en el idioma de la app. Se escribe para filtrar, sin tildes.

```tsx
import { CountryPicker } from "sebs7n-ui/country-picker"
```

## Ejemplos

### Básico

Los 249 países con su bandera, por nombre en el idioma de la app. Se escribe sin tildes: «peru» encuentra «Perú».

```tsx
import { CountryPicker } from "sebs7n-ui/country-picker"
import { Field, FieldLabel } from "sebs7n-ui"

function Basic() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>País de facturación</FieldLabel>
      <CountryPicker defaultValue="AR" name="country" />
    </Field>
  )
}
```

### SomeCountries países

`countries` limita la lista; se ordena por nombre.

```tsx
import { CountryPicker } from "sebs7n-ui/country-picker"
import { Field, FieldLabel } from "sebs7n-ui"

function SomeCountries() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>País del emisor</FieldLabel>
      <CountryPicker countries={["AR", "UY", "CL", "PY", "BR"]} />
    </Field>
  )
}
```

## Props

### CountryPicker

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `aria-describedby` | `string` | — | El `id` de la ayuda o del error del campo. |
| `aria-invalid` | `boolean` | — | Marca el campo inválido (borde rojo). |
| `aria-label` | `string` | — | Nombre accesible del elemento. |
| `aria-labelledby` | `string` | — | El `id` del elemento que nombra el campo, si no es un `<label>`. |
| `countries` | `readonly string[]` | `COUNTRY_CODES` | Los países de la lista, si no son todos. En el orden que sea: se ordenan por nombre. |
| `defaultValue` | `string` | `null` | El valor inicial. Es la versión no controlada de `value`. |
| `disabled` | `boolean` | — | Apaga el campo. |
| `id` | `string` | — | El `id` del campo, para un `<Label htmlFor>`. |
| `labels` | `Partial<Labels["countryPicker"]>` | — | Textos: `locale` (el idioma de los nombres) y `placeholder`. «Limpiar» y «Sin resultados» son los de `combobox`. |
| `locale` | `string` | — | El idioma de los nombres. Por defecto, el de `labels` (`countryPicker.locale`, `es-AR`). |
| `name` | `string` | — | El nombre con el que el código viaja en un formulario. |
| `onValueChange` | `(value: string \| null) => void` | — | Avisa el código elegido, o `null` al limpiar. |
| `placeholder` | `string` | — | Lo que dice el campo vacío. Por defecto, `labels.placeholder` («Elegí un país»). |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 28, 36 (default) o 40, como los campos. |
| `value` | `string` | — | El país elegido, código ISO 3166-1 alfa-2 («AR»). `null` es ninguno. Pasarlo lo vuelve controlado. |
| `className` | `string` | — | Clases de la superficie. |

## Teclado

| Tecla | Qué hace |
|---|---|
| a–z | Filtran por nombre, sin tildes ni mayúsculas, o por código ISO («US» es Estados Unidos, y va primero); la primera coincidencia queda resaltada. |
| ↓ / ↑ | Abren la lista y la recorren. |
| Enter | Elige el país resaltado. |
| Escape | Cierra la lista. |

## Accesibilidad

- Es un `combobox` con `listbox` de `Combobox`: **nombre obligatorio** con `aria-label`, `aria-labelledby` o un `FieldLabel`.
- La bandera es decorativa (`aria-hidden`): la opción se lee por el nombre.
- «Sin resultados» sale en la región viva del combobox.

## Reglas de uso

- El valor es el código ISO 3166-1 alfa-2 («AR»), que es lo que se guarda; el nombre sale de `Intl.DisplayNames` en `countryPicker.locale` de `labels` (o la prop `locale`).
- La bandera es un emoji armado con el código: en Windows se ven las dos letras («AR»).
- `countries` limita la lista (los países donde se opera). `sebs7n-ui/lib/countries` trae `COUNTRY_CODES`, `isCountryCode`, `countryFlag` y `countryName`, también para el servidor.
- Solo por subpath (`sebs7n-ui/country-picker`): no está en el barrel, por peso.

## Relacionados

[combobox](/docs/components/combobox.md) · [phone-input](/docs/components/phone-input.md) · [select](/docs/components/select.md)