The <halo-report> element

Every attribute, method and event of the web component that embeds a Halo report, with the filter values it takes and the errors it reports.

<halo-report> is a web component that draws a report in an iframe and lets your page talk to it. It adds about 2 KB gzipped, with no React and no other dependencies. For where to get an embed link and how to list your site, start with Embed a report on your site.

<script type="module" src="https://cdn.usehalo.net/halo-report.js"></script>
<halo-report src="https://{org}.usehalo.net/embed/hle_…"></halo-report>

<script type="module" src="https://cdn.usehalo.net/halo-report.js"></script>
<halo-report token="SIGNED_EMBED_TOKEN" origin="https://{org}.usehalo.net"></halo-report>

Load the script once per page.

Attributes

With neither src nor token, the element shows a note saying so.

What happens when an attribute changes

The frame loads lazily, so halo:ready waits until the element is near the viewport.

The address it opens

The element builds the frame's address from its attributes, and an iframe can use the same query parameters:

{src}?element={element}&edition={edition}&{state}&theme={theme}
{origin}/embed/signed?element={element}&{state}&theme={theme}#token={token}

Methods

The report property holds the report's id once the frame is ready.

const report = document.querySelector("halo-report");

report.addEventListener("halo:ready", () => {
  report.setFilters({ region: ["North", "South"] });
});

report.addEventListener("halo:click", (event) => {
  console.log(event.detail.element, event.detail.values);
});

report.addEventListener("halo:error", (event) => {
  console.warn(event.detail.code, event.detail.message);
});

Events

All are CustomEvents that bubble and cross the shadow boundary, with their values in detail.

To have a click on one embed filter another, pass it across:

first.addEventListener("halo:click", (event) => second.setFilters(event.detail.values));

Filter values

Filters are an object keyed by field name. Each lands on the report's controls over that field, as if a reader had picked it, so the report's own rules for scope, targets and dependent choices apply. null clears a field.

Relative presets are today, yesterday, last_n_days, last_n_weeks, last_n_months, this_week, last_week, month_to_date, quarter_to_date, year_to_date, last_month, last_quarter, last_year, rolling_12_months, fiscal_quarter_to_date, fiscal_year_to_date, last_fiscal_quarter and last_fiscal_year. The last_n_* presets need n.

You can only set fields the report has a control for. To filter by something else, add a filter control to the report, or use a signed embed's locked filters.

Errors

halo:error carries a code and a message in plain words.

Any other code is the public API's, passed on. A filter_* error doesn't stop the report, and the other filters in the same call still apply. A chart that asks for a field the report doesn't share says so in that chart, and your page hears nothing.

Size

The frame takes its content's height, and updates as it changes, unless your page sizes the element. Give the element a height or min-height, and the frame fills that instead:

halo-report { height: 720px; }

A one-element embed asks for that element's own height. The element is display: flex and takes the hidden attribute.

Editions

On a report with editions, an embed opens the latest, with no menu to change it, unless you pin one with edition. An embed link shows the published figures. Its token decides for a signed embed. A signed embed asks your data again as of that edition's date, under your locked filters and row policies.

Themes

Embeds start light, since the page around them decides. system follows the reader's setting and updates when it changes. A report that fixes its own mode keeps it. See Your brand on reports.

How it talks to the frame

The element and the frame exchange postMessage objects marked protocol: "halo-report" and version: 1, and you don't need to send them yourself.

• The element accepts messages only from its own iframe's window, at that iframe's origin, and posts only to that origin.

• The frame ignores everything until a hello from its parent window, fixes the parent's origin from it, then accepts only that window and origin.

• A plain iframe never says hello, so the frame never posts to it. That's why an iframe embed has no events, filter API or automatic height.

To keep a reader's place, store event.detail.state from halo:filterchange and set it as state next time. An iframe embed takes the same query string in its address. Unlike a public link, an embed never changes the address of the page around it.