An HTML + JS custom visual draws its tile with the uni global: the rows the report sends, selection, saved state, the report's theme, assets, libraries and the outside content the sandbox allows. This page is the developer reference for that global and the platform limits around it. For the editor around your code, see The custom visual Studio; for the tier that runs no JavaScript, Custom visual templates.
uni.), and everything your code does runs inside the sandbox, which has no network of its own.uni. is view, edit, preview, print or export; uni. is the element your drawing goes into; uni. is the locale the tile formats in.uni. mirrors what the tile may do: select, composite, openUrl, assets, export, slicer, highlight and the allowed hosts. Some of these follow the Visual tab's Interactions section (Acts as, Selection from other tiles, Allow links); the allowed hosts come from the administrator's list.uni. carries width, height, scale, dpr and visible, and it stays current as the tile resizes.uni. holds the option values the viewer set, and uni. holds the filters the report applied to this visual, each with its label, operator, values and source.The groups behind the global:
| Group | Members | Use it for |
|---|---|---|
uni. | status, fields, dimensions, measures, rows, total, loaded, hasMore, isEmpty, error, field, role, value, text, number, sum, avg, min, max, count, groupBy, sortBy, requestMore | Reading what the tile received |
uni. | appearance, tokens, chartColors, color, hex, chart, series, ramp, diverging, echarts, chartjs, vegaConfig, plot | Colours and chart-library themes |
uni. | value, number, percent, abbrev, date | Formatting values yourself |
uni. | own, origin, isSelected | Your marks and the highlight state |
uni. | enabled, field, values, set, clear, autoPick | The slicer role |
uni. | get, set, reset | The viewer's saved state |
uni. | onSnapshot, onNative, pageCount, setPage | The export picture |
uni. | url, bytes, list, has, json | The report's asset files |
uni. | started, finished, failed | Long paints |
uni. registers the paint. The host runs it on mount and again on every data, size, theme, selection, filters, options, state, reset or mode change.root, data, size, theme, selection, state, options, mode and reason; the reason is mount, swap, or the change that triggered the paint.uni. before the work and uni. when it is drawn; a paint that settles without started() counts as finished. uni. signals readiness when there is nothing to paint, and uni. (also exposed as uni.) reports a failure.uni.render((ctx) => {
const label = ctx.data.isEmpty ? 'No rows' : `${ctx.data.count()} rows`;
uni.text(ctx.root, label);
});uni. listens to one render event (data, size, theme, selection, filters, options, state, reset, mode) and returns a function that removes the listener; an unknown event throws uni..uni. runs when your code is replaced or the tile closes, newest callbacks first. Register once at the top of the file, never inside the paint, and cancel timers, animation frames and observers there.uni. made inside a paint is applied when the paint ends, and a paint that keeps repeating in one frame is stopped and recorded as a render loop in the Diagnostics.uni. lists the bound fields, each with id, label, role, kind, type, biType, filterable and its display format; dimensions and measures split the same list. uni. returns the field bound to a data role.uni. resolves a field by id first, then by a unique label, and throws listing the available names: uni..__index (its position) and __selected (on, off or neutral).value, text (formatted with the field's own format), number, sum, avg, min, max and count read the rows; groupBy returns groups in first-appearance order, each with key, label and rows, and sortBy sorts rows, ascending or desc. An aggregate over a column with no numeric values returns NaN.status is loading, ready, refreshing, error or rlsDenied; total, loaded, hasMore, isEmpty and error describe the result.requestMore() cannot fetch more in SDK v1: it resolves false and records the warning uni.. Set the tile's rows under General > Limits; see Custom visual options, data and limits.uni. marks a value; a target is { field, value }, or { row, fields } to select a row's fields. Only filterable fields count, and the value must come from the rows the tile received.uni. posts several fields as one tuple, for values that belong together; uni. clears the tile's own mark, and uni. is true on Ctrl or Cmd when you handle a click yourself.uni. reads a row's state; uni. is the tile's own mark, and origin says whose selection is showing (own, or a sibling tile's under Highlight).uni. takes over: field is the first filterable dimension in the Data well, set(values, operator) replaces the selection (at most 1,000 values per set), 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.uni. off the role, uni. with nothing bound, and uni. with selection switched off. uni. is disabled in the slicer role.data-uni-select, which needs a row or a group of that field in scope: data-uni-select="..uni., uni. and uni. keep small state for the viewer, handed back on the next visit. The set is capped at 16 KB; a bigger patch is refused with uni.. For how long the state is kept, see Custom visual options, data and limits.uni. formats 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. is read-only in your code; the controls around it are the ones the visual's author declares, described in Custom visual options, data and limits.uni. builds markup from a tagged template and escapes every interpolated value; uni. is the only entry that takes raw markup, and it runs the sandbox's sanitiser first.uni., uni. and uni. build and place that markup; uni. takes a template from the two builders above.uni. and uni. draw the tile's tooltip through the app.uni. writes to the tile's console and the Diagnostics: debug and info read as log entries, warn and error keep their level. Plain console calls from your code are collected the same way.uni. is light or dark, and the report's tokens are applied to the visual as CSS variables: each --name token holds colour channels, a --uni-name mirror wraps it in hsl(., and the frame carries the light or dark class. A theme switch runs the paint again.uni., hex(name), chart(index) and series(labels) read the palette; ramp(from, to, steps) and diverging(steps) build scales with at least 2 and 3 steps.uni., chartjs(), vegaConfig() and plot(); give chart datasets uni. for their series colours. Vega views take the interpreter the vega library ships, because the sandbox does not evaluate expressions.status-good to status-success, status-bad to status-error, status-neutral to status-pending, status-warn to status-warning, diverging-min to status-error, diverging-center to muted, diverging-max to status-success and foreground-muted to muted-foreground. An unknown name throws uni..uni. returns a data: URL for image, font and data files and a blob: URL for binary ones; bytes(name) returns the raw bytes, list() and has(name) describe the attached files, and json(name) parses a JSON or GeoJSON asset, rejecting with uni. or the parse error.uni. 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; the first four are remembered, so a repeat fails the same way, while an upstream failure is retried. A refused host reads uni..uni. 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. It takes an https address, up to 32 embeds per visual (uni.), and anything else warns uni..uni. opens an https link to an allowed host, with noopener, and a host allowed only by * asks the viewer first. With links switched off it warns uni., and it refuses anything but http(s) with uni..import * as d3 from 'd3'; the bare names include d3, d3-sankey, chart., echarts, vega, vega-lite and @observablehq/, and the Libraries menu of the Studio declares which of them a visual gets. Anything else is refused and the refusal names it.uni. draws a bundled icon as inline SVG in currentColor, with size, strokeWidth, className and label options; an unknown name throws uni..uni. lets the visual provide its own picture (a canvas, an SVG or a blob) for export and print; without it, the sandbox captures the drawn tile.uni. provides the native pieces the export file can carry, and pageCount with setPage turn a tall visual into several pages.| What | Limit |
|---|---|
| Template render | 20,000 nodes (see Custom visual templates) |
| Viewer state | 16 KB |
| Slicer set | 1,000 values |
| Embeds | 32 per visual |
uni. or a finished paint) is reported failed with missing-ready; export and print allow far longer than a report on screen.javascript: addresses; template style values refuse url(), expression() and javascript:, and @import is stripped from template CSS.uni. returns the field bound to that role, and the index picks among several fields in the same role. Bound fields also carry their role id in field., and uni. lists them all.
The paint's context carries reason: mount for the first paint, swap when the code is replaced, or the change that triggered it (data, size, theme, selection, filters, options, state, reset or mode). Use it to skip work a paint does not need.
In the Studio's Diagnostics. uni. writes a console entry (debug and info read as log entries, warn and error keep their level), and plain console calls from your code are collected the same way.
Read uni. (light or dark) and draw with the tokens: the report's tokens are applied to the visual as CSS variables, with a --uni- mirror in hsl(. form and a light or dark class on the frame. A theme switch runs the paint again, so a repaint picks the new values up.
Any token in uni., plus the names that fall back when the report does not define them, such as status-good to status-success and status-bad to status-error. An unknown name throws uni. with the list of known names. Ask through uni., hex(), chart() or series() rather than reading raw channel values.
uni. returns an inline SVG you can append to the drawing, and it accepts size, strokeWidth, className and label options. An unknown name throws uni. with the available names.
The sandbox notices a paint that keeps repeating in one frame, stops it and records a render loop in the Diagnostics. A uni. made inside a paint waits until the paint ends, so it cannot start a new paint on its own.
With uni.: the handler is asked for a canvas, an SVG or a blob when the report is exported or printed. onNative provides native pieces instead, and pageCount with setPage handle a visual that spans several pages.
The declared libraries install once per frame, so changing the set replaces the frame with one that carries the new set. Libraries the visual does not declare are refused, and the refusal names them.
Read uni.: draw a loading state for loading and refreshing, the tile's empty or error state for error, and an empty state for rlsDenied, where row-level security withholds the rows. An empty result is isEmpty.