Custom visual SDK reference

A custom visual's code draws its tile with the uni global: the rows the report sends, selection, saved state, the report theme, assets and the outside content an administrator allows. This page is the reference for that global, for the template tier that draws without JavaScript, and for the limits and checks that go with them. For what a custom visual is and how it is shared, see Custom visuals and the visual library; for the editing workflow, see The custom visual Studio.

What the SDK gives you

• The uni global belongs to the HTML + JS tier, and its version is SDK 1 (uni.version.sdk).
• The Template tier runs no author JavaScript; it uses the directives below instead of uni.*.
• Everything runs inside the sandbox, which has no network of its own; what it may load is set out in Sandbox, network and the allowlist.
• You paint with one function, uni.render. The host runs it on mount, and again whenever the data, size, theme, selection, filters, options, state or mode change.
• The tile's settings decide what the frame allows, and uni.capabilities mirrors them: select, composite, openUrl, slicer, highlight and the allowlisted hosts. The Visual pane sets Acts as and Selection from other tiles; a new visual cross-filters other tiles from its marks, and links open only when Allow links is on and only for http(s) addresses, otherwise uni.openUrl warns uni.openUrl: links are disabled for this visual (interactions.openUrl = false).

Paint, events and helpers

• uni.render(fn) registers the paint. Its context carries root, data, size, theme, selection, state, options, mode and reason.
• For a paint that takes time, call uni.render.started() before it and uni.render.finished() when it is drawn; a callback that settles without started() counts as finished. uni.render.failed(reason) reports a failure, and uni.ready() signals readiness without a paint.
• uni.on(event, cb) listens to one render event; the events are data, size, theme, selection, filters, options, state, reset and mode. An unknown event warns uni.on: unknown event "...".
• uni.onDispose(cb) runs your cleanup when the code is replaced or the tile closes, newest callback first. Register once at the top of the file, never inside the paint, and cancel timers, animation frames and observers here; a callback that throws is logged and the rest still run.
• uni.html builds a template from a tagged string and escapes every interpolated value; uni.unsafeHtml is the only entry that accepts raw markup, and it runs the sandbox's sanitiser. uni.repeat, uni.mount and uni.text build and place those templates, and uni.icon(name, options) renders a bundled Lucide icon as inline SVG, throwing on an unknown name.
• A visual that never signals readiness is reported failed with the reason missing-ready; a paint that keeps re-triggering itself is stopped and recorded as a render loop.
• uni.mode is view, edit, preview, print or export. Run timers and animation only in the live modes, and paint the final frame when the mode is export or print.

Read the data

• uni.data.fields lists the bound fields, and each field carries id, label, kind, type and its display format. field(idOrLabel) resolves by id, then by a unique label; otherwise it throws uni.data.field("Field"): no such field. Available fields: ....
• rows are read-only, and each row carries __index and __selected. Values are raw: wide integers arrive as strings and dates as wall-clock strings, so format them rather than doing arithmetic on them.
• value, text (formatted with the field's own format), number, sum, avg, min, max, count, groupBy (first-appearance order) and sortBy read the rows; aggregates return NaN on an empty column, so guard totals on zero rows.
• status is loading, ready, refreshing, error or rlsDenied; render an empty state for error and rlsDenied. total, loaded and hasMore say how much of the result arrived.
• requestMore() cannot load more in SDK v1: it resolves false and records the warning uni.data.requestMore() is not available in SDK v1; the row limit is fixed by the tile. Set the tile's row count under General > Limits; see Custom visual options, data and limits.

Selection and the slicer role

• uni.select(target, options) selects: a target is { field, value }, or { row, fields } to select every filterable field of one row. uni.selectComposite(targets) posts several fields as one tuple, for values that belong together. Only filterable fields count, and a value the delivered rows do not carry is dropped.
• uni.isAdditive(event) is true for Ctrl or Cmd; pass { additive: true } when you handle a click yourself. uni.clearSelection() clears the tile's own selection.
• A row's __selected is on, off or neutral. Under Highlight from another tile, the rows the selection keeps read on and the rest read off; a selection that names a column you do not bind dims nothing, and the tile filters instead. A disabled selection warns uni.select: selection is disabled for this visual (interactions.select = false).
• In the slicer role, uni.slicer takes over: field is the first filterable dimension in the Data well, set(values, operator) replaces the selection, clear() clears it and autoPick(values) applies a starting pick that is never saved as the report default.
• The operators are in, eq, neq, between, gt, lt, gte, lte, isnull and notnull, and a set holds at most 1,000 values.
• Off the slicer role the methods warn uni.slicer: this visual is not a slicer (set interactions.role to "slicer" in the Visual pane); with no dimension bound they warn uni.slicer.<method>: bind a dimension to the Data well first.

State, format and theme

• uni.state.get(), uni.state.set(patch) and uni.state.reset() keep small state for the viewer, handed back on the next visit; a set inside the paint applies when the paint ends. State is capped at 16 KB; a bigger patch is refused with uni.state.set: state would be N bytes, above the 16384-byte cap; keep only what the visual needs to restore itself.
• uni.format.value(value, field) renders a value with the field's saved format, and number, percent, abbrev and date are stable helpers that do not depend on the viewer's locale.
• uni.theme carries tokens, color, hex, chart, series, ramp and diverging; echarts(), chartjs(), vegaConfig() and plot() return ready-made colour sets for those libraries. An unknown name throws and lists the known ones: uni.theme: unknown token "...".
• Theme names are colour channels, so write hsl(var(--primary)) or var(--uni-primary); a bare var(--primary) is not a colour and the declaration is dropped. Use chart-1 to chart-12 for series colours, never for status.

Assets, images, embeds and libraries

• uni.assets.url(name) returns a data: URL for image, font and data assets and a blob: URL for binary ones; bytes(name) returns a copy of the raw bytes, list() and has(name) describe the attached files, and json(name) parses a JSON or GeoJSON asset. Only assets attached to this visual exist; uni.assets.json reports uni.assets.json: unknown asset "name" or the parse error.
• uni.image(url) loads an https image through the app and resolves to a data: URL, cached per address. It rejects with a code: host-not-allowed, not-https, not-an-image, too-large or upstream. A refusal by host, scheme, type or size is remembered; a temporary upstream failure is retried on the next load. A refused host reads uni.image: host "..." is not in the sandbox allowlist.
• uni.embed(el, url, options) marks an element as an embedded player's box; the app draws the player in view, edit and preview, and a thumbnail stands in for it in export and print. YouTube, Vimeo and Loom links are normalised, and any other https page embeds as it is. A visual can carry at most 32 embeds (uni.embed: at most 32 embeds per visual; extra ones are ignored) and only https addresses (uni.embed: only https URLs can be embedded, got "...").
• The libraries import by bare name, such as import * as d3 from 'd3'. Only the libraries the visual declares are present, and only these twelve exist: d3 7, d3-sankey 0.12, chart.js 4, echarts 6, vega 6, vega-lite 6, @observablehq/plot 0.6, three 0.186, lottie-web 5, topojson-client 3, d3-cloud 1 and world-atlas 2. Anything else is refused and the refusal names it; changing the declared set reloads the visual.

Template directives

The template tier draws HTML and CSS only. The directives:

• Interpolations, {{ expression | filter }}, are text; they fit in attributes such as title, alt, aria-label, placeholder, lang and plain data-*, never in href, src, style or class. {{{ }}} inserts markup and runs the sanitiser.
• The scope holds row, g, rows, total, page, options and index; the builtins are field, sum, avg, min, max, count, groups and token; the filters are number, percent, abbrev, date, text, upper, lower, default and format.
• A failing element is skipped and reported with its position, such as div[0]/ul/li, and the render continues; scripts, on* attributes, javascript: addresses and prototype access are refused. page is not filled in this version, so a counter guarded by data-uni-if="page" stays hidden.

Limits

• A source or template over its cap is refused when you apply, with a message naming the part and the cap. The options schema and the saved definition have their own caps, listed in Custom visual options, data and limits.

Checks and diagnostics

• Every run reports to Diagnostics in the Studio: the errors with their positions, the console, blocked content, the findings and what was rendered. A run is ok when it ran without errors or blocked content, and a capture taken before the paint finished is noted as partial.
• Findings cover literal colours, forbidden APIs, external addresses, a missing ready signal, a render loop, unknown assets, password-shaped fields and the source caps. Publishing to the library refuses literal colours; the checks are listed in Sandbox, network and the allowlist.
• The visual and the tile talk over a channel the app owns: messages are versioned, sequence-checked and size-checked, and anything that fails is dropped rather than acted on.
• The tile runs only code whose signature it can verify; editing the code outside the Studio leaves the tile unrendered until you apply and save again. Any change to the code, to the declared libraries (their order included) or to the definition (roles, options, assets, export) makes a new signature.
• For what a failing tile shows, see Troubleshooting custom visuals.

Questions, answered

How do I show a value in the report's own format?

uni.format.value(value, field) applies the format saved for that field, and uni.data.text(row, field) does the same when you read a row.

How do I react when new data arrives?

You do not need to register anything: the host runs your uni.render callback again on every data, size, theme, selection, filters, options, state or mode change. uni.on('data', cb) and the other events give you the same moments for side reads.

Is there an SDK for the template tier?

No. A Template visual runs no author JavaScript, so uni does not exist in it; read rows, groups and options through interpolations and the directives above. Switch to HTML + JS when you need libraries or the full uni global.

Why does uni.data.requestMore() do nothing?

It cannot load more in SDK v1: the call resolves false and records the warning uni.data.requestMore() is not available in SDK v1; the row limit is fixed by the tile. Set the tile's rows under General > Limits instead.

How much can I keep in uni.state?

Up to 16 KB. A bigger patch is refused with uni.state.set: state would be N bytes, above the 16384-byte cap; keep only what the visual needs to restore itself, and a set made inside a paint is applied when the paint ends.

When should I cancel timers, animation frames and observers?

In uni.onDispose, registered once at the top of the file. It runs when your code is replaced or the tile closes, newest first, so an old loop cannot keep running beside a new one.

Which libraries can I import, and how?

The twelve listed above, by bare name, for example import * as d3 from 'd3'. Only the libraries the visual declares reach the frame; anything else is refused and the refusal names it.

Why is uni.select doing nothing?

Either selection is switched off for the tile, which warns uni.select: selection is disabled for this visual (interactions.select = false), or the tile is in the slicer role, where uni.select is disabled and uni.slicer.set replaces it. Check uni.capabilities.select and uni.capabilities.slicer.

What does a row's __selected value mean?

on, off or neutral. Your own marks set it, and so does Highlight from another tile: the rows the selection keeps read on, the rest read off. neutral means nothing selects that row.

Why does uni.image reject an image?

The rejection carries a code: host-not-allowed, not-https, not-an-image, too-large or upstream. A refusal by host, scheme, type or size is remembered, so a repeat fails the same way; an upstream failure is retried. Ask an administrator to allow the host, or load from one that is already allowed; see Sandbox, network and the allowlist.

Is uni.unsafeHtml actually unsafe?

No. It is the only entry that accepts raw markup, and the markup runs through the sandbox's sanitiser first; uni.html escapes every interpolated value. Keep row values in text positions either way, because escaping does not make a value safe inside href, src or style.

Why does a colour disappear when I write var(--primary)?

Theme names are colour channels, not colours: var(--primary) holds channel numbers, so the browser drops the declaration. Write hsl(var(--primary)) or var(--uni-primary).