Tags

import { ... } from '@ag.ds-next/react/tags';

Do

• use when content has multiple categories
• use with or without links
• add to a page to improve SEO
• use links to filter/group data types
• precede them with an appropriate heading.

Don’t

• use as a status indicator – use StatusBadge
• overwrite Tag colours or fills.
• use Tags with links and remove buttons together, as it is confusing for users.

Tags with links

A list of related tags that use links.

Note: An appropriate heading level should be used to introduce the purpose of the list.

<Tags
	heading={
		<Text as="h2" fontWeight="bold">
			Tags:
		</Text>
	}
	items={[
		{ href: '#', label: 'Apple' },
		{ href: '#', label: 'Orange' },
		{ href: '#', label: 'Peach' },
	]}
/>

Tags without links

A list of related tags without links.

<Tags
	heading={
		<Text as="h2" fontWeight="bold">
			Tags:
		</Text>
	}
	items={[{ label: 'Apple' }, { label: 'Orange' }, { label: 'Peach' }]}
/>

Removable tags

Tags can be removed from a list by passing a function to the onRemove prop.

When a user removes a tag, their focus automatically shifts to the previous tag in the list. If the last tag is removed, focus is lost, and depending on the context, you may need to manually set focus within onRemove to help the user continue their task.

For screen reader users, it’s important to provide feedback when a tag is removed; the method of which depends on the context. In the example below, an explicit announcement is made. More commonly, however, the page that the tags affect would announce the resulting changes (e.g., “25 results found”), similar to the approach used in the Search filter pattern.

Avoid using Tags with links and Remove buttons together, as this will confuse users.

() => {
	const [items, setItems] = React.useState([
		{ label: 'Apple' },
		{ label: 'Orange' },
		{ label: 'Peach' },
	]);
	const [announcement, setAnnouncement] = React.useState('');

	const handleRemove = (label) => {
		setItems((prevItems) => prevItems.filter((item) => item.label !== label));
		setAnnouncement(`${label} removed`);
	};

	const itemsWithHandlers = items.map((item) => ({
		...item,
		onRemove: () => handleRemove(item.label),
	}));

	return (
		<>
			<Box css={visuallyHiddenStyles} role="status">
				{announcement}
			</Box>
			{items.length > 0 ? (
				<Tags
					heading={
						<Text as="h2" fontWeight="bold">
							Tags:
						</Text>
					}
					items={itemsWithHandlers}
				/>
			) : undefined}
		</>
	);
};

Related components

• Indicator dot – Indicator dots are small, decorative, badge-like indicators used to call attention to an item, such as an unread message.
• Notification badge – Notification badges are visual indicators for numeric values.
• Status badge – Status badges are visual indicators used to highlight an item’s status for quick recognition.