Iconography

Luke UI includes one icon set. All the icons have the same weight, and all use a 24 by 24 grid. The build collects the icons into one spritesheet file. The Icon component shows one symbol from that file.

Browse

Use an icon

Import Icon and give it a name from the set. The name prop accepts only the names in the gallery above. The compiler rejects any other name. See Icon for the component API.

Size

Set size to xsmall, small, medium, or large. Each size is a theme token, not a pixel value. A custom theme can give each size a different value.

The default size is medium.

To give a group of icons the same size, put an IconSizeProvider around them. An icon that has its own size prop keeps that size.

Colour

An icon takes the colour of the text around it. To change the colour of an icon, set the colour on the icon or on a parent element.

An icon that gives information must have a contrast ratio of 3 to 1 or more against its background. An icon that only decorates adjacent text has no contrast requirement.

Accessibility

Each icon is decorative or informative.

The icon is decorative when the text next to it gives the meaning. Do not give it a title. The component then hides the icon from assistive technology.

The icon is informative when it appears alone. Give it a title. The component then shows the icon to assistive technology as an image.

Do not set aria-hidden and title on the same icon.

Set up the spritesheet

The Icon component reads its symbols from a spritesheet file. The package supplies this file at @luke-ui/react/spritesheet.svg.

Put an IconSpritesheetProvider around your application. Give the provider the URL of the spritesheet file.

import { IconSpritesheetProvider } from '@luke-ui/react/icon';
import type { PropsWithChildren } from 'react';

export function AppSpritesheetProvider({ children }: PropsWithChildren) {
	return (
		<IconSpritesheetProvider href="/assets/spritesheet.svg">{children}</IconSpritesheetProvider>
	);
}

Your bundler must give a URL for the spritesheet file. It must not inline the file as a data: URL, because a <use> reference to a data: URL does not resolve in all browsers. In Vite, the ?url&no-inline query gives this result.

import spriteSheetHref from '@luke-ui/react/spritesheet.svg?url&no-inline';

When the set does not have an icon

Use createIcon to make a component for a symbol that the set does not include. The new component gets the same size behaviour and accessibility behaviour as Icon.

Continue learning