[5.x] Getting Started

Drupal version compatibility

• Drupal 10.3 || 11 || 12

Introduction

The Charts module helps site builders create data visualizations without writing any code. It also provides a framework for developers to build custom solutions. The system is made of a "core" module that handles the logic and several "submodules" that connect to specific charting tools.

More up-to-date documentation is available here: https://drupalcharts.info.

Supported charting libraries

The core module does not create visuals on its own. You must install at least one submodule for a specific library to render your data. Charts supports:

• Billboard.js
• C3.js
• Chart.js
• Google Charts
• Highcharts

Each submodule acts as a translator, taking the data from Drupal and turning it into a format the specific JavaScript library understands.

Note: If you want a visual color picker for your chart settings, install the Color Field module.

Installation

By default, the module loads the necessary files from a Content Delivery Network (CDN), which is a collection of servers that deliver web content. If you prefer to host these files on your own server for privacy or performance reasons, you can place them in your /libraries folder using one of the methods below.

Option 1: Using composer (Recommended)

Composer is a tool used to manage all the different parts and "packages" that make up your Drupal site. This method treats the JavaScript library as a project package.

1. Ensure the composer/installers package is installed in your project.
2. Check your composer.json file for installer-paths. This tells Drupal exactly where to put different types of files. You should have a path set for the drupal-library type.
3. Add the library's information to the repositories section of your composer.json. Each submodule usually has a README.md file with the exact text you need to copy. For Google Charts, you would add:
   

           {
         "type": "package",
         "package": {
         "name": "google/charts",
         "version": "45",
         "type": "drupal-library",
         "extra": {
         "installer-name": "google_charts"
       },
       "dist": {
       "url": "https://www.gstatic.com/charts/loader.js",
       "type": "file"
           },
         "require": {
         "composer/installers": "~1.0"
           }
         }
       }
       

4. Run the download command in your terminal:
   composer require --prefer-dist google/charts:45

Option 2: Using the composer merge plugin

This is a more automated way to let submodules tell your main project the libraries they need.

1. Install the wikimedia/composer-merge-plugin and oomphinc/composer-installers-extender packages.
2. In your main composer.json file, find the extra section and add bower-asset and npm-asset to the installer-types list.
   

                   "installer-types": [
            "bower-asset",
            "npm-asset"
           ]
       

3. Update your installer-paths to include these new types so they land in your /libraries folder:
   

           "web/libraries/{$name}": [
       "type:drupal-library",
       "type:bower-asset",
       "type:npm-asset"
       ]
       

4. Add the submodule's configuration file to the merge-plugin section under the extra section of your project's composer.json, so it can be read automatically:
   

           "merge-plugin": {
       "include": [
           "web/modules/contrib/charts/modules/charts_highcharts/composer.json"
         ]
       }
       

5. Run the composer require command mentioned in that specific submodule's instructions.

Option 3: Manual installation

You can download the JavaScript files yourself and put them in the /libraries folder. The module will recognize them as long as they are placed in the correct directory.

Creating charts in the user interface

You can manage your global settings, like default colors, at /admin/config/content/charts. Once you pick a default library, more specific options for that library appear.

There are three options for creating a chart within the UI:

• Using Views
• Using a Chart Field
• Using a Chart Block

Creating charts with Views

Views is a powerful Drupal tool used to fetch and display lists of content.

1. Create a new view:
   1. Go to admin/structure/views/add.
   2. Pick Chart as the display format, and ensure the Show setting is set to Fields.
2. Add a label field: Under the Fields section, add the data you want to use for labels (like "Event Title").
   These will be the names on your chart axes or pie slices.
3. Add data fields: Add the numeric fields for your data.
   The names of these fields will appear in the legend. Pie charts usually only work with a single data field.
4. Handle non-numeric data (Aggregation): If your content doesn't have a number field, use Aggregation.
   This feature groups data together. By turning on aggregation and using the count function, you can count how many times an item appears and turn that into a chartable number.
5. Configure the display:
   1. Click Settings next to the Chart format.
   2. Choose your library, the chart type, and which fields represent the labels and data.
6. Save your view: Save the view to finish your chart.

Tip: It is often easier to start with a Table display to make sure your numbers are correct. Once the data looks right, switch the format to Chart.

Creating combo charts

A combo chart is a single visualization that uses two different types of charts at once, like a bar chart with a trend line over it.

1. Add a Chart attachment display to your existing view.
2. Use the settings in the middle column of the view to "attach" this to your main chart.
3. Choose if this extra data should use the main Y-axis (the vertical line on the left) or a secondary Y-axis on the right.

Note: You will need to configure the Settings in the Format section.

Creating charts with a chart field

Use this method for "static" data—information that you type in manually for a specific piece of content (such as a single article or "node") rather than data pulled from across the site.

1. Add a Chart field to your content type through the Manage Fields tab.
2. When you create a new page, you can choose the library and chart type directly on the edit screen.
3. Enter your data into the table or upload a CSV.

Creating charts with chart blocks

This is the best option for using Layout Builder, which is Drupal's visual page editor, or for placing the same chart in different sidebars across your site.

1. Add a Chart Block through the block layout or layout builder interface.
2. Configure your library and chart type.
3. Provide your data using the manual table or by uploading a CSV.