theme

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 24, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package theme provides visual styling configurations for plots. Themes control non-data visual elements: background colors, fonts, grid lines, tick marks, spacing, and the discrete color palette used when no explicit color scale is set.

Elements follow ggplot2's inheritance hierarchy:

text                 → root text defaults
├── plot.title
├── plot.subtitle
├── axis.title       → axis.title.x, axis.title.y
├── axis.text        → axis.text.x, axis.text.y
├── legend.title
├── legend.text
└── strip.text

line                 → root line defaults
├── axis.line        → axis.line.x, axis.line.y
├── axis.ticks       → axis.ticks.x, axis.ticks.y
├── panel.grid.major
└── panel.grid.minor

rect                 → root rect defaults
├── plot.background
├── panel.background
├── panel.border
├── legend.background
├── legend.key
└── strip.background

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrEmptyName is returned when registering a theme with an empty name.
	ErrEmptyName = errors.New("theme: cannot register empty name")
	// ErrNilFactory is returned when registering a nil factory.
	ErrNilFactory = errors.New("theme: cannot register nil factory")
	// ErrDuplicateName is returned when a theme name is already registered.
	ErrDuplicateName = errors.New("theme: name already registered")
	// ErrUnknownName is returned when resolving an unregistered theme name.
	ErrUnknownName = errors.New("theme: unknown name")
)

Functions

func DefaultCmapFor added in v0.0.5

func DefaultCmapFor(name Name, aes Aesthetic, cat colormap.Category) colormap.Cmap

DefaultCmapFor returns the recommended Cmap for the given theme, aesthetic, and colormap category. This is the primary integration point for the scale pipeline: when a user hasn't set an explicit colormap, the scale can call

cmap := theme.DefaultCmapFor(th.Name, theme.AesColor, colormap.Qualitative)

and get a sensible default that matches the theme's visual language.

func IsBlank added in v0.0.4

func IsBlank(e Element) bool

IsBlank reports whether an Element is ElementBlank.

func MustRegister

func MustRegister(name Name, f Factory)

MustRegister is Register but panics on error. Intended for init().

func Register

func Register(name Name, f Factory) error

Register adds a named theme factory to the global registry.

Types

type Aesthetic added in v0.0.7

type Aesthetic string

Aesthetic identifies the color or fill aesthetic channel.

const (
	// AesColor is the stroke/outline color aesthetic.
	AesColor Aesthetic = "color"
	// AesFill is the fill color aesthetic.
	AesFill Aesthetic = "fill"
)

type ColorDefaults added in v0.0.5

type ColorDefaults struct {
	// ColorDiscrete is the qualitative palette for categorical color data.
	ColorDiscrete colormap.Cmap
	// ColorSequential is the continuous ramp for ordered color data.
	ColorSequential colormap.Cmap
	// FillDiscrete is the qualitative palette for categorical fill data.
	// Falls back to ColorDiscrete when nil.
	FillDiscrete colormap.Cmap
	// FillSequential is the continuous ramp for ordered fill data.
	// Falls back to ColorSequential when nil.
	FillSequential colormap.Cmap
	// Diverging emphasises departure from a meaningful midpoint.
	Diverging colormap.Cmap
	// Cyclic wraps so that 0 and 1 are the same color (phase, angle).
	Cyclic colormap.Cmap
}

ColorDefaults maps a theme to its recommended colormaps by aesthetic and data category. The scale pipeline consults these when the user hasn't explicitly set a colormap, so that dark themes get bright-ended ramps, accessibility themes get colorblind-safe maps, and editorial themes get restrained neutrals.

Color* fields are used for stroke/outline aesthetics (aes.Color). Fill* fields are used for fill aesthetics (aes.Fill). Zero-value Fill* fields fall back to the corresponding Color* field.

func DefaultColorDefaults added in v0.0.5

func DefaultColorDefaults(name Name) ColorDefaults

DefaultColorDefaults returns the ColorDefaults for the given theme. If the theme has no explicit entry, the package-level defaults are returned (Tab10 discrete, Viridis sequential, Blues fill-sequential, RdBu diverging, Twilight cyclic).

type Element added in v0.0.4

type Element interface {
	// contains filtered or unexported methods
}

Element is a sealed interface for theme element types. Only ElementText, ElementLine, ElementRect, and ElementBlank implement it.

type ElementBlank added in v0.0.4

type ElementBlank struct{}

ElementBlank suppresses drawing of the element entirely. When encountered during inheritance resolution, the element is hidden.

type ElementLine added in v0.0.4

type ElementLine struct {
	Color    color.Color // line color; nil = inherit
	Size     float64     // line width in pixels; 0 = inherit
	Linetype []float64   // dash pattern: nil = solid, e.g. {4,4} = dashed
	Lineend  string      // "butt", "round", "square"; "" = inherit
}

ElementLine controls line appearance (axes, grid lines, ticks).

func MergeLine added in v0.0.4

func MergeLine(child, parent ElementLine) ElementLine

MergeLine returns a new ElementLine with zero-value fields in child filled from parent.

type ElementRect added in v0.0.4

type ElementRect struct {
	Fill     color.Color // interior fill; nil = inherit
	Color    color.Color // border stroke; nil = inherit
	Size     float64     // border width in pixels; 0 = inherit
	Linetype []float64   // border dash pattern
}

ElementRect controls rectangle appearance (backgrounds, borders).

func MergeRect added in v0.0.4

func MergeRect(child, parent ElementRect) ElementRect

MergeRect returns a new ElementRect with zero-value fields in child filled from parent.

type ElementText added in v0.0.4

type ElementText struct {
	Family     string      // font family ("sans-serif", "serif", "mono"); "" = inherit
	Size       float64     // font size in points; 0 = inherit
	Color      color.Color // text color; nil = inherit
	Bold       bool
	Italic     bool
	Hjust      float64 // horizontal justification [0,1] (0=left, 0.5=center, 1=right)
	Vjust      float64 // vertical justification [0,1]
	Angle      float64 // rotation in degrees
	Margin     Margin  // spacing around the text element
	LineHeight float64 // line spacing multiplier; 0 = default 1.2
}

ElementText controls text appearance (titles, labels, annotations).

func MergeText added in v0.0.4

func MergeText(child, parent ElementText) ElementText

MergeText returns a new ElementText with zero-value fields in child filled from parent. Non-zero child fields take precedence.

type Factory

type Factory func() Theme

Factory builds a Theme on demand.

type GeomDefaults

type GeomDefaults struct {
	// PatchEdgeColor is the stroke color drawn around filled geoms.
	// A nil value means "darken the fill color" (legacy behaviour).
	PatchEdgeColor color.Color
	// PatchEdgeWidth is the stroke line width for filled geoms (pixels).
	PatchEdgeWidth float64
	// PatchAlpha is the default fill opacity for filled geoms [0,1].
	// Zero is treated as "use geom's built-in default" (typically 0.85).
	PatchAlpha float64
}

GeomDefaults holds theme-level visual defaults for geometry primitives (bars, histograms, areas, boxplots). These act as fallbacks when the user has not explicitly overridden a property with a geom option.

type Margin added in v0.0.4

type Margin struct {
	Top, Right, Bottom, Left float64
}

Margin holds spacing around an element (top, right, bottom, left in px).

type Name

type Name string

Name identifies a built-in theme.

const (
	// Default is the default theme.
	Default Name = "default"

	// Minimal is the library-original minimal theme.
	Minimal Name = "minimal"

	// Dark is the dark theme.
	Dark Name = "dark"
	// BW is the black and white theme.
	BW Name = "bw"

	// Ggplot is the matplotlib ggplot preset.
	Ggplot Name = "ggplot"

	// Classic is the classic theme.
	Classic Name = "classic"

	// Grayscale is the grayscale theme.
	Grayscale Name = "grayscale"

	// Bmh is the bmh theme.
	Bmh Name = "bmh"

	// Fivethirtyeight is the fivethirtyeight theme.
	Fivethirtyeight Name = "fivethirtyeight"

	// DarkBackground is the dark background theme.
	DarkBackground Name = "dark_background"

	// SolarizeLight2 is the solarize light2 theme.
	SolarizeLight2 Name = "solarize_light2"

	// SolarizeDark is the solarize dark theme.
	SolarizeDark Name = "solarize_dark"

	// TableauColorblind10 is the tableau colorblind10 theme.
	TableauColorblind10 Name = "tableau_colorblind10"

	// Fast is the fast theme.
	Fast Name = "fast"

	// Seaborn family — chrome variants.
	Seaborn Name = "seaborn"

	// SeabornDarkgrid is the seaborn darkgrid theme.
	SeabornDarkgrid Name = "seaborn_darkgrid"

	// SeabornWhitegrid is the seaborn whitegrid theme.
	SeabornWhitegrid Name = "seaborn_whitegrid"

	// SeabornDark is the seaborn dark theme.
	SeabornDark Name = "seaborn_dark"

	// SeabornWhite is the seaborn white theme.
	SeabornWhite Name = "seaborn_white"

	// SeabornTicks is the seaborn ticks theme.
	SeabornTicks Name = "seaborn_ticks"

	// SeabornDeep is the Seaborn deep palette variant.
	SeabornDeep Name = "seaborn_deep"

	// SeabornMuted is the Seaborn muted palette variant.
	SeabornMuted Name = "seaborn_muted"

	// SeabornBright is the Seaborn bright palette variant.
	SeabornBright Name = "seaborn_bright"

	// SeabornColorblind is the Seaborn colorblind palette variant.
	SeabornColorblind Name = "seaborn_colorblind"

	// SeabornPastel is the Seaborn pastel palette variant.
	SeabornPastel Name = "seaborn_pastel"

	// SeabornDarkPalette is the Seaborn dark palette variant.
	SeabornDarkPalette Name = "seaborn_dark_palette"

	// SeabornPaper is the Seaborn paper font-size variant.
	SeabornPaper Name = "seaborn_paper"

	// SeabornNotebook is the Seaborn notebook font-size variant.
	SeabornNotebook Name = "seaborn_notebook"

	// SeabornTalk is the Seaborn talk font-size variant.
	SeabornTalk Name = "seaborn_talk"

	// SeabornPoster is the Seaborn poster font-size variant.
	SeabornPoster Name = "seaborn_poster"

	// PaulTol is the Paul Tol colorblind-safe palette from pyplot-themes.
	PaulTol Name = "paul_tol"

	// Few is the few theme.
	Few Name = "few"

	// FewLight is the few light theme.
	FewLight Name = "few_light"

	// FewDark is the few dark theme.
	FewDark Name = "few_dark"

	// UCBerkeley is the ucberkeley theme.
	UCBerkeley Name = "uc_berkeley"

	// Tableau is the tableau theme (Tableau10 palette, white panel).
	Tableau Name = "tableau"

	// Observable is the Observable modern theme (Observable10 palette).
	Observable Name = "observable"

	// Colorblind-safe theme (Wong 2011, 8 colors).
	Colorblind Name = "colorblind"

	// Autumn1 is a seasonal palette on tableau chrome.
	Autumn1 Name = "autumn1"
	// Autumn2 is a seasonal palette on tableau chrome.
	Autumn2 Name = "autumn2"
	// Canyon is a seasonal palette on tableau chrome.
	Canyon Name = "canyon"
	// Chili is a seasonal palette on tableau chrome.
	Chili Name = "chili"
	// Tomato is a seasonal palette on tableau chrome.
	Tomato Name = "tomato"

	// SolarizeLight is the solarized light companion (pyplot-themes palette).
	SolarizeLight Name = "solarize_light"

	// Petroff10 (new in matplotlib 3.10).
	Petroff10 Name = "petroff10"

	// ObservableDark is the dark variant of the Observable modern theme.
	ObservableDark Name = "observable_dark"
	// Dashboard is a clean card-style dashboard theme.
	Dashboard Name = "dashboard"
	// Quartz is an Apple-inspired minimal theme.
	Quartz Name = "quartz"
	// Air is a minimal, airy theme with hidden axes.
	Air Name = "air"
	// Ink is a slate-dark theme with bright accents.
	Ink Name = "ink"

	// Tufte is a Tufte-inspired minimal theme (serif, no grid).
	Tufte Name = "tufte"
	// Academic is a journal-ready theme with serif type.
	Academic Name = "academic"
	// Newsroom is a bold headline-first editorial theme.
	Newsroom Name = "newsroom"
	// Editorial is a warm serif editorial theme.
	Editorial Name = "editorial"
	// Monochrome is a strict black-and-white theme.
	Monochrome Name = "monochrome"

	// GitHubLight is GitHub's light color scheme.
	GitHubLight Name = "github_light"
	// GitHubDark is GitHub's dark color scheme.
	GitHubDark Name = "github_dark"
	// Nord is the Nord color palette theme.
	Nord Name = "nord"
	// Dracula is the Dracula color palette theme.
	Dracula Name = "dracula"
	// GruvboxLight is the Gruvbox light color scheme.
	GruvboxLight Name = "gruvbox_light"
	// GruvboxDark is the Gruvbox dark color scheme.
	GruvboxDark Name = "gruvbox_dark"

	// AstronomyDark is a deep-space dark theme with pastel accents.
	AstronomyDark Name = "astronomy_dark"
	// NASA is a NASA-blue institutional theme.
	NASA Name = "nasa"
	// Ocean is a blue-gradient ocean-inspired theme.
	Ocean Name = "ocean"
	// Earth is a warm earthy-tone theme.
	Earth Name = "earth"
	// Forest is a green nature-inspired theme.
	Forest Name = "forest"
	// Desert is a warm sand-toned theme.
	Desert Name = "desert"

	// HighContrast is a maximum-contrast accessibility theme.
	HighContrast Name = "high_contrast"
	// OkabeIto is the Okabe-Ito colorblind-safe palette theme.
	OkabeIto Name = "okabe_ito"
	// Viridis is a theme using the viridis perceptual colormap.
	Viridis Name = "viridis"
	// Cividis is a theme using the cividis colorblind-safe colormap.
	Cividis Name = "cividis"

	// Cyberpunk is a neon-on-dark cyberpunk theme.
	Cyberpunk Name = "cyberpunk"
	// Blueprint is a blueprint-paper theme with white-on-blue.
	Blueprint Name = "blueprint"
	// Terminal is a code-terminal theme with monospace type.
	Terminal Name = "terminal"
	// Retro is a vintage parchment-toned theme.
	Retro Name = "retro"
)

Built-in theme names.

Default resolves to the Dashboard card-style theme; users who want the matplotlib ggplot preset should use Theme("ggplot") explicitly.

func AllNames

func AllNames() []Name

AllNames returns every registered Name in alphabetical order.

type Spacing

type Spacing struct {
	// MarginTop is the top margin.
	MarginTop float64
	// MarginRight is the right margin.
	MarginRight float64
	// MarginBottom is the bottom margin.
	MarginBottom float64
	// MarginLeft is the left margin.
	MarginLeft float64
	// PanelSpacing is the spacing between panels.
	PanelSpacing float64
	// TickLength is the length of axis tick marks in pixels.
	TickLength float64
	// GridLineCount is the number of major grid lines (0 = auto).
	GridLineCount int
	// GridDashPattern is the dash pattern for grid lines (nil = solid).
	GridDashPattern []float64
}

Spacing controls margins and inter-element spacing.

type Theme

type Theme struct {
	// Name is the theme's display name.
	Name string

	// Palette is the discrete color cycle used when the plot has no
	// explicit color scale. May be nil; callers fall back to colormap.Tab10.
	Palette []color.Color

	// Spacing controls margins and inter-element spacing.
	Spacing Spacing

	// Geom holds default visual properties for geometry primitives.
	Geom GeomDefaults

	// Elements maps ggplot2-style dotted paths to Element values.
	// The resolver walks the inheritance chain to fill missing fields.
	Elements map[string]Element
}

Theme encapsulates the complete visual styling for a plot. Elements follow ggplot2's inheritance hierarchy, keyed by dotted path names (e.g. "text", "axis.title.x", "panel.background").

func Resolve

func Resolve(name Name) (Theme, error)

Resolve returns a Theme for the given name.

func (Theme) AnnotationText added in v0.0.4

func (t Theme) AnnotationText() ElementText

AnnotationText returns the resolved annotation text element.

func (Theme) AxisLine added in v0.0.4

func (t Theme) AxisLine() ElementLine

AxisLine returns the resolved axis line element.

func (Theme) AxisTextElem added in v0.0.4

func (t Theme) AxisTextElem() ElementText

AxisTextElem returns the resolved axis tick-label text element.

func (Theme) AxisTicks added in v0.0.4

func (t Theme) AxisTicks() ElementLine

AxisTicks returns the resolved axis ticks line element.

func (Theme) AxisTitle added in v0.0.4

func (t Theme) AxisTitle() ElementText

AxisTitle returns the resolved axis title text element.

func (Theme) AxisTitleX added in v0.0.4

func (t Theme) AxisTitleX() ElementText

AxisTitleX returns the resolved X-axis title text element.

func (Theme) AxisTitleY added in v0.0.4

func (t Theme) AxisTitleY() ElementText

AxisTitleY returns the resolved Y-axis title text element.

func (Theme) LegendBackground added in v0.0.4

func (t Theme) LegendBackground() ElementRect

LegendBackground returns the resolved legend background rect element.

func (Theme) LegendKey added in v0.0.4

func (t Theme) LegendKey() ElementRect

LegendKey returns the resolved legend key rect element.

func (Theme) LegendTextElem added in v0.0.4

func (t Theme) LegendTextElem() ElementText

LegendTextElem returns the resolved legend text element.

func (Theme) LegendTitle added in v0.0.4

func (t Theme) LegendTitle() ElementText

LegendTitle returns the resolved legend title text element.

func (Theme) PanelBackground added in v0.0.4

func (t Theme) PanelBackground() ElementRect

PanelBackground returns the resolved panel background rect element.

func (Theme) PanelBorder added in v0.0.4

func (t Theme) PanelBorder() ElementRect

PanelBorder returns the resolved panel border rect element.

func (Theme) PanelGridMajor added in v0.0.4

func (t Theme) PanelGridMajor() ElementLine

PanelGridMajor returns the resolved major grid line element.

func (Theme) PanelGridMinor added in v0.0.4

func (t Theme) PanelGridMinor() ElementLine

PanelGridMinor returns the resolved minor grid line element.

func (Theme) PlotBackground added in v0.0.4

func (t Theme) PlotBackground() ElementRect

PlotBackground returns the resolved plot background rect element.

func (Theme) PlotSubtitle added in v0.0.4

func (t Theme) PlotSubtitle() ElementText

PlotSubtitle returns the resolved plot subtitle text element.

func (Theme) PlotTitle added in v0.0.4

func (t Theme) PlotTitle() ElementText

PlotTitle returns the resolved plot title text element.

func (Theme) StripBackground added in v0.0.4

func (t Theme) StripBackground() ElementRect

StripBackground returns the resolved facet strip background rect.

func (Theme) StripText added in v0.0.4

func (t Theme) StripText() ElementText

StripText returns the resolved facet strip text element.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL