Skip to content

Themes & Styling

Control the visual appearance of your dashboard globally or per-chart.

Global Styling

Set styling options for the entire dashboard:

style:
  palette: "category10"         # Color scheme name
  font: "Inter"                  # Font family
  grid_lines: true               # Show grid lines by default
  background: "#f5f5f5"          # General background color
  backgrounds:                   # Format-specific backgrounds
    svg: transparent
    png: "#ffffff"
    pdf: "#ffffff"
  css: "assets/custom.css"       # Import custom CSS file

Style Options

  • palette: Color scheme (e.g., "category10", "viridis", "blues")
  • font: Font family name
  • grid_lines: true or false to show/hide grid lines by default
  • background: General background color (hex, rgb, name, or "transparent")
  • backgrounds: Format-specific backgrounds (svg, png, pdf)
  • css: Path to a custom CSS file (relative to dashboard file or public root)

CSS Scope & Limitations

The style.css file styles the Dashboard Shell (HTML), but has limitations regarding internal Chart elements (SVG).

What CSS Can Style (HTML)

  • Layout: Rows, columns, grids, margins.
  • Typography: Section titles, markdown text, KPI cards, headers.
  • Interactive Elements: Filter inputs, buttons, tabs.
  • Backgrounds: Page background, section borders, shadows.

What CSS Cannot Style (Charts)

  • Chart Internals: Bars, lines, axes, legends inside the Vega-Lite charts.
  • PDF Exports: Static exports use a different rendering path where external CSS may not apply fully.

Recommendation: - Use Style Options (style.palette, chart.style) for chart colors and axes. - Use Custom CSS for layout, typography, and branding of the surrounding page.

Chart-Level Styling

Override theme for specific charts:

charts:
  custom_chart:
    title: "Custom Styled Chart"
    query: queries.sales
    type: bar
    x: month
    y: total_revenue
    style:
      palette: "viridis"          # Different color scheme
      legend: show                # Show legend
      grid_lines: false           # Hide grid lines
      labels: show                # Always show labels

Style Options

Color Palettes

Choose from built-in color palettes:

  • category10 - Default categorical palette (10 colors)
  • viridis - Perceptually uniform sequential palette
  • blues - Blue sequential palette
  • reds - Red sequential palette
  • greens - Green sequential palette
  • grays - Grayscale palette

Choosing a palette: - Categorical data: Use category10 or other categorical palettes - Sequential data: Use viridis, blues, reds, greens - Accessibility: Consider colorblind-friendly palettes

Legend

Control legend display:

style:
  legend: show    # Always show legend
  legend: hide    # Hide legend

Grid Lines

Show or hide grid lines:

style:
  grid_lines: true   # Show grid lines
  grid_lines: false  # Hide grid lines

Labels

Control axis label display:

style:
  labels: auto   # Auto-label placement (default)
  labels: show   # Always show labels
  labels: hide   # Hide labels

Typography

Set the font family via the top-level style configuration:

style:
  font: "Inter"  # Font family name

Common font choices: - Inter - Modern, readable sans-serif - Roboto - Google's Material Design font - Open Sans - Friendly, readable sans-serif - Lato - Humanist sans-serif

Layout Styling

Section Spacing

Sections automatically have appropriate spacing. The layout system handles: - Section margins - Chart spacing - Gap between items

Chart Sizing

Charts automatically size based on: - Layout type (row, grid, tabs) - Available space - Responsive breakpoints

Best Practices

Consistent Styling

  • Use the same color palette throughout a dashboard
  • Keep font choices consistent
  • Use grid lines consistently (all on or all off)

Accessibility Considerations

  • Choose colorblind-friendly palettes
  • Ensure sufficient contrast
  • Use labels and legends for clarity

Color Choices

  • Categorical data: Use distinct colors (category10)
  • Sequential data: Use gradient palettes (viridis, blues)
  • Avoid: Too many colors (5-7 max for clarity)

Performance

  • Styling has minimal performance impact
  • Use global style when possible (more efficient)
  • Override only when necessary
  • Charts - Chart styling options
  • Boards - Layout and organization