Data Embed

01Quick Start

Include the script on any page. The widget renders inside a Shadow DOM, so its styles are fully isolated from yours.

<!-- using unpkg -->
<script src="https://unpkg.com/data-embed@0.1.0/dist/data-embed.iife.js"></script>

<!-- or using Cloudflare Pages -->
<script src="https://data-embed.pages.dev/data-embed.iife.js"></script>HTML

That's it. No build step, no framework dependencies, no CSS conflicts. Add a container element with one of three embed methods and the widget takes care of the rest.

02Embed Methods

A — Config from URL

Point data-embed at a JSON config file. The widget fetches and parses it automatically.

<div data-embed="/widget-config.json"></div>HTML

B — Inline JSON

Pass the full config object as the data-embed-inline attribute value. Useful when you want everything in one place.

<div data-embed-inline='{
  "dataUrl": "/data.json",
  "dimensions": ["state"],
  "metrics": [
    { "field": "id", "aggregation": "count", "label": "Total" }
  ]
}'></div>HTML

C — Programmatic

Call DataEmbed.mount() for full control. Pass a DOM element and a config object.

<div id="my-widget"></div>
<script>
  DataEmbed.mount(document.getElementById("my-widget"), {
    dataUrl: "/data.json",
    dimensions: ["state"],
    metrics: [
      { field: "id", aggregation: "count", label: "Total" }
    ]
  });
</script>JavaScript

03Configuration

Widget Config

Property	Type	Description
dataUrl required	string	URL to the JSON data file.
dimensions required	string[]	Initial fields to group by.
metrics required	Metric[]	Aggregations to compute per group. Multiple metrics appear as table columns; the chart plots the selected one.
dimensionOptions	DimensionOption[]	Restricts and labels the "Group by" dropdown. Each entry: a plain string or an object with `field`, `label`, and optional `chartType`.
title	string	Widget header title. Default: `"Data Explorer"`
chartType	string	Default chart type: `column`, `bar`, `line`, `area`, `pie`, `stacked-bar`, or `stacked-column`. Default: `"column"`
defaultView	string	`"chart"` or `"table"`. Default: `"chart"`
height	number	Chart height in pixels. Default: `400`
pageSize	number	Rows per page in the table. Default: `20`
showTotals	boolean	Show a totals row in the table footer and a total badge in the header. Default: `false`
showExport	boolean	Show the "Export" dropdown menu in the header. Default: `true`
animationDuration	number	Chart animation duration in milliseconds. Default: `0` (disabled)
footerText	string	Optional text displayed in the widget footer. Hidden if omitted.
theme	string	Color theme: `"light"`, `"dark"`, or `"auto"`. Default: `"auto"`
primaryColor	string	Brand primary color (e.g. `"#10b981"`). Configures buttons, tabs, load spinners, and badges.
chartColors	string[]	Custom palette of hex colors for the chart visual elements.
fontFamily	string	The CSS font family to apply across all elements (e.g. `"Inter, sans-serif"`).
fontUrl	string	URL to dynamically download a custom Google font stylesheet.

Metric Object

Property	Type	Description
field required	string	The data field to aggregate.
aggregation required	string	`count`, `sum`, `avg`, `min`, or `max`.
label	string	Display label for this metric. Auto-generated if omitted.

Full Example

{
  "dataUrl": "/data/optn_membership.json",
  "dimensions": ["organizationType"],
  "dimensionOptions": [
    { "field": "organizationType", "label": "Organization Type", "chartType": "pie" },
    { "field": "state", "label": "State", "chartType": "column" },
    { "field": "region", "label": "Region", "chartType": "column" }
  ],
  "metrics": [
    { "field": "centerCode", "aggregation": "count", "label": "Members" }
  ],
  "title": "OPTN Membership Data",
  "chartType": "column",
  "defaultView": "chart",
  "pageSize": 25,
  "showTotals": true
}JSON

04Data Format

The dataUrl endpoint should return JSON with a data array of flat objects. All keys become available as dimensions.

{
  "lastUpdated": "2026-06-05",
  "data": [
    {
      "region": 3,
      "centerCode": "ALCH",
      "organizationType": "Transplant Hospital",
      "state": "AL",
      "membershipStatus": "Approved"
    }
  ]
}JSON

lastUpdated is optional and displayed in the widget header when present.