`<Select>`

Category: Control tag · AfriAnnotate-specific

A searchable single- or multi-select. Instead of hand-listing every language or country as <Choice> elements, point the tag at a built-in dataset and, if you like, narrow it: the languages of two countries, the countries of one region, a whitelist of codes. Annotators type a few letters and pick from suggestions; the result is stored exactly like <Choices>, so review, agreement, filters and every export format already understand it.

<View>
  <Audio name="audio" value="$audio" zoom="true" hotkey="space"/>
  <TextArea name="transcript" toName="audio" rows="6" required="true"/>

  <Header value="Language(s) present"/>
  <Select name="languages" toName="audio" dataset="languages" countries="NG"
          selected="English" required="true"
          requiredMessage="Select every language you hear."/>
</View>

The built-in datasets

All four are complete registries, regenerated from the standards with a script in the repository and loaded on first use (one small download per dataset, cached afterwards).

`dataset`	What it holds	Source
`languages`	Every ISO 639-3 language: 7,867 entries, of which 7,027 living and 143 sign languages. Each carries its ISO 639-3 code, ISO 639-1 code where one exists, English name, native name and aliases, the countries and regions it is spoken in, language family, type and scope.	SIL ISO 639-3 registry (the code list Ethnologue uses); countries, native names and families from Glottolog, CLDR and Wikidata; a curated African language-to-country list on top
`countries`	Every ISO 3166-1 territory (254) with UN M49 region and subregion and common aliases (DR Congo, Ivory Coast, Swaziland, ...).	CLDR territory containment, ICU names
`scripts`	The ISO 15924 writing systems (214), with the African ones annotated: Latin, Arabic and Ajami, Ge'ez, N'Ko, Tifinagh, Vai, Adlam, Bamum, Mende Kikakui, Osmanya, Coptic.	ISO 15924 registry, ICU names
`currencies`	ISO 4217 currencies in current use (153) with the countries that use them.	CLDR currency data, ICU names

Search matches the name, the code, the ISO 639-1 code, aliases and native names, and country codes, so "ha", "hausa" and "هَوْسَ" all find Hausa, and "zaire" finds the Democratic Republic of the Congo.

Narrowing the list

Attribute	Applies to	Example
`region`	all	`region="Africa"` or `region="Africa,Asia"` (Africa, Americas, Asia, Europe, Oceania)
`subregion`	countries	`subregion="Western Africa,Eastern Africa"`
`countries`	languages, currencies	`countries="NG,GH"` keeps the languages spoken in Nigeria and Ghana
`kind`	languages	`spoken` (default), `sign`, or `all`
`types`	languages	`living` (default) or `all`; or a list such as `living,extinct`
`scope`	languages	`individual`, `macrolanguage`, or `all` (default)
`family`	languages	Glottolog top-level family: `family="Atlantic-Congo"`, `family="Afro-Asiatic,Nilotic"`
`include`	all	whitelist of codes or names: `include="NG,GH,KE,ZA,ET"`
`exclude`	all	drop entries: `exclude="eng,fra"`

Filters combine with AND. include alone is the way to offer exactly the handful you want while keeping the search, codes and hints.

Your own list instead of, or on top of, a dataset

Attribute	Effect
`items="Yoruba,English"`	Use this list and no dataset. `items="yor:Yoruba,eng:English"` gives each entry a code.
`extra="Naija,Pidgin"`	Append entries to whatever the dataset and filters produce.
`value="$languages"`	Take the list from task data: an array of strings, or of objects `{value, code, alt, hint}`.
`allowCustom="true"`	Let the annotator add a value that is not in the list by typing it and choosing Add "…". The added value is stored like any other.

Preselecting and locking

Attribute	Effect
`selected="English"`	Preselected, but the annotator can remove it. Codes work too: `selected="eng"`.
`fixed="Nigeria"`	Preselected and locked: it stays in the answer whatever the annotator does.

What is stored

By default the entry's name is stored, exactly like a <Choice value>:

{ "from_name": "languages", "to_name": "audio", "type": "choices",
  "value": { "choices": ["Hausa", "English"] } }

With codes="true" the code is stored instead (["hau", "eng"], ["NG"], ["Latn"], ["NGN"]), which is what most pipelines want. showCodes="true" shows the code next to the name in the list without changing what is stored.

All attributes

Attribute	Type	Default	Description
`name`	string	required	Name of the element
`toName`	string	required	Name of the element it applies to
`dataset`	`languages` \| `countries` \| `scripts` \| `currencies`		Built-in list
`items`	string		Custom list, comma-separated, optionally `code:name`
`extra`	string		Entries appended to the list
`value`	string		Task data field (`$field`) holding the list
`region`, `subregion`, `countries`, `kind`, `types`, `scope`, `family`, `include`, `exclude`	string		Filters, see above
`selected`	string		Preselected entries
`fixed`	string		Preselected and locked entries
`codes`	boolean	`false`	Store codes instead of names
`showCodes`	boolean	`false`	Show codes in the list
`allowCustom`	boolean	`false`	Annotator can add a value
`choice`	`single` \| `multiple`	`multiple`	One answer or several
`layout`	`select` \| `inline` \| `vertical`	`select`	Searchable dropdown, or checkboxes for short lists
`placeholder`	string		Text in the search box
`required`, `requiredMessage`			As for Choices
`perRegion`, `visibleWhen`, `whenTagName`, `whenChoiceValue`			As for Choices

Recipes

Code-mixed speech, languages of one country, ISO codes in the export:

<Select name="languages" toName="audio" dataset="languages" countries="NG" codes="true" required="true"/>

Speaker's country, Africa only, one answer:

<Select name="country" toName="audio" dataset="countries" region="Africa" choice="single" codes="true"/>

Script of a scanned page, including the Ajami case:

<Select name="script" toName="image" dataset="scripts" region="Africa" choice="single"/>

A fixed shortlist plus room for surprises:

<Select name="languages" toName="text" dataset="languages" include="hau,yor,ibo,pcm,eng" allowCustom="true"/>

Short list as checkboxes rather than a dropdown:

<Select name="script" toName="text" dataset="scripts" include="Latn,Arab,Ethi" layout="inline" choice="single"/>

Notes

The dataset chunk downloads the first time a task using the tag opens and is cached by the browser; the languages list is about 1 MB.
On the desktop app the datasets ship inside the app, so the tag works offline.
Aliases are for search only; the stored value is always the name (or code). Rename nothing: exports from different projects stay comparable.
A value an annotator added with allowCustom is kept: when the task is reopened it is offered and selected again even though it is not in the dataset. The same applies if you narrow the list after answers exist.
Loading the list is not an edit: opening a task does not mark the annotation as changed and does not create a draft.
To rebuild the datasets from the upstream registries: node libs/editor/scripts/select-datasets/build.mjs --refresh in web/.

<Choices> — the tag this one extends; use it for short, fixed lists.
<Taxonomy> — hierarchical pick-lists you define yourself.
Transcribe audio — the recipe this tag was built for.

The built-in datasets​

Narrowing the list​

Your own list instead of, or on top of, a dataset​

Preselecting and locking​

What is stored​

All attributes​

Recipes​

Notes​

Related​