How Can You Configure Your Vega-Lite Charts?

Creating a consistent and visually appealing data visualization can be challenging. That's where Vega-Lite's config object comes in! This guide will introduce you to config, show you how to customize various properties, and walk you through some examples to help you get started.

What is the `config` Object?

The config object in Vega-Lite lets you define global properties for your visualizations. Think of it like setting the rules for the game: once defined, these settings apply everywhere in your visualization unless specifically overridden.

{
  ...,
  "config": {
    ...,
    "axis"      : { ... },   // Define Axis configuration
    "header"    : { ... },   // Define Header configuration
    "legend"    : { ... },   // Define Legend configuration
    "mark"      : { ... },   // Define Mark configuration
    "style"     : { ... },   // Define Style configuration
    "range"     : { ... },   // Define Scale Range configuration
    "scale"     : { ... },   // Define Scale configuration
    "projection": { ... },   // Define Projection configuration
    "selection" : { ... },   // Define Selection configuration
    "title"     : { ... },   // Define Title configuration
    "view"      : { ... },   // Define View configuration
    "concat"    : { ... },   // Define Concat configuration
    "facet"     : { ... },   // Define Facet configuration
    "repeat"    : { ... },   // Define Repeat configuration
    "locale"    : { ... },   // Define Locale configuration
    "aria"      : ...        // Define ARIA configuration
  }
}

The config object allows you to ensure your charts have a consistent look and feel.

Top-Level Configuration

What Can You Configure at the Top-Level?

You can set various global properties in the config object:

autosize
background
countTitle
fieldTitle
font
lineBreak
padding
tooltipFormat

Format Configuration

Format settings define the default numerical and time formats for text marks, axes, headers, tooltips, and legends.

Examples:

{
  "config": {
    "numberFormat": "0.2f", // two decimal places
    "timeFormat": "%Y-%m-%d" // date format
  }
}

Custom Formatters

If the default formats don't meet your needs, you can create custom formatters.

Steps to Customize Formatters:

vega.expressionFunction('customFormatA', function(datum, params) {
  return "<formatted string>";
});

Enable custom format types in your config.

{
  ...,
  "config": {"customFormatTypes": true}
}

Use this custom format in your visualization.

{
  "format": <params>,
  "formatType": "customFormatA"
}

Tips:

Customize tooltip formats separately.
Utilize higher screen estate in tooltips to show more detailed information.

Guide Configurations

You can configure guides like axes, headers, and legends globally:

Axis Configuration

Define default settings for axes. There are properties for all axes and specific axis types, which take precedence in the following order: Type-Based > Orientation-Based > General

{
  "config": {
    "axis": {
      "labelColor": "blue", // all axes
      "grid": false, 
    },
    "axisX": {
      "labelAngle": -45 // x-axis only
    },
    "axisY": {
      "labelColor": "red" // y-axis only
    }
  }
}

Header and Legend Configurations

Header and legend settings follow similar pattern to axis configurations:

{
  "config": {
    "header": {
      "titlePadding": 10
    },
    "legend": {
      "orient": "right"
    }
  }
}

Mark Configurations

Mark configurations define default properties for visual elements like bars and lines. You can set general defaults or specific mark type defaults.

{
  "config": {
    "mark": {
      "tooltip": true
    },
    "bar": {
      "cornerRadiusEnd": 5
    }
  }
}

Style Configuration

Named styles are another way to customize defaults. These can be invoked within a mark or axis definition.

{
  "config": {
    "style": {
      "customStyle": {
        "fill": "red",
        "stroke": "black"
      }
    }
  }
}

Scale and Scale Range Configuration

Define how scales (like linear or color scales) are configured and applied.

{
  "config": {
    "scale": {
      "bandPaddingInner": .4,
      "bandPaddingOuter": 4,
    },
  }
}

Projection Configuration

Define settings for spatial projections.

Selection Configuration

Control how interactive selections are configured.

Title Configuration

Set defaults for titles.

View & View Composition Configuration

Handle configurations for composite views like concat, facet, and repeat.

Locale Configuration and ARIA

Configure localization and accessibility settings.

FAQ

1. What is the benefit of using a `config` object?

The config object allows you to apply consistent settings across your charts, saving time and ensuring a uniform look and feel.

2. Can I use custom number and time formats?

Yes, you can create custom formatters and enable them in your configuration to fine-tune how your data is presented.

3. How do I target specific types of axes, legends, or marks in my configurations?

Use the type-specific properties in the config object, such as "axisX", "legend", or "bar" to apply settings only to those elements.

Overview Data