> ## Documentation Index
> Fetch the complete documentation index at: https://swish.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Header

> Add the Swish button to your store header.

The header placement adds a button that opens the Swish drawer. It displays a heart icon and an optional badge showing how many items the customer has saved. By default, Swish places this button in your store's header through the app embed.

## Setup

Use `swish.placements.create()` to position the button in your header. Target the container where your header icons live.

```js theme={null}
swish.placements.create({
  id: "header-header-button",
  target: {
    selector: ".header__icons",
  },
  mount: {
    mode: "prepend",
  },
  element: {
    name: "header-button",
  },
});
```

## Styling

Pass design tokens under `design` to match the button to your header style.

```js theme={null}
swish.placements.create({
  id: "header-header-button",
  target: { selector: ".header__icons" },
  mount: { mode: "prepend" },
  element: { name: "header-button" },
  design: {
    height: 44,
    iconSize: 24,
    iconStrokeWidth: 1.5,
    statusIndicatorBackground: "#e24b4a",
    statusIndicatorInset: "0 0 auto auto",
  },
});
```

Left alone, the button looks like the theme's own header icons: a 44px button around a 20px heart drawn in the header's text colour, with the badge centred on the heart's corner and no ring around it. Set `iconSize`, `iconStrokeWidth` or `iconColor` to change it.

| Token | Type | Description |
| - | - | - |
| `width` | `string \| number` | Button width. Numbers are treated as pixels. |
| `height` | `string \| number` | Button height. Numbers are treated as pixels. |
| `iconSize` | `string \| number` | Heart icon size. |
| `iconStrokeWidth` | `number` | Icon line weight. |
| `iconMarginLeft` | `string \| number` | Space left of the icon. |
| `iconMarginRight` | `string \| number` | Space right of the icon. |
| `iconColor` | `string` | Icon color. |
| `statusIndicatorBackground` | `string` | Badge color. |
| `statusIndicatorTextColor` | `string` | Badge text color. |
| `statusIndicatorFontSize` | `string \| number` | Badge text size. |
| `statusIndicatorFontWeight` | `string \| number` | Badge text weight. |
| `statusIndicatorSize` | `string \| number` | Badge diameter. |
| `statusIndicatorPadding` | `string \| number` | Badge padding. |
| `statusIndicatorBorderRadius` | `string \| number` | Badge corner radius. |
| `statusIndicatorOutline` | `string` | Badge outline, e.g. `2px solid #fff`. |
| `statusIndicatorInset` | `string` | Badge corner, as a CSS `inset` shorthand. Defaults to `0 0 auto auto` (top right). |
| `statusIndicatorOffsetX` | `string \| number` | Nudges the badge horizontally from that corner. |
| `statusIndicatorOffsetY` | `string \| number` | Nudges the badge vertically from that corner. |

## Customize the button

Control what the button shows using element props:

```js theme={null}
swish.placements.create({
  id: "header-header-button",
  target: { selector: ".header__icons" },
  mount: { mode: "prepend" },
  element: {
    name: "header-button",
    props: {
      iconOnly: false,
      text: "Saved",
      hideCount: true,
    },
  },
});
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `iconOnly` | `boolean` | `false` | Show only the heart icon, without `text`. Not exposed in the Swish admin, which offers a **Show text** toggle instead and publishes `iconOnly: true` when it is off. |
| `text` | `string` | `""` | Label shown beside the icon. Blank renders an icon-only button. The Swish admin seeds **Wishlist** for a new placement. |
| `hideStatus` | `boolean` | `false` | Hide the notification badge entirely. |
| `hideCount` | `boolean` | `false` | Hide the numeric count but still show the dot indicator. |
| `showZeroCount` | `boolean` | `false` | Show the badge even when the count is zero. |

By default the badge is hidden when nothing is saved. `showZeroCount` keeps it
visible at zero — it acts on the count, so it has no effect alongside
`hideCount`.

> [!NOTE]
>
> With no `text`, the button has nothing to render beside the icon, so it stays
> icon-only whatever `iconOnly` says.

## Programmatic creation

Create the button outside of the placement system:

```js theme={null}
const button = await swish.ui.createElement("header-button");
button.setAttribute("icon-only", "true");
document.querySelector(".header__icons").prepend(button);
```

## Further reading

* [Placements overview](https://swish.app/docs/guides/customize/placements/overview.md) for mount options, layout types, and responsive values
* [Drawer](https://swish.app/docs/guides/customize/views/drawer.md) to configure the drawer that the button opens
* [Placements reference](https://swish.app/docs/references/sdk/placements.md) for the full API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.