Chart

The mod.chart() method creates a chart per the arguments passed to the method using D3.js. There are currently six supported chart types: line, bar, bar-horizontal, pie, doughnut, and gauge.

// Using mod(-plus).iife.min.js
window.mod.chart(type: string, options: object);

// Using mod(-plus).esm.min.js
import { chart } from 'path/to/mod(-plus).esm.min.js';
chart(type: string, options: object);

Usage Examples

Use the following usage examples to guide your implementation. Reference the Method Arguments below to see all available method options.

Line Chart

Single Line Chart

// NOTE: Inline styles are the preferred method for adjusting width
// and height to control chart appearance in your app's UI.

<div data-mod-chart="single-line" style="width: 100%; height: 300px;"></div>

window.mod.chart('line', {
  target: 'single-line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      name: 'Sales',
      color: '#FF9F40',
      values: [30, 45, 35, 50, 40]
    }]
  }
});

Multi-Line Chart

// NOTE: Inline styles are the preferred method for adjusting width
// and height to control chart appearance in your app's UI.

<div data-mod-chart="multi-line" style="width: 100%; height: 300px;"></div>

window.mod.chart('line', {
  target: 'multi-line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      name: 'Sales',
      color: '#FF9F40',
      values: [30, 45, 35, 50, 40]
    }, {
      name: 'Revenue',
      color: '#36A2EB',
      values: [50, 35, 45, 60, 55]
    }]
  },
  gradient: true,
  data_points: true,
  animate: true,
  axis: { x: true, y: true },
  axis_gap: { x: 10, y: 5 }
});

Line Chart + Custom Tooltip

// NOTE: Inline styles are the preferred method for adjusting width
// and height to control chart appearance in your app's UI.

<div data-mod-chart="custom-tooltip" style="width: 100%; height: 300px;"></div>

window.mod.chart('line', {
  target: 'custom-tooltip',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [{
      name: 'Sales',
      color: '#FF9F40',
      values: [30, 45, 35, 50, 40]
    }, {
      name: 'Revenue',
      color: '#36A2EB',
      values: [50, 35, 45, 60, 55]
    }]
  },
  gradient: true,
  data_points: true,
  tooltip: (data = {}) => `
    <div class="custom-tooltip">
      <h4>${data.label}</h4>
      ${data.datasets.map((dataset = {}) => `
        <div>
          <span style="color: ${dataset.color}">${dataset.name}:</span>
          ${dataset.value.toLocaleString()}
        </div>
      `).join('')}
    </div>
  `
});

Line Chart API

type string required

The type of chart to create. Must be 'line' for line charts.

options object required

Configuration options for the line chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the chart.

labels array required

Array of labels for the x-axis.

datasets array required

Array of dataset objects containing values and styling.

name string

Name of the dataset.

values array

Array of numeric values.

color string

Color for the dataset (hex, rgb, or css variable).

animate boolean

Enable animation when rendering the chart.

tooltip function

Custom tooltip render function that receives tooltip data and returns HTML string.

tooltip_enabled boolean

Enable/disable tooltips for the chart.

axis object

Axis display configuration.

x boolean

Show/hide x-axis.

y boolean

Show/hide y-axis.

axis_gap object|number

Gap between axis and labels.

x number

Gap for x-axis.

y number

Gap for y-axis.

gradient boolean

Enable gradient fill under the line.

data_points boolean

Show data points on the line.

Bar Chart

<div data-mod-chart="bar-chart" style="height: 300px;" class="mod-chart"></div>

window.mod.chart('bar', {
  target: 'bar-chart',
  animate: true,
  axis: { x: true, y: true },
  bar_radius: 5,
  chart_padding: 0,
  axis_gap: {
    x: 15,
    y: 15
  },
  bar_gap: 5,
  group_gap: 15,
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    datasets: [
      {
        name: '2024',
        color: 'var(--mod-success)',
        values: [30, 50, 20, 80, 40]
      },
      {
        name: '2023',
        color: 'var(--mod-brand)',
        values: [20, 40, 25, 65, 30]
      }
    ]
  }
});

Bar Chart API

type string required

The type of chart to create. Must be 'bar' for vertical bar charts.

options object required

Configuration options for the bar chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the chart.

labels array required

Array of labels for the x-axis.

datasets array required

Array of dataset objects containing values and styling.

name string required

Name of the dataset.

values array required

Array of numeric values.

color string required

Color for the dataset bars.

animate boolean

Enable animation when rendering the chart.

tooltip function

Custom tooltip render function.

axis object

Axis display configuration.

x boolean

Show/hide x-axis.

y boolean

Show/hide y-axis.

axis_gap object|number

Gap between axis and labels.

x number

Gap for x-axis labels.

y number

Gap for y-axis labels.

bar_radius number

Border radius of the bars.

bar_gap number

Gap between bars within the same group.

group_gap number

Gap between groups of bars.

chart_padding number

Padding around the entire chart.

Horizontal Bar Chart

<div data-mod-chart="horizontal-bar-chart" style="height: 300px;" class="mod-chart"></div>

window.mod.chart('bar-horizontal', {
  target: 'horizontal-bar-chart',
  animate: true,
  axis: { x: true, y: true },
  bar_radius: 5,
  chart_padding: 0,
  axis_gap: {
    x: 5,
    y: 5
  },
  bar_gap: 5,
  group_gap: 10,
  data: {
    labels: ['Electronics', 'Clothing', 'Home & Garden', 'Books', 'Sports'],
    datasets: [
      {
        name: 'Q1 Sales',
        color: 'var(--mod-success)',
        values: [85000, 62000, 45000, 38000, 25000]
      },
      {
        name: 'Q2 Sales',
        color: 'var(--mod-brand)',
        values: [92000, 58000, 51000, 42000, 28000]
      },
    ]
  },
});

Horizontal Bar Chart API

type string required

The type of chart to create. Must be 'bar-horizontal' for horizontal bar charts.

options object required

Configuration options for the horizontal bar chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the chart.

labels array required

Array of labels for the y-axis.

datasets array required

Array of dataset objects containing values and styling.

name string required

Name of the dataset.

values array required

Array of numeric values.

color string required

Color for the dataset bars.

animate boolean

Enable animation when rendering the chart.

tooltip function

Custom tooltip render function.

axis object

Axis display configuration.

x boolean

Show/hide x-axis.

y boolean

Show/hide y-axis.

axis_gap object|number

Gap between axis and labels.

x number

Gap for x-axis labels.

y number

Gap for y-axis labels.

bar_radius number

Border radius of the bars.

bar_gap number

Gap between bars within the same group.

group_gap number

Gap between groups of bars.

chart_padding number

Padding around the entire chart.

Pie Chart

<div data-mod-chart="pie-chart" style="height: 300px;" class="mod-chart"></div>

window.mod.chart('pie', {
  target: 'pie-chart',
  animate: true,
  data: {
    labels: ['Android', 'iOS', 'Windows', 'macOS', 'Linux'],
    datasets: [{
      name: 'Operating Systems',
      colors: ['var(--mod-brand)', 'var(--mod-info)', 'var(--mod-success)', 'var(--mod-warning)', 'var(--mod-danger)'],
      values: [41.7, 27.2, 13.5, 11.2, 6.4]
    }]
  },
});

Pie Chart API

type string required

The type of chart to create. Must be 'pie' for pie charts.

options object required

Configuration options for the pie chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the chart.

labels array required

Array of labels for each slice.

datasets array required

Array containing a single dataset object.

name string required

Name of the dataset.

values array required

Array of numeric values for each slice.

color string

Default color for all slices if individual colors not specified.

colors array

Array of colors for individual slices. Overrides default color.

animate boolean

Enable animation when rendering the chart.

tooltip function

Custom tooltip render function.

corner_radius number

Border radius of the pie slices.

Doughnut Chart

<div data-mod-chart="doughnut-chart" style="height: 300px;" class="mod-chart"></div>

window.mod.chart('doughnut', {
  target: 'doughnut-chart',
  animate: true,
  data: {
    labels: ['Android', 'iOS', 'Windows', 'macOS', 'Linux'],
    datasets: [{
      name: 'Operating Systems',
      colors: ['#32CD32', '#007AFF', '#00A4EF', '#A2AAAD', '#FCC624'],
      values: [41.7, 27.2, 13.5, 11.2, 6.4]
    }]
  },
  label: {
    top: 'Total Users',
    bottom: 75
  }  
});

Doughnut Chart API

type string required

The type of chart to create. Must be 'doughnut' for doughnut charts.

options object required

Configuration options for the doughnut chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the chart.

labels array required

Array of labels for each slice.

datasets array required

Array containing a single dataset object.

name string required

Name of the dataset.

values array required

Array of numeric values for each slice.

color string

Default color for all slices if individual colors not specified.

colors array

Array of colors for individual slices. Overrides default color.

animate boolean

Enable animation when rendering the chart.

tooltip function

Custom tooltip render function.

hole_size number

Size of the center hole as a proportion of the radius.

corner_radius number

Border radius of the doughnut slices.

stroke object

Configuration for slice borders.

color string

Color of the stroke between slices.

width number

Width of the stroke between slices.

label object

Configuration for center labels.

top string

Text to display in the top label (smaller text).

bottom string

Text to display in the bottom label (larger text).

Gauge Chart

<div data-mod-chart="gauge-chart" style="height: 300px;" class="mod-chart"></div>

window.mod.chart('gauge', {
  target: 'gauge-chart',
  data: {
    max: 100,
    value: 75,
  },
  animate: true,
  color: 'var(--mod-brand)',
  background_color: 'var(--mod-neutral-e)',
  thickness: 0.12,
  label: {
    suffix: '%',
    direction: 'up',
    direction_change: '5%',
    bottom: 'Conversion Rate'
  }
});

Gauge Chart API

type string required

The type of chart to create. Must be 'gauge' for gauge charts.

options object required

Configuration options for the gauge chart.

target string required

The data-mod-chart attribute value of the target element where the chart will be rendered.

data object required

The data to be displayed in the gauge.

value number required

Current value to display on the gauge.

max number required

Maximum value for the gauge scale.

animate boolean

Enable animation when rendering the chart.

color string

Color of the gauge fill.

background_color string

Color of the gauge background (automatically set based on theme).

thickness number

Thickness of the gauge arc as a proportion of the radius.

label object

Configuration for gauge labels.

suffix string

Suffix to append to the value display.

direction string

Direction indicator ('up' or 'down') for the arrow.

direction_change string

Text to display next to the direction arrow.

bottom string

Text to display below the value.