# Header card

> Canonical HTML: https://screenrig.ai/docs/cards/header/

A bar along the top edge of the screen: a left and a right slot, and a message that sits still, crawls or turns through pages.

A bar the full width of the screen, flush to the top edge, rolls up the small things a screen needs. The left and right slots each show one item: words, a tag, a clock, the weather now, an icon, the date, a status dot, your logo, a countdown, a number, the page you are on or a quiet alert that turns warm or red. The middle carries a message that sits still, crawls when it is long or turns through up to eight pages. You set the items and the message and change them while the bar plays; it keeps its place on every screen.

## Live card

This card is drawn in your browser by the same code the Players run, with sample data.

Category: Messages. Tags: Lobbies and reception, Offices and workplaces, Stores.

## Layouts

This bar card is placed as a header: a full-width bar, 80 high, flush to the top edge. It takes no layout or anchor.

Layouts: header. Forms: strip.

[Card layouts, themes and publishing](/docs/cards/). [Browse the cards](/apps/#cards).

## Data and privacy

Feed: `screenrig.weather/v1`.

Feed documents carry source attribution. The Player supplies the feed to the card.

Weather attribution: Weather data by Weatherbit, as named in the feed document.

## Properties

For theme, background and accent, see [Common properties](/docs/cards/#common-properties). A bar card has no `layout` or `anchor` property: it is always placed as its header.

Set static properties in `params`. Bind `data` to a project card data key for live values; that document holds only dynamic properties. Without a data key, put the complete configuration in `params`. Nested rows describe the contents of their parent property.

### Static properties

| Name | Type | Default | Values and limits | Description |
| --- | --- | --- | --- | --- |
| `location` | object, null | `null` | additionalProperties: `false` | Where the weather item reads its conditions; without it there is no weather data and the item stays empty. |
| `location.name` | string |  | maxLength: `40`; Required |  |
| `location.latitude` | number |  | minimum: `-90`; maximum: `90`; Required |  |
| `location.longitude` | number |  | minimum: `-180`; maximum: `180`; Required |  |
| `timeZone` | string, null | `null` | maxLength: `64` | IANA zone of the clock, date and countdown items; null uses the screen's zone. |
| `backgroundColor` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | Overrides the card ground and plate with a flat CSS-ordered colour. #RRGGBBAA supplies opacity. background none takes precedence. |
| `textColor` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | Overrides the main and secondary text colours. Accent and semantic status colours retain their roles. |

### Dynamic properties

| Name | Type | Default | Values and limits | Description |
| --- | --- | --- | --- | --- |
| `left` | object, null | `null` | additionalProperties: `false` | The left slot, 250 px wide (240 x 70 inside it), content at its start. null leaves it empty; it keeps its room. What `kind` reads: text, tag and date `text`; clock `hourCycle` and `timeZone`; weather `unit` (from the weather feed); icon `icon`; status `text`, `tone` and `pulse`; logo `media`; countdown `at` and `label`; number `label` and `value`; page `page`, `of` and `style`; alert `active`, `severity` and `text`. |
| `left.kind` | string |  | `"text"`, `"tag"`, `"clock"`, `"weather"`, `"icon"`, `"date"`, `"status"`, `"logo"`, `"countdown"`, `"number"`, `"page"`, `"alert"`; Required | What the slot shows. |
| `left.text` | string | `""` | maxLength: `60` | The words of a text, tag, status or alert item. |
| `left.size` | string | `"small"` | `"small"`, `"medium"`, `"large"` | Type size of text, tag, date, status and alert items (24, 32 and 44 px at 1080p; small takes two lines, the others one) and of the figures of a clock, weather, countdown, page and icon item. |
| `left.color` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | #RRGGBB or #RRGGBBAA text or icon colour; null takes the theme's text colour. |
| `left.fill` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | A tag's rounded rectangle: #RRGGBB or #RRGGBBAA; null is the text colour at half strength (an outline in the Clear themes). |
| `left.icon` | null, string | `null` | `null`, `"activity-01"`, `"air-vent"`, `"airplane-01"`, `"alert-01"`, `"alert-02"`, `"american-football"`, `"analytics-up"`, `"apple"`, `"arrow-down-01"`, `"arrow-down-right-01"`, `"arrow-up-01"`, `"arrow-up-right-01"`, `"award-01"`, `"baseball"`, `"basketball-01"`, `"battery-full"`, `"bell-ring"`, `"bicycle"`, `"birthday-cake"`, `"bitcoin"`, `"bus-01"`, `"calendar-03"`, `"calendar-04"`, `"calendar-add-01"`, `"calendar-check"`, `"call-02"`, `"camera-01"`, `"cancel-circle"`, `"car-01"`, `"champion"`, `"chart-decrease"`, `"chart-increase"`, `"checkmark-circle-02"`, `"clock-01"`, `"clock-02"`, `"cloud"`, `"cloud-angled-rain"`, `"cloud-angled-zap"`, `"cloud-big-rain"`, `"cloud-drizzle"`, `"cloud-fog"`, `"cloud-hailstone"`, `"cloud-snow"`, `"coffee-01"`, `"coffee-02"`, `"contact-01"`, `"container-truck-01"`, `"cricket-bat"`, `"crown"`, `"delivery-truck-01"`, `"dices"`, `"discord"`, `"discount-tag-01"`, `"dollar-02"`, `"door-closed-locked"`, `"door-open"`, `"drink"`, `"droplet"`, `"ethereum"`, `"euro"`, `"exchange-01"`, `"facebook-01"`, `"factory"`, `"fast-wind"`, `"favourite"`, `"ferry-boat"`, `"fire"`, `"fire-02"`, `"first-aid-kit"`, `"flag-01"`, `"flag-02"`, `"flash"`, `"flower-01"`, `"football"`, `"gauge"`, `"gift"`, `"git-branch"`, `"globe-02"`, `"google"`, `"hand-prayer"`, `"heart"`, `"help-circle"`, `"home-01"`, `"hourglass"`, `"humidity"`, `"ice-hockey"`, `"information-circle"`, `"instagram"`, `"lamp-01"`, `"lantern"`, `"leaf-01"`, `"leaf-02"`, `"lightbulb"`, `"link-01"`, `"linkedin-01"`, `"litecoin"`, `"location-01"`, `"location-04"`, `"mail-01"`, `"medal-first-place"`, `"medical-mask"`, `"meeting-room"`, `"megaphone-01"`, `"message-01"`, `"money-exchange-02"`, `"moon-02"`, `"moon-cloud"`, `"moon-star"`, `"music-note-01"`, `"navigation-03"`, `"new-releases"`, `"new-twitter"`, `"news"`, `"news-01"`, `"noodles"`, `"package-delivered"`, `"parking-area-square"`, `"party"`, `"party-popper"`, `"pause-circle"`, `"percent-circle"`, `"pinterest"`, `"pizza-01"`, `"play-circle"`, `"play-store"`, `"podium"`, `"pound"`, `"pumpkin"`, `"qr-code"`, `"qr-code-01"`, `"queue-01"`, `"quote-down"`, `"quote-up"`, `"ranking"`, `"restaurant-01"`, `"rocket-01"`, `"rss"`, `"running-shoes"`, `"sale-tag-01"`, `"security-check"`, `"shop-sign"`, `"shopping-bag-01"`, `"siren"`, `"smart-phone-01"`, `"snapchat"`, `"snowflake"`, `"sparkles"`, `"spotify"`, `"star"`, `"star-half"`, `"star-off"`, `"stop-circle"`, `"store-01"`, `"sun-03"`, `"sun-cloud-02"`, `"sunrise"`, `"sunset"`, `"swimming"`, `"tag-01"`, `"target-02"`, `"temperature"`, `"tennis-ball"`, `"thermometer"`, `"thermometer-cold"`, `"thermometer-warm"`, `"threads"`, `"ticket-01"`, `"tiktok"`, `"time-quarter-pass"`, `"timer-01"`, `"tornado-02"`, `"train-01"`, `"tram"`, `"trophy"`, `"tropical-storm"`, `"tsunami"`, `"user-02"`, `"user-group"`, `"user-love-01"`, `"vegetarian-food"`, `"volleyball"`, `"volume-high"`, `"vote"`, `"walking"`, `"warehouse"`, `"waves"`, `"whatsapp"`, `"wheat-off"`, `"wifi-01"`, `"wifi-full-signal"`, `"wifi-lock"`, `"wrench-01"`, `"yen"`, `"youtube"` | The icon of an icon item. |
| `left.tone` | string | `"cool"` | pattern: `"^(success\|warm\|danger\|cool\|accent\|muted\|#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?)$"` | The colour of a status dot: a palette key (success is ok or open, warm watch or soon, danger alarm or closed, cool information) or #RRGGBB. |
| `left.pulse` | boolean | `false` |  | A status dot that breathes once a second. |
| `left.hourCycle` | string | `"24"` | `"12"`, `"24"` | A clock's hours: 2:05 PM (12) or 14:05 (24). |
| `left.timeZone` | string, null | `null` | maxLength: `64` | IANA zone of a clock, date or countdown; null takes the bar's zone, else the screen's. |
| `left.dateStyle` | string | `"short"` | `"short"`, `"long"` | A date item: Tue 21 Oct (short) or Tuesday 21 October (long). |
| `left.at` | string, null | `null` | maxLength: `40` | ISO 8601 instant a countdown runs to; without an offset it is wall time in the item's zone. |
| `left.label` | string | `""` | maxLength: `24` | A number's label above its value; the words a countdown shows once its instant has come. |
| `left.value` | string | `""` | maxLength: `16` | A number's value, formatted as you want it read (1,284 or 98%). |
| `left.media` | string | `""` | maxLength: `200` | A logo item's image: a project media reference (media:<id>), fitted whole into 240 x 70. |
| `left.page` | integer | `1` | minimum: `1`; maximum: `999` | A page item's current page, from 1. |
| `left.of` | integer | `1` | minimum: `1`; maximum: `999` | A page item's page count. |
| `left.style` | string | `"numbers"` | `"dots"`, `"numbers"` | A page item as 3 / 8 or as dots (dots keep to twelve pages). |
| `left.active` | boolean | `false` |  | An alert item: false is a quiet check mark, true takes the severity colour and its words. |
| `left.severity` | string | `"warm"` | `"warm"`, `"danger"` | An active alert item's colour: warm for watch, danger for alarm. |
| `left.unit` | string | `"c"` | `"c"`, `"f"` | A weather item's temperature scale: Celsius or Fahrenheit. |
| `right` | object, null | `null` | additionalProperties: `false` | The right slot, 250 px wide (240 x 70 inside it), content at its end. The same items as the left slot. |
| `right.kind` | string |  | `"text"`, `"tag"`, `"clock"`, `"weather"`, `"icon"`, `"date"`, `"status"`, `"logo"`, `"countdown"`, `"number"`, `"page"`, `"alert"`; Required | What the slot shows. |
| `right.text` | string | `""` | maxLength: `60` | The words of a text, tag, status or alert item. |
| `right.size` | string | `"small"` | `"small"`, `"medium"`, `"large"` | Type size of text, tag, date, status and alert items (24, 32 and 44 px at 1080p; small takes two lines, the others one) and of the figures of a clock, weather, countdown, page and icon item. |
| `right.color` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | #RRGGBB or #RRGGBBAA text or icon colour; null takes the theme's text colour. |
| `right.fill` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | A tag's rounded rectangle: #RRGGBB or #RRGGBBAA; null is the text colour at half strength (an outline in the Clear themes). |
| `right.icon` | null, string | `null` | `null`, `"activity-01"`, `"air-vent"`, `"airplane-01"`, `"alert-01"`, `"alert-02"`, `"american-football"`, `"analytics-up"`, `"apple"`, `"arrow-down-01"`, `"arrow-down-right-01"`, `"arrow-up-01"`, `"arrow-up-right-01"`, `"award-01"`, `"baseball"`, `"basketball-01"`, `"battery-full"`, `"bell-ring"`, `"bicycle"`, `"birthday-cake"`, `"bitcoin"`, `"bus-01"`, `"calendar-03"`, `"calendar-04"`, `"calendar-add-01"`, `"calendar-check"`, `"call-02"`, `"camera-01"`, `"cancel-circle"`, `"car-01"`, `"champion"`, `"chart-decrease"`, `"chart-increase"`, `"checkmark-circle-02"`, `"clock-01"`, `"clock-02"`, `"cloud"`, `"cloud-angled-rain"`, `"cloud-angled-zap"`, `"cloud-big-rain"`, `"cloud-drizzle"`, `"cloud-fog"`, `"cloud-hailstone"`, `"cloud-snow"`, `"coffee-01"`, `"coffee-02"`, `"contact-01"`, `"container-truck-01"`, `"cricket-bat"`, `"crown"`, `"delivery-truck-01"`, `"dices"`, `"discord"`, `"discount-tag-01"`, `"dollar-02"`, `"door-closed-locked"`, `"door-open"`, `"drink"`, `"droplet"`, `"ethereum"`, `"euro"`, `"exchange-01"`, `"facebook-01"`, `"factory"`, `"fast-wind"`, `"favourite"`, `"ferry-boat"`, `"fire"`, `"fire-02"`, `"first-aid-kit"`, `"flag-01"`, `"flag-02"`, `"flash"`, `"flower-01"`, `"football"`, `"gauge"`, `"gift"`, `"git-branch"`, `"globe-02"`, `"google"`, `"hand-prayer"`, `"heart"`, `"help-circle"`, `"home-01"`, `"hourglass"`, `"humidity"`, `"ice-hockey"`, `"information-circle"`, `"instagram"`, `"lamp-01"`, `"lantern"`, `"leaf-01"`, `"leaf-02"`, `"lightbulb"`, `"link-01"`, `"linkedin-01"`, `"litecoin"`, `"location-01"`, `"location-04"`, `"mail-01"`, `"medal-first-place"`, `"medical-mask"`, `"meeting-room"`, `"megaphone-01"`, `"message-01"`, `"money-exchange-02"`, `"moon-02"`, `"moon-cloud"`, `"moon-star"`, `"music-note-01"`, `"navigation-03"`, `"new-releases"`, `"new-twitter"`, `"news"`, `"news-01"`, `"noodles"`, `"package-delivered"`, `"parking-area-square"`, `"party"`, `"party-popper"`, `"pause-circle"`, `"percent-circle"`, `"pinterest"`, `"pizza-01"`, `"play-circle"`, `"play-store"`, `"podium"`, `"pound"`, `"pumpkin"`, `"qr-code"`, `"qr-code-01"`, `"queue-01"`, `"quote-down"`, `"quote-up"`, `"ranking"`, `"restaurant-01"`, `"rocket-01"`, `"rss"`, `"running-shoes"`, `"sale-tag-01"`, `"security-check"`, `"shop-sign"`, `"shopping-bag-01"`, `"siren"`, `"smart-phone-01"`, `"snapchat"`, `"snowflake"`, `"sparkles"`, `"spotify"`, `"star"`, `"star-half"`, `"star-off"`, `"stop-circle"`, `"store-01"`, `"sun-03"`, `"sun-cloud-02"`, `"sunrise"`, `"sunset"`, `"swimming"`, `"tag-01"`, `"target-02"`, `"temperature"`, `"tennis-ball"`, `"thermometer"`, `"thermometer-cold"`, `"thermometer-warm"`, `"threads"`, `"ticket-01"`, `"tiktok"`, `"time-quarter-pass"`, `"timer-01"`, `"tornado-02"`, `"train-01"`, `"tram"`, `"trophy"`, `"tropical-storm"`, `"tsunami"`, `"user-02"`, `"user-group"`, `"user-love-01"`, `"vegetarian-food"`, `"volleyball"`, `"volume-high"`, `"vote"`, `"walking"`, `"warehouse"`, `"waves"`, `"whatsapp"`, `"wheat-off"`, `"wifi-01"`, `"wifi-full-signal"`, `"wifi-lock"`, `"wrench-01"`, `"yen"`, `"youtube"` | The icon of an icon item. |
| `right.tone` | string | `"cool"` | pattern: `"^(success\|warm\|danger\|cool\|accent\|muted\|#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?)$"` | The colour of a status dot: a palette key (success is ok or open, warm watch or soon, danger alarm or closed, cool information) or #RRGGBB. |
| `right.pulse` | boolean | `false` |  | A status dot that breathes once a second. |
| `right.hourCycle` | string | `"24"` | `"12"`, `"24"` | A clock's hours: 2:05 PM (12) or 14:05 (24). |
| `right.timeZone` | string, null | `null` | maxLength: `64` | IANA zone of a clock, date or countdown; null takes the bar's zone, else the screen's. |
| `right.dateStyle` | string | `"short"` | `"short"`, `"long"` | A date item: Tue 21 Oct (short) or Tuesday 21 October (long). |
| `right.at` | string, null | `null` | maxLength: `40` | ISO 8601 instant a countdown runs to; without an offset it is wall time in the item's zone. |
| `right.label` | string | `""` | maxLength: `24` | A number's label above its value; the words a countdown shows once its instant has come. |
| `right.value` | string | `""` | maxLength: `16` | A number's value, formatted as you want it read (1,284 or 98%). |
| `right.media` | string | `""` | maxLength: `200` | A logo item's image: a project media reference (media:<id>), fitted whole into 240 x 70. |
| `right.page` | integer | `1` | minimum: `1`; maximum: `999` | A page item's current page, from 1. |
| `right.of` | integer | `1` | minimum: `1`; maximum: `999` | A page item's page count. |
| `right.style` | string | `"numbers"` | `"dots"`, `"numbers"` | A page item as 3 / 8 or as dots (dots keep to twelve pages). |
| `right.active` | boolean | `false` |  | An alert item: false is a quiet check mark, true takes the severity colour and its words. |
| `right.severity` | string | `"warm"` | `"warm"`, `"danger"` | An active alert item's colour: warm for watch, danger for alarm. |
| `right.unit` | string | `"c"` | `"c"`, `"f"` | A weather item's temperature scale: Celsius or Fahrenheit. |
| `middle` | object, null | `null` | additionalProperties: `false` | The message between the slots. Without text (or pages) the middle stays empty and keeps its room; it is hidden when it would be under 100 px wide. |
| `middle.text` | string | `""` | maxLength: `160` | The words of a static or crawling message. |
| `middle.size` | string | `"small"` | `"small"`, `"medium"`, `"large"` | 26 px with up to two lines, 38 px or 52 px on one line, at 1080p. |
| `middle.align` | string | `"center"` | `"start"`, `"center"`, `"end"` | Where the words sit across the middle. |
| `middle.color` | string, null | `null` | pattern: `"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"` | #RRGGBB or #RRGGBBAA text colour; null takes the theme's text colour. |
| `middle.mode` | string | `"static"` | `"static"`, `"crawl"`, `"pages"` | static ends a long message in an ellipsis, crawl scrolls it across the middle (it stands still when it fits), pages shows the strings of `pages` one after another. |
| `middle.pages` | array | `[]` | maxItems: `8` | The messages of pages mode, in order. |
| `middle.pageSeconds` | integer | `8` | minimum: `3`; maximum: `60` | Seconds each page stays up; the page shown follows the clock, so every screen shows the same one. |

## Canvas example

Add this item to a playlist page’s `primitives`. [Publish the playlist and assign a screen](/docs/cards/#publish-a-card-canvas).

```json
{
  "id": "header",
  "primitive": "card",
  "card": "header",
  "major": 1,
  "layout": "header",
  "params": {
    "theme": "neomustard",
    "location": {
      "name": "Vancouver",
      "latitude": 49.25,
      "longitude": -123.0
    }
  },
  "content_fit": "fill",
  "data": "example-key"
}
```

## Write live data

The canvas example binds its `data` field to `example-key`. That value is a data key: a name this canvas item chooses, not the name of the card. Give each canvas item its own key when items should show different data, or share one key when they should show the same data. Keys are scoped to the project, follow the K/V key grammar, and cannot start with `feed:`.

Create this document before showing the card, then replace it to update the screen without republishing. Writes to a key that live canvas items bind are checked against each bound card’s dynamic properties. Use the same project as the playlist.

Save the document as `card-data.json`. The CLI reads the document itself, with no wrapper:

```json
{
  "left": null,
  "right": null,
  "middle": null
}
```

```console
screenrig card-data put example-key --file card-data.json
```

Or call the API directly. The API wraps the same document in a `document` field. An agent token already names its project, so no project header is sent; if you send `ScreenRig-Project`, it must match the token’s project. Supply your API authorization through the environment; see [API authentication](/docs/authentication/).

```console
curl --request PUT "https://api.screenrig.ai/api/card-data/example-key" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"document":{"left":null,"right":null,"middle":null}}'
```