Foundations

Iconography

Find an icon in the Luke UI set, then use it at the correct size and colour.

Luke UI includes one icon set. All the icons have the same weight, and all use a 24 by 24 grid. The Luke UI stylesheet draws them, so Icon needs no setup beyond the stylesheet import. The stylesheet loads each icon from a data: URL. If your application sets a Content Security Policy, see Installation.

Browse

22 icons

add

arrowDown

arrowLeft

arrowRight

arrowUp

bookOpen

check

checkCircle

chevronDown

chevronLeft

chevronRight

chevronUp

closeCircle

copy

delete

edit

exclamationTriangle

expand

externalLink

minimize

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. iconNames lists the names in no guaranteed order. See Icon for the component API.

Size

Set size to xsmall, small, medium, or large. These sizes currently map to 16, 20, 24, and 32 CSS pixels at a 16px root. They use rem and scale with the root font size.

Icon: Sizes

Open in playground

xsmall

small

medium

large

import { Icon } from '@luke-ui/react/icon';
import { Comparison, ComparisonItem } from '#docs';

export default () => {
	return (
		<Comparison direction="horizontal">
			<ComparisonItem label="xsmall">
				<Icon name="search" size="xsmall" />
			</ComparisonItem>
			<ComparisonItem label="small">
				<Icon name="search" size="small" />
			</ComparisonItem>
			<ComparisonItem label="medium">
				<Icon name="search" size="medium" />
			</ComparisonItem>
			<ComparisonItem label="large">
				<Icon name="search" size="large" />
			</ComparisonItem>
		</Comparison>
	);
};

Controls size the icons inside them, so an icon in a control needs no size. A Button and an Icon Button use xsmall. A field control uses xsmall at the small control size and small at medium. Elsewhere, the default size is medium.

Icon: Size from a control

Open in playground

import { Button } from '@luke-ui/react/button';
import { Icon } from '@luke-ui/react/icon';

export default () => {
	return <Button startContent={<Icon name="add" />}>Add item</Button>;
};

To give a group of icons the same size, set the --luke-icon-size custom property on an element around them. iconSizeVars(size) returns that property for one of the four sizes. Pass the result to the element's style, or to the vars of a Vanilla Extract style. The nearest element that sets the property wins, so an inner group can use another size. An icon that has its own size keeps that size. Loading Spinner takes its size the same way.

Icon: Shared size

Open in playground

import { Cluster } from '@luke-ui/react/cluster';
import { Icon, iconSizeVars } from '@luke-ui/react/icon';

export default () => {
	return (
		<div style={iconSizeVars('small')}>
			<Cluster alignItems="center" gap="space.16">
				<Icon name="chevronLeft" title="Previous" />
				<Icon name="chevronRight" title="Next" />
				<Icon name="search" size="large" title="Search" />
			</Cluster>
		</div>
	);
};

Colour

An icon takes the colour of the text around it, including the readable colour a Luke UI background sets. To change the colour of an icon, wrap it in a Text with a color, as in this example.

Icon: Colour

Open in playground

Primary

Secondary

Neutral

Accent

Info

Success

Warning

Danger

import { Icon } from '@luke-ui/react/icon';
import { Text } from '@luke-ui/react/text';
import { Comparison, ComparisonItem } from '#docs';

export default () => {
	return (
		<Comparison align="center" direction="horizontal">
			<ComparisonItem label="Primary">
				<Text color="primary">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Secondary">
				<Text color="secondary">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Neutral">
				<Text color="neutral">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Accent">
				<Text color="accent">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Info">
				<Text color="info">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Success">
				<Text color="success">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Warning">
				<Text color="warning">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
			<ComparisonItem label="Danger">
				<Text color="danger">
					<Icon name="checkCircle" />
				</Text>
			</ComparisonItem>
		</Comparison>
	);
};

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.

Icon: Decorative

Open in playground

Continue

import { Cluster } from '@luke-ui/react/cluster';
import { Icon } from '@luke-ui/react/icon';
import { Text } from '@luke-ui/react/text';

export default () => {
	return (
		<Cluster alignItems="center" gap="space.4">
			<Text>Continue</Text>
			<Icon name="externalLink" size="xsmall" />
		</Cluster>
	);
};

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

Icon: Informative

Open in playground

import { Icon } from '@luke-ui/react/icon';

export default () => {
	return <Icon name="checkCircle" title="Payment complete" />;
};

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

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. See Icon.

Browse

Use an icon

Size

Colour

Accessibility

When the set does not have an icon

Continue learning

Icon

Icon Button