Styles

Customise the visual appearance using lipgloss styles:

styles := clog.DefaultStyles()

// Customise level colours
styles.Levels[clog.ErrorLevel] = new(
  lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("9")), // bright red
)

// Customise field key appearance
styles.KeyDefault = new(
  lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("12")), // bright blue
)

clog.SetStyles(styles)

Value Colouring

Values are styled with a three-tier priority system:

1. Key styles - style all values of a specific field key
2. Value styles - style values matching a typed key (bool true != string "true")
3. Type styles - style values by their Go type

styles := clog.DefaultStyles()

// 1. Key styles: all values of the "status" field are green
styles.Keys["status"] = new(lipgloss.NewStyle().
  Foreground(lipgloss.Color("2"))) // green

// 2. Value styles: typed key matches (bool `true` != string "true")
styles.Values["PASS"] = new(
  lipgloss.NewStyle().
  Foreground(lipgloss.Color("2")), // green
)

styles.Values["FAIL"] = new(lipgloss.NewStyle().
  Foreground(lipgloss.Color("1")), // red
)

// 3. Type styles: string values -> white, numeric values -> magenta, errors -> red by default
styles.FieldString = new(lipgloss.NewStyle().Foreground(lipgloss.Color("15")))
styles.FieldNumber = new(lipgloss.NewStyle().Foreground(lipgloss.Color("5")))
styles.FieldError  = new(lipgloss.NewStyle().Foreground(lipgloss.Color("1")))
styles.FieldString = nil  // set to nil to disable
styles.FieldNumber = nil  // set to nil to disable

clog.SetStyles(styles)

Styles Reference

Configuration

Behavioural settings are configured via setter methods on Logger (or package-level convenience functions for the Default logger):

Each Threshold pairs a minimum value with style overrides:

type ThresholdStyle struct {
  Number Style // Override for the number segment (nil = keep default).
  Unit   Style // Override for the unit segment (nil = keep default).
}

type Threshold struct {
  Value float64        // Minimum numeric value (inclusive) to trigger this style.
  Style ThresholdStyle // Style overrides for number and unit segments.
}

Thresholds are evaluated in descending order - the first match wins:

styles.QuantityThresholds["ms"] = clog.Thresholds{
  {Value: 5000, Style: clog.ThresholdStyle{Number: redStyle, Unit: redStyle}},
  {Value: 1000, Style: clog.ThresholdStyle{Number: yellowStyle, Unit: yellowStyle}},
}

Value styles only apply at Info level and above by default. Use SetFieldStyleLevel to change the threshold.

Per-Level Message Styles

Style the log message text differently for each level:

styles := clog.DefaultStyles()

styles.Messages[clog.ErrorLevel] = new(
  lipgloss.NewStyle().Foreground(lipgloss.Color("1")), // red
)

styles.Messages[clog.WarnLevel] = new(
  lipgloss.NewStyle().Foreground(lipgloss.Color("3")), // yellow
)

clog.SetStyles(styles)

Use DefaultMessageStyles() to get the defaults (unstyled for all levels).

Use DefaultValueStyles() to get the default value styles (true=green, false=red, nil=grey, ""=grey).

Use DefaultPercentGradient() to get the default red → yellow → green gradient stops used for Percent fields.

Percent Gradient Direction

By default the Percent gradient runs red (0%) → yellow (50%) → green (100%) - useful when a higher value is better (e.g. battery, health score). For metrics where a lower value is better (CPU usage, disk usage, error rate), reverse the gradient:

// Global: all Percent fields on the Default logger
clog.SetPercentReverseGradient(true)

// Per-logger: all Percent fields on this logger
logger.SetPercentReverseGradient(true)

// Per-field: just this Percent field, regardless of logger setting
clog.Info().
  Percent("cpu", 92, clog.WithPercentReverseGradient()).
  Percent("battery", 85).
  Msg("System status")
// "cpu" renders red at 92%, "battery" renders green at 85%

WithPercentReverseGradient() is a PercentOption passed directly to Event.Percent. It toggles the logger-level setting for that field - so if the logger already has the gradient reversed, WithPercentReverseGradient() flips it back to normal. This makes it easy to mix metrics with different semantics on the same log line regardless of the logger default.

Format Hooks

Override the default formatting for Elapsed and Percent fields:

// Custom elapsed format: truncate to whole seconds
clog.SetElapsedFormatFunc(func(d time.Duration) string {
  return d.Truncate(time.Second).String()
})

// Custom percent format: "75/100" instead of "75%"
clog.SetPercentFormatFunc(func(v float64) string {
  return fmt.Sprintf("%.0f/100", v)
})

When set to nil (the default), the built-in formatters are used (formatElapsed with SetElapsedPrecision for elapsed, strconv.FormatFloat with SetPercentPrecision + “%” for percent).

Field Sort Order

Control the order fields appear in log output. By default fields preserve insertion order.

// Sort fields alphabetically by key
clog.SetFieldSort(clog.SortAscending)

// Or reverse alphabetical
clog.SetFieldSort(clog.SortDescending)

clog.Info().
  Str("zoo", "animals").
  Str("alpha", "first").
  Int("count", 42).
  Msg("Sorted")
// SortNone:       INF ℹ️ Sorted zoo=animals alpha=first count=42
// SortAscending:  INF ℹ️ Sorted alpha=first count=42 zoo=animals
// SortDescending: INF ℹ️ Sorted zoo=animals count=42 alpha=first

Renderer Binding

Styles created with lipgloss.NewStyle() are bound to the global renderer (anchored to os.Stdout). When stdout is piped, that renderer detects Ascii profile and all colours are silently stripped - even for styles meant for stderr.

clog handles this automatically: New, SetStyles, SetOutput, and SetColorMode all call WithRenderer to rebind styles to the logger’s output renderer. Custom styles passed to SetStyles are transparently rebound - no changes needed in user code.

For advanced use, Styles and JSONStyles expose WithRenderer(*lipgloss.Renderer):

styles := clog.DefaultStyles()
styles.WithRenderer(output.Renderer())

Both methods mutate and return the receiver for fluent chaining.