Bar chart race

Make your own bar chart race with Flourish

Updated 8 days ago to v17.0.3 by Flourish team

How to use this template

What's it for?

Use this template to visualise the changing fortunes of people or groups in competition with each other, like political candidates, country populations or football teams.

How to get started

  1. The first thing you need is a CSV or Excel file of your data.
  2. You need to make sure that there’s a row for each participant in the race – like a candidate or a football team. Use the first column to populate with the participants’ names. Each other column is a “stage” of the race – like a specific date, week or years.
  3. Here's an example:
    name Day 1 Day 2 Day 3
    Lance Armstrong 0 4 7
    Chris Hoyle 0 3 6

Not sure how to upload your data to Flourish? See our handy guide

Adding captions

You can use the second data sheet to create captions that should appear over the top of the chart at the specified times.

Credits

Bar chart template: Created by the Flourish team. Want to see additional features? Let us know at support@flourish.studio.

Data: Example data show urban population by nation and continent, from the World Bank.

This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.

template: @flourish/bar-chart-race

version: 17

Template data

There are three different formats in which you can supply data to this template. The most convenient for you to use likely depends on the source of your data, as described below.

1. Array of arrays, and a bindings object

You can supply arrays of arrays to opts.data, which might look like:

{
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        captions: [
            [ "CaptionsColumn1Value1", "CaptionsColumn2Value1",
            [ "CaptionsColumn1Value2", "CaptionsColumn2Value2",
            [ "CaptionsColumn1Value3", "CaptionsColumn2Value3",
            ...
        ]
    }
}

where each array of arrays represents the rows in a data sheet.

To tell the API how the values from each column should be associated with the keys that the template is expecting, you must also supply an object attached to opts.bindings. (The meanings of the keys in the bindings object are documented below.) The minimal bindings you can supply for this template are as shown in this example:

{
    template: "@flourish/bar-chart-race",
    version: "17",
    bindings: {
        data: {
            label: 0, // index of a column in your data
        },
        captions: {
            
        }
    },
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        captions: [
            [ "CaptionsColumn1Value1", "CaptionsColumn2Value1",
            [ "CaptionsColumn1Value2", "CaptionsColumn2Value2",
            [ "CaptionsColumn1Value3", "CaptionsColumn2Value3",
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "@flourish/bar-chart-race",
    version: "17",
    bindings: {
        data: {
            label: 0, // index of a column in your data
            values: [1, 2, ...], // index(es) of column(s) in your data
            category: 3, // index of a column in your data
            image: 4, // index of a column in your data
        },
        captions: {
            from: 0, // index of a column in your data
            to: 1, // index of a column in your data
            text: 2, // index of a column in your data
            image: 3, // index of a column in your data
        }
    },
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        captions: [
            [ "CaptionsColumn1Value1", "CaptionsColumn2Value1",
            [ "CaptionsColumn1Value2", "CaptionsColumn2Value2",
            [ "CaptionsColumn1Value3", "CaptionsColumn2Value3",
            ...
        ]
    }
}

2. Array of objects with arbitrary keys, and a bindings object

This format is most likely useful when you have data from an external source, such as CSV data loaded from d3-dsv. You should supply this attached to the opts.data, which might look like:

{
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        captions: [
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            ...
        ]
    }

... but with the keys being the column headers from your source data instead. You must also supply an object attached to opts.bindings. The minimal bindings you can supply for this template are as shown in this example:

{
    template: "@flourish/bar-chart-race",
    version: "17",
    bindings: {
        data: {
            label: "DataHeader1",
        },
        captions: {
            
        }
    },
    data: {
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        captions: [
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "@flourish/bar-chart-race",
    version: "17",
    bindings: {
        data: {
            label: "DataHeader1",
            values: ["DataHeader2", "DataHeader3", ...],
            category: "DataHeader4",
            image: "DataHeader5",
        },
        captions: {
            from: "CaptionsHeader1",
            to: "CaptionsHeader2",
            text: "CaptionsHeader3",
            image: "CaptionsHeader4",
        }
    },
    data: {
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        captions: [
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            ...
        ]
    }
}

(As before, the keys containing "Header" would be replaced by column names from your data source.)

3. Array of objects with template-defined keys

There is an alternative format you can use, which is likely to be easier to use if your data is not from a spreadsheet source. With this alternative format you supply your data to the template as an array of objects, attached to opts.data, where the keys must be those used by the template, as documented below. In this case there is no need to supply a bindings object, since the key names are already those expected by the template. The required properties in the data object are as follows (scroll down for a description of what each property is):

{
    template: "@flourish/bar-chart-race",
    version: "17",
    data: {
    data: [
        {
            label: ...,
            values: [...]
        },
        ...
    ]
},
    ...
}

And the full list of all possible properties is as follows:

{
    template: "@flourish/bar-chart-race",
    version: "17",
    data: {
    data: [
        {
            label: ...,
            values: [...],
            category: ...,
            image: ...
        },
        ...
    ],
    captions: [
        {
            from: ...,
            to: ...,
            text: ...,
            image: ...
        },
        ...
    ]
},
    ...
}

Meanings of the template data keys:

  • data.label: A column containing the names of the bars, e.g. countries or people string
  • data.values: Multiple columns of numbers, each column representing a <a href="https://help.flourish.studio/article/84-how-to-make-data-cumulative">point in time</a> number
  • data.category: Optional category column to <a href="https://help.flourish.studio/article/47-how-to-change-the-colour-of-your-bars">color the bars</a>. Make sure the <b>Color mode</b> setting is set to <b>By Category</b> in the <b>Bar colors</b> settings panel string
  • data.image: Optional column with URLs of images string
  • captions.from: Must match the column headers in the main data sheet string, datetime
  • captions.to: Must match the column headers in the main data sheet string, datetime
  • captions.text: Text or HTML to show string
  • captions.image: Image to show. Add an <a href="https://help.flourish.studio/article/46-how-to-add-images-to-your-visualization">image URL</a> or right-click on a cell to upload an image. string

Template metadata

Note: metadata is optional, and the API will interpret your data for you if you do not specify it. A typical example of when specifying metadata can be useful is when column(s) in your data contain numbers or dates that you wish to format visually (e.g. to display a column containing MM/DD/YYYY dates in DD/MM/YYYY format).

This template supports an optional metadata property. metadata informs the template what type of data is in each of your columns, and how that data should be formatted visually.

You can specify metadata in one of three formats, depending on the format of opts.data.

1. Array of objects with column indexes as keys

You should supply metadata in this format when opts.data is in the previously described 'array of arrays' format. In this case, metadata should be an object with column index: column type object key/value pairs (column type objects must have type, type_id, and output_format_id keys, documented below):

{
    template: "@flourish/bar-chart-race",
    version: "17",
    ...
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        captions: [
            [ "CaptionsColumn1Value1", "CaptionsColumn2Value1",
            [ "CaptionsColumn1Value2", "CaptionsColumn2Value2",
            [ "CaptionsColumn1Value3", "CaptionsColumn2Value3",
            ...
        ]
    },
    metadata: {
        data: {
            0: { type: ..., type_id: ..., output_format_id: ... },
            1: { type: ..., type_id: ..., output_format_id: ... },
            2: { type: ..., type_id: ..., output_format_id: ... },
        }
    },
    ...
}

2. Array of objects with column headers as keys

You should supply metadata in this format when opts.data is in the previously described 'array of objects with arbitrary keys' format. In this case, metadata should be an object with column header: column type object key/value pairs (column type objects must have type, type_id, and output_format_id keys, documented below):

{
    template: "@flourish/bar-chart-race",
    version: "17",
    data: {
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        captions: [
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            { "CaptionsHeader1": ..., "CaptionsHeader2": ..., ... },
            ...
        ]
    },
    metadata: {
        data: {
            "DataHeader1": { type: ..., type_id: ..., output_format_id: ... },
            "DataHeader2": { type: ..., type_id: ..., output_format_id: ... },
            "DataHeader3": { type: ..., type_id: ..., output_format_id: ... },
        }
    },
    ...
}

Column type objects:

Column type objects tell the API what type of data is in a column:

{
    type: "number", // options also include 'string', and 'datetime'
    type_id: "number$comma_point", // numbers in the format 13,429.17
    output_format_id: "number$space_comma", // numbers in the format 13 429,17
}

For more information on valid column type values, see Recognized Type Formats.

Template settings

Options for opts.state.

Setup

column_chart boolean

Chart style.

Allowed values:

  • false (Horizontal)
  • true (Vertical)

number_of_bars number

No. bars.

Min: 1

bar_margin number

Spacing (Percentage). Spacing as a percentage of bar width. For example at "50" the bar height will equal bar spacing.

Max: 99

sort_enabled boolean

Sorting.

Allowed values:

  • true (On)
  • false (Off)

sort_ascending boolean

Sort mode.

Allowed values:

  • false (fa-sort-amount-desc)
  • true (fa-sort-amount-asc)

bars_advanced boolean

Show advanced.

height_mode string

Bar height.

Allowed values:

  • fill_space (Auto)
  • specified (Specified)

bar_height number

Height. Height of the bar; expressed as a multiple of the base font size to make it responsive

Max: 99

bar_min_value number

Hide bars below value. This will hide all bars that have a value below the number specified in this setting

bar_empty_spaces boolean

When not enough bars. If enabled, the chart and bars will remain the same size as more bars enter the race

Allowed values:

  • true (Leave space)
  • false (Resize)

Colors

color_mode string

Color mode. Whether to color by category (if you have a category column set in the datasheet), by each individual bar, or give every bar the same color

Allowed values:

  • category (By category)
  • bar (By bar)
  • single (Single)

color_single color

Single color.

color.categorical_palette colors

Palette.

color.categorical_extend boolean

Extend. Automatically generate additional colours when needed to avoid the palette colours being used more than once

color.categorical_custom_palette text

Color overrides. Enter the label name for which you wish to set the color, followed by a colon and the desired color value.

Colors can be set using Hex, RGB, color names or RGBA, if you want to set the opacity. Multiple colors can be set using multiple lines. For example:


Party 1: red
Party 2: #4455AA
Party 3: rgb(30,168,26)

color.numeric_type string

Scale type.

Allowed values:

  • sequential (Sequential)
  • diverging (Diverging)

color.binning boolean

In linear mode, the color scale will run as a smooth gradient between 2 colors. In binned mode, the gradient will be divided in smaller blocks.

Allowed values:

  • false (Linear)
  • true (Binned)

color.bin_mode string

Binning mode.

Allowed values:

  • fixed (Fixed width)
  • quantile (Quantile)
  • custom (Custom thresholds)

color.bin_count number

Number of bins.

color.bin_thresholds string

Custom thresholds. Enter your desired thresholds, separating them with a ";". For instance, "5;10;15".

Bins form as follows:

  • From the data's minimum value (domain minimum) up to the first threshold.
  • Between consecutive thresholds.
  • From the last threshold to the data's maximum value (domain maximum).

    • For "5;10;15", you'll get four bins based on your data's range.

      color.sequential_palette string

      Palette.

      Allowed values:

      • Oranges (Oranges)
      • Reds (Reds)
      • Blues (Blues)
      • Greens (Greens)
      • Greys (Greys)
      • Purples (Purples)
      • Viridis (Viridis)
      • Inferno (Inferno)
      • Magma (Magma)
      • Plasma (Plasma)
      • Warm (Warm)
      • Cool (Cool)
      • CubehelixDefault (Cubehelix)
      • BuGn (Blue/Green)
      • BuPu (Blue/Purple)
      • GnBu (Green/Blue)
      • OrRd (Orange/Red)
      • PuBuGn (Purple/Blue/Green)
      • PuBu (Purple/Blue)
      • PuRd (Purple/Red)
      • RdPu (Red/Purple)
      • YlGnBu (Yellow/Blue/Green)
      • YlGn (Yellow/Green)
      • YlOrBr (Yellow/Orange/Brown)
      • YlOrRd (Yellow/Orange/Red)
      • Carrots
      • Custom

      color.sequential_reverse boolean

      Reverse.

      color.sequential_custom_min color

      Minimum color.

      color.sequential_custom_max color

      Maximum color.

      color.sequential_color_space string

      Color space.

      Allowed values:

      • rgb (RGB)
      • lab (LAB)
      • hcl (HCL)
      • hsl (HSL)

      color.sequential_custom_domain boolean

      Domain.

      Allowed values:

      • false (Auto)
      • true (Custom)

      color.sequential_domain_min number

      Min.

      color.sequential_domain_max number

      Max.

      color.diverging_palette string

      Palette.

      Allowed values:

      • RdBu (Red/Blue)
      • RdYlGn (Red/Yellow/Green)
      • PiYG (Pink/Yellow/Green)
      • BrBG (Brown/Blue/Green)
      • PRGn (Purple/Red/Green)
      • PuOr (Purple/Orange)
      • RdGy (Red/Grey)
      • RdYlBu (Red/Yellow/Blue)
      • Spectral (Spectral)
      • Custom

      color.diverging_reverse boolean

      Reverse.

      color.diverging_custom_min color

      Minimum color.

      color.diverging_custom_mid color

      Midpoint color.

      color.diverging_custom_max color

      Maximum color.

      color.diverging_color_space string

      Color space.

      Allowed values:

      • rgb (RGB)
      • lab (LAB)
      • hcl (HCL)
      • hsl (HSL)

      color.diverging_custom_domain boolean

      Domain.

      Allowed values:

      • false (Auto)
      • true (Custom)

      color.diverging_domain_min number

      Min.

      color.diverging_domain_mid number

      Mid.

      color.diverging_domain_max number

      Max.

      color_single_overrides text

      Color overrides. Enter the label name for which you wish to set the color, followed by a colon and the desired color value.

      Colors can be set using Hex, RGB, color names or RGBA, if you want to set the opacity. Multiple colors can be set using multiple lines. For example:


      Party 1: red
      Party 2: #4455AA
      Party 3: rgb(30,168,26)

      bar_opacity number

      Bar opacity.

      Max: 1

      Labels

      label_max_size number

      Max size. In rems, a multiple of the page's base font size

      label_mode string

      Labels mode.

      Allowed values:

      • bars (Labels on bars (images in axis))
      • axis (Labels in axis (images on bars))

      label_color_in color

      Color.

      label_axis_width number

      Space. In rems, a multiple of the page's base font size

      show_value boolean

      Show values.

      label_color_out color

      Color.

      padding_right number

      Space.

      Images

      image_height number

      Height. As a percentage of bar height

      image_width number

      Width. As a percentage of bar height

      image_margin_right number

      Margin right. As a percentage of bar height. Use a negative value to get images to show to the right of the bar.

      image_scale string

      Image sizing.

      Allowed values:

      • fill (Fill)
      • fit (Fit)
      • stretch (Stretch)

      image_circle boolean

      Shape.

      Allowed values:

      • false (Rectangle)
      • true (Circle)

      Counter & totalizer

      counter boolean

      Show current time.

      counter_font_size number

      Size (percentage of screen).

      counter_color color

      Color.

      counter_line_height number

      Line height.

      Max: 2

      totaliser boolean

      Show total. Shows the sum of all the values in the datasheet for the current time, including any bars not currently visible in the chart.

      totaliser_font_size number

      Size (percentage of screen).

      totaliser_color color

      Color.

      totaliser_label string

      Label.

      Timed captions

      caption_background_color color

      Background.

      caption_border_color color

      Border.

      caption_opacity number

      Opacity.

      Max: 1

      caption_padding number

      Padding. In rems – multiples of the base font size

      caption_text_align string

      Align.

      Allowed values:

      • flex-start (fa-align-left)
      • center (fa-align-center)
      • flex-end (fa-align-right)

      caption_position string

      Position.

      Allowed values:

      • top-left (Top left)
      • center-left (Center left)
      • bottom-left (Bottom left)
      • top-right (Top right)
      • center-right (Center right)
      • bottom-right (Bottom right)
      • top-center (Top center)
      • center-center (Center)
      • bottom-center (Bottom center)

      caption_font_size number

      Font size. In rems – multiples of the base font size

      caption_text_color color

      Text.

      caption_mode string

      Content mode. In Text with colors mode, any phrases matching category names will be automatically colored. In HTML mode, no colors will be applied, but you can include any HTML in the datasheet to add images, etc.

      Allowed values:

      • text_legend (Text with colors)
      • html (HTML)

      caption_image_width number

      Width. As a percentage of the caption container width

      Max: 80

      caption_image_position string

      Position.

      Allowed values:

      • column (Images below (content above))
      • column-reverse (Images above (content below))
      • row (Images right (content left))
      • row-reverse (Images left (content right))

      caption_space_between number

      Space between. Space between the image and text in rems, a multiple of the page's base font size

      Controls

      sort_control boolean

      Show sort control.

      sort_descending_text string

      “Highest” label.

      sort_ascending_text string

      “Lowest” label.

      controls_style.font_size number

      Text size.

      Max: 5

      controls_style.font_weight string

      Text weight.

      Allowed values:

      • bold (Bold)
      • normal (Normal)

      controls_style.height number

      Height.

      Max: 5

      button_style.background color

      Background.

      button_style.background_selected color

      Selected.

      button_style.background_hover color

      Mouse over.

      button_style.font_color color

      Text color.

      button_style.font_color_selected color

      Selected.

      button_style.font_color_hover color

      Mouse over.

      button_style.button_styles_advanced boolean

      Button border styles.

      button_style.border_width number

      Border width.

      Max: 20

      button_style.border_color color

      Color.

      button_style.border_transparency number

      Transparency.

      Max: 1

      button_style.border_radius number

      Radius.

      Max: 100

      Legend

      legend_container.alignment string

      Alignment.

      Allowed values:

      • start (fa-align-left)
      • center (fa-align-center)
      • end (fa-align-right)

      legend_container.orientation string

      Orientation.

      Allowed values:

      • horizontal (Horizontal)
      • vertical (Vertical)

      legend_container.title_weight string

      Title weight.

      Allowed values:

      • bold (Bold)
      • normal (Normal)

      legend_container.text_weight string

      Text weight.

      Allowed values:

      • bold (Bold)
      • normal (Normal)

      legend_container.text_color color

      Color.

      legend_container.text_size number

      Size.

      Max: 10

      legend_categorical.show_legend boolean

      Legend mode. A legend will not show with a single entry

      Allowed values:

      • true (Enabled)
      • false (Disabled)

      legend_categorical.title_mode string

      Title mode.

      Allowed values:

      • auto (Auto)
      • custom (Custom)

      legend_categorical.title string

      Title.

      legend_categorical.swatch_width number

      Width.

      legend_categorical.swatch_height number

      Height.

      legend_categorical.swatch_radius number

      Roundness. The radius of the corners of the swatch (in pixels)

      legend_categorical.legend_items_padding number

      Padding. Padding between legend items (in rems)

      legend_categorical.swatch_outline boolean

      Outline. An optional outline for the swatch in the legend

      legend_categorical.swatch_outline_color color

      Color.

      legend_categorical.order_override text

      Custom order override. Manually specify the order of legend entries (one entry per line)

      legend_categorical.icon_height number

      Height. Height of icon (in rems)

      legend_categorical.icon_color color

      Color. Fallback color (icon color if not determined by template)

      legend_categorical.max_width number

      Max width.

      legend_categorical.orientation string

      Orientation.

      Allowed values:

      • horizontal (Horizontal)
      • vertical (Vertical)

      text_legend string

      Allowed values:

      • auto (Auto)
      • custom (Custom)
      • off (Off)

      text_legend_title boolean

      Title.

      text_legend_subtitle boolean

      Subtitle.

      text_legend_caption boolean

      Captions.

      text_legend_bold boolean

      Bold. If checked, always use bold for colored items

      Axis

      axis_text_color color

      Text color.

      axis_font_size number

      Text size. In rems, a multiple of the page's base font size

      axis_color color

      Line color.

      axis_gridline_dash number

      Line dash.

      Max: 5

      scale_type string

      Type. The dynamic scale type sets a dynamix X axis that will animate with the chart. The fixed or custom scale type sets a fixed maximum value on the X axis.

      Allowed values:

      • auto (Dynamic)
      • auto_fixed (Fixed)
      • manual (Custom)

      scale_min number

      Min range. The axis will go from zero to this value, then be dynamic

      scale_max number

      Max.

      Annotations

      annotations_enabled boolean

      Allowed values:

      • true (Enabled)
      • false (Disabled)

      annotations_content text

      Annotations. One line per annotation.

      Syntax
      Annotation text :: Value on X axis

      Example
      Winner :: 250
      Majority :: 200

      annotations_text_color color

      Text color.

      annotations_text_size number

      Size.

      annotations_text_weight string

      Weight.

      Allowed values:

      • bold (Bold)
      • normal (Regular)

      annotations_line_color color

      Line color.

      annotations_line_opacity number

      Opacity.

      Max: 1

      annotations_line_width number

      Width.

      annotations_line_dash number

      Dash.

      annotations_align string

      Align.

      Allowed values:

      • start (Start)
      • middle (Middle)
      • end (End)

      annotations_offset string

      Offset. Offset text mode

      Allowed values:

      • above (Above line)
      • on (On line)
      • below (Below line)

      Timeline & animation

      timeline.enabled boolean

      Allowed values:

      • true (Enabled)
      • false (Disabled)

      timeline.style string

      Style.

      Allowed values:

      • timeline (Timeline)
      • button (Play/pause)

      timeline.graph boolean

      Show chart.

      Allowed values:

      • true (Show)
      • false (Hide)

      timeline.play_on_load boolean

      Play on load.

      timeline.loop boolean

      Loop timeline. When turned on, the timeline will return to the beginning once complete. Otherwise, it will stop when it reaches the end.

      timeline.duration number

      Timeline duration. Total duration of the timeline during normal playback in seconds.

      timeline.duration_tween number

      Time jump duration. Duration of transitions between different points in time on the timeline.

      This is the transition you see in the story player when switching between slides with a different time on the timeline (in seconds).

      timeline.duration_wait_at_end number

      Pause before loop.

      timeline.axes_custom_enabled boolean

      Axis settings.

      timeline.color_axes color

      Axes color.

      timeline.axis_font_size number

      Font size.

      Max: 3

      timeline.date_format_display string

      X axis date format.

      Predefined values:

      • (Auto)
      • %Y-%m-%dT%H:%M:%S.%LZ (1986-01-28T11:39:13.000Z)
      • %Y-%m-%d (1986-01-28)
      • %m/%d/%Y (01/28/1986)
      • %d/%m/%Y (28/01/1986)
      • %d-%b-%y (28-Jan-86)
      • %m/%Y (01/1986)
      • %b %Y (Jan 1986)
      • %b '%y (Jan '86)
      • %B %d (January 28)
      • %d %b (28 Jan)
      • %Y (1986)
      • %B (January)
      • %b (Jan)
      • %A (Tuesday)
      • %a (Tue)
      • %H:%M:%S (11:39:13)
      • %I:%M %p (11:39 AM)
      • %H:%M (11:39)

      timeline.axis_nice_x boolean

      Clean X axis. Rounds out the X axis so that its start and end values are nice, round dates

      timeline.axis_nice_y boolean

      Clean Y axis. Rounds out the Y axis so that its start and end values are nice, round numbers

      timeline.scrubber_snap boolean

      Snap when scrubbing. When turned on, you can only jump to values that are supplied in the dataset and nothing in between

      timeline.scrubber_snap_paused boolean

      Snap when paused. Activate to snap the timeline to the closest interval when non animating. This is useful for ensuring the data visible in the visualization always reflects the data you have supplied.

      timeline.layout_settings boolean

      Layout settings.

      timeline.margin.top number

      Top.

      timeline.margin.left number

      Left.

      timeline.margin.bottom number

      Bottom.

      timeline.margin.right number

      Right.

      timeline.playback_button.margin_right number

      Space between button and timeline.

      timeline.scrubber_height number

      Scrubber height.

      timeline.playback_button.margin_right_button number

      Space between button and text.

      timeline.graph_settings boolean

      Chart settings.

      timeline.color_background color

      Background.

      timeline.graph_height number

      Height.

      timeline.curve boolean

      Curved lines.

      timeline.playback_styling boolean

      Play button settings.

      timeline.playback_button.button_color color

      Button color.

      timeline.playback_button.button_size number

      Button size.

      Max: 8

      timeline.playback_button.icon_color color

      Icon color.

      timeline.playback_button.icon_size number

      Icon size.

      Max: 8

      timeline.playback_button.label_size number

      Label size.

      Max: 8

      animation_duration number

      Bar swap duration. Animation duration of the bars swapping, in seconds

      Number formatting

      formatting.prefix string

      Prefix. Text to place in front of a number

      formatting.suffix string

      Suffix. Text to place after a number

      formatting.n_dec number

      Decimal places. Decimal places. You can also enter a negative integer to round to a whole number with that many zeros. For example, -2 will round to the nearest hundred.

      Min: -10

      Max: 10

      formatting.advanced boolean

      Advanced.

      formatting.negative_sign string

      Styling of negative numbers.

      Allowed values:

      • -$nk (-$100k)
      • $-nk ($-100k)
      • ($nk) (($100k))
      • $(n)k ($(100)k)
      • none ($100k)

      formatting.strip_zeros boolean

      Remove trailing zeros.

      formatting.strip_separator boolean

      Hide thousands separator below 10,000. Turn off if you want four-digit numbers to include a separator, e.g. “1,234” rather than “1234”.

      formatting.transform_labels boolean

      Multiply/divide values.

      formatting.transform string

      Allowed values:

      • multiply (Multiply by)
      • divide (Divide by)
      • exponentiate (×10 to the power of)

      formatting.multiply_divide_constant number

      formatting.exponentiate_constant number

      blank_cells string

      How to handle blank/invalid cells. Interpolate fills the gaps between the last and next valid values.
      Use last valid will use the last number for the bar.
      Treat as zero will set the value of the blank cell to zero.
      Remove bar will remove the bar for any blank/invalid cells.

      Allowed values:

      • interpolate (Interpolate)
      • last_valid (Use last valid)
      • zero (Treat as zero)
      • remove (Remove bar)

      Layout

      layout.body_font font

      Main font. This font will apply to the whole graphic by default. You can optionally change the font for the title, subtitle, footer, etc in the Header and Footer settings panels.

      layout.font_color color

      Text color. This color will apply to the whole graphic by default, You can optionally change the color for individual text elements, in other settings panels.

      layout.background_color_enabled boolean

      Color.

      Allowed values:

      • true (On)
      • false (Off)

      layout.background_image_enabled boolean

      Image.

      Allowed values:

      • true (On)
      • false (Off)

      layout.background_color color

      Background color.

      layout.background_image_src url

      Image URL.

      layout.background_image_size string

      Size.

      Allowed values:

      • cover (Fill)
      • contain (Fit)
      • auto (Original)
      • 100% 100% (Stretch)

      layout.background_image_position string

      Position.

      Allowed values:

      • top left (Top left)
      • top center (Top center)
      • top right (Top right)
      • center left (Center left)
      • center center (Center)
      • center right (Center right)
      • bottom left (Bottom left)
      • bottom center (Bottom center)
      • bottom right (Bottom right)

      layout.max_width_target string

      Maximum width. Apply a maximum width to just the main graphic or everything (main graphic plus header, footer, etc).

      Allowed values:

      • none (None)
      • wrapper (Everything)
      • primary (Main graphic)

      layout.max_width number

      Maximum width. Leave blank to stretch to container width

      Min: 50

      layout.max_width_align string

      Align.

      Allowed values:

      • left (fa-align-left)
      • center (fa-align-center)
      • right (fa-align-right)

      layout.layout_order string

      Layout order.

      Allowed values:

      • stack-default (Header – controls – legend – primary graphic – footer)
      • stack-2 (Primary graphic – header – controls – legend – footer)
      • stack-3 (Header – primary graphic – controls – legend – footer)
      • stack-4 (Controls – primary graphic – header – legend – footer)
      • grid-1 (Grid mode: Primary graphic on the right)

      layout.space_between_sections string

      Space between sections.

      Allowed values:

      • 0.5 (▁)
      • 1 (▃)
      • 1.5 (▄)
      • custom (...)

      layout.space_between_sections_custom number

      Custom.

      Max: 100

      layout.margin_top number

      Top.

      layout.margin_right number

      Right.

      layout.margin_bottom number

      Bottom.

      layout.margin_left number

      Left.

      layout.border.enabled boolean

      Show borders around visualisation.

      layout.border.top.width number

      Top.

      layout.border.top.style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.border.top.color color

      Color.

      layout.border.right.width number

      Right.

      layout.border.right.style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.border.right.color color

      Color.

      layout.border.bottom.width number

      Bottom.

      layout.border.bottom.style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.border.bottom.color color

      Color.

      layout.border.left.width number

      Left.

      layout.border.left.style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.border.left.color color

      Color.

      layout.read_direction string

      Read direction. This will change the reading direction of the main text elements on the page. It's not possible to adjust this on all elements, such as axes.

      Note that when direction is set to right to left any alignment icons will be reversed.

      Allowed values:

      • ltr (Left to right)
      • rtl (Right to left)

      layout.font_size_mobile_small number

      layout.font_size_mobile_big number

      layout.font_size_tablet number

      layout.font_size_desktop number

      layout.font_size_big_screen number

      layout.breakpoint_mobile_small number

      layout.breakpoint_mobile_big number

      layout.breakpoint_tablet number

      layout.breakpoint_desktop number

      layout.breakpoint_big_screen number

      layout.header_align string

      Alignment.

      Allowed values:

      • left (fa-align-left)
      • center (fa-align-center)
      • right (fa-align-right)

      layout.title html

      layout.title_styling boolean

      Styling.

      layout.title_font font

      Title Font.

      layout.title_size string

      Size.

      Allowed values:

      • 1.4 (ᴀ)
      • 1.6 (A)
      • 2 (fa-font)
      • custom (...)

      layout.title_size_custom number

      Custom. Specify a custom responsive font size in rems. The best results will be with values between 1.2 and 3

      layout.title_weight string

      Weight.

      Allowed values:

      • bold (Bold)
      • normal (Regular)

      layout.title_color color

      Color.

      layout.title_line_height number

      Line height.

      Max: 3

      layout.title_space_above string

      Space above.

      Allowed values:

      • 0 (▁)
      • 0.5 (▃)
      • 1 (▄)
      • custom (...)

      layout.title_space_above_custom number

      Custom.

      Max: 100

      layout.subtitle html

      layout.subtitle_styling boolean

      Styling.

      layout.subtitle_font font

      Subtitle Font.

      layout.subtitle_size string

      Size.

      Allowed values:

      • 1.4 (ᴀ)
      • 1.6 (A)
      • 2 (fa-font)
      • custom (...)

      layout.subtitle_size_custom number

      Custom. Specify a custom responsive font size in rems. The best results will be with values between 1.2 and 3

      layout.subtitle_weight string

      Weight.

      Allowed values:

      • bold (Bold)
      • normal (Regular)

      layout.subtitle_color color

      Color.

      layout.subtitle_line_height number

      Line height.

      Max: 3

      layout.subtitle_space_above string

      Space above.

      Allowed values:

      • 0 (▁)
      • 0.5 (▃)
      • 1 (▄)
      • custom (...)

      layout.subtitle_space_above_custom number

      Custom.

      Max: 100

      layout.header_text html

      layout.header_text_styling boolean

      Styling.

      layout.header_text_size string

      Size.

      Allowed values:

      • 1.2 (ᴀ)
      • 1.4 (A)
      • 1.6 (fa-font)
      • custom (...)

      layout.header_text_size_custom number

      Custom. Specify a custom responsive font size in rems. The best results will be with values between 1.2 and 3

      layout.header_text_weight string

      Weight.

      Allowed values:

      • bold (Bold)
      • normal (Regular)

      layout.header_text_color color

      Color.

      layout.header_text_line_height number

      Line height.

      Max: 3

      layout.header_text_space_above string

      Space above.

      Allowed values:

      • 0 (▁)
      • 0.5 (▃)
      • 1 (▄)
      • custom (...)

      layout.header_text_space_above_custom number

      Custom.

      Max: 100

      layout.header_border string

      Allowed values:

      • top (Top)
      • bottom (Bottom)
      • top_and_bottom (Top & bottom)
      • none (None)

      layout.header_border_width number

      Width.

      layout.header_border_color color

      Color.

      layout.header_border_style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.header_border_space number

      Space. Space between border and header text

      layout.header_logo_enabled boolean

      Allowed values:

      • true (Enabled)
      • false (Disabled)

      layout.header_logo_src url

      Image.

      layout.header_logo_alt string

      Alt text.

      Link.

      layout.header_logo_height number

      Height.

      layout.header_logo_align string

      Align. Align logo inside either the header or the main visualization container

      Allowed values:

      • inside (Header)
      • outside (Main container)

      layout.header_logo_position_inside string

      Position.

      Allowed values:

      • top (Top)
      • left (Left)
      • right (Right)

      layout.header_logo_position_outside string

      Position.

      Allowed values:

      • left (Left)
      • right (Right)

      layout.header_logo_margin_top number

      Top.

      layout.header_logo_margin_right number

      Right.

      layout.header_logo_margin_bottom number

      Bottom.

      layout.header_logo_margin_left number

      Left.

      layout.footer_align string

      Alignment.

      Allowed values:

      • left (fa-align-left)
      • center (fa-align-center)
      • right (fa-align-right)
      • justify (fa-align-justify)

      layout.footer_text_size number

      Size.

      layout.footer_text_color color

      Color.

      layout.footer_styling boolean

      Advanced footer styles.

      layout.footer_font font

      Font.

      layout.footer_text_weight string

      Weight.

      Allowed values:

      • bold (Bold)
      • normal (Regular)

      layout.source_name string

      Source name.

      layout.source_url string

      Source url.

      layout.multiple_sources boolean

      Multiple sources.

      layout.source_name_2 string

      Source name.

      layout.source_url_2 string

      Source url.

      layout.source_name_3 string

      Source name.

      layout.source_url_3 string

      Source url.

      layout.source_label string

      Source label.

      layout.footer_note html

      Note. To add the time/date stamp of when the data was last updated add {{data_last_updated}}. For example, "Last updated at {{data_last_updated}}". To customize the format, use the advanced options below.

      layout.footer_note_secondary html

      Note (secondary). The secondary note is placed below the source and primary note. To add the time/date stamp of when the data was last updated add {{data_last_updated}}. For example, "Last updated at {{data_last_updated}}". To customize the format, use the advanced options below.

      layout.advanced_note_styling boolean

      Advanced.

      layout.footer_timestamp_format string

      Time/date stamp formatting. To change the date/time format of your timestamp, choose from the below options or provide a custom date format in d3-time-format syntax

      Predefined values:

      • %H:%M:%S (13:39:13)
      • %I:%M %p (01:39 PM)
      • %H:%M (13:39)
      • %H:%M %p (13:39 PM)
      • %H:%M:%S, %d %b %Y (13:39:13, 28 Jan 2024)
      • %H:%M, %d %b %Y (13:39, 28 Jan 2024)
      • %H:%M, %d/%m/%Y (13:39, 28/01/2024)
      • %H:%M, %m/%d/%Y (13:39, 01/28/2024)
      • %H:%M, %d-%m-%Y (13:39, 28-01-2024)
      • %H:%M, %m-%d-%Y (13:39, 01-28-2024)
      • %d %b %Y (28 Jan 2024)
      • %m/%d/%Y (01/28/2024)
      • %d/%m/%Y (28/01/2024)
      • %m-%d-%Y (01-28-2024)
      • %d-%m-%Y (28-01-2024)
      • %Y-%m-%d (2024-01-28)
      • %Y-%m-%d %H:%M:%S (2024-01-28 13:39:13)

      layout.footer_logo_enabled boolean

      Image.

      Allowed values:

      • true (Enabled)
      • false (Disabled)

      layout.footer_logo_src url

      Image.

      layout.footer_logo_src_light hidden

      Image (light version). If provided this version will be used whenever the background color is dark

      layout.footer_logo_alt string

      Alt text.

      Link.

      layout.footer_logo_height number

      Height.

      layout.footer_logo_margin number

      Margin.

      layout.footer_logo_order string

      Position.

      Allowed values:

      • left (Left)
      • right (Right)

      layout.footer_align_vertical string

      V. align.

      Allowed values:

      • flex-start (Top)
      • center (Center)
      • flex-end (Bottom)

      layout.footer_border string

      Allowed values:

      • top (Top)
      • bottom (Bottom)
      • top_and_bottom (Top & bottom)
      • none (None)

      layout.footer_border_width number

      Width.

      layout.footer_border_color color

      Color.

      layout.footer_border_style string

      Style.

      Allowed values:

      • solid (Solid)
      • dashed (Dashed)
      • dotted (Dotted)

      layout.footer_border_space number

      Space. Space between border and footer text

      Accessibility

      layout.screenreader_text_primary text

      Screenreader description. A text alternative to the visual content that will only be visible to screenreaders, e.g. “The line chart shows China consistently higher than the other countries since 1990”.

      Do not replicate your title, since that will also be read by screenreaders.

      layout.screenreader_label string

      Screenreader label. A short text label given to the main Flourish embed wrapper to provide an accessible name that is only visible to screenreaders. Added in the form of an "aria-label".

      layout.screenreader_hide_primary boolean

      Screenreader mode for main visual container. Whether the main visual container is visible to screenreaders. (Text in the header and footer are always available to screenreaders.)

      Allowed values:

      • true (Hidden)
      • false (Readable)