---
title: "Tag"
description: "Tags are used to label items by a set of shared properties, like category or status."
url: https://developers.dhis2.org/docs/ui/components/tag
source: https://github.com/dhis2/developer-portal/edit/main/docs/ui/components/tag.md
---

# Tag

Tags are used to label items by a set of shared properties, like category or status.

[Interactive demo: tag--default](https://developers.dhis2.org/demo/?path=/story/tag--default)

## Usage

### When to use

- **Showing a status or category**. Use a tag to give a quick indicator of something's status or category, usually as part of a group of many items.
- **Several items share common properties**. Use tags when several items, like rows in a table, share subsets of common properties. Tags help a user quickly understand which items have which properties.

### When not to use

- **Primary actions**. Don't use tags for any type of important action. A tag isn't a button. A tag could be used to a secondary action, like opening a convenient view of items with similar tags.

### Variants

| Variant  | When to use                                                               |
| -------- | ------------------------------------------------------------------------- |
| Default  | The default choice. Use this if no other variant matches the use case.    |
| Neutral  | Use to communicate neutrality, when something isn't positive or negative. |
| Positive | Use to communicate success or validity.                                   |
| Negative | Use to communicate a problem or error.                                    |

**Default**

        [Interactive demo: tag--default](https://developers.dhis2.org/demo/?path=/story/tag--default)

**Neutral**

        [Interactive demo: tag--neutral](https://developers.dhis2.org/demo/?path=/story/tag--neutral)

**Positive**

        [Interactive demo: tag--positive](https://developers.dhis2.org/demo/?path=/story/tag--positive)

**Negative**

        [Interactive demo: tag--negative](https://developers.dhis2.org/demo/?path=/story/tag--negative)

```jsx
<Tag>Default</Tag>
<Tag neutral>Neutral</Tag>
<Tag positive>Positive</Tag>
<Tag negative>Negative</Tag>
```

### Format

#### Label

- Use short, understandable words for tag labels. If possible, use a single word.

## Options

### Icon

[Interactive demo: tag--with-large-icon](https://developers.dhis2.org/demo/?path=/story/tag--with-large-icon)

```jsx
<Tag icon={<IconCheckmarkCircle16/>} positive>Passed</Tag>
<Tag icon={<IconError16/>} negative>Failed</Tag>
```

- A tag can show an icon before the text label.
- Use icons to support the text label by providing context or a visual reference.
- Don't include icons for decoration only, they add complexity to the interface.

### Bold

**Default**

        [Interactive demo: tag--bold](https://developers.dhis2.org/demo/?path=/story/tag--bold)

**Neutral**

        [Interactive demo: tag--bold](https://developers.dhis2.org/demo/?path=/story/tag--bold)

**Positive**

        [Interactive demo: tag--bold](https://developers.dhis2.org/demo/?path=/story/tag--bold)

**Negative**

        [Interactive demo: tag--bold](https://developers.dhis2.org/demo/?path=/story/tag--bold)

```jsx
<Tag bold>Tag label</Tag>
<Tag bold neutral>Tag label</Tag>
<Tag bold positive>Tag label</Tag>
<Tag bold negative>Tag label</Tag>
```

- Use bold tags where it's important the information is noticed by a user.
- Don't overuse bold tags, only use them when the information is important.

## API Reference

### Tag

#### Usage

To use `Tag`, you can import the component from the `@dhis2/ui` library  

```js
import { Tag } from '@dhis2/ui'
```

#### Props

|Name|Type|Default|Required|Description|
|---|---|---|---|---|
|bold|boolean|||Use bold tags where it is important that the tag is seen by the user in an information dense interface. Bold tags should be reserved for edge cases and not overused.|
|children|node||||
|className|string||||
|dataTest|string|``'dhis2-uicore-tag'``|||
|icon|node|||Tags can contain icons. Use icons where they will help users easily identify the content of the tag. Tags must have a text label and cannot display only an icon.|
|maxWidth|string|``'240px'``|||
|negative|custom|||Red 'negative' tags imply an error or a problem. `neutral`, `positive`, and `negative` are mutually exclusive props|
|neutral|custom|||Blue 'neutral' tags are used when a tag _could_ have valid or error status but is currently neutral. `neutral`, `positive`, and `negative` are mutually exclusive props|
|positive|custom|||Green 'valid' tags should be used to indicate validity or success. `neutral`, `positive`, and `negative` are mutually exclusive props|
