StatTile

<caos-stat-tile>

a single headline number with its label and trend

May be placed on an app’s home page, a page inside an app and a record page.

Inputs

Name	Attribute	Description	Type	Default	Required
label	label, markup only	What the number is — a short mono eyebrow above it. Not drawn at all when empty, which leaves a figure with nothing saying what it counts.	text	none declared	Optional
value	value, markup only	The figure itself, already formatted — this piece rounds, groups and abbreviates nothing. Set as text rather than a number so a currency mark, a unit or a percent sign can travel with it. Drawn large, in tabular figures.	text	none declared	Optional
delta	delta, markup only	The change since whatever the comparison is — “+12%”, “-3”, “+4 this week”. The tile does not work it out, and does not say what it is compared against, so the string has to.	text	none declared	Optional
trend	trend, markup only	Which way the delta went: up, down or flat. Draws the matching arrow and colours the delta in the semantic ink. Nothing is drawn unless there is a delta to draw it beside, and nothing checks that the direction agrees with the number.	text — one of up, down, flat	none declared	Optional
intent	intent, markup only	Tint the WHOLE tile: info, success, warning or danger. It says something about the figure rather than about the change — a red tile is a bad number, which is not the same statement as a downward trend. Read by the stylesheet rather than by script.	text — one of info, success, warning, danger	none declared	Optional
clickable	clickable, markup only	Make the tile a deep link to whatever is behind the number: a pointer, an accent border on hover and focus, a place in the tab order, and the caos-stat-select event. Without it the tile is inert and clicking it does nothing.	boolean	false	Optional

Events

Name	When it fires	What it carries
caos-stat-select	A clickable tile is activated — by click, Enter or Space. A tile without clickable set raises nothing, whatever is done to it.	{ label, value } — the two strings the tile was given. Note it does NOT carry an id, so the host works out what to open from the label it set.

Slots

Name	What goes in it
visual	A small graphic at the right-hand end of the footer line, beside the delta — a sparkline or similar. The library has nothing to put here yet, so it takes an app-supplied element. The slot is not drawn at all when it is empty.

Styling hooks

Design token	What it controls
--caos-color-surface	The ground of an untinted tile.
--caos-color-border	The border of an untinted tile.
--caos-radius-lg	The corners of the tile.
--caos-space-4	The padding inside the tile.
--caos-space-2	The gap between the label, the value and the footer line.
--caos-space-1	The gap between the trend arrow and the delta.
--caos-color-accent	The border a clickable tile takes on hover and focus.
--caos-accent-wash	The ring around a focused clickable tile.
--caos-font-mono	The face of the label.
--caos-text-label	The size of the label.
--caos-font-weight-label	The weight of the label.
--caos-tracking-wide	The letter spacing of the label.
--caos-color-text-muted	The label ink, and the delta of a flat trend.
--caos-font-display	The face of the figure.
--caos-text-kpi	The size of the figure.
--caos-color-text	The ink of the figure on an untinted tile.
--caos-font	The face of the delta.
--caos-color-info-bg	The fill of an info tile.
--caos-color-info	The border of an info tile, mixed toward transparent.
--caos-color-info-text	The figure ink on an info tile.
--caos-color-info-text-muted	The label ink on an info tile.
--caos-color-success-bg	The fill of a success tile.
--caos-color-success	The border of a success tile, mixed toward transparent.
--caos-color-success-text	The figure ink on a success tile, and the delta of an upward trend.
--caos-color-success-text-muted	The label ink on a success tile.
--caos-color-warning-bg	The fill of a warning tile.
--caos-color-warning	The border of a warning tile, mixed toward transparent.
--caos-color-warning-text	The figure ink on a warning tile.
--caos-color-warning-text-muted	The label ink on a warning tile.
--caos-color-danger-bg	The fill of a danger tile.
--caos-color-danger	The border of a danger tile, mixed toward transparent.
--caos-color-danger-text	The figure ink on a danger tile, and the delta of a downward trend.
--caos-color-danger-text-muted	The label ink on a danger tile.

Methods

Nothing else drives this piece by calling it.

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(tile)	the tile	Always
::part(label)	the label above the figure	Always
::part(value)	the figure	Always
::part(delta)	the change beside the figure	Always
::part(visual)	the area a sparkline or other visual is slotted into	Always

When to use it

One number that somebody should see before they see anything else, with enough room for the label that says what it counts and, where there is one, the change since last time. Three to six across the head of a surface is the shape; twenty of them is a table.

What to use instead

• AppHome — You are building the whole landing surface — what needs attention, gathered — rather than placing one figure on a page you already have.
• ProgressBar — The number is a proportion of a whole, or a long operation moving through stages.
• DataTable — There are more figures than a person reads at a glance, or they need comparing against each other rather than noticing on their own.
• StatusPill — What is being shown is a STATE rather than a figure — Draft, In review, Closed.

Accessibility

A clickable tile becomes a real button in the tab order — role, tabindex and Enter/Space are handled, and the focus ring is drawn. The figure is set in tabular figures so a column of them lines up. Three things are left to the author. The tile is not a live region: a figure that changes while somebody is looking at it announces nothing. The trend arrow is decorative and the direction is carried by colour, so the delta string itself has to say which way it went — “+12%” does, “12%” does not. And the intent tint is colour alone: a figure that is bad has to read as bad in words too.

Examples

A row of figures

Four tiles as they read across the head of a surface: one bare figure, and the three trend directions with the delta each one colours.

{
  "id": "example",
  "section": "A row of figures",
  "columns": 1,
  "items": [
    {
      "id": "stat_tile_1",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Open orders",
        "value": "248"
      }
    },
    {
      "id": "stat_tile_2",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Closed this month",
        "value": "31",
        "delta": "+12%",
        "trend": "up"
      }
    },
    {
      "id": "stat_tile_3",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Cancelled",
        "value": "9",
        "delta": "-3",
        "trend": "down"
      }
    },
    {
      "id": "stat_tile_4",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Avg. days to close",
        "value": "4.2",
        "delta": "0.0",
        "trend": "flat"
      }
    }
  ]
}

<caos-stat-tile label="Open orders" value="248"></caos-stat-tile>
<caos-stat-tile label="Closed this month" value="31" delta="+12%" trend="up"></caos-stat-tile>
<caos-stat-tile label="Cancelled" value="9" delta="-3" trend="down"></caos-stat-tile>
<caos-stat-tile label="Avg. days to close" value="4.2" delta="0.0" trend="flat"></caos-stat-tile>

The four tints

The whole tile tinted to say something about the FIGURE — which is a different statement from the trend colour above, where only the delta was coloured and the number itself was not.

{
  "id": "example",
  "section": "The four tints",
  "columns": 1,
  "items": [
    {
      "id": "stat_tile_1",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "In process",
        "value": "17",
        "intent": "info"
      }
    },
    {
      "id": "stat_tile_2",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Closed this month",
        "value": "31",
        "intent": "success"
      }
    },
    {
      "id": "stat_tile_3",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Due this week",
        "value": "6",
        "intent": "warning"
      }
    },
    {
      "id": "stat_tile_4",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Overdue",
        "value": "3",
        "intent": "danger"
      }
    }
  ]
}

<caos-stat-tile label="In process" value="17" intent="info"></caos-stat-tile>
<caos-stat-tile label="Closed this month" value="31" intent="success"></caos-stat-tile>
<caos-stat-tile label="Due this week" value="6" intent="warning"></caos-stat-tile>
<caos-stat-tile label="Overdue" value="3" intent="danger"></caos-stat-tile>

A figure you can follow

The tile as a deep link: it takes focus, warms to the accent on hover, and reports the press so the host can open the records behind the number.

{
  "id": "example",
  "section": "A figure you can follow",
  "columns": 1,
  "items": [
    {
      "id": "stat_tile_1",
      "type": "component",
      "key": "stat_tile",
      "inputs": {
        "label": "Awaiting approval",
        "value": "12",
        "delta": "+4",
        "trend": "up",
        "clickable": true
      }
    }
  ]
}

<caos-stat-tile label="Awaiting approval" value="12" delta="+4" trend="up" clickable></caos-stat-tile>