Skip to content
NOEMATA

Content & media

These blocks render text, code, icons, badges, tooltips, and links. They display content rather than query results. Many accept a bare string as shorthand. See the block reference for their options.

@block/text and @block/md

For words. Use @block/text for a label, a heading, or a caption — sized and coloured with tokens, and split into emphasised spans when a caption carries numbers. Use @block/md when you want a block of prose with real Markdown: headings, lists, emphasis, GFM tables, and embedded live blocks via ```block fences (see Notebooks). Reach for md to narrate a dashboard or write a runbook alongside the data.

{ "@block/text": { "text": "Title", "size": "xl", "color": "muted" } }

When text resolves to a number, add a format to render it as bytes, a duration, a percent, and so on — the same formats used by @block/stat and @block/table columns. String values pass through unchanged.

{ "@block/text": { "text": { "@expr/get_context": "bytes_used" }, "format": "bytes" } }

For a caption whose numbers should stand out from the words around them, give text an array of spans. Each span is a string, a number, an expression, or an object with its own weight (normal, medium, semibold, bold), color, and format; the block’s color, weight, and format apply to every span that sets none of its own. Spans render inline, in order, on one line of flowing text.

{
  "@block/text": {
    "size": "sm",
    "color": "muted",
    "text": [
      {
        "text": { "@expr/get_context": "cpu_cost_usd" },
        "format": { "currency": "USD" },
        "weight": "bold",
        "color": "default"
      },
      " / day of ClickHouse CPU · ",
      {
        "text": { "@expr/get_context": "query_share" },
        "format": "percent",
        "weight": "bold",
        "color": "warning"
      },
      " of all queries"
    ]
  }
}

A span’s text is rendered as text, so a value containing <strong> or **bold** shows those characters. Emphasis comes from the span’s own weight and color.

@block/md takes a bare Markdown string, or an object when you want to set its size — the base text size, on the same token scale as @block/text. Headings, inline code, code blocks, and paragraph leading are all relative to it, so one size moves the whole document together. It defaults to md, the reading size; drop to sm for prose that sits beside dense UI and shouldn’t compete with it.

{ "@block/md": { "text": "Rolled back at **09:20**.", "size": "sm" } }

@block/code

A syntax-highlighted code block — show a query, a config snippet, an example payload. Give it the source and a language.

{ "@block/code": { "code": "select 1", "language": "sql" } }

@block/icon and @block/badge

Small status affordances. An @block/icon marks or decorates; a @block/badge is a coloured pill for a short status — healthy, degraded, 3 open. Both take colour tokens, so drive the colour from data to turn them into at-a-glance signals.

icon_type takes any Lucide name, or an OpenTelemetry telemetry.sdk.language value for a programming-language mark: cpp, dotnet, erlang, go, java, nodejs, php, python, ruby, rust, swift, webjs. Those are the attribute’s own values, so bind one straight from the column — no mapping.

{ "@block/badge": { "title": "Healthy", "color": "success" } }

The variant prop picks the surface treatment. default (omitted) is a tinted fill, outline renders a bordered chip with no fill, status renders a colored indicator dot next to the title, and level renders no fill — just a 4px palette-colored bar down the left edge with the title in the palette’s foreground color.

{ "@block/badge": { "title": "Live", "color": "success", "variant": "status" } }

A badge in a narrow row, such as a panel’s aside on a quarter-width card, truncates its title with an ellipsis instead of overflowing.

@block/tooltip

Shows a plain-text content when the reader hovers or focuses its trigger, so an explanation takes no layout space. Wrap a child block to make it the trigger, such as a badge, a progress bar, or a line of text. The child sits beside content ("@block/badge": …) or under block.

{
  "@block/tooltip": {
    "content": "Firing alerts and open recommendations from this pack's detection rules.",
    "@block/badge": { "title": "2 firing", "color": "warning", "variant": "status" }
  }
}

Without a child, an info icon is the trigger. size sets the icon to match a text size (default md):

{ "@block/tooltip": { "content": "Share of disk space used on the fullest disk." } }

An empty content renders the child alone, or nothing when there is no child. A panel’s description renders as this childless tooltip beside the title, with the icon sized to the title text; see Panels.

Wraps a text child in a link. Use it to connect dashboards: a service name that jumps to that service’s detail frame.

The target is one of three arms, and everything the link needs — its text child, its variant — goes inside the arm:

frame — another frame, by its id plus the params filling any {Name} placeholders. Extra params become query params.

{
  "@block/link": {
    "frame": {
      "id": "services/{ServiceName}",
      "params": { "ServiceName": "checkout" },
      "@block/text": "checkout"
    }
  }
}

to — a URL, in-app or external, with optional query params. The URL is expressible, so a table row can point at a per-row address.

{
  "@block/link": {
    "to": { "url": "https://example.com/docs", "@block/text": "Read the docs" }
  }
}

frame_instance — a frame by its already-concrete, encoded id, for when you hold one rather than a pattern plus params (a copied block, a notebook frame fence). It is used verbatim.

frame_instance and to also take their target on its own, and the link’s text defaults to it — { "@block/link": { "to": "https://example.com" } }. frame has no shorthand, because its id may still carry {Name} placeholders that would render as literal braces.

{
  "@block/link": {
    "frame_instance": { "id": "services/checkout", "@block/text": "checkout" }
  }
}

Only the frame arms name a route, so only they can be current: the link compares its resolved frame instance id against the frame being rendered, and marks the anchor aria-current="page" when they are the same. That reads the frame runtime rather than the address bar, so it holds in a notebook or a story too.