Tag

Tags present static metadata or contextual information. They provide a fixed visual treatment, making them ideal for displaying system-defined values, attributes, or informational labels.

import {Tag} from "@qualcomm-ui/react/tag"

Examples

Icons

Icons are supplied using the startIcon and endIcon props.

LabelLabel
<Tag emphasis="neutral" startIcon={Plus}>
  Label
</Tag>
<Tag emphasis="neutral" endIcon={Plus}>
  Label
</Tag>

Variants

A tag renders as one of four types:

  • read-only (default) renders static metadata.
  • dismissable adds a close button. Set variant to dismissable and pair it with the dismiss callback.
  • selectable renders as a toggle <button>. Set variant to selectable.
  • link renders the tag as an anchor. Use the render prop to supply <Link to="…" /> or <a href="…" />. Set aria-current on the active anchor for accessibility. The optional active prop applies the current-item styling.
read-onlydismissablelinkactive link
<Tag>read-only</Tag>
<Tag variant="dismissable">dismissable</Tag>
<Tag variant="selectable">selectable</Tag>
<Tag render={<Link to="/" />}>link</Tag>
<Tag active render={<Link aria-current="true" to="/components/tag" />}>
  active link
</Tag>

Controlled State

Set the initial value using the defaultSelected prop, or use selected and onSelectedChange to control the value manually. These props follow our controlled state pattern. Only applicable when variant is selectable.

import {type ReactElement, useState} from "react"

import {Check, Plus, Star} from "lucide-react"

import {Tag} from "@qualcomm-ui/react/tag"

export function TagControlledDemo(): ReactElement {
  const [selected, setSelected] = useState<boolean>(false)

  return (
    <div className="flex flex-col items-start gap-2">
      <Tag
        endIcon={<Star />}
        onSelectedChange={setSelected}
        selected={selected}
        size="lg"
        startIcon={selected ? Check : Plus}
        variant="selectable"
      >
        {selected ? "Subscribed" : "Subscribe"}
      </Tag>
    </div>
  )
}

Colors

Control the visual emphasis with different colors via the emphasis prop. The default emphasis is brand-outline.

<Tag emphasis="brand-outline" startIcon={Smile} variant="selectable">
  brand-outline
</Tag>
<Tag emphasis="neutral-outline" startIcon={Smile} variant="selectable">
  neutral-outline
</Tag>
<Tag
  emphasis="neutral-outline-brand"
  startIcon={Smile}
  variant="selectable"
>
  neutral-outline-brand
</Tag>
<Tag emphasis="neutral" startIcon={Smile} variant="selectable">
  neutral
</Tag>
<Tag emphasis="info" startIcon={Smile} variant="selectable">
  info
</Tag>
<Tag emphasis="success" startIcon={Smile} variant="selectable">
  success
</Tag>
<Tag emphasis="warning" startIcon={Smile} variant="selectable">
  warning
</Tag>
<Tag emphasis="danger" startIcon={Smile} variant="selectable">
  danger
</Tag>
<Tag emphasis="blue" startIcon={Smile} variant="selectable">
  blue
</Tag>
<Tag emphasis="cyan" startIcon={Smile} variant="selectable">
  cyan
</Tag>
<Tag emphasis="teal" startIcon={Smile} variant="selectable">
  teal
</Tag>
<Tag emphasis="lime" startIcon={Smile} variant="selectable">
  lime
</Tag>
<Tag emphasis="green" startIcon={Smile} variant="selectable">
  green
</Tag>
<Tag emphasis="yellow" startIcon={Smile} variant="selectable">
  yellow
</Tag>
<Tag emphasis="amber" startIcon={Smile} variant="selectable">
  amber
</Tag>
<Tag emphasis="orange" startIcon={Smile} variant="selectable">
  orange
</Tag>
<Tag emphasis="red" startIcon={Smile} variant="selectable">
  red
</Tag>
<Tag emphasis="magenta" startIcon={Smile} variant="selectable">
  magenta
</Tag>
<Tag emphasis="violet" startIcon={Smile} variant="selectable">
  violet
</Tag>
<Tag emphasis="purple" startIcon={Smile} variant="selectable">
  purple
</Tag>

Sizes

Choose from four sizes: sm, md, lg, and xl. The default size is md.

LabelLabelLabelLabel
<Tag size="sm" variant="dismissable">
  Label
</Tag>
<Tag size="md" variant="dismissable">
  Label
</Tag>
<Tag size="lg" variant="dismissable">
  Label
</Tag>
<Tag size="xl" variant="dismissable">
  Label
</Tag>

States

Disable the tag by setting the disabled prop.

LabelLabel
<Tag variant="dismissable">Label</Tag>
<Tag disabled variant="dismissable">
  Label
</Tag>

Shape

Control the shape of the tag with the shape prop. The default shape is square.

LabelLabel
<Tag shape="square">Label</Tag>
<Tag shape="rounded">Label</Tag>

API

<Tag>

PropTypeDefault
v1.25.0
Applies the active style to a link tag. Honored only when it is rendered as an anchor via render. This is purely visual; set aria-current on the anchor for accessibility.
boolean
false
React children prop.
Initial selected state when the component is uncontrolled. Only applicable when variant is selectable. Ignored when selected is provided.
boolean
false
Controls the component's interactivity. If true, the component becomes unresponsive to input and is visually dimmed to indicate its disabled state.
boolean
Accessible label for the dismiss button. Only applicable when variant is dismissable.
string
'Dismiss'
Governs the color of the tag. neutral-outline-brand looks like neutral-outline, except when selected, where it looks like brand-outline.
| 'brand-outline'
| 'neutral-outline'
| 'neutral-outline-brand'
| 'neutral'
| 'info'
| 'success'
| 'warning'
| 'danger'
| 'amber'
| 'blue'
| 'cyan'
| 'green'
| 'lime'
| 'magenta'
| 'orange'
| 'purple'
| 'red'
| 'teal'
| 'violet'
| 'yellow'
| 'kiwi'
| 'outline-brand'
| 'outline-neutral'
'brand-outline'
lucide-react icon, positioned after the button text. Can be supplied as a ReactElement for additional customization. Ignored when variant is dismissable, as it is reserved for the dismiss icon.
| LucideIcon
| ReactElement
Callback fired when the dismiss button is clicked. Only applicable when variant is dismissable.
() => void
Callback fired when the selected state changes. Fires in both controlled and uncontrolled modes. Only applicable when variant is selectable.
(
selected: boolean,
) => void
Deprecated in v1.16.0, migrate to shape

Governs the shape of the tag.
| 'square'
| 'rounded'
'square'
Allows you to replace the component's HTML element with a different tag or component. Learn more
| ReactElement
| ((
props: object,
) => ReactElement)
v1.24.0
Controls the selected state. When omitted, the tag manages its own selected state internally. Only applicable when variant is selectable.
boolean
v1.17.0
Governs the shape of the tag.
| 'square'
| 'rounded'
'square'
Governs the size of the text, icons, spacing, and padding.
| 'sm'
| 'md'
| 'lg'
| 'xl'
'md'
lucide-react icon, positioned before the button text. Can be supplied as a ReactElement for additional customization.
| LucideIcon
| ReactElement
Governs the interactive style of the tag.
| 'selectable'
| 'dismissable'
| 'link'
v1.25.0
Type
boolean
Description
Applies the active style to a link tag. Honored only when it is rendered as an anchor via render. This is purely visual; set aria-current on the anchor for accessibility.
Description
React children prop.
Type
boolean
Description
Initial selected state when the component is uncontrolled. Only applicable when variant is selectable. Ignored when selected is provided.
Type
boolean
Description
Controls the component's interactivity. If true, the component becomes unresponsive to input and is visually dimmed to indicate its disabled state.
Type
string
Description
Accessible label for the dismiss button. Only applicable when variant is dismissable.
Type
| 'brand-outline'
| 'neutral-outline'
| 'neutral-outline-brand'
| 'neutral'
| 'info'
| 'success'
| 'warning'
| 'danger'
| 'amber'
| 'blue'
| 'cyan'
| 'green'
| 'lime'
| 'magenta'
| 'orange'
| 'purple'
| 'red'
| 'teal'
| 'violet'
| 'yellow'
| 'kiwi'
| 'outline-brand'
| 'outline-neutral'
Description
Governs the color of the tag. neutral-outline-brand looks like neutral-outline, except when selected, where it looks like brand-outline.
Type
| LucideIcon
| ReactElement
Description
lucide-react icon, positioned after the button text. Can be supplied as a ReactElement for additional customization. Ignored when variant is dismissable, as it is reserved for the dismiss icon.
Type
() => void
Description
Callback fired when the dismiss button is clicked. Only applicable when variant is dismissable.
Type
(
selected: boolean,
) => void
Description
Callback fired when the selected state changes. Fires in both controlled and uncontrolled modes. Only applicable when variant is selectable.
Type
| 'square'
| 'rounded'
Description
Deprecated in v1.16.0, migrate to shape

Governs the shape of the tag.
Type
| ReactElement
| ((
props: object,
) => ReactElement)
Description
Allows you to replace the component's HTML element with a different tag or component. Learn more
v1.24.0
Type
boolean
Description
Controls the selected state. When omitted, the tag manages its own selected state internally. Only applicable when variant is selectable.
v1.17.0
Type
| 'square'
| 'rounded'
Description
Governs the shape of the tag.
Type
| 'sm'
| 'md'
| 'lg'
| 'xl'
Description
Governs the size of the text, icons, spacing, and padding.
Type
| LucideIcon
| ReactElement
Description
lucide-react icon, positioned before the button text. Can be supplied as a ReactElement for additional customization.
Type
| 'selectable'
| 'dismissable'
| 'link'
Description
Governs the interactive style of the tag.

StartIcon

EndIcon

Note that the endIcon prop is ignored when variant is dismissible.

Updated by Olaf Kappes