# Label
> Component for labelling content with certain keywords, showing unread content, highlighting new content and displaying status.

> **Tip**
>
> `Label` is a badge for statuses, counts, and tags — not an HTML `<label>`. To caption a form control, use [`FormField.Label`](https://next.wave-design-system.pages.dev/components/forms/form-field.md).

## Import

```js
import { Label, LabelDot } from '@volue/wave-react';
```

## Examples

### Sizes

`Label` comes in two sizes: `medium` and `small`. By default, it uses `medium` size.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label size="medium">Medium</Label>
  <Label size="small">Small</Label>
</Flex>
```

### Colours

Label can be used to communicate an object's status or attribute, and thus support multiple colour schemes.
Wave's standard palettes are available via the `color` prop.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label>Label</Label>
  <Label color="accent">Label</Label>
  <Label color="success">Label</Label>
  <Label color="danger">Label</Label>
  <Label color="warning">Label</Label>
  <Label color="info">Label</Label>
</Flex>
```

### Variants

Each colour can be used with its default (`strong`) appearance or with `subtle` and `outline` variants.

Subtle and outline labels have more minimal appearance and can be used to avoid visual overload.

```jsx
<Flex flow="column" gap="spacingM">
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="strong">Label</Label>
    <Label variant="strong" color="accent">
      Label
    </Label>
    <Label variant="strong" color="success">
      Label
    </Label>
    <Label variant="strong" color="danger">
      Label
    </Label>
    <Label variant="strong" color="warning">
      Label
    </Label>
    <Label variant="strong" color="info">
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="subtle">Label</Label>
    <Label variant="subtle" color="accent">
      Label
    </Label>
    <Label variant="subtle" color="success">
      Label
    </Label>
    <Label variant="subtle" color="danger">
      Label
    </Label>
    <Label variant="subtle" color="warning">
      Label
    </Label>
    <Label variant="subtle" color="info">
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="outline">Label</Label>
    <Label variant="outline" color="accent">
      Label
    </Label>
    <Label variant="outline" color="success">
      Label
    </Label>
    <Label variant="outline" color="danger">
      Label
    </Label>
    <Label variant="outline" color="warning">
      Label
    </Label>
    <Label variant="outline" color="info">
      Label
    </Label>
  </Flex>
</Flex>
```

### With icons

`Label` can be decorated with supporting icons using `startElement` and `endElement` props.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label
    variant="outline"
    color="accent"
    startElement={<SvgIcon iconName="heart" />}
  >
    Favourite pick
  </Label>
  <Label
    variant="subtle"
    color="warning"
    startElement={<SvgIcon iconName="warning" />}
  >
    Attention needed
  </Label>
  <Label
    variant="strong"
    color="success"
    endElement={<SvgIcon iconName="check" />}
  >
    Task completed
  </Label>
  <Label
    variant="subtle"
    color="success"
    startElement={<SvgIcon iconName="arrowUp" />}
  >
    {'20%'}
  </Label>
  <Label
    variant="subtle"
    color="danger"
    startElement={<SvgIcon iconName="arrowDown" />}
  >
    {'12%'}
  </Label>
</Flex>
```

### With dots

`Label` can be decorated with dot indicator by passing `LabelDot` to `startElement` prop.

> **Tip**
>
> `LabelDot` composes [Hint Dot component](https://next.wave-design-system.pages.dev/components/hint-dot.md).

```jsx
<Flex flow="column">
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="subtle" color="accent" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="success" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="danger" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="warning" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="subtle" color="info" startElement={<LabelDot />}>
      Label
    </Label>
  </Flex>
  <Flex gap="spacingS" wrap="wrap">
    <Label variant="outline" color="accent" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="outline" color="success" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="outline" color="danger" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="outline" color="warning" startElement={<LabelDot />}>
      Label
    </Label>
    <Label variant="outline" color="info" startElement={<LabelDot />}>
      Label
    </Label>
  </Flex>
</Flex>
```

`LabelDot` can be coloured independently from the `Label`, which makes it possible to pair neutral outline labels with colourful dots.

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label variant="outline" startElement={<LabelDot color="colorLazuli60" />}>
    Label
  </Label>
  <Label variant="outline" startElement={<LabelDot color="colorLime60" />}>
    Label
  </Label>
  <Label variant="outline" startElement={<LabelDot color="colorPink60" />}>
    Label
  </Label>
</Flex>
```

### Pill shape

Each label type can be pill-shaped.

```jsx
<Flex gap="spacingS">
  <Label pill color="accent">
    Label
  </Label>
  <Label pill variant="subtle">
    Label
  </Label>
  <Label pill variant="outline" startElement={<SvgIcon iconName="time" />}>
    Label
  </Label>
  <Label pill variant="subtle" color="success" startElement={<LabelDot />}>
    Label
  </Label>
</Flex>
```

Pill labels are typically used for counts:

```jsx
<Flex gap="spacingS">
  <Label pill color="success">
    10
  </Label>
  <Label pill variant="outline" color="danger">
    2
  </Label>
  <Label pill color="danger" size="small">
    543
  </Label>
  <Label pill variant="outline" color="info" size="small">
    615
  </Label>
</Flex>
```

> **Tip**
>
> For decorative icon-only circular containers, use the dedicated [IconFrame](https://next.wave-design-system.pages.dev/components/icon-frame.md) component.

### Removable label

A label can be used as a tag with close button. Use `onRemove` property to make label removable.

```jsx
() => {
  const [colors, setColors] = React.useState(['Danger', 'Success', 'Info']);

  return (
    <Flex flow="column">
      <Flex gap="spacingS">
        {colors.map(color => (
          <Label
            key={color}
            color={color.toLowerCase()}
            onRemove={() =>
              setColors(old => old.filter(state => state !== color))
            }
          >
            {color}
          </Label>
        ))}
      </Flex>
    </Flex>
  );
};
```

### Custom theming

For non-standard use cases, `Label` supports theming via `css` prop which gives you access to [any colour token](https://next.wave-design-system.pages.dev/tokens/colors.md):

```jsx
<Flex gap="spacingS" wrap="wrap">
  <Label
    css={{
      color: '$foregroundAccent',
      backgroundColor: '$backgroundAccentBold'
    }}
  >
    Label
  </Label>
  <Label
    css={{
      color: '$colorWhite',
      backgroundColor: '$colorPurple80'
    }}
  >
    Label
  </Label>
  <Label
    variant="outline"
    css={{
      color: '$colorPurple80'
    }}
    startElement={<LabelDot />}
  >
    Label
  </Label>
</Flex>
```

### Possible applications

Labels can be used within block lists, buttons, headings and more:

```jsx
<Flex flow="column" cross="start">
  <Flex gap="spacingS">
    <Heading as="h2">Heading</Heading>
    <Label color="info" size="small">
      New
    </Label>
  </Flex>

  <Button>
    {'Button'}
    <Label className="mLs" variant="subtle" color="accent" pill size="small">
      2
    </Label>
  </Button>

  <Grid
    columns="3"
    className="bdrAs roundedAs bdr-neutral--subtle pAxl elevationS"
  >
    <Box>Squirrel</Box>
    <Label color="success" variant="subtle">
      Mammal
    </Label>
    <GridItem>
      <Label variant="subtle" pill>
        0
      </Label>
    </GridItem>
    <Box>Koala</Box>
    <Label color="success" variant="subtle">
      Mammal
    </Label>
    <GridItem>
      <Label pill color="warning">
        8
      </Label>
    </GridItem>
    <Box>Dove</Box>
    <Label color="info" variant="subtle" css={{ width: 'max-content' }}>
      Bird
    </Label>
    <GridItem>
      <Label pill color="danger">
        25
      </Label>
    </GridItem>
  </Grid>

  <Flex flow="column" gap="spacingS" cross="start">
    <h4>Filters</h4>
    <Flex gap="spacingS">
      <Label variant="subtle" onRemove={() => {}}>
        {'4WD'}
      </Label>
      <Label variant="subtle" onRemove={() => {}}>
        {'Undamaged'}
      </Label>
      <Label variant="subtle" onRemove={() => {}}>
        {'< 50km'}
      </Label>
      <Label variant="subtle" onRemove={() => {}}>
        {'Black, red'}
      </Label>
    </Flex>
  </Flex>
</Flex>
```

With help of [Anchor component](https://next.wave-design-system.pages.dev/components/layout/anchor.md) you can attach `Label` to a corner of an element:

```jsx
<Flex>
  <Anchor.Root>
    <Avatar.Root of="Fritjof">
      <Avatar.Initials />
    </Avatar.Root>
    <Anchor.Target
      inset="14%"
      as={Label}
      color="danger"
      pill
      size="small"
      showOutlineRing
    >
      {'5'}
    </Anchor.Target>
  </Anchor.Root>
  <Anchor.Root>
    <Button variant="outline" withLoneIcon aria-label="3 filters active">
      <SvgIcon iconName="filter" />
    </Button>
    <Anchor.Target inset="$sizes$2" as={Label} color="info" pill size="small">
      {'3'}
    </Anchor.Target>
  </Anchor.Root>
  <Anchor.Root>
    <Button
      variant="outline"
      withLoneIcon
      aria-label="More than 99 unread messages"
    >
      <SvgIcon iconName="mail" />
    </Button>
    <Anchor.Target inset="$sizes$2" as={Label} color="info" pill size="small">
      {'99+'}
    </Anchor.Target>
  </Anchor.Root>
</Flex>
```

---

## API reference

### Label

| Name              | Type                                                                    | Default     | Description                                                                                                                                                                                                                                                                                                                              | Required |
| ----------------- | ----------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`              | `keyof JSX.IntrinsicElements \| React.ComponentType<any>`               | `span`      | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](https://next.wave-design-system.pages.dev/get-started/composition.md#polymorphism) guide. |          |
| `css`             | `StitchesCss`                                                           |             | Apply styles directly to a component in a similar way how you would define inline styles. Wave uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                                                             |          |
| `color`           | `"neutral" \| "accent" \| "success" \| "danger" \| "info" \| "warning"` | `"neutral"` | The colour of the label.                                                                                                                                                                                                                                                                                                                 |          |
| `variant`         | `"strong" \| "subtle" \| "outline"`                                     | `"strong"`  | Visual variant of the label.                                                                                                                                                                                                                                                                                                             |          |
| `pill`            | `boolean`                                                               |             | When `true`, label is pill-shaped.                                                                                                                                                                                                                                                                                                       |          |
| `size`            | `"small" \| "medium"`                                                   | `medium`    | The size of the label.                                                                                                                                                                                                                                                                                                                   |          |
| `startElement`    | `React.ReactElement`                                                    |             | `ReactElement` to render to the left of the label's children.                                                                                                                                                                                                                                                                            |          |
| `endElement`      | `React.ReactElement`                                                    |             | `ReactElement` to render to the right of the label's children.                                                                                                                                                                                                                                                                           |          |
| `isDisabled`      | `boolean`                                                               |             | When `true`, the label will be disabled,                                                                                                                                                                                                                                                                                                 |          |
| `onRemove`        | `(event: React.MouseEvent<HTMLButtonElement>) => void`                  |             | If present, the label renders a built-in remove button; this callback fires when it's clicked. Mutually exclusive with `removeButton`.                                                                                                                                                                                                   |          |
| `removeLabel`     | `string`                                                                | `"Remove"`  | Accessible name for the built-in remove button.                                                                                                                                                                                                                                                                                          |          |
| `removeButton`    | `React.ReactElement`                                                    |             | Renders a custom element as the remove control instead of the built-in button — styled and positioned like it, with the close icon injected.                                                                                                                                                                                             |          |
| `showOutlineRing` | `boolean`                                                               |             | When `true`, an outline ring around the label is shown. This is useful for a cut-out effect when placing the label over other element.                                                                                                                                                                                                   |          |
| `margin`          | `SpacingToken`                                                          |             | Sets `margin` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                                        |          |
| `marginX`         | `SpacingToken`                                                          |             | Sets `margin-left` and `margin-right` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                |          |
| `marginY`         | `SpacingToken`                                                          |             | Sets `margin-top` and `margin-bottom` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                |          |
| `marginBottom`    | `SpacingToken`                                                          |             | Sets `margin-bottom` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                                 |          |
| `marginLeft`      | `SpacingToken`                                                          |             | Sets `margin-left` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                                   |          |
| `marginRight`     | `SpacingToken`                                                          |             | Sets `margin-right` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                                  |          |
| `marginTop`       | `SpacingToken`                                                          |             | Sets `margin-top` to one of the corresponding [spacing tokens](https://next.wave-design-system.pages.dev/tokens/spacing-and-size.md).                                                                                                                                                                                                    |          |

### LabelDot

| Name    | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ------- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`   | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Wave uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `color` | `ColorToken`  |         | The colour of the dot. Foreground, core and data visualisation values from [colour tokens](https://next.wave-design-system.pages.dev/tokens/colors.md) are available.                                                                        |          |