IconPicker
A picker that returns an icon identifier string.
Usage
Trigger and Inline
inline renders the panel directly, and sections limits the sections it offers.
Custom emoji packs
emojiPacks lists your own emoji packs at the start of the emoji section, one heading per pack with a usable emoji; a picked custom emoji is stored as a url: identifier.
Best Practices
- Store the identifier as-is and resolve it at render time with
parseIconIdentifier; don't split it into two columns that can disagree. - A custom emoji is stored as a
url:identifier whose value is the image address; prefer https addresses, because adata:address is written into storage in full. - In modules that only read a stored value, import
parseIconIdentifierfrom@talex-touch/tuffex/icon-pickerwithout loading the panel. - When narrowing
sections, keepaiif users pick model vendors: vendor marks and AI glyphs live there, not under Brands or Icons. - Turn
shapeSelectableoff when the host draws its own plate, or users pick a shape they never see. - Use
TxIconChipto display a small icon plate; this component only chooses one.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | '' | The icon identifier, bound with v-model. |
shape | IconPickerShape | 'rounded' | Plate shape, bound with v-model:shape; ICON_PICKER_SHAPES lists all twelve. |
sections | IconPickerSection[] | all five | Sections to offer, in tab order: emoji, icon, brand, ai, and file as a choose-file button. |
catalog | Partial<Record<IconPickerCatalogSection, IconPickerEntry[]>> | - | Replaces a section's bundled rows; an entry's category groups it under a heading. |
emojiPacks | readonly TxEmojiPack[] | - | Custom emoji packs listed at the start of the emoji section, one heading per pack with a usable emoji; they add to catalog.emoji or the bundled emoji rather than replacing them. |
shapeSelectable | boolean | true | Shows the shape row; turn off when the host draws its own plate. |
fileChooser | () => Promise<string | null> | - | Host file dialog resolving to an absolute path, or null on cancel. |
accept | string | 'image/*' | Accept list for the file dialog and the fallback input. |
disabled | boolean | false | Disables the trigger and the panel. |
size | number | 44 | Edge length of the trigger plate, in px. |
placeholder | string | '' | The trigger's aria-label; falls back to the search label. |
inline | boolean | false | Renders the panel directly instead of behind a trigger. |
labels | Partial<IconPickerLabels> | English defaults | Section, shape and category names, the search placeholder, and the actions. |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | string | Fires on a pick, with '' when cleared. |
update:shape | IconPickerShape | Fires when the shape changes. |
change | string | Fires together with update:modelValue. |
file-error | unknown | Fires when the chooser throws or the fallback input can't read the file. |
Exposed Methods
| Name | Type | Description |
|---|---|---|
toggle(value?) | (value?: boolean) => void | Opens or closes the panel per value, or flips it when omitted; an inline panel always shows. |
The Identifier
A pick is a <type>:<value> string. It splits at the first colon, so a value may contain colons (url:, a Windows file:C:/…).
emoji:🚀
class:i-ri-rocket-line
file:/Users/me/a.png
url:https://example.com/y.svg
builtin:star
parseIconIdentifier and formatIconIdentifier convert both ways. An unprefixed string is not guessed at and returns null; a bare emoji is the one exception.
import { parseIconIdentifier } from '@talex-touch/tuffex/icon-picker'
parseIconIdentifier('class:i-ri-rocket-line') // { type: 'class', value: 'i-ri-rocket-line' }
parseIconIdentifier('rocket.png') // null
parseIconIdentifier('🚀') // { type: 'emoji', value: '🚀' }
A custom emoji from emojiPacks is stored as url:<src>, the same form as the url: example above. When its address is a data: address the whole address is written into the identifier, so prefer https addresses for anything you persist.
Rendering a Picked Class
The picker draws its bundled classes from path data it ships, so its grid needs no icon CSS from the host. Outside the picker a picked class: value is only a class name: give TxIcon the picker's glyphs through classGlyph, or safelist ICON_CATALOG_CLASSES in the host's utility-CSS engine.
import { TX_ICON_CONFIG_KEY } from '@talex-touch/tuffex'
import { resolveIconPickerGlyph } from '@talex-touch/tuffex/icon-picker'
app.provide(TX_ICON_CONFIG_KEY, { classGlyph: resolveIconPickerGlyph })
import { ICON_CATALOG_CLASSES } from '@talex-touch/tuffex/icon-picker'
export default defineConfig({
safelist: [...ICON_CATALOG_CLASSES],
})
Overview
- Search covers every section at once, the open tab first, matching keywords, class names and category headings; it tolerates a typo and takes Chinese, full pinyin or initials (
火箭,huojian,hj). Focus stays in the search box: arrow keys move through the grid, Enter picks the highlighted cell (the top result while searching), and Esc clears the query before it closes the panel. - Browsing groups a section by category, with a row of shortcuts that jumps between them.
- Custom emoji packs with a usable emoji form groups at the start of the emoji section, headed by the pack name; search matches an emoji's name, its keywords and the pack name.
- The trigger morphs from one plate outline to the next; under reduced motion it switches at once.
- The file section depends on the host: pass
fileChooser(for example an Electrondialog.showOpenDialogbridge); without it, a hidden<input type="file">yields a data URL. shapeis presentational and stored separately; it is not part of the identifier.
Technologies
- Glyph path data is generated by
scripts/generate-icon-picker-data.mjsand loaded per section the first time it is shown; the plate morphs through TxIconMorph's engine. - Remix Icon 4.8.0 data ships under Apache-2.0 (
REMIXICON-LICENSE) and Simple Icons data under CC0-1.0; brand marks remain trademarks of their owners. - Source:
packages/tuffex/packages/components/src/icon-picker/.