Theme Configuration - nyurik/vega GitHub Wiki
This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.
The same set of charts can be rendered with different custom configurations, resulting in different themes applied to the same underlying visualization specification. Properties in the configuration supplement those provided in a Vega JSON specification. Thus, one can omit certain properties (e.g., the fill color of marks) in order to automatically apply the theme's fill color value.
For example, below are two bar charts. Both share the same JSON specification but are rendered with different theme configurations. The first uses an "Excel" theme while the second uses a "ggplot2" theme.
The sections below document the various configuration and theme properties that can be set.
General Properties
These general properties are defined at the top-level of the configuration.
| Property | Type | Description |
|---|---|---|
| width | Number | The width, in pixels, of the chart. |
| height | Number | The height, in pixels, of the chart. |
| background | Color | The fill color for the background of the chart. |
| padding | Number | Object | String | The internal padding, in pixels, from the edge of the visualization canvas to the data rectangle. If an object is provided, it must include {top, left, right, bottom} properties. Two string values are also acceptable: "auto" (the default) and "strict". For more information, see the padding property |
| autopadInset | Number | The inset padding for automatic padding calculation. |
Axis Properties
The following properties can be nested under the axis, axis_x, and axis_y keys. Properties specified under axis_x or axis_y will only modify the corresponding axis, and take precedence over any specified under axis. For example,
config.axis = {
orient: 'bottom',
ticks: 10,
axisColor: '#979797',
};
config.axis_x = {
tickSize: 10,
grid: {
ordinal: false,
default: true
}
}
config.axis_y = {
tickSize: 0,
grid: true
}
| Property | Type | Description |
|---|---|---|
| orient | String | The orientation of the axis. One of top, bottom, left or right. The orientation can be used to further specialize the axis type (e.g., a y axis oriented for the right edge of the chart). By default, x axis is placed on the bottom and y axis is placed on the left. |
| axisWidth | Number | The width, in pixels, of axis. |
| axisColor | Color | The axis fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| padding | Number | The padding, in pixels, between ticks and text labels. |
| ticks | Number | A desired number of ticks, for axes visualizing quantitative scales. The resulting number may be different so that values are "nice" (multiples of 2, 5, 10) and lie within the underlying scale's range. |
| tickSize | Number | The size, in pixels, of major, minor and end ticks. |
| tickWidth | Number | The width, in pixels, of ticks (major, minor and end). |
| tickColor | Color | The tick fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| tickPlacement | String | The placement of ticks for ordinal scales. 'between' specifies tick marks to be between labels. (change to boolean?) |
| tickLabelColor | Color | The tick label fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| tickLabelFont | String | The font for tick labels. |
| tickLabelFontSize | Number | The size of tick labels. |
| grid | Boolean | Object | A flag indicating if gridlines should be created in addition to ticks. An object can instead be defined with keys that are types of scales and the value being a boolean. Grids can specified to be true/false based on the type of scale being defined. |
| gridWidth | Number | The width, in pixels, of gridlines. |
| gridColor | Color | The grid fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| gridOpacity | Number | The opacity, between 0 and 1, of gridlines. |
| gridDash | Array | An array of alternating stroke for gridlines, space lengths for creating dashed or dotted lines. |
| layer | String | A string indicating if the axis (and any gridlines) should be placed above or below the data marks. One of "front" (default) or "back". (changes end tick...?) |
| titleOffset | Number | The offset (in pixels) from the axis at which to place the title. |
| titleOffsetAutoMin | Number | TODO |
| titleOffsetAutoMax | Number | TODO |
| titleOffsetAutoMargin | Number | TODO |
| titleColor | Color | String | The title fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| titleFont | String | The font for titles. |
| titleFontSize | Number | The size of titles. |
| titleFontWeight | String | Number | The weight for titles. Can also specify a number between 100 and 900. |
Scale Properties
| Property | Type | Description |
|---|---|---|
| time | Scale | Specifies time look up tables. All d3.scale.* instances supported. |
| utc | Scale | Specifies utc look up tables. All d3.scale.* instances supported. |
| padding | Number | For bar charts. A number between 0 and 1 which represents the padding between bars. |
| outerPadding | Number | For bar charts. A number between 0 and 1 which represents the two outer most padding. |
Marks Properties
| Property | Type | Description |
|---|---|---|
| color | Color | String | The default fill or stroke color, depending on the mark type, that is applied if none is specified in the specification. |
| symbolSize | Number | The pixel area of the symbol for marks. For example: in the case of circles, the radius is determined in part by the square root of the size value. |
Legend Properties
| Property | Type | Description |
|---|---|---|
| orient | String | The orientation of the legend. One of "left" or "right". This determines how the legend is positioned within the scene. |
| offset | Number | The horizontal offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle. |
| padding | Number | The padding, in pixels, from the offset specified. This is added to both x and y directions. |
| labelColor | Color | String | The label fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| labelFontSize | Number | The font size of labels. |
| labelFont | String | The font for labels. |
| labelAlign | String | The alignment of the legend. One of right, left, or center. |
| labelBaseline | String | One of 'top', 'middle' or 'bottom' which specifies vertically where to align the legend. |
| labelOffset | Number | TODO |
| symbolShape | String | The symbol shape to use in legends. One of circle, square, cross, diamond, triangle-up, or triangle-down. |
| symbolColor | Color | String | The symbol fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. (Need to fill with fill color regardless??) |
| symbolSize | Number | The pixel area of the symbol for marks. For example: in the case of circles, the radius is determined in part by the square root of the size value. |
| symbolStrokeWidth | Number | The width, in pixels, of symbol stroke. |
| titleColor | Color | String | The legend title fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| titleFont | String | The font for legend title. |
| titleFontSize | Number | The font size of legend title. |
| titleFontWeight | String | Number | The weight for legend titles. Can also specify a number between 100 and 900. |
| tickLabelFontSize | Number | The font size of tick labels. |
| gradientStrokeWidth | Number | The width, in pixels, of the stroke around the gradient. |
| gradientStrokeColor | Color | String | The legend title fill color. Can also set as 'default' which uses the defaultFill in config.marks if one is specified. |
| gradientHeight | Number | The height, in pixels, of the gradient. |
| gradientWidth | Number | The width, in pixels, of the gradient. |
Scene Properties
These properties modify the "data rectangle" (i.e., the area that encloses the marks but does not include legends and axes).
| Property | Type | Description |
|---|---|---|
| fill | Color | The scenegraph background color. |
| fillOpacity | Number | The scenegraph opacity. |
| stroke | Color | The stroke color around the scenegraph. |
| strokeOpacity | Number | The stroke opacity around the scenegraph. |
| strokeWidth | Number | The stroke width around the scenegraph. |
| strokeDash | Array | An array of alternating stroke around the scenegraph, space lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The offset (in pixels) into which to begin drawing with the stroke dash array around the scenegraph. |
Load Properties
| Property | Type | Description |
|---|---|---|
| baseURL | String | The base url for loading external data files. Used only for server-side operation. |
| domainWhiteList | Array | false | Allows domain restriction when using data loading via XHR. To enable, set it to a list of allowed domains e.g., ['wikipedia.org', 'eff.org'] |
Render Properties
| Property | Type | Description |
|---|---|---|
| retina | Boolean | Set to false to display pixel doubling when using the Canvas renderer on retina displays. |
Range Properties
Custom scale ranges can be defined within the configuration, and invoked by name when defining scales in the JSON specification. For example,
config.range = {
"summer": ["#ffffe0", "#ffd59b", "#ffa474", "#f47461", "#db4551", "#b81b34", "#8b0000"]
};
"scales": [
{
"name": "fillColor",
"type": "ordinal",
"domain": {"data": "nodes", "field": "group"},
"range": "summer"
}
]
Custom Shapes
Custom shapes can also be specified within a theme configuration, and used with symbol mark types and legends. See the custom shapes documentation for more information.