Icon
Examples
Basic Usage
Sizes
Colors
Round Icons
Padded Icons
Squared Icons
Blink Animation
Icon Libraries
Material Symbols Outlined (Default)
Material Icons Variants
Line Icons
Brand Icons
Custom Images
Avatar Generation
Gravatar
Libravatar
Advanced Features
Alt Text for Accessibility
Special Syntax
Slotted Content
CSS Custom Properties
CSS Parts
Use Cases
In Buttons
In Navigation
Status Indicators
User Avatars in Lists
Material Icons Reference
Importing
Slots
Events
Custom Properties
Parts
Dependencies

Icon

<zn-icon> | ZnIcon

Since 1.0

experimental

Short summary of the component’s intended use.

<zn-icon src="check"></zn-icon>

The icon component provides a flexible way to display icons from multiple libraries including Material Icons, Material Symbols, Line Icons, and custom brand icons. It also supports avatar generation, Gravatar, and custom image sources.

Examples

Basic Usage

The simplest way to use an icon is by specifying the icon name in the src attribute. By default, icons use the Material Symbols Outlined library.

<zn-icon src="home"></zn-icon>
<zn-icon src="settings"></zn-icon>
<zn-icon src="favorite"></zn-icon>
<zn-icon src="shopping_cart"></zn-icon>

Sizes

Use the size attribute to control the icon’s dimensions. The default size is 24 pixels.

<zn-icon src="star" size="16"></zn-icon>
<zn-icon src="star" size="24"></zn-icon>
<zn-icon src="star" size="32"></zn-icon>
<zn-icon src="star" size="48"></zn-icon>
<zn-icon src="star" size="64"></zn-icon>

Colors

Use the color attribute to apply semantic or predefined colors to your icons.

<zn-icon src="check_circle" color="default" size="32"></zn-icon>
<zn-icon src="check_circle" color="primary" size="32"></zn-icon>
<zn-icon src="check_circle" color="accent" size="32"></zn-icon>
<zn-icon src="check_circle" color="info" size="32"></zn-icon>
<zn-icon src="check_circle" color="warning" size="32"></zn-icon>
<zn-icon src="check_circle" color="error" size="32"></zn-icon>
<zn-icon src="check_circle" color="success" size="32"></zn-icon>
<zn-icon src="check_circle" color="disabled" size="32"></zn-icon>

Additional color options are available for specific use cases:

<zn-icon src="palette" color="red" size="32"></zn-icon>
<zn-icon src="palette" color="blue" size="32"></zn-icon>
<zn-icon src="palette" color="green" size="32"></zn-icon>
<zn-icon src="palette" color="orange" size="32"></zn-icon>
<zn-icon src="palette" color="yellow" size="32"></zn-icon>
<zn-icon src="palette" color="indigo" size="32"></zn-icon>
<zn-icon src="palette" color="violet" size="32"></zn-icon>
<zn-icon src="palette" color="pink" size="32"></zn-icon>
<zn-icon src="palette" color="grey" size="32"></zn-icon>
<zn-icon src="palette" color="white" size="32" style="background: #333; padding: 4px;"></zn-icon>

Round Icons

Add the round attribute to give icons a circular background.

<zn-icon src="person" size="40" color="primary" round></zn-icon>
<zn-icon src="mail" size="40" color="info" round></zn-icon>
<zn-icon src="favorite" size="40" color="error" round></zn-icon>
<zn-icon src="settings" size="40" color="accent" round></zn-icon>

Padded Icons

Use the padded attribute to add internal spacing around the icon.

<zn-icon src="notifications" size="40" color="warning" padded round></zn-icon>
<zn-icon src="shopping_cart" size="40" color="success" padded round></zn-icon>
<zn-icon src="search" size="40" color="info" padded round></zn-icon>

Squared Icons

Use the squared attribute to maintain a 1:1 aspect ratio for the icon container.

<zn-icon src="dashboard" size="40" color="primary" squared></zn-icon>
<zn-icon src="analytics" size="40" color="accent" squared></zn-icon>

Blink Animation

Add the blink attribute to create a blinking effect, useful for notifications or alerts.

<zn-icon src="notification_important" size="32" color="warning" blink></zn-icon>
<zn-icon src="error" size="32" color="error" blink></zn-icon>

Icon Libraries

The icon component supports multiple icon libraries. You can specify the library using the library attribute or use shorthand notation with the @ symbol in the src attribute.

Material Symbols Outlined (Default)

Material Symbols Outlined is the default library. These icons are modern and versatile.

<zn-icon src="home" size="32"></zn-icon>
<zn-icon src="account_circle" size="32"></zn-icon>
<zn-icon src="lightbulb" size="32"></zn-icon>
<zn-icon src="schedule" size="32"></zn-icon>

Material Icons Variants

Material Icons come in several variants: filled, outlined, round, sharp, and two-tone.

<zn-icon src="favorite@material" size="32"></zn-icon>
<zn-icon src="favorite@material-outlined" size="32"></zn-icon>
<zn-icon src="favorite@material-round" size="32"></zn-icon>
<zn-icon src="favorite@material-sharp" size="32"></zn-icon>
<zn-icon src="favorite@material-two-tone" size="32"></zn-icon>

You can also use the library attribute directly:

<zn-icon src="star" library="material" size="32"></zn-icon>
<zn-icon src="star" library="material-outlined" size="32"></zn-icon>
<zn-icon src="star" library="material-round" size="32"></zn-icon>
<zn-icon src="star" library="material-sharp" size="32"></zn-icon>
<zn-icon src="star" library="material-two-tone" size="32"></zn-icon>

Shorthand Library Notation

You can use convenient shorthand notations:

@m or @mat → material
@mo → material-outlined
@mr → material-round
@ms → material-sharp
@mt or @m2 → material-two-tone
@mso → material-symbols-outlined

<zn-icon src="home@m" size="32"></zn-icon>
<zn-icon src="home@mo" size="32"></zn-icon>
<zn-icon src="home@mr" size="32"></zn-icon>
<zn-icon src="home@ms" size="32"></zn-icon>
<zn-icon src="home@mt" size="32"></zn-icon>

Line Icons

Line Icons provide a collection of modern, consistent icons. Use library="line" or the @line shorthand.

View Line Icons

<zn-icon src="heart" library="line" size="32"></zn-icon>
<zn-icon src="bookmark-1" library="line" size="32"></zn-icon>
<zn-icon src="home" library="line" size="32"></zn-icon>
<zn-icon src="user" library="line" size="32"></zn-icon>
<zn-icon src="envelope" library="line" size="32"></zn-icon>

Using shorthand notation:

<zn-icon src="rocket@line" size="32"></zn-icon>
<zn-icon src="cloud-upload@line" size="32"></zn-icon>
<zn-icon src="star@line" size="32"></zn-icon>

Brand Icons

Display brand logos and custom company icons using the brands library.

<style>.icncont{ width:40px; height:40px; background:#efefef; display:inline-flex; align-items: center; justify-content: center; margin:3px;}</style>
<span class=icncont><zn-icon src="adyen" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="bottomline" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="chargehive" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="checkout" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="clearhaus" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="cwams" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="epx" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="flexpay" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="gpayments" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="kount" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="qualpay" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="recaptcha" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="tokenex" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="trustpayments" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="worldpay" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="yapstone" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="chargie" size="32" library="brands"></zn-icon></span>
<span class=icncont><zn-icon src="chargie-head" size="32" library="brands"></zn-icon></span>

Custom Images

Use custom images by providing a file path or URL in the src attribute. When using a path with a forward slash, the icon automatically uses the src library mode.

<zn-icon src="https://via.placeholder.com/32" size="32"></zn-icon>
<zn-icon src="https://via.placeholder.com/48" size="48"></zn-icon>

You can also explicitly set library="src":

<zn-icon src="https://via.placeholder.com/32" library="src" size="32"></zn-icon>

Avatar Generation

The avatar library automatically generates avatar initials with consistent color schemes. Perfect for user profiles and identity representation.

Basic Avatars

<zn-icon src="John Doe" library="avatar" size="40" round></zn-icon>
<zn-icon src="Jane Smith" library="avatar" size="40" round></zn-icon>
<zn-icon src="Bob Wilson" library="avatar" size="40" round></zn-icon>
<zn-icon src="Alice Johnson" library="avatar" size="40" round></zn-icon>
<zn-icon src="Mike Brown" library="avatar" size="40" round></zn-icon>

The avatar automatically extracts initials intelligently:

First letter of first word + first letter of any capital letter or word boundary
Supports camelCase (e.g., “ThankYou” → “TY”)
Supports space-separated names (e.g., “John Doe” → “JD”)

Alphabet Display

<zn-icon src="A" size=32 library="avatar" round></zn-icon>
<zn-icon src="B" size=32 library="avatar" round></zn-icon>
<zn-icon src="C" size=32 library="avatar" round></zn-icon>
<zn-icon src="D" size=32 library="avatar" round></zn-icon>
<zn-icon src="E" size=32 library="avatar" round></zn-icon>
<zn-icon src="F" size=32 library="avatar" round></zn-icon>
<zn-icon src="G" size=32 library="avatar" round></zn-icon>
<zn-icon src="H" size=32 library="avatar" round></zn-icon>
<zn-icon src="I" size=32 library="avatar" round></zn-icon>
<zn-icon src="J" size=32 library="avatar" round></zn-icon>
<zn-icon src="K" size=32 library="avatar" round></zn-icon>
<zn-icon src="L" size=32 library="avatar" round></zn-icon>
<zn-icon src="M" size=32 library="avatar" round></zn-icon>
<zn-icon src="N" size=32 library="avatar" round></zn-icon>
<zn-icon src="O" size=32 library="avatar" round></zn-icon>
<zn-icon src="P" size=32 library="avatar" round></zn-icon>
<zn-icon src="Q" size=32 library="avatar" round></zn-icon>
<zn-icon src="R" size=32 library="avatar" round></zn-icon>
<zn-icon src="S" size=32 library="avatar" round></zn-icon>
<zn-icon src="T" size=32 library="avatar" round></zn-icon>
<zn-icon src="U" size=32 library="avatar" round></zn-icon>
<zn-icon src="V" size=32 library="avatar" round></zn-icon>
<zn-icon src="W" size=32 library="avatar" round></zn-icon>
<zn-icon src="X" size=32 library="avatar" round></zn-icon>
<zn-icon src="Y" size=32 library="avatar" round></zn-icon>
<zn-icon src="Z" size=32 library="avatar" round></zn-icon>

Avatars with Colors

Override the automatic color generation by specifying a color attribute:

<zn-icon src="RV" size="40" library="avatar" round></zn-icon>
<zn-icon src="RV" size="40" library="avatar" color="primary"></zn-icon>
<zn-icon src="BG" size="40" library="avatar" color="accent" round></zn-icon>
<zn-icon src="Random Name" size="40" library="avatar" color="error" round></zn-icon>
<zn-icon src="ThankYou" size="40" library="avatar" color="success" round></zn-icon>
<zn-icon src="What NeXt" size="40" library="avatar" color="warning" round></zn-icon>

Avatar Shapes

Avatars work with or without the round attribute:

<zn-icon src="Square Avatar" size="40" library="avatar"></zn-icon>
<zn-icon src="Round Avatar" size="40" library="avatar" round></zn-icon>
<zn-icon src="Padded Avatar" size="48" library="avatar" round padded></zn-icon>

Using shorthand notation:

<zn-icon src="John Doe@avatar" size="40" round></zn-icon>
<zn-icon src="Jane Smith@av" size="40" round></zn-icon>

Gravatar

Gravatar provides globally recognized avatars based on email addresses. Simply provide an email address as the src and the component will automatically detect it and use Gravatar.

<zn-icon src="test1@example.com" size="48" round></zn-icon>
<zn-icon src="user@example.com" size="48" round></zn-icon>
<zn-icon src="hello@example.com" size="48" round></zn-icon>

Gravatar with Fallback

You can specify a fallback image type using the # symbol followed by the fallback type:

<zn-icon src="nonexistent@example.com#identicon" size="48" round></zn-icon>
<zn-icon src="nonexistent@example.com#monsterid" size="48" round></zn-icon>
<zn-icon src="nonexistent@example.com#wavatar" size="48" round></zn-icon>
<zn-icon src="nonexistent@example.com#retro" size="48" round></zn-icon>
<zn-icon src="nonexistent@example.com#robohash" size="48" round></zn-icon>

Explicit library specification:

<zn-icon src="test1@example.com" library="gravatar" size="48"></zn-icon>

Using shorthand notation:

<zn-icon src="test1@example.com@grav" size="48" round></zn-icon>

Libravatar

Libravatar is an open-source alternative to Gravatar. Use it for federated avatar services.

<zn-icon src="test1@example.com" library="libravatar" size="48" round></zn-icon>
<zn-icon src="user@example.com" library="libravatar" size="48" round></zn-icon>

Similar to Gravatar, you can specify fallback options:

<zn-icon src="nonexistent@example.com#identicon" library="libravatar" size="48" round></zn-icon>

Advanced Features

Alt Text for Accessibility

Use the alt attribute to provide alternative text for image-based icons (custom images, Gravatar, Libravatar).

<zn-icon src="https://via.placeholder.com/32" alt="Placeholder image" size="32"></zn-icon>
<zn-icon src="user@example.com" alt="User avatar" size="32" round></zn-icon>

Special Syntax

The icon component supports special syntax in the src attribute for quick configuration.

Hash Symbol (#) for Modifiers

Add modifiers after a # symbol:

<zn-icon src="star#round" size="32" color="warning"></zn-icon>
<zn-icon src="favorite#round" size="32" color="error"></zn-icon>

At Symbol (@) for Library Selection

Quickly specify the library using @:

<zn-icon src="home@material" size="32"></zn-icon>
<zn-icon src="star@line" size="32"></zn-icon>
<zn-icon src="John Doe@avatar" size="40" round></zn-icon>

Combined with modifiers:

<zn-icon src="favorite@material#round" size="32" color="error"></zn-icon>

Slotted Content

When no src is provided and no library is specified, you can use the default slot to insert custom content:

<zn-icon size="32" style="color: var(--zn-color-primary);">
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z"/>
  </svg>
</zn-icon>

CSS Custom Properties

The icon component exposes CSS custom properties for advanced styling:

--icon-size: Controls the icon dimensions (default: 24px)
--icon-color: Controls the icon color (default: inherit)

<zn-icon src="settings" style="--icon-size: 48px; --icon-color: #ff5722;"></zn-icon>
<zn-icon src="home" style="--icon-size: 32px; --icon-color: #3f51b5;"></zn-icon>

CSS Parts

The icon component exposes the icon part for styling the internal icon element:

<style>
  .custom-icon::part(icon) {
    filter: drop-shadow(2px 2px 4px rgba(0, 0, 0, 0.3));
  }
</style>
<zn-icon class="custom-icon" src="star" size="48" color="warning"></zn-icon>

Use Cases

In Buttons

Icons are commonly used within buttons to provide visual context:

Add Item

Delete

Edit

<zn-button icon="add">Add Item</zn-button>
<zn-button icon="delete" color="error">Delete</zn-button>
<zn-button icon="edit" color="info">Edit</zn-button>

Use icons to enhance navigation items:

Home

Settings

Profile

<zn-menu style="max-width: 200px;">
  <zn-menu-item>
    <zn-icon src="home" slot="prefix" size="20"></zn-icon>
    Home
  </zn-menu-item>
  <zn-menu-item>
    <zn-icon src="settings" slot="prefix" size="20"></zn-icon>
    Settings
  </zn-menu-item>
  <zn-menu-item>
    <zn-icon src="person" slot="prefix" size="20"></zn-icon>
    Profile
  </zn-menu-item>
</zn-menu>

Status Indicators

Combine icons with colors to show status:

Active

Error

Warning

Info

<div style="display: flex; gap: 1rem; align-items: center;">
  <div style="display: flex; align-items: center; gap: 0.5rem;">
    <zn-icon src="check_circle" color="success" size="20"></zn-icon>
    <span>Active</span>
  </div>
  <div style="display: flex; align-items: center; gap: 0.5rem;">
    <zn-icon src="error" color="error" size="20"></zn-icon>
    <span>Error</span>
  </div>
  <div style="display: flex; align-items: center; gap: 0.5rem;">
    <zn-icon src="warning" color="warning" size="20"></zn-icon>
    <span>Warning</span>
  </div>
  <div style="display: flex; align-items: center; gap: 0.5rem;">
    <zn-icon src="info" color="info" size="20"></zn-icon>
    <span>Info</span>
  </div>
</div>

User Avatars in Lists

John Smith

john.smith@example.com

Sarah Connor

sarah.connor@example.com

Mike Johnson

mike.johnson@example.com

<div style="display: flex; flex-direction: column; gap: 1rem;">
  <div style="display: flex; align-items: center; gap: 0.75rem;">
    <zn-icon src="John Smith@avatar" size="40" round></zn-icon>
    <div>
      <div style="font-weight: 600;">John Smith</div>
      <div style="font-size: 0.875rem; color: #666;">john.smith@example.com</div>
    </div>
  </div>
  <div style="display: flex; align-items: center; gap: 0.75rem;">
    <zn-icon src="Sarah Connor@avatar" size="40" round></zn-icon>
    <div>
      <div style="font-weight: 600;">Sarah Connor</div>
      <div style="font-size: 0.875rem; color: #666;">sarah.connor@example.com</div>
    </div>
  </div>
  <div style="display: flex; align-items: center; gap: 0.75rem;">
    <zn-icon src="Mike Johnson@avatar" size="40" round></zn-icon>
    <div>
      <div style="font-weight: 600;">Mike Johnson</div>
      <div style="font-size: 0.875rem; color: #666;">mike.johnson@example.com</div>
    </div>
  </div>
</div>

Material Icons Reference

Our icons are taken directly from Material Icons. Click or tap on any icon to copy its name, then you can use it in your HTML like this:

View Icons


<zn-icon src="check"></zn-icon>

Outlined

Filled

All icons

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/icon/icon.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.0.86/dist/components/icon/icon.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/icon/icon.js';

Slots

Name	Description
(default)	The default slot.
`example`	An example slot.

Learn more about using slots.

Events

Name	React Event	Description	Event Detail
`zn-event-name`		Emitted as an example.	-

Learn more about events.

Custom Properties

Name	Description	Default
`--example`	An example CSS custom property.

Learn more about customizing CSS custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<zn-example>

Examples

Basic Usage

Sizes

Colors

Round Icons

Padded Icons

Squared Icons

Blink Animation

Icon Libraries

Material Symbols Outlined (Default)

Material Icons Variants

Shorthand Library Notation

Line Icons

Brand Icons

Custom Images

Avatar Generation

Basic Avatars

Alphabet Display

Avatars with Colors

Avatar Shapes

Gravatar

Gravatar with Fallback

Libravatar

Advanced Features

Alt Text for Accessibility

Special Syntax

Hash Symbol (#) for Modifiers

At Symbol (@) for Library Selection

Slotted Content

CSS Custom Properties

CSS Parts

Use Cases

In Buttons

In Navigation

Status Indicators

User Avatars in Lists

Material Icons Reference

Importing

Slots

Events

Custom Properties

Parts

Dependencies