NationalityCombobox
A searchable country or nationality choice by code, from the list and names your application supplies.
Nationality picks a country or a nationality. The value is a code, typically ISO 3166-1
alpha-2; the reader sees the name and can search on the name or the code. It is a thin layer over
SearchCombobox.
Value: ''
// apps/docs/examples/ui/nationality-combobox.tsx'use client';
import {useMemo, useState} from 'react';
import {NationalityCombobox} from '@workspace/active-ui/components/composed/nationality-combobox';import { Field, FieldDescription, FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Switch} from '@workspace/active-ui/components/primitives/switch';
// The application's list and order: two common countries first, then the rest.const FIRST = ['NL', 'BE'];const REST = ['DE', 'FR', 'ES', 'IT', 'PL', 'PT', 'SE', 'TR', 'MA', 'GB', 'US'];
/** * A country by its ISO 3166-1 code, with names from `Intl.DisplayNames`. * The code is searchable even when it is not shown; switch on "Show codes" * to see it before the name. */export default function NationalityComboboxExample() { const [country, setCountry] = useState(''); const [showCode, setShowCode] = useState(false); const options = useMemo(() => { const names = new Intl.DisplayNames(['en'], {type: 'region'}); const named = (code: string) => ({code, name: names.of(code) ?? code}); return [ ...FIRST.map(named), ...REST.map(named).sort((a, b) => a.name.localeCompare(b.name, 'en')), ]; }, []); return ( <div className="grid w-full max-w-xs gap-6"> <Field orientation="horizontal"> <Switch id="show-codes" checked={showCode} onCheckedChange={setShowCode} /> <FieldLabel htmlFor="show-codes">Show codes</FieldLabel> </Field> <Field> <FieldLabel htmlFor="nationality">Nationality</FieldLabel> <NationalityCombobox id="nationality" value={country} onValueChange={setCountry} options={options} showCode={showCode} locale="en" placeholder="Choose a country" searchLabel="Search countries" searchPlaceholder="Search…" emptyText="No country found." aria-describedby="nationality-value" /> <FieldDescription id="nationality-value"> Value: <code>{country || "''"}</code> </FieldDescription> </Field> </div> );}What the composition adds#
A code as the value,
''when nothing is chosen.The code is searchable even when it is not shown.
show(defaultCode false) shows it before the name,NL - Netherlands, where the reader also reads codes.
It owns no list, no names and no order: a subset, a historical entry or common countries first are simply a different array.
Usage#
import {NationalityCombobox} from '@workspace/active-ui/components/composed/nationality-combobox';
<NationalityCombobox id="nationality" value={country} onValueChange={setCountry} options={[{code: 'NL', name: 'Netherlands'}]} locale="en" placeholder="Choose a country" searchLabel="Search countries" searchPlaceholder="Search…" emptyText="No country found."/>;What your application provides#
The countries in the order to show, with names in the reader's language; the example uses
Intl.and puts two countries first.Display Names The translated texts; there are no English defaults.
Accessibility#
As SearchCombobox: name the button with Field
its id; aria- and aria- go to the button.
API#
Import from @workspace/
Props
- Type
string
Text when the search finds nothing. Supplied translated.
- Type
string
The reader's language, for matching the query against the names, as Search does. It does not produce the names: those arrive in options.
- Type
readonly NationalityCombobox Optio…
The complete set of countries or nationalities to choose from, in the order they are shown.
Required, and there is no built-in list: which entries exist, what they are called in the reader's language, and which come first are reference data and project policy, owned by the caller. A subset, an extra territory or a historical entry is simply a different array. An empty array is valid and shows empty.
- Type
string
Text on the button while nothing is chosen. Supplied translated.
Required, like every text below: an empty value is a valid state of this field, and a blank button or a blank empty state tells the user nothing. There is no default and no English fallback: the same contract as Search.
- Type
string
Accessible name of the search field inside the menu. Supplied translated.
- Type
string
Text in the search field inside the menu. Supplied translated.
- Type
string
The chosen code, or '' when nothing is chosen.
- Type
string
The ids of the texts that describe this choice: a Field, a Field, or both separated by a space.
- Type
"false""grammar""spelling""true"boolean
The validation state of the field, set by the caller from its form state (field). It lands on the button that carries the choice, where assistive technology reads it and the field's invalid border keys on it. This component decides nothing about validity itself.
- Type
string
Classes for the button.
- Type
boolean- Default
false
Disables the button.
- Type
string
The id of the button that carries the choice, so a visible label can name it programmatically with html.
Generic and without a domain word: this component does not know which field it is. The prop exists because a Field without html above a Base UI trigger is only visually a label; the button's accessible name stayed empty.
- Type
boolean- Default
false
Shows the code before the name: NL - Nederland.
Off by default: for a person, a nationality is a word and not a code. The code still takes part in searching.
Turn it on where the field stores a country code and the reader also reads that code, such as an administration form; Currency shows its codes in the same form (EUR - Euro).
The order does not change: it stays the order of options.
Events
Called by the component when something happens.
- Type
(value: string) => void
Receives the chosen code, or '' when the choice is cleared.
Takes only the props listed.
Types
One country or nationality the caller offers.
The shape a reference-data source typically produces: a code and a translated name. This package imports no such source; the caller maps its own data to this shape.
interface NationalityComboboxOption {
code: string;
name: string;
}