# Icon picker

A key that shows the icon it holds, with a clear key beside it, and that opens a card of the kit’s own icons to change it. The card hangs from the key on the popover’s printed leader, with the search field above a grid of icons in a few groups (Moving, Marking, Doing, Things and Transport). The search answers to the words an icon goes by as well as its name: “delete” finds the trash. The arrow keys walk the grid across the group headings, the one under the arrows is named in the card’s foot, and the one picked is pressed down with its lamp lit. Nothing from outside the kit’s icon set can be picked.

Kit part · With the Kit · https://tactileui.dev/parts/icon-picker

> The code and styling for this part come with the Tactile UI Kit, which is in the Founder Pass. Sign in if you have it. Sign in: https://tactileui.dev/auth/sign-in The price: https://tactileui.dev/pricing

## Anatomy

The card is the popover, whole: its leader, placement and top-layer behaviour. The search is the search field, with its count and its clear key. The icons are the icon set, drawn at its larger size, and the cells are the keys the icon grid in the icon set’s own page uses, standing in a recess. The lamp that marks the pick is the kit’s. No icon from outside the set can be picked, and no colour is added.

## Variants

- Empty · placeholder
- With a pick
- Some groups only · groups
- One group
- Required · in a form
- Disabled

## States

- Open, nothing picked
- Open, one picked
- Searched
- Nothing found

## Props and options

| Name | Kind | Description |
| - | - | - |
| value | attribute · property | The icon picked, by its name in the icon set. A name the set does not have is “”. The clear key is shown only while there is one. |
| name · required · disabled | attribute | The element is form-associated: name submits the icon’s name. Required is invalid with nothing picked. |
| placeholder | attribute | The words on the key while nothing is picked. |
| groups | attribute | Which groups the card shows: moving, marking, doing, things, transport. An icon in none of them is set under More. |
| aria-label · aria-labelledby | attribute | What the key is for (“Berth notices”); it is spoken with the pick: “Berth notices: Bell. Change the icon.” |
| open · key | property | Whether the card is out, and the key that opens it. |
| show() · hide() | method | Open or close the card from code. |
| change · input | event | When the pick changes by the card, the clear key or the keyboard. Not fired when value is set from code. |
| iconGroups() · iconFilter() · iconMatches() · iconLabel() | function | The groups to show; the groups with only the icons that match a query; whether one icon does; an icon’s name in words. |
| iconGridMove() · iconGridHTML() · iconPickerHTML() | function | The cell an arrow lands on, from the cells’ positions; the grid and the element as markup, for a server or a specimen. |

## Usage notes

Press the key beside Berth notices: the card opens with the focus in Find an icon. Type “delete” and the grid narrows to the trash, the count says 1 icon. Clear the search with Escape, press the Down arrow and walk the grid with the arrows; the name of the icon under them is in the foot. Press Enter and the key shows it. The clear key takes it away.

## Accessibility

- The key says what it is for and what it holds in one name (“Berth notices: Bell. Change the icon.”). The card is a dialog named “Choose an icon”. The clear key is named (“Clear the icon for Berth notices”) and is there only while there is something to clear.
- The focus goes to the search field as the card opens. The count is spoken as the search narrows (“1 icon”, “No icon matches ‘zzq’”).
- ↓ or Tab goes from the search into the grid; there ← → move one icon, ↑ ↓ move a row (across the group headings), Home and End go to the ends, Enter or Space picks and closes, and a letter goes back to the search. ↑ from the first row returns to the search. Esc clears the search, then closes the card, and the focus goes back to the key. Tabbing out of the card closes it.
- The picked icon is pressed down and has its lamp lit (the kit’s green), and its name is in the card’s foot, so it does not rest on the drawing or the lamp alone. The icons print in the ink they sit in, so they hold the kit’s contrast in every finish.
- The card does not animate under reduced motion.

## Related parts

- [Icons](https://tactileui.dev/parts/icons): The kit’s glyphs as one set.
- [Popover](https://tactileui.dev/parts/popover): A card hung from the key that opened it, with a printed leader running back to the key. Not modal: the page stays live around it.
- [Search field](https://tactileui.dev/parts/search-field): A recess for a question. A glass is printed on its floor at the start, the words run on, an optional count is printed behind an engraved line, and a clear key sits in the far corner while there is something to clear. Escape empties it.
- [Icon key](https://tactileui.dev/parts/icon-key): A key with an icon and no words, square or round: transport, power, the small tools. Its aria-label names it; a tip shows the name.