theme

package
v0.7.17 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultEnvPrefix = "CLIB"

DefaultEnvPrefix is the default environment variable prefix.

Variables

This section is empty.

Functions

func Names 

func Names() []string

Names returns the built-in theme names accepted by Theme.UnmarshalText.

func SetEnvPrefix 

func SetEnvPrefix(prefix string)

SetEnvPrefix sets a custom environment variable prefix. 

theme.SetEnvPrefix("MYAPP")
// Now checks MYAPP_THEME_LIGHT/MYAPP_THEME_DARK first, then CLIB_THEME_LIGHT/CLIB_THEME_DARK

Types

type Background 

type Background int

Background describes the terminal background a theme is designed for. 

const (
	BackgroundUnspecified Background = iota
	BackgroundLight
	BackgroundDark
)

func DetectBackground 

func DetectBackground() (Background, bool)

DetectBackground queries the controlling terminal for its background color.

func (Background) String 

func (b Background) String() string

type EnumStyle 

type EnumStyle int

EnumStyle controls how enum values are rendered in help output. 

const (
	EnumStylePlain            EnumStyle = iota // [open, closed, merged, all] - all dim
	EnumStyleHighlightDefault                  // [auto, always, never] - default value highlighted
	EnumStyleHighlightPrefix                   // [open, closed, merged, all] - bold hints highlighted
	EnumStyleHighlightBoth                     // bold hints + default value highlighted
)

type EnumValue 

type EnumValue struct {
	Name      string
	Bold      string
	IsDefault bool
}

EnumValue represents a single enum option for help display. Bold is the substring to highlight within Name (first occurrence). If Bold is empty, the entire Name renders as dim with no bold prefix. IsDefault marks this value as the default (rendered with HelpEnumDefault style).

type HelpUsageExampleStyle 

type HelpUsageExampleStyle struct {
	Prompt       string         // Prefix string shown before commands (default "$").
	PromptStyle  lipgloss.Style // Style applied to the prompt.
	CommandStyle lipgloss.Style // Style applied to the command text.
}

HelpUsageExampleStyle controls the rendering of examples in the "Examples" help section (the "$ command" lines).

type Option 

type Option func(*Theme)

Option configures a Theme.

func WithBlue 

func WithBlue(s lipgloss.Style) Option

WithBlue sets the blue color style.

func WithBold 

func WithBold(s lipgloss.Style) Option

WithBold sets the bold style.

func WithBoldGreen 

func WithBoldGreen(s lipgloss.Style) Option

WithBoldGreen sets the bold green color style.

func WithDim 

func WithDim(s lipgloss.Style) Option

WithDim sets the dim (faint) style.

func WithEntityColors 

func WithEntityColors(c ...color.Color) Option

WithEntityColors sets the color palette for entity colorization.

func WithEnumStyle 

func WithEnumStyle(s EnumStyle) Option

WithEnumStyle sets how enum values are rendered in help output.

func WithGreen 

func WithGreen(s lipgloss.Style) Option

WithGreen sets the green color style.

func WithHelpAlias 

func WithHelpAlias(s lipgloss.Style) Option

WithHelpAlias sets the style for alias names in the Aliases section. When unset, command aliases use the HelpSubcommand style.

func WithHelpArg 

func WithHelpArg(s lipgloss.Style) Option

WithHelpArg sets the style for argument names in help output.

func WithHelpArgOptional 

func WithHelpArgOptional(s lipgloss.Style) Option

WithHelpArgOptional sets the style for optional argument names in help output when they coexist with required arguments.

func WithHelpBoldDim 

func WithHelpBoldDim(s lipgloss.Style) Option

WithHelpBoldDim sets the bold-dim style used in help output.

func WithHelpCommand 

func WithHelpCommand(s lipgloss.Style) Option

WithHelpCommand sets the style for command names in help output.

func WithHelpDefaultChars 

func WithHelpDefaultChars(openChar, closeChar rune) Option

WithHelpDefaultChars overrides the bracket characters used to wrap [default: X] annotations in help output. Defaults to '[' and ']'. Useful for callers who prefer e.g. (default: X).

func WithHelpDescBacktick 

func WithHelpDescBacktick(s lipgloss.Style) Option

WithHelpDescBacktick sets the style for backtick-enclosed text in flag descriptions.

func WithHelpDescList added in v0.6.0 

func WithHelpDescList(s lipgloss.Style) Option

WithHelpDescList sets the fallback marker style for lists auto-detected in a Description blurb, used when no marker-specific style (numbered/bullet) applies.

func WithHelpDescNumberedList added in v0.6.0 

func WithHelpDescNumberedList(s lipgloss.Style) Option

WithHelpDescNumberedList sets the style applied to the marker ("1.", "2)") of a numbered list auto-detected in a Description blurb. Passing a zero style still overrides the fallback; leave it nil on the theme to fall back to WithHelpDescList.

func WithHelpDescUnorderedList added in v0.6.0 

func WithHelpDescUnorderedList(s lipgloss.Style) Option

WithHelpDescUnorderedList sets the style applied to the marker of an unordered list auto-detected in a Description blurb, falling back to WithHelpDescList when left nil on the theme.

func WithHelpDescUnorderedListChars added in v0.6.0 

func WithHelpDescUnorderedListChars(chars ...string) Option

WithHelpDescUnorderedListChars sets the glyphs that unordered list markers ("-", "*", "+") are normalised to in Description blurbs, cycled by nesting depth (default "•", "◦", "▪" - the same progression GitHub-flavoured Markdown uses). Pass no arguments to leave each author's original marker character unchanged.

func WithHelpDim 

func WithHelpDim(s lipgloss.Style) Option

WithHelpDim sets the dim style used in help output.

func WithHelpEnumDefault 

func WithHelpEnumDefault(s lipgloss.Style) Option

WithHelpEnumDefault sets the style for the default value in enum lists.

func WithHelpExampleChars 

func WithHelpExampleChars(openChar, closeChar rune) Option

WithHelpExampleChars overrides the bracket characters used to wrap [example: X] annotations in help output. Defaults to '[' and ']'.

func WithHelpFlag 

func WithHelpFlag(s lipgloss.Style) Option

WithHelpFlag sets the style for flag names in help output.

func WithHelpFlagBacktick 

func WithHelpFlagBacktick(s lipgloss.Style) Option

WithHelpFlagBacktick sets the style for backtick-enclosed flag-like text in flag descriptions.

func WithHelpFlagDefault 

func WithHelpFlagDefault(s lipgloss.Style) Option

WithHelpFlagDefault sets the style for flag default annotations in help output.

func WithHelpFlagExample 

func WithHelpFlagExample(s lipgloss.Style) Option

WithHelpFlagExample sets the style for flag example annotations in help output.

func WithHelpFlagNote 

func WithHelpFlagNote(s lipgloss.Style) Option

WithHelpFlagNote sets the style for trailing flag notes in help output.

func WithHelpKeyValueSeparator 

func WithHelpKeyValueSeparator(sep rune) Option

WithHelpKeyValueSeparator sets the separator rune between flag and placeholder.

func WithHelpKeyValueSeparatorStyle 

func WithHelpKeyValueSeparatorStyle(s lipgloss.Style) Option

WithHelpKeyValueSeparatorStyle sets the style for the flag-placeholder separator.

func WithHelpPlaceholder 

func WithHelpPlaceholder(s lipgloss.Style) Option

WithHelpPlaceholder sets the style for value placeholders in help output.

func WithHelpRepeatEllipsis 

func WithHelpRepeatEllipsis(s lipgloss.Style) Option

WithHelpRepeatEllipsis sets the style for the repeat ellipsis on repeatable flags.

func WithHelpRepeatEllipsisEnabled 

func WithHelpRepeatEllipsisEnabled(enabled bool) Option

WithHelpRepeatEllipsisEnabled sets whether repeatable flag placeholders show an ellipsis.

func WithHelpSection 

func WithHelpSection(s lipgloss.Style) Option

WithHelpSection sets the style for help section headers.

func WithHelpSubcommand 

func WithHelpSubcommand(s lipgloss.Style) Option

WithHelpSubcommand sets the style for subcommand names in help output.

func WithHelpUsageExample 

func WithHelpUsageExample(s HelpUsageExampleStyle) Option

WithHelpUsageExample sets the style for usage examples in help output.

func WithMagenta 

func WithMagenta(s lipgloss.Style) Option

WithMagenta sets the magenta color style.

func WithMarkdownCode 

func WithMarkdownCode(s lipgloss.Style) Option

WithMarkdownCode sets the style for inline code in markdown rendering.

func WithMarkdownText 

func WithMarkdownText(s lipgloss.Style) Option

WithMarkdownText sets the style for plain text in markdown rendering.

func WithOrange 

func WithOrange(s lipgloss.Style) Option

WithOrange sets the orange color style.

func WithRed 

func WithRed(s lipgloss.Style) Option

WithRed sets the red color style.

func WithTimeAgoThresholds 

func WithTimeAgoThresholds(th []TimeAgoThreshold) Option

WithTimeAgoThresholds sets the time-ago color thresholds.

func WithTrueColor added in v0.7.9 

func WithTrueColor() Option

WithTrueColor replaces the entity color palette with 32 curated 24-bit colors, every pair visually distinct - use when entities outnumber the default ANSI-256 palette. The palette adapts to the theme's Background, so apply this option to a preset (which sets Background first). The caller is responsible for ensuring the terminal supports true color.

func WithYellow 

func WithYellow(s lipgloss.Style) Option

WithYellow sets the yellow color style.

type Pair 

type Pair struct {
	Light    *Theme
	Dark     *Theme
	Fallback Background
}

Pair holds the light and dark themes an application supports.

func DefaultPair 

func DefaultPair(opts ...PairOption) *Pair

DefaultPair returns clib's built-in light/dark theme pair.

func MustPair 

func MustPair(light, dark *Theme, opts ...PairOption) *Pair

MustPair creates a theme pair and panics if it is invalid.

func NewPair 

func NewPair(light, dark *Theme, opts ...PairOption) (*Pair, error)

NewPair creates a theme pair with one light theme and one dark theme.

func PairFromEnv 

func PairFromEnv(opts ...PairOption) (*Pair, error)

PairFromEnv builds a theme pair from <PREFIX>_THEME_LIGHT and <PREFIX>_THEME_DARK.

func (*Pair) Auto 

func (p *Pair) Auto() *Theme

Auto selects from the pair using the terminal background, falling back to the pair's Fallback when detection is unavailable.

func (*Pair) ForBackground 

func (p *Pair) ForBackground(bg Background) *Theme

ForBackground returns the theme matching bg.

type PairOption 

type PairOption func(*Pair)

PairOption configures a theme Pair.

func WithFallback 

func WithFallback(bg Background) PairOption

WithFallback sets the background used when terminal detection is unavailable.

type Theme 

type Theme struct {

	// Background declares the terminal background this theme is designed for.
	Background Background

	// Base styles.
	Bold *lipgloss.Style
	Dim  *lipgloss.Style

	// Semantic color styles.
	Red       *lipgloss.Style
	Green     *lipgloss.Style
	Yellow    *lipgloss.Style
	Blue      *lipgloss.Style
	Magenta   *lipgloss.Style
	Orange    *lipgloss.Style
	BoldGreen *lipgloss.Style

	// Help styles.
	HelpAlias                  *lipgloss.Style
	HelpArg                    *lipgloss.Style
	HelpArgOptional            *lipgloss.Style
	HelpBoldDim                *lipgloss.Style
	HelpCommand                *lipgloss.Style
	HelpDescBacktick           *lipgloss.Style // Backtick-enclosed text in flag descriptions (nil = leave backticks intact).
	HelpDescList               *lipgloss.Style // Fallback marker style for any list detected in a Description (nil = unstyled).
	HelpDescNumberedList       *lipgloss.Style // Marker ("1.", "2)") of a numbered list (nil = fall back to HelpDescList; default: bold).
	HelpDescUnorderedList      *lipgloss.Style // Marker of an unordered list (nil = fall back to HelpDescList).
	HelpDescUnorderedListChars []string        // Glyphs unordered markers are normalised to, cycled by nesting depth (default "•","◦","▪"; empty = keep author's char).
	HelpDim                    *lipgloss.Style
	HelpEnumDefault            *lipgloss.Style // Default value in EnumStyleHighlightDefault lists (default: dim green).
	HelpFlag                   *lipgloss.Style
	HelpFlagBacktick           *lipgloss.Style // Override for backtick-enclosed flag-like text in descriptions (nil = fall back to HelpFlag).
	HelpDefaultOpen            string          // Opening bracket for default-value annotations (default "(", e.g. "(default: X)").
	HelpDefaultClose           string          // Closing bracket for default-value annotations (default ")").
	HelpExampleOpen            string          // Opening bracket for example annotations (default "(", e.g. "(example: X)").
	HelpExampleClose           string          // Closing bracket for example annotations (default ")").
	HelpFlagDefault            *lipgloss.Style // [default: ...] annotations in flag descriptions.
	HelpFlagExample            *lipgloss.Style // [example: ...] annotations in flag descriptions.
	HelpFlagNote               *lipgloss.Style // Trailing (...) notes in flag descriptions.
	HelpKeyValueSeparator      rune            // Separator between flag and placeholder (default: ' ').
	HelpKeyValueSeparatorStyle *lipgloss.Style // Style applied to the separator (default: nil = unstyled).
	HelpRepeatEllipsis         *lipgloss.Style // "…" suffix on repeatable flag placeholders (default: dim red).
	HelpRepeatEllipsisEnabled  bool            // Whether to show "…" suffix on repeatable placeholders (default: true).
	HelpSection                *lipgloss.Style
	HelpSubcommand             *lipgloss.Style
	HelpUsageExample           HelpUsageExampleStyle // Examples section prompt and command styling.
	HelpValuePlaceholder       *lipgloss.Style
	EnumStyle                  EnumStyle // How enum values are rendered in help output.

	// Markdown styles.
	MarkdownCode *lipgloss.Style
	MarkdownText *lipgloss.Style

	// Time-ago thresholds (ordered by MaxAge ascending).
	TimeAgoThresholds []TimeAgoThreshold

	// Entity color palette for unique entity colorization.
	EntityColors []color.Color
	// contains filtered or unexported fields
}

Theme holds all style definitions for CLI output. All lipgloss.Style fields are pointers so that nil means "not configured". Use a preset to construct a Theme, or [Init] to fill nil fields on an existing theme.

func Auto 

func Auto() *Theme

Auto selects from clib's built-in themes using the terminal background.

func CatppuccinFrappe 

func CatppuccinFrappe() *Theme

CatppuccinFrappe returns a theme based on the Catppuccin Frappé (dark) palette.

func CatppuccinLatte 

func CatppuccinLatte() *Theme

CatppuccinLatte returns a theme based on the Catppuccin Latte (light) palette.

func CatppuccinMacchiato 

func CatppuccinMacchiato() *Theme

CatppuccinMacchiato returns a theme based on the Catppuccin Macchiato (dark) palette.

func CatppuccinMocha 

func CatppuccinMocha() *Theme

CatppuccinMocha returns a theme based on the Catppuccin Mocha (dark) palette.

func Dark 

func Dark() *Theme

Dark returns clib's default dark-background theme.

func Dracula 

func Dracula() *Theme

Dracula returns a theme based on the Dracula color scheme.

func GruvboxDark 

func GruvboxDark() *Theme

GruvboxDark returns a theme based on the Gruvbox Dark color scheme.

func GruvboxLight 

func GruvboxLight() *Theme

GruvboxLight returns a theme based on the Gruvbox Light color scheme.

func Light 

func Light() *Theme

Light returns clib's default light-background theme.

The help styles come from the light palette, but the semantic color slots (Red/Green/Yellow/Blue/Magenta/Orange/BoldGreen) and the time-ago gradient are set explicitly so they faithfully mirror Dark's meaning with light-background contrast. Deriving them from the help palette would scramble semantics (e.g. Green would render as the palette's blue "arg" color).

func Monochrome 

func Monochrome(background Background) *Theme

Monochrome returns a theme with no colors - only bold and dim.

func Monokai 

func Monokai() *Theme

Monokai returns a theme inspired by the Monokai color scheme.

func Nord 

func Nord() *Theme

Nord returns a theme based on the Nord Arctic color scheme.

func OneDark 

func OneDark() *Theme

OneDark returns a theme based on the Atom One Dark color scheme.

func Plain 

func Plain(background Background) *Theme

Plain returns a theme with no styling at all.

func SolarizedDark 

func SolarizedDark() *Theme

SolarizedDark returns a theme based on the Solarized dark color scheme.

func SolarizedLight 

func SolarizedLight() *Theme

SolarizedLight returns a theme based on the Solarized light color scheme.

func Synthwave 

func Synthwave() *Theme

Synthwave returns a theme based on the Synthwave '84 color scheme.

func TokyoNight 

func TokyoNight() *Theme

TokyoNight returns a theme based on the Tokyo Night color scheme.

func (*Theme) DimDefault 

func (th *Theme) DimDefault(value string) string

DimDefault formats a default value annotation as " [default: X]" (with a leading space). The bracket characters are taken from HelpDefaultOpen and HelpDefaultClose. Returns the empty string if value is empty.

func (*Theme) DimNote 

func (th *Theme) DimNote(text string) string

DimNote formats a parenthetical note in dim.

func (*Theme) EntityColor 

func (th *Theme) EntityColor(text string) color.Color

EntityColor returns a stable theme color for text.

func (*Theme) EntityStyle 

func (th *Theme) EntityStyle(text string) lipgloss.Style

EntityStyle returns a foreground style using Theme.EntityColor.

func (*Theme) FmtDefaultAnnotation 

func (th *Theme) FmtDefaultAnnotation(value string) string

FmtDefaultAnnotation renders a leading-space "[default: X]" annotation using the theme's HelpDefaultOpen/Close brackets and HelpFlagDefault style.

func (*Theme) FmtEnum 

func (th *Theme) FmtEnum(values []EnumValue) string

FmtEnum formats an enum list with bold shortcut substrings inside dim brackets. e.g. FmtEnum([]EnumValue{{Name: "open", Bold: "o"}, {Name: "closed", Bold: "c"}}) renders as dim("[") + boldDim("o") + dim("pen, ") + boldDim("c") + dim("losed]").

func (*Theme) FmtEnumDefault 

func (th *Theme) FmtEnumDefault(defaultVal string, values []EnumValue) string

FmtEnumDefault formats an enum list followed by a default annotation rendered as "[default: X]" (brackets configurable via HelpDefaultOpen/Close).

func (*Theme) Init 

func (t *Theme) Init() *Theme

Init returns a copy of t with nil styles replaced by zero-value styles and structural defaults filled in so zero-value themes remain usable.

func (*Theme) MarshalText 

func (t *Theme) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Theme) RenderEntity 

func (th *Theme) RenderEntity(text string) string

RenderEntity renders text with its stable theme entity color.

func (*Theme) RenderMarkdown 

func (th *Theme) RenderMarkdown(text string) string

RenderMarkdown renders a short markdown string for inline display. Handles inline code spans with themed colors.

func (*Theme) RenderTimeAgo 

func (th *Theme) RenderTimeAgo(t time.Time, tty bool) string

RenderTimeAgo formats a time as a colored relative string using the theme's TimeAgoThresholds. When tty is false, returns plain text.

func (*Theme) RenderTimeAgoCompact 

func (th *Theme) RenderTimeAgoCompact(t time.Time, tty bool) string

RenderTimeAgoCompact formats a time as a compact colored relative string (e.g. "15m ago" instead of "15 minutes ago").

func (*Theme) String 

func (t *Theme) String() string

String returns the preset name for built-in themes, or "custom" for themes that were modified programmatically.

func (*Theme) UnmarshalText 

func (t *Theme) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (*Theme) With 

func (t *Theme) With(opts ...Option) *Theme

With returns a copy of t with the given options applied.

type TimeAgoThreshold 

type TimeAgoThreshold struct {
	MaxAge time.Duration
	Style  lipgloss.Style
}

TimeAgoThreshold defines a coloring threshold for time-ago rendering. Thresholds are evaluated in order; the first one where the duration is less than MaxAge wins. Entries beyond the last threshold use the theme's Red style as a fallback.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.