Skip to Content

Developers

Build a custom chart

Make your own chart type in the Chart studio, publish it, and use it in any metric.

Make a chart type of your own. After you publish it, it shows in the Custom group of every metric’s Chart type picker in your company.

Before you start

  • You are an Admin. Only Admins see Custom charts in Settings.
  • Your role has the metric Edit permission.

Make a chart in the Chart studio

  1. Go to Settings > Developers > Custom charts. The page is at /settings/custom-charts.

    Settings sidebar with Custom charts highlighted under Developers
    Custom charts is under Developers in the Settings sidebar.
  2. Select New chart.

    Custom charts page header with the New chart button highlighted next to Upload bundle
    New chart is at the top right of Custom charts.
  3. In New custom chart, start blank or choose a working chart.

    New custom chart picker with Blank and the Bars with target template highlighted
    Start blank, or pick a working chart such as Bars with target.
  4. Enter a Chart name.

    Chart studio header with the chart name field highlighted
    The chart name is at the top left of the studio.
  5. In the shape panel, add the data slots and options. A slot is a field the chart needs, for example a dimension for the label and a measure for the value.

    Chart studio with the Slots panel highlighted on the left and the chart preview in the middle
    Slots are the fields the chart needs. Add slot adds one more.
  6. Edit the code in the chart.js and chart.css tabs.

    Chart studio with the chart.js code tab highlighted
    The chart.js and chart.css tabs are under the preview.
  7. Select Run to draw the chart with sample data.

    Chart studio header with the Run button highlighted
    Run draws the chart with the sample data.
  8. Select Save version.

    Chart studio header with the Save version button highlighted
    Save version keeps this draft as a preview version.

The version is saved as a preview. Nothing changes on a dashboard until you publish it. The studio for a chart is at /settings/custom-charts/studio/<chart key>.

Publish the chart

  1. In the studio, select Publish. Or, on Custom charts, open the chart and select Publish preview.

    Chart studio header with the Publish button highlighted
    Publish is at the top right of the studio.
  2. Confirm. Every dashboard that uses the chart draws this version.

The chart is now a chart type in every metric editor in your company. To remove a preview you do not want, select Discard preview. The published version keeps running.

Upload a bundle instead

If you build the chart in your own code project, upload the build output.

  1. Start a chart project with the CLI:

    npx @databrainhq/mcp-server databrain custom-chart init my-chart
  2. Build the project.

  3. Select Upload bundle.

    Custom charts page header with the Upload bundle button highlighted
    Upload bundle is next to New chart.
  4. Drop dist/bundle.zip, the four files from dist/, or the dist/ folder.

  5. Fix any problems the check lists, then select Upload.

The upload goes in as a preview. Publish it as above. The studio shows a chart built this way as Read-only: built with the CLI. Change its code in your project and upload a new version.

Use the chart in a metric

  1. Open a metric in the metric builder.
  2. Select Chart type, then pick your chart in the Custom group.
  3. In Chart settings, bind your fields to the Data slots.
  4. Set the Options.
  5. Save the metric.

A metric with a published custom chart also draws it in embedded dashboards. Embedding is on the Enterprise plan.

Ask Bryn in the studio

Select Bryn in the Chart studio and describe a change, for example “Show percentages on the arcs”. Bryn edits chart.js, chart.css, the slots, the options and the sample data in your draft, then runs the chart. You still save the version and publish. Select Undo this or Restore to before Bryn to go back.

Limits

ItemLimit
Chart code (dist/index.js)2 MB
chart.css256 KB
icon.svg16 KB, with no scripts
manifest.json32 KB, up to 16 slots and 32 options
Versions per chart50

If something goes wrong

  • “You need the metric Edit permission to change custom charts.” Ask an Admin to give your role the metric Edit permission.
  • “This exact bundle is already v…” You uploaded the same bundle again. Nothing changed.
  • “Add a data slot before saving a version.” Add at least one slot in the shape panel.
  • “Custom chart … already has 50 versions” Discard its preview version to make room.
  • Your chart is not in the Custom group. It is not published yet. Publish it first.

Next: pick a chart type.