ui

package
v1.223.0-rc.11 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Badge added in v1.205.0 

func Badge(text, background, foreground string) string

Badge returns a styled badge with the given text, background color, and foreground color. Badges are compact labels with background styling, typically used for status indicators. The background and foreground should be hex colors (e.g., "#FF9800", "#000000"). Use this when you need the formatted string without writing (e.g., in help text).

func ClearLine added in v1.200.0 

func ClearLine()

ClearLine clears the current line in the terminal and returns cursor to the beginning. Respects NO_COLOR and terminal capabilities - uses ANSI escape sequences only when supported. When colors are disabled, only writes carriage return to move cursor to start of line. This is useful for replacing spinner messages or other dynamic output with final status messages. Flow: ui.ClearLine() → ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

Example usage: 

ui.ClearLine()
ui.Success("Operation completed successfully")

func Error 

func Error(text string)

Error writes an error message with red X to stderr (UI channel). Flow: ui.Error() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Errorf 

func Errorf(format string, a ...interface{})

Errorf writes a formatted error message with red X to stderr (UI channel). Flow: ui.Errorf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Experimental added in v1.205.0 

func Experimental(feature string)

Experimental writes an experimental feature notification with test tube icon to stderr (UI channel). This is used to notify users when they're using an experimental feature that may change. The notification behavior is controlled by settings.experimental in atmos.yaml (silence, disable, warn, error). The caller (root.go PersistentPreRun) handles the config check - this function just outputs. Flow: ui.Experimental() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Experimentalf added in v1.205.0 

func Experimentalf(format string, a ...interface{})

Experimentalf writes a formatted experimental feature notification with test tube icon to stderr (UI channel). Flow: ui.Experimentalf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func FormatColumns added in v1.223.0 

func FormatColumns(items []string, width int) string

FormatColumns lays out items in evenly spaced, left-aligned columns sized to fit width, filling top-to-bottom then left-to-right (the same order `ls` uses for a terminal listing), instead of a single comma-separated line that wraps unpredictably and can break mid-word. Every column is the same width (the longest item plus a small gap); only the last column may be shorter than the others when items don't divide evenly. Returns "" for an empty items slice.

func FormatComponentLabel added in v1.222.0 

func FormatComponentLabel(name string, index int) string

FormatComponentLabel renders a short colored badge for a per-item label (e.g. a container log prefix), cycling background colors by index so each item gets a distinct, stable color in the log-level label style. When color is unsupported (non-TTY, NO_COLOR, dumb terminal) it degrades to a plain `[name]` label so output stays readable in pipes and CI.

func FormatError added in v1.203.0 

func FormatError(text string) string

FormatError returns an error message with red X as a formatted string. Use this when you need the formatted string without writing (e.g., in bubbletea views).

func FormatExperimentalBadge added in v1.205.0 

func FormatExperimentalBadge() string

FormatExperimentalBadge returns an "EXPERIMENTAL" badge using theme colors. Use this to indicate experimental features in help text or command descriptions.

func FormatInline added in v1.205.0 

func FormatInline(text string) string

FormatInline renders inline markdown (backticks, bold, etc.) without icons or newlines. Use this for spinner progress messages or other single-line styled text.

func FormatSuccess added in v1.203.0 

func FormatSuccess(text string) string

FormatSuccess returns a success message with green checkmark as a formatted string. Use this when you need the formatted string without writing (e.g., in bubbletea views).

func GetColorProfile added in v1.205.0 

func GetColorProfile() termenv.Profile

GetColorProfile returns the configured termenv color profile. Use this instead of termenv.ColorProfile() to respect atmos's terminal detection. This ensures colors degrade gracefully in terminals that don't support TrueColor (like macOS Terminal.app which only supports 256 colors until macOS Tahoe).

The returned profile respects:

  • --force-color flag (returns TrueColor for screenshot generation).
  • --no-color / NO_COLOR env var (returns Ascii).
  • Terminal capabilities detected via COLORTERM env var.

Example usage. 

profile := ui.GetColorProfile()
glamour.WithColorProfile(profile)

func Hint added in v1.203.0 

func Hint(text string)

Hint writes a hint/tip message with lightbulb icon to stderr (UI channel). This is a convenience wrapper with themed hint icon and muted color. Flow: ui.Hint() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Hintf added in v1.203.0 

func Hintf(format string, a ...interface{})

Hintf writes a formatted hint/tip message with lightbulb icon to stderr (UI channel). This is a convenience wrapper with themed hint icon and muted color. Flow: ui.Hintf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Info 

func Info(text string)

Info writes an info message with cyan info icon to stderr (UI channel). Flow: ui.Info() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Infof 

func Infof(format string, a ...interface{})

Infof writes a formatted info message with cyan info icon to stderr (UI channel). Flow: ui.Infof() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func InitFormatter 

func InitFormatter(ioCtx io.Context)

InitFormatter initializes the global formatter with an I/O context. This should be called once at application startup (in root.go).

func Markdown 

func Markdown(content string)

Markdown writes rendered markdown to stdout (data channel). Use this for help text, documentation, and other pipeable formatted content. Note: Delegates to globalFormatter.Markdown() for rendering, then writes to data channel. Write errors are logged but not returned since callers cannot meaningfully handle them.

func MarkdownMessage 

func MarkdownMessage(content string)

MarkdownMessage writes rendered markdown to stderr (UI channel). Use this for formatted UI messages and errors. Write errors are logged but not returned since callers cannot meaningfully handle them.

func MarkdownMessageNoWrap added in v1.223.0 

func MarkdownMessageNoWrap(content string)

MarkdownMessageNoWrap writes rendered markdown to stderr (UI channel) without word-wrapping long lines. Use for deterministic, snapshot-stable single-line notices where wrapping would otherwise vary by terminal width. Write errors are logged but not returned since callers cannot meaningfully handle them.

func MarkdownMessageNoWrapf added in v1.223.0 

func MarkdownMessageNoWrapf(format string, a ...interface{})

MarkdownMessageNoWrapf writes formatted markdown to stderr (UI channel) without word-wrapping.

func MarkdownMessagef 

func MarkdownMessagef(format string, a ...interface{})

MarkdownMessagef writes formatted markdown to stderr (UI channel).

func Markdownf 

func Markdownf(format string, a ...interface{})

Markdownf writes formatted markdown to stdout (data channel).

func NewRenderer added in v1.223.0 

func NewRenderer(w stdio.Writer) *lipgloss.Renderer

NewRenderer returns a lipgloss renderer bound to w that uses the globally detected color profile (terminal detection plus force flags) with a dark background assumed. Use this instead of lipgloss.NewRenderer so per-writer renderers share the single Atmos color-detection pipeline instead of re-detecting capabilities from the writer (which degrades to 16 colors on pipes and breaks the --force-color TrueColor contract).

func ReinitFormatter added in v1.210.0 

func ReinitFormatter()

ReinitFormatter re-creates the global formatter with a fresh I/O context. This is needed after output capture (os.Pipe) is stopped, because the original InitFormatter() ran while pipes were active — terminal detection saw pipes instead of the real terminal and cached ColorNone. After capture restores os.Stdout/os.Stderr, calling ReinitFormatter() re-detects the real terminal and restores color support.

func Reset added in v1.203.0 

func Reset()

Reset clears all UI globals (formatter, I/O, terminal). This is primarily used in tests to ensure clean state between test executions.

func SetColorProfile added in v1.200.0 

func SetColorProfile(profile termenv.Profile)

SetColorProfile sets the color profile for all UI systems (lipgloss, theme, logger). This is primarily intended for testing when environment variables are set after package initialization. For normal operation, color profiles are automatically configured during InitFormatter() based on terminal capabilities.

Example usage in tests: 

t.Setenv("NO_COLOR", "1")
ui.SetColorProfile(termenv.Ascii)

func Success 

func Success(text string)

Success writes a success message with green checkmark to stderr (UI channel). Flow: ui.Success() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Successf 

func Successf(format string, a ...interface{})

Successf writes a formatted success message with green checkmark to stderr (UI channel). Flow: ui.Successf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func TerminalWidth added in v1.223.0 

func TerminalWidth() int

TerminalWidth returns the stdout width from the global terminal detection: the real TTY size when available, or 0 when unknown (non-TTY streams ignore COLUMNS so CI snapshots and piped output keep stable wrapping; callers apply their own defaults). Returns 0 when the formatter has not been initialized.

func Toast added in v1.199.0 

func Toast(icon, message string)

Toast writes a toast message with custom icon to stderr (UI channel). Flow: ui.Toast() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Toastf added in v1.199.0 

func Toastf(icon, format string, a ...interface{})

Toastf writes a formatted toast message with custom icon to stderr (UI channel). Flow: ui.Toastf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Warning 

func Warning(text string)

Warning writes a warning message with yellow warning sign to stderr (UI channel). Flow: ui.Warning() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Warningf 

func Warningf(format string, a ...interface{})

Warningf writes a formatted warning message with yellow warning sign to stderr (UI channel). Flow: ui.Warningf() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Write 

func Write(text string)

Write writes plain text to stderr (UI channel) without icons or automatic styling. Flow: ui.Write() → terminal.Write() → io.Write(UIStream) → masking → stderr. Write errors are logged but not returned since callers cannot meaningfully handle them.

func Writef 

func Writef(format string, a ...interface{})

Writef writes formatted text to stderr (UI channel) without icons or automatic styling. Flow: ui.Writef() → terminal.Write() → io.Write(UIStream) → masking → stderr.

func Writeln 

func Writeln(text string)

Writeln writes text followed by a newline to stderr (UI channel) without icons or automatic styling. Flow: ui.Writeln() → terminal.Write() → io.Write(UIStream) → masking → stderr.

Types

type Formatter 

type Formatter interface {
	// Toast formatting - flexible toast notifications with custom icons and multiline support
	// Automatically handles newlines with proper indentation
	Toast(icon, message string) string                   // Returns "{icon} {message}" with multiline support
	Toastf(icon, format string, a ...interface{}) string // Returns formatted toast

	// Status message formatting - standardized output with icons
	// This is the foundational method used by Success/Error/Warning/Info
	StatusMessage(icon string, style *lipgloss.Style, text string) string

	// Semantic formatting - returns styled strings with automatic icons (uses theme.StyleSet)
	// These methods use Toast internally with predefined icons and colors
	Success(text string) string                      // Returns "✓ {text}" in green
	Successf(format string, a ...interface{}) string // Returns "✓ {formatted}" in green
	Warning(text string) string                      // Returns "⚠ {text}" in yellow
	Warningf(format string, a ...interface{}) string // Returns "⚠ {formatted}" in yellow
	Error(text string) string                        // Returns "✗ {text}" in red
	Errorf(format string, a ...interface{}) string   // Returns "✗ {formatted}" in red
	Info(text string) string                         // Returns "▶ {text}" in cyan.
	Infof(format string, a ...interface{}) string    // Returns "▶ {formatted}" in cyan.
	Hint(text string) string                         // Returns "💡 {text}" in muted color
	Hintf(format string, a ...interface{}) string    // Returns "💡 {formatted}" in muted color
	Muted(text string) string                        // Returns muted text (gray, no icon)

	// Text formatting - returns styled strings
	Bold(text string) string    // Returns bold text
	Heading(text string) string // Returns heading-styled text
	Label(text string) string   // Returns label-styled text

	// Theme access
	Styles() *theme.StyleSet // Access to full theme-aware StyleSet

	// Capability queries (delegates to terminal.Terminal)
	ColorProfile() terminal.ColorProfile
	SupportsColor() bool

	// Markdown rendering - returns rendered markdown string (pure function, no I/O)
	// For writing markdown to channels, use package-level ui.Markdown() or ui.MarkdownMessage()
	Markdown(content string) (string, error)

	// MarkdownNoWrap renders markdown without word-wrapping long lines, for
	// deterministic, snapshot-stable single-line notices. For writing to
	// channels, use package-level ui.MarkdownMessageNoWrap().
	MarkdownNoWrap(content string) (string, error)
}

Formatter provides text formatting with automatic degradation. Key Principle: Formatter RETURNS FORMATTED STRINGS - it never writes to streams.

Usage Pattern: 

io := cmd.Context().Value(ioContextKey).(io.Context)
ui := cmd.Context().Value(uiFormatterKey).(ui.Formatter)

// Format text with automatic icons
msg := ui.Success("Deployment complete!")  // Returns "✓ Deployment complete!" in green

// Developer chooses channel
fmt.Fprintf(io.UI(), "%s\n", msg)  // UI message → stderr

Uses io.Terminal for capability detection and theme.StyleSet for styling. 

var Format Formatter

Format exposes the global formatter for advanced use cases. Most code should use the package-level functions (ui.Success, ui.Error, etc.). Use this when you need the formatted string without writing it.

func NewFormatter 

func NewFormatter(ioCtx io.Context, term terminal.Terminal) Formatter

NewFormatter creates a new Formatter with I/O context and terminal. Most code should use the package-level functions instead (ui.Markdown, ui.Success, etc.).

Source Files

View all Source files

Directories

Path Synopsis
Package markdown provides custom markdown rendering with extended syntax support.
 Package markdown provides custom markdown rendering with extended syntax support.
extensions
Package extensions provides custom goldmark extensions for enhanced markdown syntax.
 Package extensions provides custom goldmark extensions for enhanced markdown syntax.
fps
Package fps centralizes the optional spinner redraw-rate override so every spinner in Atmos honors a single control.
 Package fps centralizes the optional spinner redraw-rate override so every spinner in Atmos honors a single control.

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.