Theme

Enabling the theme

import attaviz
attaviz.enable()                  # medium size (default)
attaviz.enable(size="small")      # charts under ~400px wide
attaviz.enable(size="large")      # charts wider than ~700px

enable() registers and activates a theme variant globally. Every subsequent Altair chart in the session picks up WBG typography, colors, grids, and mark styling.

What the theme applies

Element	WBG specification
Font	Open Sans, sans-serif
Title	18px, bold, #111111
Subtitle	15px, regular, #666666
Axis labels	13px, semibold, #111111
Tick labels	13px, regular, #666666
Grid lines	#CED4DE, 1px, dashed (4 2)
Legend	14×14px symbol dots, semibold labels
Categorical colors	9-color WBG palette
Sequential colors	WBG blue ramp (default)
Diverging colors	WBG default diverging scale
Line marks	4px stroke, round caps/joins
Point marks	1px white stroke outline
Geo shapes	0.3px grey stroke, round joins

The values above are the medium defaults. small and large scale typography and spacing proportionally.

Size system

Size	Typical width	Typography / spacing
small	under 400px	compact
medium	400–700px	default
large	over 700px	expanded

Registered names: wbg (the default medium size), wbg-small, wbg-medium, and wbg-large.

Per-chart sizing

import altair as alt
import pandas as pd
import attaviz

attaviz.enable()
data = pd.DataFrame({"category": ["A", "B", "C"], "value": [10, 25, 18]})
chart = attaviz.bar(data, category="category", value="value", title="Example values")
attaviz.configure_size(chart, width=600, aspect_ratio="16:9")

configure_size() adds top-level Altair configuration for a standalone chart. For a chart you will pass to frame(), specify width and height on the template and choose typography with enable(size=...); Altair cannot nest a configured chart inside another composition.

• width — target pixel width; the size variant is inferred automatically.
• height — optional explicit pixel height, overriding the aspect ratio.
• aspect_ratio — "1:1", "4:3", "3:2", "16:9", "2:1", "square", "widescreen", or a numeric width/height ratio such as 1.5.

Calculating dimensions

w, h = attaviz.calculate_dimensions(800, "16:9")  # (800, 450)
attaviz.bar(data, category="category", value="value", width=w, height=h)

Useful when you need the height up front (e.g. for a faceted chart whose rows must add up to a known total).

Size context managers

To override the active theme for a single chart (or a block of charts) without changing the global setting, use alt.theme.enable as a context manager against the registered variants:

theme_registry = alt.theme if hasattr(alt, "theme") else alt.themes

with theme_registry.enable("wbg-small"):
    small_chart = attaviz.bar(data, category="category", value="value", width=300, height=150)
    small_chart.to_dict()  # serialize/export while the temporary theme is active

with theme_registry.enable("wbg-large"):
    large_chart = attaviz.bar(data, category="category", value="value", width=800, height=400)
    large_chart.to_dict()

alt.theme is the current Altair interface; the fallback keeps this example compatible with older supported Altair 5 releases. When the block exits, the previously active theme is restored. Altair applies the theme when serializing the chart, so display or export inside the block to capture that temporary theme.

Theme configuration

wbg_theme() returns the raw theme dictionary. Use size, width, height, and aspect_ratio to inspect or register a configuration for a specific output medium:

@alt.theme.register("wbg-widescreen", enable=True)
def wbg_widescreen():
    return alt.theme.ThemeConfig(
        attaviz.wbg_theme(width=1200, aspect_ratio="16:9")
    )

chart = attaviz.bar(data, category="category", value="value", width=1200, height=675)
chart.to_dict()  # includes the custom theme configuration
attaviz.enable()  # restore the default for subsequent examples

Typography and spacing scale off the supplied width using the size breakpoints above (so a 1200px theme inherits large tokens).

This registration example uses the current registry introduced in Altair 5.5. On older Altair 5 releases, register a function returning the raw wbg_theme() dictionary through alt.themes.register(), then enable it with alt.themes.enable().

Sizing constants

For custom theming or introspection, these constants are re-exported:

• attaviz.SIZE_BREAKPOINTS — {"small": 400, "medium": 700}
• attaviz.TYPOGRAPHY — per-size font-size dicts
• attaviz.SPACING — per-size spacing tokens (xs, s, m, l, xl)
• attaviz.ASPECT_RATIOS — named ratio lookup
• attaviz.DEFAULT_DIMENSIONS — default (w, h) per size