Custom visual options, data and limits

A custom visual draws the fields you place on its tile and the values you set in its panel. This page covers what the visual receives, how its options work, and the caps on rows, code and assets. For writing the code itself, see The custom visual Studio.

What the visual receives

• The tile's Data well holds the fields the visual receives. Every row carries only those fields; a column you do not place there is not sent. A visual with an empty Data well is a static visual: it receives no rows.
• A visual can declare up to 16 data roles: named slots that its code reads fields by. A role id starts with a lower-case letter, followed by up to 31 letters or digits, and a role can take up to 8 fields.
• Each field arrives with an id the code reads it by, its kind (a dimension or a measure), its type and its display format. A field bound to a role carries that role's id.
• The visual also receives the report's theme, so it can draw in the report's style: the appearance, the theme's tokens and the chart colours.
• The visual cannot fetch anything on its own. What it may load and reach is set out in Sandbox, network and the allowlist.

How many rows the visual loads

Rows, under General > Limits, sets how many rows the tile asks for.

• The value starts at 1,000 and accepts up to 100,000; the help line under the field reads "Default 1,000 · max 100,000".
• The value applies when you leave the field or press Enter, and the tile runs again with it. Once the value differs from the default, a reset button returns it to the default.
• When the result holds more rows than the value, the visual receives the rows that fit, and the data it receives says that more exist (hasMore).
• One message from the report to the visual carries about 32 MB of row data. A bigger result arrives as the longest prefix that fits, and the data says more rows exist in this case too.

Change a visual's options

Options are the settings a visual's author declares, such as a label, a colour or a number. They show beside the tile, and each tile keeps its own values.

1. Open the report in edit mode and select the custom visual tile.
2. In the Visualizations panel, open the Visual tab.
3. Change the values under Visual options. The change goes into the report, so save the report to keep it.

The control depends on what the option holds:

• An option can depend on another: until the option it depends on holds the value its author named, it stays hidden.
• An option can hold a colour token, a reference to one of the tile's fields, or one of the report's asset files.
• Clearing a number field removes your value, and the visual falls back to its own default.
• A visual that declares no options shows This visual declares no options. in the section.
• When you apply, the values in options.json are checked against the visual's schema. A problem is refused with a message such as options.json must be a JSON object, options.json: "title" is required or options.json: "count" must be a number. A definition that cannot be read is refused with the visual definition could not be parsed.

Assets and their budget

Asset files belong to the report, and a visual references them. To upload and manage files, open the Studio's assets/ row; the dialog is described on Custom visual Studio, assets and diagnostics.

• Uploads accept up to 20 MB per file, and up to 20 files per drop.
• A visual may transfer up to 8 MB of assets; the dialog warns when the report's files would pass that budget.
• A visual can reference up to 64 asset files.

Size caps

The definition is checked against these caps when you apply. Crossing a cap refuses the apply, and the message names the part and the cap, in the form visual.css is N bytes; the cap is 65536.

Export

• When the report is exported, every custom visual is pictured with its page. A visual that cannot be pictured is reported in a warning that names the tile, such as Custom visual "Gauge" could not be pictured: did not answer in time, and the rest of the export continues. The short reasons read: did not answer in time, did not finish before its deadline, refused the capture, was not running or has nothing to render.
• A visual that is not running is captured as a placeholder, and a visual that has not said it finished drawing is captured as it is; the export notes both.
• Every visual carries export settings: a policy (auto, native, snapshot or table), a pages setting (current, all or first) and a scale (1, 1.5 or 2). A new visual starts from auto, current and 2.

What the tile keeps

• Viewer state: state a visual saves for its viewer stays with the tile and is handed back on the next visit. It is cleared after five days, and the visual then starts from its own default. State over 16 KB 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.
• Diagnostics: the last runtime report keeps a rolling log of up to 200 entries for the Diagnostics drawer.

Questions, answered

How many rows can a custom visual load?

Up to 100,000. Set it under General > Limits, on the Rows row; it starts at 1,000 and the help line reads "Default 1,000 · max 100,000". The value applies when you leave the field or press Enter, and the tile runs again with it.

Why does the visual receive fewer rows than the query returns?

The tile asks for the number of rows set under General > Limits, so a bigger result is cut to that number. A single message also carries about 32 MB of row data, so a very large result arrives as the longest prefix that fits. In both cases the data the visual receives says that more rows exist (hasMore).

Can a custom visual see columns that are not on the tile?

No. Every row carries only the fields placed on the tile's Data well; a column you do not place there is not sent to the visual.

Where do I change a visual's options?

In edit mode, select the tile, open the Visual tab of the Visualizations panel, and change the values under Visual options. The values belong to this tile; save the report to keep them.

Why is one of the visual's options missing?

An option can depend on another: it stays hidden until the option it depends on holds the value its author named. Change that option and the hidden one appears.

Do option changes save with the report?

Yes. Option values belong to the tile in the report you have open, and other people see them once the report is saved.

How large can an uploaded asset be?

Up to 20 MB per file, and up to 20 files per drop. A visual may transfer up to 8 MB of assets, and the dialog warns when the report's files would pass that budget. See Custom visual Studio, assets and diagnostics.

Why does Apply refuse my code as too large?

The definition has caps: visual.html 96 KB, visual.css 64 KB, visual.js 128 KB, all source files together 256 KB, the options schema 32 KB and the whole saved definition 512 KB. The message names the part and the cap, in the form visual.css is N bytes; the cap is 65536. Trim the file below its cap and apply again.

What happens to custom visuals when the report is exported?

Every custom visual is pictured with its page. A visual that cannot be pictured is reported in a warning that names the tile and the short reason, such as Custom visual "Gauge" could not be pictured: did not answer in time, and the rest of the export continues.

Does a custom visual remember what a viewer changed?

For five days. State the visual saves for its viewer stays with the tile and is handed back on the next visit; after five days it is cleared, and the visual starts from its own default.