# Tag

Tags are compact, inline elements used to label, categorize, or organize items. They provide visual metadata and can optionally be dismissed by users.

## When to Use

- **Categorization**: Label items with topics, categories, or types
- **Filtering**: Display active filters or search criteria
- **Status**: Show status indicators or states
- **User Input**: Display selected items in multi-select scenarios
- **Metadata**: Show additional information about content

## When Not to Use

- **Navigation**: Use `Button` or `Link` for navigation actions
- **Actions**: Use `Button` for primary or secondary actions
- **Long text**: Tags should contain short, scannable text
- **Complex content**: For multi-line or detailed content, use `Badge` or `Card`

## Component

---

### Properties

- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Visual theme of the tag
- **`size`** `string` (default: `inline`) — Size of the tag
- **`isClosable`** `boolean` (default: `false`) — Whether the tag can be closed
- **`onClose`** `() => void` — Handler called when close button is pressed
- **`closeButtonStyles`** `Styles` — Custom styles for the close button
- **`icon`** `ReactNode` — Icon displayed before the content
- **`rightIcon`** `ReactNode` — Icon displayed after the content
- **`prefix`** `ReactNode` — Content rendered before the label
- **`suffix`** `ReactNode` — Content rendered after the label
- **`description`** `ReactNode` — Secondary text below the main content
- **`tooltip`** `string | boolean | object` (default: `true`) — Tooltip configuration: string for text, `true` for auto overflow tooltips, or object for advanced config
- **`hotkeys`** `string` — Keyboard shortcut displayed and triggered
- **`isSelected`** `boolean` (default: `false`) — Whether the tag shows as selected with a checkmark
- **`isLoading`** `boolean` (default: `false`) — Show loading state, replacing an icon slot with a spinner
- **`actions`** `ReactNode` — Inline action buttons displayed on the right side
- **`autoHideActions`** `boolean` (default: `false`) — When true, actions are hidden by default and shown on hover or focus
- **`preserveActionsSpace`** `boolean` (default: `false`) — Preserve the actions width when hidden (only changes opacity, not layout)
- **`disableActionsFocus`** `boolean` (default: `false`) — Disable focus on action buttons by setting tabIndex to -1
- **`level`** `1 | 2 | 3 | 4 | 5 | 6` (default: `3`) — Heading level for the label element when type is "header" or "card"
- **`highlight`** `string` — String to highlight within children text
- **`highlightCaseSensitive`** `boolean` (default: `false`) — Whether highlight matching is case-sensitive

Inherits from [Item](./Item.md).

### Base Properties

Supports [Base properties](../../BaseProperties.md)

## Examples

### Themes

Tags support multiple themes for different semantic meanings:

Available themes:
- **Default**: Neutral, for general categorization
- **Warning**: Yellow/amber, caution or attention needed
- **Note**: Violet, informational content
- **Success**: Green, positive states or completed actions
- **Danger**: Red, errors or destructive actions
- **Special**: Purple, highlighted or premium features
- **Disabled**: Gray, inactive or unavailable items

### With Icons

Icons can be added to provide additional visual context:

```jsx
import { IconCoin } from '@tabler/icons-react';

<Tag icon={<IconCoin />}>With Icon</Tag>
```

### Closable Tags

Tags can be made dismissible with the `isClosable` prop:

All themes support the closable variant:

```jsx
<Tag isClosable onClose={() => console.log('Tag closed')}>
  Closable Tag
</Tag>
```

### Closable with Icons

Combine icons with closable functionality:

### Sizes

Tags support multiple sizes inherited from the Item component:

- **inline** (default): Compact size that fits inline with text
- **xsmall**: Extra small button-like size
- **small**: Small button-like size
- **medium**: Medium button-like size
- **large**: Large button-like size

### Custom Styles

Apply custom styling using the `styles` prop:

```jsx
<Tag
  styles={{
    fill: '#purple.10',
    color: '#purple',
    border: '#purple.30',
  }}
>
  Custom Tag
</Tag>
```

## Best Practices

### Content

- Keep tag text short and scannable (1-3 words ideal)
- Use sentence case for tag labels
- Use consistent terminology across similar tags
- Avoid punctuation unless necessary

### Interaction

- Only make tags closable when users can dismiss them
- Provide feedback when a tag is closed (e.g., update list)
- Consider confirmation for destructive closures
- Ensure close buttons are accessible via keyboard

### Visual Design

- Use theme consistently for semantic meaning
- Don't mix too many themes in the same group
- Maintain adequate spacing between tags
- Consider wrapping behavior for multiple tags

### Accessibility

- Tags have `role="status"` for screen readers
- Close buttons include `aria-label="Close"`
- All themes maintain sufficient color contrast
- Keyboard navigation is fully supported via Item

## Related Components

- **Badge**: For numerical indicators or counts
- **Chip**: For interactive selection chips
- **Button**: For actions and navigation
- **Item**: Base component that Tag extends from

## Migration from Legacy Tag

The Tag component now extends from `Item`, providing enhanced functionality:

```jsx
// Old API still works
<Tag type="success">Legacy</Tag>

// New API (preferred)
<Tag theme="success">Modern</Tag>

// New features from Item
<Tag tooltip="Additional info" isDisabled>
  With Tooltip
</Tag>
```

The `type` prop is deprecated in favor of `theme` for consistency with other components.

