Custom icons

Config fields like icon-name: tb-home-symbolic resolve against the lys-shell icon theme installed at ~/.local/share/lys-shell/icons/. The lys-shell icons subcommand populates that directory from CDN sources or local SVG files.

List available sources

lys-shell icons sources

Five sources ship in-tree. Slug names come directly from the upstream catalogues, linked below.

Source	Prefix	Contents	Browse
tabler	tb-	Outline UI icons	tabler.io/icons
tabler-filled	tbf-	Solid UI icons	tabler.io/icons
simple-icons	si-	Brand and app logos	simpleicons.org
material	md-	Google Material Design	fonts.google.com/icons
lucide	ld-	Alternative UI icons (Feather fork)	lucide.dev/icons

Install from a CDN source

lys-shell icons install <source> <slug> [<slug>...]

Example:

lys-shell icons install tabler home settings bell

This downloads the three Tabler icons and installs them as tb-home-symbolic, tb-settings-symbolic, and tb-bell-symbolic. The source name determines the prefix; the slug is the icon's name on the upstream site.

Brand logos work the same way:

lys-shell icons install simple-icons firefox spotify

Produces si-firefox-symbolic and si-spotify-symbolic.

Import a local SVG

lys-shell icons import <path> [name]

For a single file, pass a name. The icon is installed with the cm- prefix:

lys-shell icons import ~/Downloads/my-logo.svg my-logo

Installs as cm-my-logo-symbolic.

For a directory, omit the name. Every SVG is imported; files already starting with a known prefix (tb-, tbf-, si-, md-, ld-, cm-) keep their name, and anything else gets cm- added.

lys-shell icons import ~/exported-icons/

Imported SVGs are transformed into symbolic icons so they pick up theme colours.

List and remove

lys-shell icons list
lys-shell icons list --source tb

--source filters by prefix. Add --interactive for an fzf-backed search if fzf is on $PATH.

To remove icons, pass their full names:

lys-shell icons remove tb-home-symbolic si-firefox-symbolic

Referencing icons in config

Any module field that takes an icon name accepts installed icons directly:

modules:
  clock:
    icon-name: ld-clock-symbolic
  network:
    icon-name: tb-wifi-symbolic

The value is the full icon name, prefix included. An icon no theme provides draws nothing, so the shell warns about each one at startup and on every config reload, naming the icon and how to get it: lys-shell icons sync for a CDN prefix, lys-shell icons import for a cm- icon.

lys-shell bundles Lucide (ld-) for its own glyphs and Simple Icons (si-) for brand logos. A config written against an older release may name Tabler (tb-) or Material (md-) icons that are no longer bundled; lys-shell icons sync fetches them, or switch to the ld- equivalent.