Components/IconPicker

IconPicker

A picker that returns an icon identifier string.

VerifiedSince 0.6.0

Usage

Trigger and Inline

inline renders the panel directly, and sections limits the sections it offers.

Loading demo...

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.

Loading demo...

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 a data: address is written into storage in full.
  • In modules that only read a stored value, import parseIconIdentifier from @talex-touch/tuffex/icon-picker without loading the panel.
  • When narrowing sections, keep ai if users pick model vendors: vendor marks and AI glyphs live there, not under Brands or Icons.
  • Turn shapeSelectable off when the host draws its own plate, or users pick a shape they never see.
  • Use TxIconChip to display a small icon plate; this component only chooses one.

API Reference

Props

PropTypeDefaultDescription
modelValuestring''The icon identifier, bound with v-model.
shapeIconPickerShape'rounded'Plate shape, bound with v-model:shape; ICON_PICKER_SHAPES lists all twelve.
sectionsIconPickerSection[]all fiveSections to offer, in tab order: emoji, icon, brand, ai, and file as a choose-file button.
catalogPartial<Record<IconPickerCatalogSection, IconPickerEntry[]>>-Replaces a section's bundled rows; an entry's category groups it under a heading.
emojiPacksreadonly 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.
shapeSelectablebooleantrueShows 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.
acceptstring'image/*'Accept list for the file dialog and the fallback input.
disabledbooleanfalseDisables the trigger and the panel.
sizenumber44Edge length of the trigger plate, in px.
placeholderstring''The trigger's aria-label; falls back to the search label.
inlinebooleanfalseRenders the panel directly instead of behind a trigger.
labelsPartial<IconPickerLabels>English defaultsSection, shape and category names, the search placeholder, and the actions.

Events

EventPayloadDescription
update:modelValuestringFires on a pick, with '' when cleared.
update:shapeIconPickerShapeFires when the shape changes.
changestringFires together with update:modelValue.
file-errorunknownFires when the chooser throws or the fallback input can't read the file.

Exposed Methods

NameTypeDescription
toggle(value?)(value?: boolean) => voidOpens 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 Electron dialog.showOpenDialog bridge); without it, a hidden <input type="file"> yields a data URL.
  • shape is presentational and stored separately; it is not part of the identifier.

Technologies

  • Glyph path data is generated by scripts/generate-icon-picker-data.mjs and 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/.
查看源码
packages/tuffex/packages/components/src/icon-picker/index.ts