---
title: Icons
description: The rules TxIcon uses to resolve and load icons.
category: Foundations
status: beta
since: 0.4.0
tags: [icon, svg, resolver, iconify]
syncStatus: reviewed
verified: false
---

## Five sources

`name` resolves only to `class` or `builtin`, in table order, and the first match wins. `emoji`, `url` and `file` arrive only through the explicit `icon` prop, which takes precedence over `name`.

| Written as | Type | Renders |
|------------|------|---------|
| `name="i-carbon-search"` | `class` | `<i>` carrying the class: an Iconify / UnoCSS preset icon |
| `name="chevron-down"` | `builtin` | Inline `<svg>` from the builtin table |
| `name` set to any other string | `class` | As the first row; the string is used as the class name |
| `:icon="{ type: 'emoji', value }"` | `emoji` | The characters, as text |
| `:icon="{ type: 'url', value }"` | `url` | Fetched and painted |
| `:icon="{ type: 'file', value }"` | `file` | Fetched and painted after the local-file protocol is applied |

:::TuffCodeBlock{lang="vue"}
---
code: |
  <template>
    <!-- class: any Iconify collection your build ships -->
    <TxIcon name="i-carbon-search" />

    <!-- builtin: no icon set required -->
    <TxIcon name="chevron-down" />

    <!-- explicit sources -->
    <TxIcon :icon="{ type: 'emoji', value: '🚀' }" />
    <TxIcon :icon="{ type: 'url', value: '/icons/plugin.svg' }" />
    <TxIcon :icon="{ type: 'file', value: '/Users/me/icon.png', colorful: true }" />
  </template>
---
:::

## The builtin table

`check`, `chevron-down`, `close`, `search`, `user`, `star`, `star-half`, `info`, `check-circle`, `x-circle` and `alert-triangle` ship inside the component, so core affordances render even with no icon collection configured.

- The table is not a general icon library; use an Iconify class or an explicit source for anything else.
- Entries are filled silhouettes or open strokes. `chevron-down` is stroked: it is a disclosure affordance at 12–14px, where a filled wedge reads as a heavy blob beside its label.

## Color, mask, and `colorful`

Applies to `url` / `file` sources.

| Mode | Renders | Use for |
|------|---------|---------|
| Monochrome (default) | A single-color SVG painted as a CSS mask; takes `currentColor` and follows the theme | UI glyphs |
| `colorful: true` | An `<img>` with its own colors | Logos and app icons |

`color` on the source overrides the monochrome ink.

## Loading your own icons

When icons sit behind a custom protocol, an authenticated endpoint, or a transport layer, provide a config once; every descendant `TxIcon` picks it up:

:::TuffCodeBlock{lang="typescript"}
---
code: |
  import { TX_ICON_CONFIG_KEY } from '@talex-touch/tuffex/icon'

  app.provide(TX_ICON_CONFIG_KEY, {
    // Rewrite a raw value into something the browser can fetch
    urlResolver: (url, type) => (type === 'file' ? `tfile://${url}` : url),
    // Own the fetch: retries, auth headers, an IPC transport…
    svgFetcher: async url => (await fetch(url)).text(),
    // Prefix applied to `file` sources when no resolver is given
    fileProtocol: 'tfile://',
  })
---
:::

A single `TxIcon` overrides the injected config with its own `urlResolver` / `svgFetcher` props.

## Animated icons

For an icon that moves, [AnimateIcons](https://animateicons.in/) offers 542 MIT-licensed animated icons built on Lucide geometry.

- It ships as React components (`motion/react`), not a dependency for Tuffex or a Vue app; what ports is the SVG geometry and per-path timing.
- It is not an Iconify collection: there is no `i-animateicons-*` class, and a port is a component, not a `name` string.
- If the icon doesn't need to move, prefer a collection your build already ships (`carbon`, `ri`, `simple-icons`…).
- Keep the attribution and MIT notice with any geometry you copy.

## Technologies

- Resolution and rendering: `packages/tuffex/packages/components/src/icon/src/TxIcon.vue`.
- Config contract: `packages/tuffex/packages/components/src/icon/src/types.ts` (`TxIconSource`, `TxIconConfig`, `TX_ICON_CONFIG_KEY`).

## Related components

| Component | For |
|-----------|-----|
| [Icon](./icon.en.mdc) | General use and full props |
| [IconChip](./icon-chip.en.mdc) | Tinted plate for a glyph or label |
| Status icon | Tone-colored status glyph |