UsageBar

<caos-usage-bar>

one finite allowance drawn as used-of-maximum, with automatic pressure thresholds

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

Inputs

Name	Attribute	Description	Type	Default	Required
used	used, markup only	How much of the allowance is consumed. Non-numeric or absent reads as 0.	number	0	Optional
maximum	maximum, markup only	The size of the allowance. Absent, zero or negative means there is no ceiling to be a fraction of: the bar draws empty and the value line shows the bare count rather than a ratio.	number	none declared	Optional
label	label, markup only	What the allowance is, shown above the track and used as the accessible name.	text	none declared	Optional
unit	unit, markup only	A unit appended to the value line, e.g. “GB”, “calls”. Purely presentational.	text	none declared	Optional
warnAt	warn-at, markup only	Percentage consumed at which the fill turns warning.	number	75	Optional
dangerAt	danger-at, markup only	Percentage consumed at which the fill turns danger.	number	90	Optional
intent	intent, markup only	Overrides the computed colour. Setting it switches the thresholds OFF for this bar — use it only where the caller genuinely knows something the numbers do not.	text — one of accent, success, warning, danger	none declared	Optional
hideValue	hide-value, markup only	Draws the track without the “used of maximum” line, for dense rows where a shared header carries it.	boolean	false	Optional

Events

Not documented yet — this piece has not said.

Slots

Not documented yet — this piece has not said.

Styling hooks

Not documented yet — this piece has not said.

Methods

Not documented yet — this piece has not said.

Readable state

Name	Type	What it tells you
over-limit	boolean attribute on the host	Reflected onto the host when used exceeds maximum, so a row or panel around it can style the whole line without recomputing the comparison.

Styling parts

Part	Which piece of it	When it is there
::part(bar)	The outer column holding header and track.	Always
::part(header)	The label/value row above the track; hidden when both are empty.	Always
::part(label)	The name of the allowance.	Always
::part(value)	The “used of maximum” line.	Always
::part(track)	The unfilled allowance.	Always
::part(fill)	The consumed portion.	Always

When to use it

When something FINITE is being consumed and running out matters — API calls, storage, seats, records against a cap. The bar is read to answer “how close am I to the ceiling”, so it colours itself as the ceiling approaches.

What to use instead

• ProgressBar — the bar reports an OPERATION advancing — an import running, a deploy applying. Full is the goal there, so it must not redden as it fills.
• StatTile — the number matters and the proportion does not — a total with no ceiling to be a fraction of.

Accessibility

Carries role="meter" with aria-valuenow, aria-valuemin and — when there is a ceiling — aria-valuemax, plus an aria-valuetext reading “3,400 of 5,000 calls” so a screen reader hears the ratio rather than a bare number. meter rather than progressbar is the same distinction the component exists to make: this is a measurement within a known range, not a task advancing. Colour is never the only signal — the value line states the numbers, and over-limit is announced through aria-valuetext rather than by the fill turning red.

Examples

The same bar across the ramp

One allowance at four points of its own life. The colour is computed from the proportion, so nothing about these four placements differs except the number — which is the whole argument for the component over four hand-coloured bars.

{
  "id": "example",
  "section": "The same bar across the ramp",
  "columns": 1,
  "items": [
    {
      "id": "usage_bar_1",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "API calls",
        "used": 1200,
        "maximum": 10000,
        "unit": "calls"
      }
    },
    {
      "id": "usage_bar_2",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "API calls",
        "used": 7800,
        "maximum": 10000,
        "unit": "calls"
      }
    },
    {
      "id": "usage_bar_3",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "API calls",
        "used": 9400,
        "maximum": 10000,
        "unit": "calls"
      }
    },
    {
      "id": "usage_bar_4",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "API calls",
        "used": 10000,
        "maximum": 10000,
        "unit": "calls"
      }
    }
  ]
}

<caos-usage-bar label="API calls" used="1200" maximum="10000" unit="calls"></caos-usage-bar>
<caos-usage-bar label="API calls" used="7800" maximum="10000" unit="calls"></caos-usage-bar>
<caos-usage-bar label="API calls" used="9400" maximum="10000" unit="calls"></caos-usage-bar>
<caos-usage-bar label="API calls" used="10000" maximum="10000" unit="calls"></caos-usage-bar>

Past the ceiling

Spent more than the allowance. The fill pins at the full track — a bar drawn past its own end is a drawing bug, not information — while the numbers stay truthful and say by how much.

{
  "id": "example",
  "section": "Past the ceiling",
  "columns": 1,
  "items": [
    {
      "id": "usage_bar_1",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "Streaming events",
        "used": 11400,
        "maximum": 10000,
        "unit": "events"
      }
    }
  ]
}

<caos-usage-bar label="Streaming events" used="11400" maximum="10000" unit="events"></caos-usage-bar>

An allowance with no ceiling

Usage with nothing to be a proportion of. There is no fill and no meter range, because a bar drawn at some arbitrary width would be inventing a limit that does not exist.

{
  "id": "example",
  "section": "An allowance with no ceiling",
  "columns": 1,
  "items": [
    {
      "id": "usage_bar_1",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "Records stored",
        "used": 4182339,
        "unit": "records"
      }
    }
  ]
}

<caos-usage-bar label="Records stored" used="4182339" unit="records"></caos-usage-bar>

Thresholds moved in

The same 60% under the default ramp and under a tightened one. Where “approaching” starts is a judgement about the allowance, not a property of the number.

{
  "id": "example",
  "section": "Thresholds moved in",
  "columns": 1,
  "items": [
    {
      "id": "usage_bar_1",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "Default ramp — 75 / 90",
        "used": 60,
        "maximum": 100
      }
    },
    {
      "id": "usage_bar_2",
      "type": "component",
      "key": "usage_bar",
      "inputs": {
        "label": "Tightened — 40 / 55",
        "used": 60,
        "maximum": 100,
        "warn_at": 40,
        "danger_at": 55
      }
    }
  ]
}

<caos-usage-bar label="Default ramp — 75 / 90" used="60" maximum="100"></caos-usage-bar>
<caos-usage-bar label="Tightened — 40 / 55" used="60" maximum="100" warn-at="40" danger-at="55"></caos-usage-bar>