IconPicker | Tuff Docs

Usage

Trigger and Inline

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

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.
In modules that only read a stored value, import parseIconIdentifier from @talex-touch/tuffex/icon-picker without loading the panel.
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

Prop	Type	Default	Description
`modelValue`	`string`	`''`	The icon identifier, bound with `v-model`.
`shape`	`'circle' \| 'rounded' \| 'square'`	`'rounded'`	Plate shape, bound with `v-model:shape`.
`sections`	`IconPickerSection[]`	all four	Sections to offer, in tab order; `file` appears as a choose-file button.
`catalog`	`Partial<Record<'emoji' \| 'icon' \| 'brand', IconPickerEntry[]>>`	-	Replaces a section's bundled rows; hosts with their own icon set replace them whole.
`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 labels, search placeholder, and the clear and choose-file 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.

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: '🚀' }

Safelisting the Catalog

Hosts on a utility-CSS engine must safelist ICON_CATALOG_CLASSES, or every icon in the grid renders as an empty box. Spread the module export rather than copying the strings.

import { ICON_CATALOG_CLASSES } from '@talex-touch/tuffex/icon-picker'

export default defineConfig({
  safelist: [...ICON_CATALOG_CLASSES],
})

Overview

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.
Search matches keywords, not the id; the bundled keywords are bilingual (English and Chinese).
shape is presentational and stored separately; it is not part of the identifier.

Technologies

Identifier helpers: src/identifier.ts.
Source: packages/tuffex/packages/components/src/icon-picker/.