Custom visuals and the visual library

A custom visual is a report tile you write yourself, in HTML, CSS and JavaScript or from a template, and that draws the fields you put on it. You build it on a report tile, then publish it to the visual library so any report in the organisation can reuse it. This page covers what a custom visual is, how it behaves on a report, and how it moves through the library. The Studio, the sandbox, the assistant and the SDK reference have their own pages. For the built-in visual types, see Visuals.

What a custom visual is

• You write it in one of two source tiers. Template runs no author JavaScript; HTML + JS adds visual.js and the allowlisted libraries.
• The tile draws inside its own sandboxed frame, apart from the report around it, and reads only the rows delivered to the fields you bind.
• Apply commits the code to the tile in the report you have open; saving the report records the version other people see.
• You can also start from a chart you already have with Convert to custom visual, or let the assistant write the code. See Convert a chart to a custom visual and Author a custom visual with AI.

Write a custom visual

You need edit access to the report and the Author DataPrism Custom Visuals permission. Without it, the Custom visual tile is hidden from Visualizations. See Who can do what in DataPrism.

1. Open the report and click Edit in the report header.
2. Open Visualizations in the side panel. Under Custom, click Custom visual. The new tile starts from a starter card: it shows {{ count() }} rows bound and, while nothing is bound, the hint "Write code to shape this visual. Add fields whenever it needs data."
3. Add the fields the visual needs in the Data well.
4. Click Edit code on the tile, or choose Edit code from the tile menu. The Studio opens as a full-screen popup that carries the tile's title; when the tile has no title, the popup falls back to Custom visual.
5. Write the code, then click Apply or press Ctrl+Enter. Other people see the change after you save the report.
6. Leave edit mode when you are done.

The tile starts on the Template tier. Switch Source tier to HTML + JS when you need JavaScript; the Libraries menu then lists the allowlisted libraries.

Make it act as a chart or a slicer

On the Visual tab, the Interactions section decides what the visual does in the report:

• Acts as > Visual: "Cross-filters other tiles from its marks through uni.select."
• Acts as > Slicer: "Filters every tile on its first Data field through uni.slicer, keeps its selection across pages and never filters itself."
• Selection from other tiles > Filter: "Narrows the rows to the selection like a native chart."
• Selection from other tiles > Highlight: "Keeps every row and marks the selected ones through data.highlight."

A new visual acts as a Visual and filters with Filter. In the slicer role, the selection choice is not offered. The Visual options section holds the controls the visual's own code declares.

For how selections elsewhere in the report work, see Filters, slicers and interactions.

On the report: the tile menu

• In edit mode a shield sits over the visual so that dragging moves the tile. Choose Interact to hand clicks and scrolling to the visual; when it is active its tooltip reads Stop interacting with the visual, and choosing it again brings the shield back.
• A tile that waits for a free sandbox slot reads Paused to keep the page responsive with Activate; a tile that stops reads This visual stopped responding with Restart.
• Placeholders, stop messages and signature checks are listed in Troubleshooting custom visuals.

Links and embeds

• A visual has no network of its own. What it may load, link to or embed comes from the hosts an administrator allows, and everything goes through the app. See Sandbox, network and the allowlist.
• When a visual opens a link, the viewer confirms it once per report: Open this link? with Open link. The confirmation appears only when the host is allowed solely by the * pattern.
• A refused embed shows the Embed blocked card.

Custom visuals in an exported report

When a report is exported to PowerPoint or PDF, every custom visual is captured as a picture with its page. A visual that has not finished drawing is pictured as it is, and one that is not running is captured as a placeholder; the export lists each case in its warnings. See Export reports and data for the capture warnings.

Share a visual with the library

Promoting the tile's code adds it to the library as a draft; publishing makes a version other reports can insert. The full lifecycle reference lives on Visual library.

1. In edit mode, choose Add to visual library from the tile menu.
2. Fill in Name (placeholder Name shown in the library, seeded from the tile name), Description and Family. When the visual declares data roles, a switch offers to store the tile's first 50 rows as sample data; sample rows drive the gallery card and the preview, and every library reader can see them.
3. Choose Add to library. The visual is saved as a draft at version 1 and the tile is pinned to it; the confirmation adds "This tile is pinned to v1".
4. Open the library, open the draft and check its preview. Publish it when it is ready.

If something is missing, the dialog cannot add the visual and shows Enter a name for the visual or Fix the blocking checks first.

Publish a version

Publishing a version needs Publish Organization Visuals.

1. Open the visual in the library and choose Publish on the version you want to publish.
2. Choose what happens to reports that use the visual:
   • Replace in all dependant reports moves every pinned tile to the new version. Each report gets one labelled version that you can restore.
   • New version, dependants stay pinned leaves reports on the version they use; they show the Update available chip.
3. Confirm with Publish and replace when you chose to replace, or Publish otherwise.

• A version that changes the data roles or options cannot replace: the dialog marks it Breaking change and says "Replace is unavailable: this version changes the data roles or options, so dependant tiles would lose their bindings." Publish it as a new version instead.
• Publishing is blocked while the code contains literal colours: "Library visuals must use theme tokens. Remove every literal colour (or mark brand artwork with /* uni-allow: literal-color */) before publishing."

Keep dependant reports up to date

• A tile on an older version shows the Update available chip. Open it to Review update, which shows the pinned version beside the candidate; its preview is limited to the first 200 rows.
• Choose Update to move this tile, Update all in report to move every tile on an older version in this report, or Detach to leave the tile as it is. A detached tile keeps drawing and stops following the library.
• Each choice saves one labelled version of the report, and needs permission to change the report.

Browse and manage the library

Open the library on the DataPrism page: choose the Visuals tab in the feed.

• Filter by status (Published, Draft or Deprecated) and by family: Any family, Chart, Table, KPI, Map, Text, Navigation or Other. Search covers names, descriptions, families and authors; a search with no matches reads Nothing here matches your search.
• Drafts are visible only to their owner and to people who hold Publish Organization Visuals.
• Open a visual for its detail: the Preview with sample data, Versions and Used in sections. Version rows read v{n} with data-free or N role(s), compatible or breaking, and the published date; the current published version is marked current. The dependants summary reads Used in N report(s) (M tiles, K detached).

Actions on a library visual:

• Export downloads the shown version as a .dpvisual file. Import on the gallery toolbar adds such a file as a new draft; the control appears only for people who hold Author DataPrism Custom Visuals. For what the file carries, see Copy and share custom visuals.
• Edit code opens the visual in the Studio. The button appears for people who hold Author DataPrism Custom Visuals; changing a visual you do not own also needs Publish Organization Visuals.
• Deprecate marks a published visual as deprecated; reports that use it keep working and show a Deprecated chip.
• Disable everywhere stops the visual in every report; its tiles read Disabled by an administrator until someone with the permission chooses Enable.
• Delete works only while no report tile pins the visual. Otherwise it answers "This visual is still pinned by report tiles. Detach them or publish a replacement first."

Insert a library visual

1. In edit mode, open Visualizations and click Library under Custom. The Insert from the visual library picker opens.
2. Pick a visual. The picker can show the whole organisation (Organization) or just what this report already uses (This report), and it searches names, descriptions and authors.
3. Choose Insert v{n} onto page. The tile lands on the current page, pinned to that version.

• The confirmation adds "Map its roles in the Data well."; when the report does not hold a file the visual references, it lists "Assets this report is missing: ...".
• A disabled visual, or one with no published version, stays in the list, dimmed, with the reason as a tooltip.

Sizes and limits

• The Visual assets dialog holds the files a report's visuals use: "Drop files here, or click to pick them". An asset above 2 MB carries a warning: every frame that references it downloads its own copy. SVG files are sanitised on upload.
• A visual may transfer up to 8 MiB of assets; the deeper reference, from binding data to the options form, is in Custom visual options, data and limits.
• The code is signed when you save. A tile runs only code whose signature it can verify, so edits made outside the Studio leave the tile unrendered until you apply and save again.
• When a result is very large, the visual receives only the longest prefix of rows that fits, and a diagnostics line records how many rows arrived.
• When custom visuals are switched off for the whole deployment, the Custom visual tile type is hidden and tiles read Custom visuals are disabled on this deployment.

Permissions

They are DataPrism permissions, set on a role alongside the others. Anyone with a DataPrism report permission can see published visuals in the library; drafts stay with their owner and the people who hold Publish Organization Visuals.

Questions, answered

Why can I not see the Custom visual tile or Edit code?

The Custom visual tile and Edit code are offered to people who can author custom visuals: you need the Author DataPrism Custom Visuals permission and edit access to the report. Ask an administrator to add the permission to your role. See Who can do what in DataPrism.

My changes work on my screen, but my colleagues do not see them. Why?

Apply changes the tile only in the report you have open, and a change reaches other people when the report is saved. Save the report after you apply the code.

Can I use a custom visual as a slicer?

Yes. In the Interactions section, set Acts as to Slicer. The visual then filters every tile on its first Data field, keeps its selection across pages and never filters itself.

How do I reuse a library visual in another report?

In edit mode, open Visualizations and click Library under Custom, then insert the version onto the page and map its roles in the Data well. The steps are above.

Will publishing a new version change existing reports?

Only if you publish with Replace in all dependant reports. With New version, dependants stay pinned, reports keep their version and show Update available. Replace is preselected when the version is compatible, so check the choice before you publish.

Why is Replace unavailable?

The version changes the data roles or options, so tiles that pin it would lose their bindings. Publish it as a new version; each report changes when someone updates it.

What does Update available mean on a tile?

The library has a newer published version than the one this tile uses. Open the chip to Review update, then choose Update, Update all in report or Detach; each choice saves one labelled version of the report.

Why can I not delete a library visual?

A report tile still pins it: "This visual is still pinned by report tiles. Detach them or publish a replacement first." Only the visual's owner, or a person with Publish Organization Visuals, can delete it.

Who can see the sample rows stored with a library visual?

Every library reader. Sample rows drive the gallery card and the preview, so store only rows that are safe for everyone to see.