Skip to content

Icons

The full Lucide set plus your custom SVGs, validated at build time. You can’t ship an icon that doesn’t exist.

Usage

In HTML, an icon is an <svg> with the ts icon class and a size (icon-16, icon-20…, the scale steps; the general size-20 utility works too). It inherits the text color (currentColor). With npx taisho generate, the <use> points to the sprite the command builds with only the icons you use, and the name comes from the #ts-<name> fragment.

html
<svg class="ts icon icon-20" aria-hidden="true"><use href="taisho/taisho.icons.svg#ts-search"></use></svg>

The Lucide icons come from the lucide-static package, which doesn’t ship with the Core. npx taisho init offers to install it (and --install-icons installs it without asking); you can also install it by hand with npm i -D lucide-static. Without it, a project that uses no icons still compiles; if the code uses any, taisho generate warns with that command and exits with an error.

Without a build, from the CDN, there’s no sprite. Copy the icon’s SVG from lucide.dev, paste it into your HTML, and give it class="ts icon icon-20". That’s what each component’s examples use.

html

If the icon stands alone, with no text next to it, the button or link that contains it needs an aria-label. If it goes with text, leave it with aria-hidden="true". The Icon component page has the sizes and examples.


Build-time validation

If a #ts-<name> in your HTML doesn’t exist (not in Lucide and not in your custom icons), taisho generate exits with an error and suggests the closest match, by edit distance.


Custom icons

Put an .svg in src/icons. The file name (kebab-case, without .svg) becomes the icon name. Core’s CLI (taisho generate) always looks in that folder.

bash
# src/icons/taisho-mark.svg  →  #ts-taisho-mark

Resolution order is Lucide first, then the custom folder, and a build error if it’s in neither. It detects the style automatically: stroke (Lucide-style, inherits currentColor) vs. raw (with its own fills).

Guidelines for Lucide-style SVGs

viewBox="0 0 24 24", fill="none", and stroke paths—that way they inherit color and weight like Lucide’s.

Icons you build at runtime

The scanner reads the text of your files. If an icon name only exists at run time (it’s built from a variable, or comes from an API), it can’t see it and the icon stays out of the sprite. For those cases, list them in the icons option of taisho.config.ts:

taisho.config.ts
// taisho.config.ts
export default {
  // ...
  icons: ['check', 'x', 'triangle-alert'],
};

It’s the exception, not the normal path: a name written out in full in the href doesn’t need declaring. A name that exists neither in Lucide nor in your custom icons stops taisho generate.


The sprite from JS, with Vite

With the Vite taisho() plugin, the sprite lands in taisho/taisho.icons.svg, outside public/. The references you write in HTML are rewritten by vite build to the file’s final (hashed) name. The ones you build in JS from a string, like '/taisho/taisho.icons.svg#ts-moon', Vite doesn’t see: in production they point to a file that doesn’t exist. Import the sprite and use the path it gives you:

js
import sprite from '../taisho/taisho.icons.svg?no-inline';

boton.innerHTML = `<svg class="ts icon icon-20" aria-hidden="true"><use href="${sprite}#ts-moon"></use></svg>`;

?no-inline asks for the file: without it, Vite embeds small files in the JS as data: URLs and there is no file left to reference. The icon makes it into the sprite because the scanner reads the href="…#ts-moon" in that file, as long as content covers it.