Icon

An icon is a symbol representing a command, device, directory, or common action.

Icon explorer Examples Code Usage Changelog

Default (16px)

Icons default to a medium size of 16px.

import React from 'react';

import AttachmentIcon from '@atlaskit/icon/core/attachment';
import ImageIcon from '@atlaskit/icon/core/image';
import OfficeBuildingIcon from '@atlaskit/icon/core/office-building';
import StopwatchIcon from '@atlaskit/icon/core/stopwatch';
import { Inline } from '@atlaskit/primitives/compiled';

const IconDefaultNewExample = (): React.JSX.Element => {
	return (
		<Inline space="space.100">
			<ImageIcon label="" />
			<AttachmentIcon label="" />
			<OfficeBuildingIcon label="" />
			<StopwatchIcon label="" />
		</Inline>
	);
};

export default IconDefaultNewExample;

Small (12px)

New

Small icons are now available, providing a fully downscaled set of icons. These replace utility icons, which are deprecated.

Small icons are 12px, for use next to small size text, such as in bylines, and inside small components such as lozenges.

import React from 'react';

import ArrowRightIcon from '@atlaskit/icon/core/arrow-right';
import ChevronIcon from '@atlaskit/icon/core/chevron-down';
import DragHandleVerticalIcon from '@atlaskit/icon/core/drag-handle-vertical';
import StatusErrorIcon from '@atlaskit/icon/core/status-error';
import { Inline } from '@atlaskit/primitives/compiled';

const IconSmallNewExample = (): React.JSX.Element => {
	return (
		<Inline space="space.100">
			<ChevronIcon label="" size="small" />
			<ArrowRightIcon label="" size="small" />
			<StatusErrorIcon label="" size="small" />
			<DragHandleVerticalIcon label="" size="small" />
		</Inline>
	);
};

export default IconSmallNewExample;

Label

If an icon doesn’t have an existing text label or accessible text, provide a clear label with the label prop.

If an icon is associated with a button or element that also has a text label, you don’t need to provide alternative text for the icon, because the label clarifies the meaning of the icon. You can do this by setting the label prop to an empty string ("").

Icons with labels:

Beta release

Saving was interrupted

Icons without labels:

Last edited: yesterday

Merged

import React from 'react';

import Button from '@atlaskit/button/default/button';
import IconButton from '@atlaskit/button/icon/button';
import Heading from '@atlaskit/heading/heading';
import AddIcon from '@atlaskit/icon/core/add';
import EditIcon from '@atlaskit/icon/core/edit';
import EpicIcon from '@atlaskit/icon/core/epic';
import FiltersIcon from '@atlaskit/icon/core/filter';
import MergeSuccessIcon from '@atlaskit/icon/core/merge-success';
import StatusWarningIcon from '@atlaskit/icon/core/status-warning';
import { Inline, Stack, Text } from '@atlaskit/primitives/compiled';
import { token } from '@atlaskit/tokens';

const IconLabelExample = (): React.JSX.Element => {
	return (
		<Inline space="space.1000">
			<Stack space="space.200" alignBlock="center">
				<Heading size="small">Icons with labels:</Heading>
				<Inline space="space.100" alignBlock="center">
					<EpicIcon color={token('color.icon.accent.purple')} label="Issue type: Epic" />
					<Text weight="bold">Beta release</Text>
				</Inline>
				<Inline space="space.100" alignBlock="center">
					<StatusWarningIcon color={token('color.icon.warning')} label="warning" />
					<Text weight="bold" color="color.text.warning">
						Saving was interrupted
					</Text>
				</Inline>
				<IconButton label="Add" icon={AddIcon} />
			</Stack>
			<Stack space="space.200" alignBlock="center">
				<Heading size="small">Icons without labels:</Heading>
				<Inline space="space.100" alignBlock="center">
					<EditIcon color={token('color.text')} label="" />
					<Text color="color.text">Last edited: yesterday</Text>
				</Inline>
				<Inline space="space.100" alignBlock="center">
					<MergeSuccessIcon color={token('color.text.success')} label="" />
					<Text color="color.text.success">Merged</Text>
				</Inline>
				<Button iconBefore={FiltersIcon}>Filters</Button>
			</Stack>
		</Inline>
	);
};

export default IconLabelExample;

Color

Icons can use color tokens for icons, text, links, or the current text color.

import React from 'react';

import { cssMap } from '@atlaskit/css';
import LinkIcon from '@atlaskit/icon/core/link';
import SettingsIcon from '@atlaskit/icon/core/settings';
import StatusErrorIcon from '@atlaskit/icon/core/status-error';
import WhiteboardIcon from '@atlaskit/icon/core/whiteboard';
import ButtonItem from '@atlaskit/menu/button-item';
import { Box, Flex, Inline, Stack } from '@atlaskit/primitives/compiled';
import { token } from '@atlaskit/tokens';

const iconSpacingStyles = cssMap({
	space050: {
		paddingBlock: token('space.050'),
		paddingInline: token('space.050'),
	},
});

const IconColorExample = (): React.JSX.Element => {
	const [isMenuSelected, setIsMenuSelected] = React.useState(true);
	return (
		<Stack space="space.200" alignBlock="center">
			<Inline space="space.100">
				<WhiteboardIcon color={token('color.icon.accent.teal')} label="" />
				<StatusErrorIcon color={token('color.icon.danger')} label="" />
				<LinkIcon color={token('color.link')} label="" />
			</Inline>
			<Box testId="button-items">
				<ButtonItem
					isSelected={isMenuSelected}
					iconBefore={
						<Flex xcss={iconSpacingStyles.space050}>
							<SettingsIcon label="" />
						</Flex>
					}
					onClick={() => setIsMenuSelected(!isMenuSelected)}
				>
					Settings
				</ButtonItem>
			</Box>
		</Stack>
	);
};

export default IconColorExample;

Spacing props (deprecated)

The spacing prop is deprecated because icons work best when they're spacing-neutral — padding belongs in the layout around them, not built into the icon itself. Remove spacing from your icons and add padding to the surrounding component or frame instead. Engineers can use the 32.0.2-icon-spacing-to-flex-primitive codemod via npx @atlaskit/codemod-cli or use the @atlaskit/design-system/no-icon-spacing-prop ESLint rule, (opens new window) rule will flag and suggest fixes for any remaining usages.

Medium icon — `spacing` prop Deprecated

Medium icon — Flex with padding (1:1 migration)

Small icon — `spacing` prop Deprecated

Small icon — Flex with padding (1:1 migration)

import React from 'react';

import Code from '@atlaskit/code/code';
import { cssMap } from '@atlaskit/css';
import Heading from '@atlaskit/heading/heading';
import AddIcon from '@atlaskit/icon/core/add';
import ChevronDownIcon from '@atlaskit/icon/core/chevron-down';
import Lozenge from '@atlaskit/lozenge/lozenge';
import { Flex, Inline, Stack } from '@atlaskit/primitives/compiled';
import { token } from '@atlaskit/tokens';

const iconContainerStyles = cssMap({
	root: {
		borderStyle: 'dashed',
		borderRadius: token('radius.small'),
		borderColor: token('color.border.accent.magenta'),
		borderWidth: token('border.width'),
	},
});

/**
 * 1:1 migration styles generated by the `next-icon-spacing-to-flex-primitive` codemod
 * and the `@atlaskit/design-system/no-icon-spacing-prop` ESLint rule suggestion.
 * Wrap icons in a `<Flex xcss={iconSpacingStyles.spaceXXX}>` to replace the deprecated `spacing` prop.
 * Where possible, prefer updating the parent component's padding instead.
 */
const iconSpacingStyles = cssMap({
	space050: {
		paddingBlock: token('space.050'),
		paddingInline: token('space.050'),
	},
	space075: {
		paddingBlock: token('space.075'),
		paddingInline: token('space.075'),
	},
	space025: {
		paddingBlock: token('space.025'),
		paddingInline: token('space.025'),
	},
});

const IconContainer = ({ children }: { children: React.ReactNode }) => (
	<Flex xcss={iconContainerStyles.root}>{children}</Flex>
);

const IconSpacingExample = (): JSX.Element => {
	return (
		<Stack space="space.400">
			{/* Medium icons */}
			<Stack space="space.150">
				<Heading size="small">
					Medium icon — <Code>spacing</Code> prop{' '}
					<Lozenge appearance="warning" isBold>
						Deprecated
					</Lozenge>
				</Heading>
				<Inline space="space.200" alignBlock="center">
					<IconContainer>
						<AddIcon label="" />
					</IconContainer>
					<IconContainer>
						{/* eslint-disable-next-line @atlaskit/design-system/no-icon-spacing-prop -- deprecated, shown for migration reference */}
						<AddIcon label="" spacing="spacious" />
					</IconContainer>
				</Inline>
			</Stack>

			<Stack space="space.150">
				<Heading size="small">Medium icon — Flex with padding (1:1 migration)</Heading>
				<Inline space="space.200" alignBlock="center">
					<IconContainer>
						<AddIcon label="" />
					</IconContainer>
					<IconContainer>
						<Flex xcss={iconSpacingStyles.space050}>
							<AddIcon label="" />
						</Flex>
					</IconContainer>
				</Inline>
			</Stack>

			{/* Small icons */}
			<Stack space="space.150">
				<Heading size="small">
					Small icon — <Code>spacing</Code> prop{' '}
					<Lozenge appearance="warning" isBold>
						Deprecated
					</Lozenge>
				</Heading>
				<Inline space="space.200" alignBlock="center">
					<IconContainer>
						<ChevronDownIcon label="" size="small" />
					</IconContainer>
					<IconContainer>
						{/* eslint-disable-next-line @atlaskit/design-system/no-icon-spacing-prop -- deprecated, shown for migration reference */}
						<ChevronDownIcon label="" size="small" spacing="compact" />
					</IconContainer>
					<IconContainer>
						{/* eslint-disable-next-line @atlaskit/design-system/no-icon-spacing-prop -- deprecated, shown for migration reference */}
						<ChevronDownIcon label="" size="small" spacing="spacious" />
					</IconContainer>
				</Inline>
			</Stack>

			<Stack space="space.150">
				<Heading size="small">Small icon — Flex with padding (1:1 migration)</Heading>
				<Inline space="space.200" alignBlock="center">
					<IconContainer>
						<ChevronDownIcon label="" size="small" />
					</IconContainer>
					<IconContainer>
						<Flex xcss={iconSpacingStyles.space025}>
							<ChevronDownIcon label="" size="small" />
						</Flex>
					</IconContainer>
					<IconContainer>
						<Flex xcss={iconSpacingStyles.space075}>
							<ChevronDownIcon label="" size="small" />
						</Flex>
					</IconContainer>
				</Inline>
			</Stack>
		</Stack>
	);
};

export default IconSpacingExample;

Was this page helpful?

We use this feedback to improve our documentation.