Highcharts Controls

GUI controls for manipulating Highcharts charts, Grid, and Dashboards options on the fly.

Installation

Load the module file from a CDN or your own server

<script type="module" src="https://cdn.jsdelivr.net/npm/@highcharts/[email protected]"></script>

Usage

Web Components

<!DOCTYPE html>
<html>
<head>
    <script src="https://code.highcharts.com/highcharts.js"></script>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@highcharts/[email protected]"></script>
</head>
<body>
    <div id="container"></div>

    <script>
        Highcharts.chart('container', {
            title: { text: 'My Chart' },
            series: [{
                data: [1, 2, 3, 4, 5]
            }]
        });
    </script>

    <highcharts-controls target="#container">
        <highcharts-group header="Legend Settings">
            <highcharts-control
                type="boolean"
                path="legend.enabled"
                value="true">
            </highcharts-control>

            <highcharts-control
                type="select"
                path="legend.align"
                options="left,center,right"
                value="center">
            </highcharts-control>

            <highcharts-control
                type="number"
                path="legend.x">
            </highcharts-control>

            <highcharts-control
                type="color"
                path="legend.backgroundColor"
                value="#FFEEAA">
            </highcharts-control>
        </highcharts-group>
    </highcharts-controls>
</body>
</html>

JavaScript/TypeScript API

<!DOCTYPE html>
<html>
<head>
    <script src="https://code.highcharts.com/highcharts.js"></script>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@highcharts/[email protected]"></script>
</head>
<body>
    <div id="container"></div>
    <div id="controls-container"></div>

    <script type="module">

        // Create a chart
        Highcharts.chart('container', {
            title: { text: 'My Chart' },
            series: [{
                data: [1, 2, 3, 4, 5]
            }]
        });

        // Add controls
        HighchartsControls.controls('controls-container', {
            controls: [
                {
                    group: 'Legend Settings',
                    controls: [
                        {
                            // Type is optional - automatically deduced from value
                            path: 'legend.enabled',
                            value: true
                        },
                        {
                            path: 'legend.align',
                            options: ['left', 'center', 'right'],
                            value: 'center'
                        },
                        {
                            path: 'legend.x',
                            min: -100,
                            max: 100,
                            step: 10,
                            value: 0
                        },
                        {
                            path: 'legend.backgroundColor',
                            value: '#FFEEAA'
                        }
                    ]
                }
            ]
        });
    </script>
</body>
</html>

Layout control

By default, the Highcharts Controls renders in a block element, taking 100% of its parent's width. In some cases, particularly when rendering juse one or a handful controls, it looks better to keep the controls close to the labels. In that case, apply inline-block display to the top container in order to make the layout shrink to fit its content.

.highcharts-controls {
    display: inline-block;
}

API Documentation

JavaScript/TypeScript API

`HighchartsControls.controls(container, options)`

Creates a controls instance.

Parameters:

container (string | HTMLElement) - The container element or element ID where controls will be rendered
options (ControlsOptionsObject) - Configuration options

Returns: Controls instance

ControlsOptionsObject

interface ControlsOptionsObject {
    target?: ControlTarget;      // Target chart/grid (defaults to first chart)
    injectCSS?: boolean;          // Auto-inject CSS (defaults to true)
    controls: Array<ControlParams | GroupParams>;  // Array of control or group configurations
}

GroupParams

Controls can be organized into collapsible groups with headers:

interface GroupParams {
    group: string;              // Group header text
    description?: string;       // Optional description text
    controls: ControlParams[];  // Controls within the group
    collapsed?: boolean;        // Initial collapsed state (default: false)
    collapsible?: boolean;      // Allow expand/collapse (default: false)
    className?: string;         // Custom CSS class
}

Example:

HighchartsControls.controls('controls-container', {
    controls: [
        {
            group: 'Legend Settings',
            description: 'Control the appearance and behavior of the chart legend.',
            collapsible: true,     // Enable expand/collapse
            collapsed: false,      // Start expanded
            controls: [
                { path: 'legend.enabled', value: true },
                { path: 'legend.align', options: ['left', 'center', 'right'] }
            ]
        },
        {
            group: 'Chart Settings',
            collapsible: true,     // Enable expand/collapse
            collapsed: true,       // Start collapsed
            controls: [
                { path: 'chart.backgroundColor', value: '#FFFFFF' }
            ]
        },
        // Ungrouped controls can be mixed with groups
        { path: 'title.text', value: 'My Chart' }
    ]
});

Control Types

Note: The type parameter is optional. If omitted, the library will automatically deduce the control type based on the value and other parameters:

Boolean values → boolean control
Numeric values or strings with units (px, em, rem, %) → number control
Presence of options array → select control
Strings containing "color" in the path or valid color values → color control
Other string values → text control (fallback)

Boolean Control

Toggle chart options on/off with a styled checkbox.

{
    type: 'boolean',
    path: 'legend.enabled',  // Dot-separated path to option
    value: true              // Initial value (optional)
}

Select Control

Select from predefined options with button group.

{
    type: 'select',
    path: 'legend.align',
    options: ['left', 'center', 'right'],  // Available options
    value: 'center'                         // Initial selection (optional)
}

Number Control

Adjust numeric values with a range slider. Supports length units like px, em, rem, and %.

{
    type: 'number',
    path: 'legend.x',
    min: -100,   // Minimum value (optional)
    max: 100,    // Maximum value (optional)
    step: 10,    // Step increment (optional, defaults to 1)
    value: 0     // Initial value (optional, can be number or string with unit)
}

Unit Support:

The number control seamlessly handles length units commonly used in Highcharts:

// With em units (step defaults to 0.1 for em/rem)
{
    type: 'number',
    path: 'title.style.fontSize',
    min: 0.5,
    max: 3,
    value: '1.5em'  // Unit extracted from string value
}

// With percentage units
{
    type: 'number',
    path: 'chart.height',
    min: 50,
    max: 100,
    value: '80%'
}

Default min/max (when not specified):

Properties ending in lineWidth or borderWidth: min: 0, max: 5
Properties ending in x, y, offsetX, offsetY, or offset: min: -100, max: 100
Other properties: min: 0, max: 100

Unit behavior:

Units are extracted from the value string (e.g., '1.5em', '60px', '80%')
The control displays the numeric value with the unit (e.g., "1.5em")
Chart options receive the value with the unit as a string
For em and rem units, step defaults to 0.1 if not specified

Color Control

Choose colors with a color picker and opacity control.

{
    type: 'color',
    path: 'chart.backgroundColor',
    value: '#FFFFFF'  // Initial color (optional)
}

Text Control

Edit text values with a text input field.

{
    type: 'text',
    path: 'title.text',
    value: 'My Chart Title'  // Initial text (optional)
}

Nullish State Handling

When a control's value is null or undefined, each control type displays a distinct visual state to clearly indicate that no value has been set:

Visual Indicators

Boolean controls: Display as unchecked with a diagonal striped pattern on the toggle slider
Color controls: Show an em-dash (—) placeholder instead of a color value, with a striped pattern in the color picker swatch
Number controls: Display the range slider but hide the numeric label
Select controls: No button is marked as active (or no option selected in dropdown)
Text controls: Show an empty input field

Note: Select controls automatically render as a dropdown when there are more than 3 options or the total string length of all options exceeds 24 characters. Otherwise, they display as a button group.

Behavior

This typically happens if the value is not set, and the Controls are unable to read the value from the target chart or grid. In some cases, chart or grid defaults are null or undefined, indicating the behavior depends on other states.

<highcharts-controls>
    <highcharts-control path="chart.inverted" type="boolean"></highcharts-control>
    <highcharts-control path="legend.backgroundColor" type="color"></highcharts-control>
</highcharts-control>

When a user interacts with a control in nullish state (types text, clicks toggle, changes color, moves slider, or selects option), the visual nullish indicators are automatically removed and the control behaves normally.

CSS Classes:

All controls in nullish state receive the hcc-control-nullish class
Each control type also receives a type-specific class (hcc-control-boolean, hcc-control-color, hcc-control-number, hcc-control-select, hcc-control-text) for targeted styling

Web Component API

`<highcharts-controls>`

Container element for controls.

Attributes:

target (optional) - CSS selector for target chart container (e.g., "#container")
inject-css (optional) - Set to "false" to disable automatic CSS injection

Example:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@highcharts/[email protected]/css/controls.css" />
<highcharts-controls target="#my-chart" inject-css="false">
    <!-- controls here -->
</highcharts-controls>

`<highcharts-group>`

Group controls under a collapsible header. Must be a child of <highcharts-controls>.

Attributes:

header (required) - Header text for the group
collapsed (optional) - Set to "true" to start collapsed
collapsible (optional) - Set to "true" to enable expand/collapse (default: false)
class (optional) - Custom CSS class

Child Elements:

<highcharts-group-description> (optional) - Description text displayed below the header. Supports HTML markup.
<highcharts-control> - Individual controls within the group

Note: When using <highcharts-group-description> and injectCSS is set to true (default), it's recommended to add this to your page CSS to avoid a flash of unstyled content (FOUC):

highcharts-group-description {
    display: none;
}

Example:

<highcharts-controls target="#container">
    <highcharts-group header="Legend Settings" collapsible="true">
        <highcharts-group-description>
            Control the appearance and behavior of the chart legend.
        </highcharts-group-description>
        <highcharts-control path="legend.enabled" value="true"></highcharts-control>
        <highcharts-control path="legend.align" options="left,center,right"></highcharts-control>
    </highcharts-group>

    <highcharts-group header="Chart Settings" collapsible="true" collapsed="true">
        <highcharts-control path="chart.backgroundColor" value="#FFFFFF"></highcharts-control>
    </highcharts-group>

    <!-- Ungrouped controls -->
    <highcharts-control path="title.text" value="My Chart"></highcharts-control>
</highcharts-controls>

`<highcharts-control>`

Individual control element. Must be a child of <highcharts-controls>.

Attributes:

type (required) - Control type: "boolean", "select", "number", "color", or "text"
path (required) - Dot-separated path to chart option (e.g., "legend.enabled")
value (optional) - Initial value
options (required for select) - Comma-separated list of options
min (optional for number) - Minimum value for range slider
max (optional for number) - Maximum value for range slider
step (optional for number) - Step increment for range slider

Examples:

<!-- Boolean -->
<highcharts-control
    type="boolean"
    path="legend.enabled"
    value="true">
</highcharts-control>

<!-- Select -->
<highcharts-control
    type="select"
    path="legend.align"
    options="left,center,right"
    value="center">
</highcharts-control>

<!-- Number -->
<highcharts-control
    type="number"
    path="legend.x"
    min="-100"
    max="100"
    step="10">
</highcharts-control>

<!-- Number with units -->
<highcharts-control
    type="number"
    path="title.style.fontSize"
    min="0.5"
    max="3"
    value="1.5em">
</highcharts-control>

<highcharts-control
    type="number"
    path="chart.marginTop"
    min="0"
    max="200"
    value="60px">
</highcharts-control>

<!-- Color -->
<highcharts-control
    type="color"
    path="chart.backgroundColor"
    value="#FFFFFF">
</highcharts-control>

<!-- Text -->
<highcharts-control
    type="text"
    path="title.text"
    value="My Chart Title">
</highcharts-control>

Features

Live Preview - See chart options update in real-time
Options Inspector - View current chart configuration as JSON
Type Safety - Full TypeScript support with type definitions
Auto-injection - Optionally inject CSS automatically
Flexible Targeting - Target specific charts or use defaults
Modern UI - Clean, styled controls with smooth animations

CSS Customization

The controls use CSS custom properties for easy theming:

.highcharts-controls {
    --hc-controls-bg: #ffffff;
    --hc-controls-border: #e0e0e0;
    --hc-controls-text: #333333;
    /* Add more custom properties as needed */
}

Browser Support

Modern browsers with support for:

ES2020 modules
Web Components (Custom Elements)
CSS Grid and Flexbox

License

ISC

Author

Torstein Honsi

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.husky		.husky
css		css
e2e		e2e
js		js
src		src
test-results		test-results
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
ROADMAP.md		ROADMAP.md
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Highcharts Controls

Installation

Usage

Web Components

JavaScript/TypeScript API

Layout control

API Documentation

JavaScript/TypeScript API

`HighchartsControls.controls(container, options)`

ControlsOptionsObject

GroupParams

Control Types

Boolean Control

Select Control

Number Control

Color Control

Text Control

Nullish State Handling

Visual Indicators

Behavior

Web Component API

`<highcharts-controls>`

`<highcharts-group>`

`<highcharts-control>`

Features

CSS Customization

Browser Support

License

Author

About

Uh oh!

Releases

Packages

Languages

highcharts/controls

Folders and files

Latest commit

History

Repository files navigation

Highcharts Controls

Installation

Usage

Web Components

JavaScript/TypeScript API

Layout control

API Documentation

JavaScript/TypeScript API

HighchartsControls.controls(container, options)

ControlsOptionsObject

GroupParams

Control Types

Boolean Control

Select Control

Number Control

Color Control

Text Control

Nullish State Handling

Visual Indicators

Behavior

Web Component API

<highcharts-controls>

<highcharts-group>

<highcharts-control>

Features

CSS Customization

Browser Support

License

Author

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`HighchartsControls.controls(container, options)`

`<highcharts-controls>`

`<highcharts-group>`

`<highcharts-control>`

Packages