---
title: Tag
summary: Use tags to show compact metadata values with optional media, badges, and remove actions.
description: Build inline tag elements with the tag class API and related tag part classes.
layout: '@layouts/DocsMdxLayout.astro'
---
import Example from '@components/Example.astro';
import Flag from '@ui/Flag.astro';
import Icon from '@ui/Icon.astro';
import Payment from '@ui/Payment.astro';
import TagsList from '@ui/TagsList.astro';

## Overview

Use `.tag` for one inline tag item. The base style supports text and an optional `.btn-close` remove action.

<Example centered>
<span class="tag"> Label <a href="#" class="btn-close" aria-label="Remove label"></a> </span>
</Example>

## Variants

### With icon

Use `.tag-icon` for a leading icon inside a tag. The icon uses compact size and secondary text color.

<Example centered>
<span class="tag"> <Icon name="star" class="tag-icon" /> Featured <a href="#" class="btn-close" aria-label="Remove featured tag"></a> </span>
</Example>

### With avatar, flag, or payment

Use `.tag-avatar`, `.tag-flag`, or `.tag-payment` to add media at the start of the tag. These classes keep spacing aligned with tag content.

<Example centered>
<TagsList> <span class="tag"> <span class="avatar avatar-xs tag-avatar">AP</span> Alex P. <a href="#" class="btn-close" aria-label="Remove Alex tag"></a> </span> <span class="tag"> <Flag flag="us" size="xxs" class="tag-flag" />United States <a href="#" class="btn-close" aria-label="Remove country tag"></a> </span> <span class="tag"> <Payment provider="visa" size="xxs" class="tag-payment" />Visa <a href="#" class="btn-close" aria-label="Remove payment tag"></a> </span> </TagsList>
</Example>

### With badge

Use `.tag-badge` for small numeric or status counters. The badge variant keeps compact padding for tag layout.

<Example centered>
<span class="tag"> Notifications <span class="badge tag-badge">12</span> <a href="#" class="btn-close" aria-label="Remove notifications tag"></a> </span>
</Example>

### With checkbox

Use `.tag-check` on a checkbox when the tag should be selectable. This variant is useful for filter sets and selectable labels.

<Example centered>
<span class="tag"> <input type="checkbox" class="form-check-input tag-check" checked /> Selected <a href="#" class="btn-close" aria-label="Remove selected tag"></a> </span>
</Example>

## Examples

### Tags list

Use `.tags-list` for groups of tags. It applies consistent spacing and wrapping between items.

<Example centered>
<TagsList> <span class="tag">Alpha <a href="#" class="btn-close" aria-label="Remove alpha tag"></a></span> <span class="tag">Beta <a href="#" class="btn-close" aria-label="Remove beta tag"></a></span> <span class="tag">Gamma <a href="#" class="btn-close" aria-label="Remove gamma tag"></a></span> <span class="tag">Delta <a href="#" class="btn-close" aria-label="Remove delta tag"></a></span> </TagsList>
</Example>

## Accessibility

- Keep tag labels short and meaningful.
- Add `aria-label` to every close button action.
- Keep selectable tags keyboard reachable when using `.tag-check`.
- Ensure icon or media tags still include readable text.
