Icon

Overview

<Icon> renders an SVG <use> reference into a sprite sheet by default, or an icon-font glyph when font is set. It's this library's default icon renderer, not a requirement: the components that draw icons of their own (Pagination, the carousel controls, NavbarToggler, the check on a selected menu or combobox item, and a string icon on Toast/Notification) let you swap in any icon set, including your own icon component — see Replacing the library's icons.

Basic usage

Pass a name matching a symbol id in the sprite. By default <Icon> references a sprite embedded in the page (<use href="#check-solid">), which is what this site does. To reference a sprite file instead, see Sprite file.

import { Icon } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Icon name="check-solid" />
      <Icon name="gear-outline" />
      <Icon name="search-solid" />
    </>
  )
}

Sizing

size takes a number of pixels or any CSS length ("1.25rem", "1em"). It sets chassis-css's --cx-icon-size on the icon, so it works for font glyphs too. Without size, an icon takes the size chassis-css gives it in context: inside a button, an input, a navbar toggler, and so on. To change the default size everywhere, set --cx-icon-size in your stylesheet.

import { Icon } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Icon name="check-solid" size={16} />
      <Icon name="check-solid" size={24} />
      <Icon name="check-solid" size={32} />
      <Icon name="check-solid" size={48} />
    </>
  )
}

Accessible name

An icon renders aria-hidden="true" by default, on the assumption that it sits next to visible text conveying the same meaning (a labeled button, a heading). Pass title to expose it to assistive technology instead — for an icon-only control where nothing else in the surrounding markup states its purpose.

import { Icon } from '@chassis-ui/react'

export const Example = () => {
  return <Icon name="exclamation-triangle-solid" title="Warning" />
}

Setting title alone is only correct when <Icon> is the sole content of its own accessible element, e.g. a link or button with no other text. Inside an icon-only <Button> or <CloseButton>, prefer that component's own aria-label/label prop over Icon's title — it names the control itself, which is what assistive technology actually announces.

Font glyphs

Setting font renders a <span class="cx-{name}"> instead of an SVG reference. This mode depends on the icon set's separate font CSS being loaded in the application. This library ships no icon font of its own, and this docs site loads only the SVG sprite, so the snippet below isn't shown as a live example:

<Icon name="check-solid" font />

An icon font generated with a different class prefix works too: set fontPrefix on IconProvider.

Sprite file

When the sprite is a file rather than embedded in the page, point sprite at its URL, either per icon or once for the whole app with IconProvider:

<Icon name="check-solid" sprite="/static/icons/chassis-icons.svg" />

Browsers don't load an external sprite from another origin, so serve the file from your own domain (not a CDN), or embed it in the page.

IconProvider

IconProvider sets defaults for every <Icon> below it: sprite, className, font, and fontPrefix. It also configures the library's own icons (below). An <Icon>'s own props still win, and nested providers extend the one above them.

// app/layout.tsx
import { IconProvider } from '@chassis-ui/react/icon'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <IconProvider sprite="/static/icons/chassis-icons.svg">{children}</IconProvider>
      </body>
    </html>
  )
}

Replacing the library's icons

Components that draw an icon of their own ask for it by purpose: check, previous, next, menu, more, play, pause, increment, decrement, search, clear, and expand. Map any of them in IconProvider's icons, either to another icon name or to an element from any icon set:

import { IconProvider, Pagination } from '@chassis-ui/react'
import { useState } from 'react'

export const Example = () => {
  const [page, setPage] = useState(2)

  return (
    <IconProvider icons={{ previous: 'arrow-left-outline', next: 'arrow-right-outline' }}>
      <Pagination activePage={page} pages={5} onActivePageChange={setPage} />
    </IconProvider>
  )
}

import { Check, ChevronLeft, ChevronRight } from 'lucide-react'

<IconProvider icons={{ check: <Check />, previous: <ChevronLeft />, next: <ChevronRight /> }}>

An element keeps its own size and color, and gets the class the component positions it by (for example menu-item-check, or directional-icon, which flips arrows in right-to-left layouts), plus aria-hidden. It doesn't get the icon class, since .icon sets fill and would paint over an outline icon set's fill="none".

To render every icon name with your own icon component instead, pass it as component. It receives name, className, and aria-hidden:

'use client'

import { IconProvider, type IconComponentProps } from '@chassis-ui/react/icon'
import { MyIcon } from './MyIcon'

const AppIcon = ({ name, ...props }: IconComponentProps) => <MyIcon glyph={name} {...props} />

export function Providers({ children }) {
  return <IconProvider component={AppIcon}>{children}</IconProvider>
}

component takes a component reference, which can't be passed from a React Server Component, so set it in a 'use client' module like the one above. icons with names or elements can be set directly from a Server Component.

A single instance can also override its icon: Pagination takes previousIcon and nextIcon, CarouselControlPrev/CarouselControlNext take icon, CarouselPlayPause takes playIcon and pauseIcon, NavbarToggler takes icon, NumberField takes incrementIcon and decrementIcon, SearchField takes searchIcon and clearIcon, and Tree takes expandIcon.

Icons drawn by chassis-css itself (the close button, carets, the datepicker arrows, and checkbox marks) are CSS masks. Restyle those through their custom properties, such as --cx-close-button-icon.

API

Icon

IconProvider