Struct Context 

pub struct Context { /* private fields */ }

The main rendering context passed to your closure each frame.

Provides all methods for building UI: text, containers, widgets, and event handling. You receive a &mut Context on every frame and describe what to render by calling its methods. SLT collects those calls, lays them out with flexbox, diffs against the previous frame, and flushes only changed cells.

Example

slt::run(|ui: &mut slt::Context| {
    if ui.key('q') { ui.quit(); }
    ui.text("Hello, world!").bold();
});

Implementations

impl Context

pub fn gauge(&mut self, ratio: f64) -> Gauge<'_>

Begin building a block-fill progress bar with optional centered label.

ratio is clamped to 0.0..=1.0. The returned Gauge auto-renders when dropped, so a bare ui.gauge(0.5); produces a default-width bar. Chain .label(...), .width(...), or .color(...) to customize. Call .show() (instead of dropping) to capture a GaugeResponse.

Color tiers follow theme colors: success below 50%, warning 50–80%, error at or above 80%. Override per-call with .color(...).

Example

ui.gauge(0.6).label("60%");
let r = ui.gauge(0.42).label("CPU").width(48).show();
if r.hovered { /* attach tooltip */ }

pub fn line_gauge(&mut self, ratio: f64) -> LineGauge<'_>

Begin building a single-line gauge with configurable fill/empty chars.

ratio is clamped to 0.0..=1.0. Chain .label(...), .width(...), .filled(...), .empty(...) to customize. Auto-renders on Drop; call .show() to capture a GaugeResponse.

Example

ui.line_gauge(0.6).label("60%").width(24);
ui.line_gauge(0.78).label("Memory").width(48).filled('━');

impl Context

pub fn scrollable_with_gutter<G, F>( &mut self, state: &mut ScrollState, opts: GutterOpts<G>, f: F, ) -> GutterResponse

where G: Fn(usize) -> String, F: FnMut(&mut Context, usize),

Scrollable column with a left gutter rendered per visible line.

state is the active scroll state. opts carries total_lines, viewport_height, and the gutter labeling closure (use GutterOpts::line_numbers for the common case). body_fn is invoked for each visible line and renders that line’s content. Highlighted lines (set via ScrollState::set_highlights) receive an accent background.

Returns a GutterResponse with the current highlight index and total highlight count for callers wiring up n / N search-result navigation keys.

Example

let r = ui.scrollable_with_gutter(
    &mut scroll,
    GutterOpts::line_numbers(lines.len(), 10),
    |ui, abs_line| {
        if let Some(line) = lines.get(abs_line) {
            ui.text(*line);
        }
    },
);
if let Some(i) = r.current_highlight {
    // show "match i of N" status
}

impl Context

pub fn separator(&mut self) -> &mut Self

Render a horizontal divider line.

The line is drawn with the theme’s border color and expands to fill the container width.

pub fn separator_colored(&mut self, color: Color) -> &mut Self

Render a horizontal separator line with a custom color.

pub fn screen( &mut self, name: &str, screens: &mut ScreenState, f: impl FnOnce(&mut Context), )

Conditionally render content when the named screen is active.

Each screen gets an isolated hook segment — use_state / use_memo calls inside one screen do not interfere with another screen’s hooks, even when you switch between screens across frames.

Focus state is saved and restored per screen automatically.

Example

ui.screen("main", &mut screens, |ui| {
    ui.text("Main screen");
});

pub fn col(&mut self, f: impl FnOnce(&mut Context)) -> Response

Create a vertical (column) container.

Children are stacked top-to-bottom. Returns a Response with click/hover state for the container area.

Example

ui.col(|ui| {
    ui.text("line one");
    ui.text("line two");
});

pub fn col_gap(&mut self, gap: u32, f: impl FnOnce(&mut Context)) -> Response

👎Deprecated since 0.20.1:

Use ui.container().gap(n).col(f) instead — same output, no name collision with ContainerBuilder::col_gap.

Create a vertical (column) container with a gap between children.

gap is the number of blank rows inserted between each child.

Deprecated since 0.20.1: the name collides with ContainerBuilder::col_gap, which sets the row-finalize main-axis gap (Tailwind gap-x axis convention) and so means the opposite thing. Use ui.container().gap(n).col(f) instead — same output, no collision.

pub fn row(&mut self, f: impl FnOnce(&mut Context)) -> Response

Create a horizontal (row) container.

Children are placed left-to-right. Returns a Response with click/hover state for the container area.

Example

ui.row(|ui| {
    ui.text("left");
    ui.spacer();
    ui.text("right");
});

pub fn row_gap(&mut self, gap: u32, f: impl FnOnce(&mut Context)) -> Response

👎Deprecated since 0.20.1:

Use ui.container().gap(n).row(f) instead — same output, no name collision with ContainerBuilder::row_gap.

Create a horizontal (row) container with a gap between children.

gap is the number of blank columns inserted between each child.

Deprecated since 0.20.1: the name collides with ContainerBuilder::row_gap, which sets the column-finalize main-axis gap (Tailwind gap-y axis convention) and so means the opposite thing. Use ui.container().gap(n).row(f) instead — same output, no collision.

pub fn line(&mut self, f: impl FnOnce(&mut Context)) -> &mut Self

Render inline text with mixed styles on a single line.

Unlike row, line() is designed for rich text — children are rendered as continuous inline text without gaps.

It intentionally returns &mut Self instead of Response so you can keep chaining display-oriented modifiers after composing the inline run.

Example

ui.line(|ui| {
    ui.text("Status: ");
    ui.text("Online").bold().fg(Color::Green);
});

pub fn line_wrap(&mut self, f: impl FnOnce(&mut Context)) -> &mut Self

Render inline text with mixed styles, wrapping at word boundaries.

Like line, but when the combined text exceeds the container width it wraps across multiple lines while preserving per-segment styles.

Example

ui.line_wrap(|ui| {
    ui.text("This is a long ");
    ui.text("important").bold().fg(Color::Red);
    ui.text(" message that wraps across lines");
});

pub fn modal(&mut self, f: impl FnOnce(&mut Context)) -> Response

Render content in a modal overlay with dimmed background.

if show {
    ui.modal(|ui| {
        ui.text("Are you sure?");
        if ui.button("OK").clicked { show = false; }
    });
}

pub fn modal_with( &mut self, opts: ModalOptions, f: impl FnOnce(&mut Context), ) -> Response

Render content in a modal overlay with configurable options.

Like modal, but accepts a ModalOptions struct. Use this to opt into focus trapping (tab_trap: true) or future modal flags without breaking the bare modal() API.

When opts.tab_trap is true, focus cannot escape the modal’s focusable range — Tab/Shift+Tab keep cycling within the modal even if Context::set_focus_index or a mouse click moved focus to a background widget. WCAG 2.1 SC 2.4.3 (Focus Order) recommends trapping focus inside modal dialogs.

Example

if show {
    ui.modal_with(slt::context::ModalOptions { tab_trap: true }, |ui| {
        ui.text("Are you sure?");
        if ui.button("OK").clicked { show = false; }
    });
}

pub fn overlay(&mut self, f: impl FnOnce(&mut Context)) -> Response

Render floating content without dimming the background.

pub fn overlay_at( &mut self, anchor: Anchor, f: impl FnOnce(&mut Context), ) -> Response

Render floating content anchored to one of the 9 compass positions.

Wraps overlay with a full-area column that pins the content to the requested anchor via flexbox align/justify. The inner column gets grow(1) so the wrapper consumes the screen, giving align/justify room to push the content to the corner.

ui.overlay_at(Anchor::TopRight, |ui| {
    ui.text("0:42").bold();
});

pub fn modal_at( &mut self, anchor: Anchor, f: impl FnOnce(&mut Context), ) -> Response

Render a modal overlay anchored to one of the 9 compass positions.

Like modal but pinned to a corner / edge / center via the same anchor wrapping as overlay_at.

pub fn overlay_at_offset( &mut self, anchor: Anchor, dx: i32, dy: i32, f: impl FnOnce(&mut Context), ) -> Response

Render f at anchor with cell offset (dx, dy) from the anchored edge.

This is the SLT analog of CSS position: absolute; top/right/bottom/left, or Flutter’s Positioned(top:, right:, ...). The 9-cell Anchor chooses which edge to anchor to; (dx, dy) insets toward the center.

Sign convention

Positive dx / dy always inset toward the viewport center. So overlay_at_offset(Anchor::BottomRight, 2, 1, ...) places the widget 2 cells left and 1 cell up from the bottom-right corner.

For Anchor::Center (and other centered axes) negative values shift in the opposite direction — (dx=-2, dy=-1) shifts 2 cells left and 1 cell up. For corner / edge anchors, negative values would push the content off-screen, so they are clamped to 0; use a different anchor instead of negative offsets to escape an edge.

CSS analogy

CSS:    place-self: end end; bottom: 1px; right: 2px;
SLT:    overlay_at_offset(Anchor::BottomRight, 2, 1, |ui| { ... })

Example

// Inset corner badge — 2 cells from the right, 1 row from the bottom.
ui.overlay_at_offset(Anchor::BottomRight, 2, 1, |ui| {
    ui.text("v0.19.3").dim();
});

pub fn modal_at_offset( &mut self, anchor: Anchor, dx: i32, dy: i32, f: impl FnOnce(&mut Context), ) -> Response

Modal variant of overlay_at_offset.

Like modal_at but with a (dx, dy) cell inset from the anchored edge. Positive values inset toward the center — see overlay_at_offset for the full sign convention.

Example

ui.modal_at_offset(Anchor::TopRight, 2, 1, |ui| {
    ui.bordered(Border::Rounded).p(1).col(|ui| {
        ui.text("Saved!");
    });
});

pub fn tooltip(&mut self, text: impl Into<String>)

Render a hover tooltip for the previously rendered interactive widget.

Call this right after a widget or container response:

if ui.button("Save").clicked { save(); }
ui.tooltip("Save the current document to disk");

pub fn group(&mut self, name: &str) -> ContainerBuilder<'_>

Create a named group container for shared hover/focus styling.

ui.group("card").border(Border::Rounded)
    .group_hover_bg(Color::Indexed(238))
    .col(|ui| { ui.text("Hover anywhere"); });

pub fn container(&mut self) -> ContainerBuilder<'_>

Create a container with a fluent builder.

Use this for borders, padding, grow, constraints, and titles. Chain configuration methods on the returned ContainerBuilder, then call .col() or .row() to finalize.

Example

use slt::Border;
ui.container()
    .border(Border::Rounded)
    .p(1)
    .title("My Panel")
    .col(|ui| {
        ui.text("content");
    });

pub fn scrollable(&mut self, state: &mut ScrollState) -> ContainerBuilder<'_>

Create a scrollable container. Handles wheel scroll and drag-to-scroll automatically.

Pass a ScrollState to persist scroll position across frames. The state is updated in-place with the current scroll offset and bounds.

Example

let mut scroll = ScrollState::new();
ui.scrollable(&mut scroll).col(|ui| {
    for i in 0..100 {
        ui.text(format!("Line {i}"));
    }
});

pub fn scroll_col( &mut self, state: &mut ScrollState, f: impl FnOnce(&mut Context), ) -> Response

Scrollable column container — shortcut for scrollable(state).grow(1).col(f).

This is the form used by nearly every scrollable view: a vertical list that fills its parent and wheels through its own content. Use the explicit Context::scrollable builder when you need custom grow, borders, padding, or a scrollbar alongside.

Example

let mut scroll = ScrollState::new();
ui.scroll_col(&mut scroll, |ui| {
    for i in 0..100 {
        ui.text(format!("Line {i}"));
    }
});

pub fn scroll_row( &mut self, state: &mut ScrollState, f: impl FnOnce(&mut Context), ) -> Response

Scrollable row container — shortcut for scrollable(state).grow(1).row(f).

Useful for horizontally-scrolling timelines, kanban boards, and similar wide layouts.

pub fn scrollbar(&mut self, state: &ScrollState) -> Response

Render a scrollbar track for a ScrollState.

Displays a track (│) with a proportional thumb (█). The thumb size and position are calculated from the scroll state’s content height, viewport height, and current offset.

Typically placed beside a scrollable() container in a row():

let mut scroll = ScrollState::new();
ui.row(|ui| {
    ui.scrollable(&mut scroll).grow(1).col(|ui| {
        for i in 0..100 { ui.text(format!("Line {i}")); }
    });
    ui.scrollbar(&scroll);
});

Returns

Currently always returns Response::none(). The Response return type reserves an extension point so future click-to-jump and drag-to-scroll handling can be added without a further breaking change.

pub fn bordered(&mut self, border: Border) -> ContainerBuilder<'_>

Shortcut for container().border(border).

Returns a ContainerBuilder pre-configured with the given border style.

pub fn is_group_hovered(&self, name: &str) -> bool

Returns true if the named group is currently hovered by the mouse.

Uses the per-frame hovered_groups HashSet populated by Context::build_hovered_groups(); turns the previous O(n) scan over prev_group_rects into an O(1) lookup. Closes the cache half of #136 / #139.

pub fn is_group_focused(&self, name: &str) -> bool

Returns true if the named group contains the currently focused widget.

pub fn form( &mut self, state: &mut FormState, f: impl FnOnce(&mut Context, &mut FormState), ) -> &mut Self

Render a form that groups input fields vertically.

Wraps the fields in a column container and forwards the form state to the closure. Use Context::form_field inside the closure to render each field with label + input + error display.

Submission is driven by Context::form_submit; validation is triggered explicitly via FormState::validate.

pub fn form_field(&mut self, field: &mut FormField) -> &mut Self

Render a single form field with label and input.

Shows a validation error below the input when present.

pub fn form_submit(&mut self, label: impl Into<String>) -> Response

Render a primary-styled submit button.

Distinguishes the submit affordance from incidental buttons in the same form by rendering in the theme’s primary color (via ButtonVariant::Primary). Returns true in .clicked when the user clicks it, presses Enter while focused, or activates it with Space. Pair with FormState::validate to gate submission on all fields being valid.

impl Context

pub fn big_text(&mut self, s: impl Into<String>) -> Response

Render 8x8 bitmap text as half-block pixels (4 terminal rows tall).

pub fn image(&mut self, img: &HalfBlockImage) -> Response

Render a half-block image in the terminal.

Each terminal cell displays two vertical pixels using the ▀ character with foreground (upper pixel) and background (lower pixel) colors.

Create a HalfBlockImage from a file (requires image feature):

let img = image::open("photo.png").unwrap();
let half = HalfBlockImage::from_dynamic(&img, 40, 20);
ui.image(&half);

Or from raw RGB data (no feature needed):

let rgb = vec![255u8; 30 * 20 * 3];
let half = HalfBlockImage::from_rgb(&rgb, 30, 10);
ui.image(&half);

pub fn kitty_image( &mut self, rgba: &[u8], pixel_width: u32, pixel_height: u32, cols: u32, rows: u32, ) -> Response

Render a pixel-perfect image using the Kitty graphics protocol.

The image data must be raw RGBA bytes (4 bytes per pixel). The widget allocates cols x rows cells and renders the image at full pixel resolution within that space.

Requires a Kitty-compatible terminal (Kitty, Ghostty, WezTerm). On unsupported terminals, the area will be blank.

Arguments

• rgba - Raw RGBA pixel data
• pixel_width - Image width in pixels
• pixel_height - Image height in pixels
• cols - Terminal cell columns to occupy
• rows - Terminal cell rows to occupy

pub fn kitty_image_fit( &mut self, rgba: &[u8], src_width: u32, src_height: u32, cols: u32, ) -> Response

Render a pixel-perfect image that preserves aspect ratio.

Sends the original RGBA data to the terminal and lets the Kitty protocol handle scaling. The container width is cols cells; height is calculated automatically from the image aspect ratio using detected cell pixel dimensions (falls back to 8×16 if detection fails).

Requires a Kitty-compatible terminal (Kitty, Ghostty, WezTerm).

pub fn sixel_image( &mut self, rgba: &[u8], pixel_width: u32, pixel_height: u32, cols: u32, rows: u32, ) -> Response

Available on crate feature crossterm only.

Render an image using the Sixel protocol.

rgba is raw RGBA pixel data, pixel_width/pixel_height are pixel dimensions, and cols/rows are the terminal cell size to reserve for the image.

Requires the crossterm feature (enabled by default). Falls back to [sixel unsupported] on terminals without Sixel support. Set the SLT_FORCE_SIXEL=1 environment variable to skip terminal detection.

Example

// 2x2 red square (RGBA: 4 pixels × 4 bytes)
let rgba = [255u8, 0, 0, 255].repeat(4);
ui.sixel_image(&rgba, 2, 2, 20, 2);

pub fn streaming_text(&mut self, state: &mut StreamingTextState) -> Response

Render streaming text with a typing cursor indicator.

Displays the accumulated text content. While streaming is true, shows a blinking cursor (▌) at the end.

let mut stream = StreamingTextState::new();
stream.start();
stream.push("Hello from ");
stream.push("the AI!");
ui.streaming_text(&mut stream);

pub fn streaming_markdown( &mut self, state: &mut StreamingMarkdownState, ) -> Response

Render streaming markdown with a typing cursor indicator.

Parses accumulated markdown content line-by-line while streaming. Supports headings, lists, inline formatting, horizontal rules, and fenced code blocks with open/close tracking across stream chunks.

let mut stream = StreamingMarkdownState::new();
stream.start();
stream.push("# Hello\n");
stream.push("- **streaming** markdown\n");
stream.push("```rust\nlet x = 1;\n");
ui.streaming_markdown(&mut stream);

pub fn tool_approval(&mut self, state: &mut ToolApprovalState) -> Response

Render a tool approval widget with approve/reject buttons.

Shows the tool name, description, and two action buttons. Returns the updated ApprovalAction each frame.

let mut tool = ToolApprovalState::new("read_file", "Read contents of config.toml");
ui.tool_approval(&mut tool);
if tool.action == ApprovalAction::Approved {
}

pub fn context_bar(&mut self, items: &[ContextItem]) -> Response

Render a context bar showing active context items with token counts.

Displays a horizontal bar of context sources (files, URLs, etc.) with their token counts, useful for AI chat interfaces.

let items = vec![ContextItem::new("main.rs", 1200), ContextItem::new("lib.rs", 800)];
ui.context_bar(&items);

impl Context

pub fn split_pane<L, R>( &mut self, state: &mut SplitPaneState, left: L, right: R, ) -> SplitPaneResponse

where L: FnOnce(&mut Context), R: FnOnce(&mut Context),

Horizontal split container with a draggable handle.

Renders left | │ | right, where │ is a 1-cell wide drag handle. The handle is focusable; arrow keys (Left/Right) adjust the ratio by 5% per press, and dragging the handle with the mouse updates the ratio proportionally to the cursor’s x position.

Example

ui.split_pane(
    &mut split,
    |ui| { ui.text("left pane"); },
    |ui| { ui.text("right pane"); },
);

pub fn vsplit_pane<T, B>( &mut self, state: &mut SplitPaneState, top: T, bottom: B, ) -> SplitPaneResponse

where T: FnOnce(&mut Context), B: FnOnce(&mut Context),

Vertical split container with a draggable handle.

Mirrors Self::split_pane but stacks the panes vertically with a 1-row horizontal divider (─) between them. The handle is focusable; arrow keys (Up/Down) adjust the ratio by 5% per press.

Example

ui.vsplit_pane(
    &mut split,
    |ui| { ui.text("top pane"); },
    |ui| { ui.text("bottom pane"); },
);

impl Context

pub fn alert(&mut self, message: &str, level: AlertLevel) -> Response

Render an alert banner with icon and level-based coloring.

pub fn confirm(&mut self, question: &str, result: &mut bool) -> Response

Yes/No confirmation dialog. Returns Response with .clicked=true when answered.

result is set to true for Yes, false for No.

Examples

let mut answer = false;
let r = ui.confirm("Delete this file?", &mut answer);
if r.clicked && answer { /* user confirmed */ }

pub fn breadcrumb<'a>(&'a mut self, segments: &'a [&'a str]) -> Breadcrumb<'a>

Begin building a breadcrumb navigation bar with the default separator (›).

Returns a Breadcrumb builder that auto-renders on Drop. Chain .separator(s) for a custom separator and .color(c) for a custom link color. Call .show() to render and obtain a BreadcrumbResponse carrying clicked_segment and Deref<Response>.

Example

// simple
ui.breadcrumb(&["Home", "Settings", "Profile"]);

// with custom separator + color, capturing the response
let r = ui
    .breadcrumb(&["Home", "src", "lib.rs"])
    .separator(" > ")
    .show();
if let Some(i) = r.clicked_segment {
    // navigate to segment `i`
}

pub fn accordion( &mut self, title: &str, open: &mut bool, f: impl FnOnce(&mut Context), ) -> Response

Collapsible section that toggles on click, Enter, or Space.

pub fn definition_list(&mut self, items: &[(&str, &str)]) -> Response

Render a key-value definition list with aligned columns.

pub fn divider_text(&mut self, label: &str) -> Response

Render a horizontal divider with a centered text label.

pub fn badge(&mut self, label: &str) -> Response

Render a badge with the theme’s primary color.

Example

ui.badge("NEW");

pub fn badge_colored(&mut self, label: &str, color: Color) -> Response

Render a badge with a custom background color.

Foreground is auto-selected for contrast via Color::contrast_fg.

Example

ui.badge_colored("ALPHA", Color::Magenta);

pub fn key_hint(&mut self, key: &str) -> Response

Render a keyboard shortcut hint with reversed styling.

Example

ui.line(|ui| {
    ui.text("Quit: ");
    ui.key_hint("Ctrl+Q");
});

pub fn stat(&mut self, label: &str, value: &str) -> Response

Render a label-value stat pair.

Renders as a column: a dim label above a bold value. Pair multiple stats in a row for a compact dashboard strip.

Example

ui.row(|ui| {
    ui.stat("Users", "1.2k");
    ui.stat("Revenue", "$8,420");
});

pub fn stat_colored( &mut self, label: &str, value: &str, color: Color, ) -> Response

Render a stat pair with a custom value color.

Example

ui.stat_colored("Errors", "0", Color::Green);

pub fn stat_trend(&mut self, label: &str, value: &str, trend: Trend) -> Response

Render a stat pair with an up/down trend arrow.

The arrow color follows the theme: success for Trend::Up, error for Trend::Down.

Example

ui.stat_trend("MRR", "$24.5k", Trend::Up);
ui.stat_trend("Churn", "1.8%", Trend::Down);

pub fn empty_state(&mut self, title: &str, description: &str) -> Response

Render a centered empty-state placeholder.

Title is rendered prominently; description is dimmed below. Both are centered horizontally and vertically inside the available space.

Example

if items.is_empty() {
    ui.empty_state("No items yet", "Press 'a' to add one");
}

pub fn empty_state_action( &mut self, title: &str, description: &str, action_label: &str, ) -> Response

Render a centered empty-state placeholder with an action button.

Returns a Response whose clicked field is true on the frame the action button is activated.

Example

if items.is_empty() {
    let r = ui.empty_state_action("No items yet", "Get started", "Add first item");
    if r.clicked {
        // open create flow
    }
}

pub fn code_block(&mut self, code: &str) -> Response

Render a code block with keyword-based syntax highlighting.

pub fn code_block_lang(&mut self, code: &str, lang: &str) -> Response

Render a code block with language-aware syntax highlighting.

pub fn code_block_numbered(&mut self, code: &str) -> Response

Render a code block with line numbers and keyword highlighting.

pub fn code_block_numbered_lang(&mut self, code: &str, lang: &str) -> Response

Render a code block with line numbers and language-aware highlighting.

impl Context

pub fn text(&mut self, s: impl Into<String>) -> &mut Self

Render a text element. Returns &mut Self for style chaining.

Example

use slt::Color;
ui.text("hello").bold().fg(Color::Cyan);

pub fn link( &mut self, text: impl Into<String>, url: impl Into<String>, ) -> &mut Self

Render a clickable hyperlink.

The link is interactive: clicking it (or pressing Enter/Space when focused) opens the URL in the system browser. OSC 8 is also emitted for terminals that support native hyperlinks.

pub fn timer_display(&mut self, elapsed: Duration) -> &mut Self

Render an elapsed time display.

Formats as HH:MM:SS.CC when hours are non-zero, otherwise MM:SS.CC.

pub fn help_from_keymap(&mut self, keymap: &KeyMap) -> Response

Render help bar from a KeyMap. Shows visible bindings as key-description pairs.

pub fn bold(&mut self) -> &mut Self

Apply bold to the last rendered text element.

pub fn dim(&mut self) -> &mut Self

Apply dim styling to the last rendered text element.

Also sets the foreground color to the theme’s text_dim color if no explicit foreground has been set.

pub fn italic(&mut self) -> &mut Self

Apply italic to the last rendered text element.

pub fn underline(&mut self) -> &mut Self

Apply underline to the last rendered text element.

pub fn reversed(&mut self) -> &mut Self

Apply reverse-video to the last rendered text element.

pub fn strikethrough(&mut self) -> &mut Self

Apply strikethrough to the last rendered text element.

pub fn fg(&mut self, color: Color) -> &mut Self

Set the foreground color of the last rendered text element.

pub fn bg(&mut self, color: Color) -> &mut Self

Set the background color of the last rendered text element.

pub fn gradient(&mut self, from: Color, to: Color) -> &mut Self

Apply a per-character foreground gradient to the last rendered text.

pub fn group_hover_fg(&mut self, color: Color) -> &mut Self

Set foreground color when the current group is hovered or focused.

pub fn group_hover_bg(&mut self, color: Color) -> &mut Self

Set background color when the current group is hovered or focused.

pub fn styled(&mut self, s: impl Into<String>, style: Style) -> &mut Self

Render a text element with an explicit Style applied immediately.

Equivalent to calling text(s) followed by style-chain methods, but more concise when you already have a Style value.

pub fn wrap(&mut self) -> &mut Self

Enable word-boundary wrapping on the last rendered text element.

pub fn truncate(&mut self) -> &mut Self

Truncate the last rendered text with … when it exceeds its allocated width. Use with .w() to set a fixed width, or let the parent container constrain it.

pub fn grow(&mut self, value: u16) -> &mut Self

Set the flex-grow factor of the last rendered text element.

A value of 1 causes the element to expand and fill remaining space along the main axis.

pub fn align(&mut self, align: Align) -> &mut Self

Set the text alignment of the last rendered text element.

pub fn text_center(&mut self) -> &mut Self

Center-align the last rendered text element horizontally. Shorthand for .align(Align::Center). Requires the text to have a width constraint (via .w() or parent container) to be visible.

pub fn text_right(&mut self) -> &mut Self

Right-align the last rendered text element horizontally. Shorthand for .align(Align::End).

pub fn w(&mut self, value: u32) -> &mut Self

Set a fixed width on the last rendered text or link element.

Sets the WidthSpec to Fixed(value), making the element occupy exactly that many columns (padded with spaces or truncated).

pub fn h(&mut self, value: u32) -> &mut Self

Set a fixed height on the last rendered text or link element.

Sets the HeightSpec to Fixed(value).

pub fn min_w(&mut self, value: u32) -> &mut Self

Set the minimum width on the last rendered text or link element.

pub fn max_w(&mut self, value: u32) -> &mut Self

Set the maximum width on the last rendered text or link element.

pub fn min_h(&mut self, value: u32) -> &mut Self

Set the minimum height on the last rendered text or link element.

pub fn max_h(&mut self, value: u32) -> &mut Self

Set the maximum height on the last rendered text or link element.

pub fn m(&mut self, value: u32) -> &mut Self

Set uniform margin on all sides of the last rendered text or link element.

pub fn mx(&mut self, value: u32) -> &mut Self

Set horizontal margin (left + right) on the last rendered text or link.

pub fn my(&mut self, value: u32) -> &mut Self

Set vertical margin (top + bottom) on the last rendered text or link.

pub fn mt(&mut self, value: u32) -> &mut Self

Set top margin on the last rendered text or link element.

pub fn mr(&mut self, value: u32) -> &mut Self

Set right margin on the last rendered text or link element.

pub fn mb(&mut self, value: u32) -> &mut Self

Set bottom margin on the last rendered text or link element.

pub fn ml(&mut self, value: u32) -> &mut Self

Set left margin on the last rendered text or link element.

pub fn spacer(&mut self) -> &mut Self

Render an invisible spacer that expands to fill available space.

Useful for pushing siblings to opposite ends of a row or column.

pub fn with_if(&mut self, cond: bool, f: impl FnOnce(&mut Self)) -> &mut Self

Apply f only if cond is true. Returns self so chaining continues.

Use this to attach a block of style modifiers to the last rendered text without breaking the fluent chain. The closure receives the same &mut Context, so any style-chain method (.bold(), .fg(), etc.) applies to the most recent text element.

Zero allocation: the closure is inlined and skipped entirely when cond is false.

Example

use slt::Color;
let is_error = true;
let is_selected = false;
ui.text("Status")
    .with_if(is_error, |t| {
        t.bold().fg(Color::Red);
    })
    .with_if(is_selected, |t| {
        t.bg(Color::DarkGray);
    });

pub fn with(&mut self, f: impl FnOnce(&mut Self)) -> &mut Self

Apply f unconditionally. Useful for factoring out a block of modifier calls that should always run, while keeping the fluent chain intact.

Example

use slt::Color;
ui.text("hi").with(|t| {
    t.bold().fg(Color::Cyan);
});

impl Context

pub fn spinner(&mut self, state: &SpinnerState) -> Response

Render an animated spinner.

The spinner advances one frame per tick. Use SpinnerState::dots or SpinnerState::line to create the state.

Returns a Response with hovered populated correctly so callers can attach tooltips or react to mouse interaction. Prior to v0.20.0 this returned &mut Self; existing code that ignores the return value keeps compiling, though the #[must_use] attribute on Response surfaces a warning that nudges callers to handle interaction state.

pub fn toast(&mut self, state: &mut ToastState) -> &mut Self

Render toast notifications. Calls state.cleanup(tick) automatically.

Expired messages are removed before rendering. If there are no active messages, nothing is rendered and self is returned unchanged.

pub fn slider( &mut self, label: &str, value: &mut f64, range: RangeInclusive<f64>, ) -> Response

Horizontal slider for numeric values.

Step defaults to span / 20.0. Use Context::slider_with_step for an explicit step (e.g. integer volume controls).

Examples

let mut volume = 75.0_f64;
let r = ui.slider("Volume", &mut volume, 0.0..=100.0);
if r.changed { /* volume was adjusted */ }

pub fn slider_with_step( &mut self, label: &str, value: &mut f64, range: RangeInclusive<f64>, step: f64, ) -> Response

Horizontal slider with an explicit step size.

Each Left/Right (or h/l) advances value by step. Use this when the default step (span / 20) is too coarse or too fine — for example integer counters need step = 1.0, fine controls need step = 0.1.

Examples

let mut volume = 50.0_f64;
ui.slider_with_step("Volume", &mut volume, 0.0..=100.0, 1.0);

impl Context

pub fn text_input(&mut self, state: &mut TextInputState) -> Response

Render a single-line text input. Auto-handles cursor, typing, and backspace.

The widget claims focus via Context::register_focusable. When focused, it consumes character, backspace, arrow, Home, and End key events.

Example

let mut input = TextInputState::with_placeholder("Search...");
ui.text_input(&mut input);
// input.value holds the current text

pub fn text_input_colored( &mut self, state: &mut TextInputState, colors: &WidgetColors, ) -> Response

Render a text input with custom widget colors.

impl Context

pub fn textarea( &mut self, state: &mut TextareaState, visible_rows: u32, ) -> Response

When focused, handles character input, Enter (new line), Backspace, arrow keys, Home, and End. The cursor is rendered as a block character.

Set TextareaState::word_wrap to enable soft-wrapping at a given display-column width. Up/Down then navigate visual lines.

Editing shortcuts: Ctrl+K deletes from the cursor to the end of the current line. Ctrl+Left / Alt+Left jumps to the previous word boundary; Ctrl+Right / Alt+Right jumps past the next word end. Ctrl+Z undoes the last edit and Ctrl+Y redoes it — see the TextareaState docs for the snapshot policy.

pub fn progress(&mut self, ratio: f64) -> Response

Render a progress bar (20 chars wide). ratio is clamped to 0.0..=1.0.

Uses block characters (█ filled, ░ empty). For a custom width use Context::progress_bar. For an inline label use Context::gauge.

Returns a Response so callers can detect hover, attach a tooltip, or implement click-to-set scrubbers. Prior to v0.20.0 this returned &mut Self; ignoring the return value still compiles but the #[must_use] attribute on Response warns at the call site.

pub fn progress_bar(&mut self, ratio: f64, width: u32) -> Response

Render a progress bar with a custom character width.

ratio is clamped to 0.0..=1.0. width is the total number of characters rendered.

pub fn progress_bar_colored( &mut self, ratio: f64, width: u32, color: Color, ) -> Response

Render a progress bar with a custom fill color.

impl Context

pub fn grid(&mut self, cols: u32, f: impl FnOnce(&mut Context)) -> Response

Render children in a fixed grid with the given number of columns.

Children are placed left-to-right, top-to-bottom. Each cell has equal width (area_width / cols). Rows wrap automatically.

Example

ui.grid(3, |ui| {
    for i in 0..9 {
        ui.text(format!("Cell {i}"));
    }
});

pub fn grid_with( &mut self, columns: &[GridColumn], f: impl FnOnce(&mut Context), ) -> Response

Render children in a grid with per-column width specifications.

The number of columns is determined by the length of columns. Children are placed left-to-right, top-to-bottom, wrapping into rows automatically.

Column specifications

• GridColumn::Auto — equal-width flex column (same as grid())
• GridColumn::Fixed(n) — exactly n character cells wide
• GridColumn::Grow(w) — flexible with grow weight w
• GridColumn::Percent(p) — p% of the grid width

Example

use slt::GridColumn;
ui.grid_with(&[
    GridColumn::Fixed(8),
    GridColumn::Grow(1),
    GridColumn::Grow(1),
    GridColumn::Fixed(4),
], |ui| {
    for i in 0..8 {
        ui.text(format!("Cell {i}"));
    }
});

pub fn list(&mut self, state: &mut ListState) -> Response

Render a selectable list. Handles Up/Down (and k/j) navigation when focused.

The selected item is highlighted with the theme’s primary color. If the list is empty, nothing is rendered.

pub fn list_colored( &mut self, state: &mut ListState, colors: &WidgetColors, ) -> Response

Render a navigable list with custom widget colors.

pub fn calendar(&mut self, state: &mut CalendarState) -> Response

Render a calendar date picker with month navigation.

Keybindings (when focused)

Key	Action
Left / h	Previous day
Right / l	Next day
Up	Previous week (−7 days)
Down	Next week (+7 days)
[	Previous month
]	Next month
Enter / Space	Select cursor day

h/l follow vim convention (cursor by one day). Use [/] for month navigation. Mouse clicks on the title row navigate months and clicks inside the day grid select that day.

pub fn file_picker(&mut self, state: &mut FilePickerState) -> Response

Render a file system browser with directory navigation.

impl Context

pub fn help(&mut self, bindings: &[(&str, &str)]) -> Response

Render a help bar showing keybinding hints.

bindings is a slice of (key, action) pairs. Keys are rendered in the theme’s primary color; actions in the dim text color. Pairs are separated by a · character.

pub fn help_colored( &mut self, bindings: &[(&str, &str)], key_color: Color, text_color: Color, ) -> Response

Render a help bar with custom key/description colors.

pub fn key(&self, c: char) -> bool

Check if a character key was pressed this frame.

Returns true if the key event has not been consumed by another widget.

pub fn key_code(&self, code: KeyCode) -> bool

Check if a specific key code was pressed this frame.

Returns true if the key event has not been consumed by another widget. Blocked when a modal/overlay is active and the caller is outside the overlay. Use raw_key_code for global shortcuts that must work regardless of modal/overlay state.

pub fn raw_key_code(&self, code: KeyCode) -> bool

Check if a specific key code was pressed this frame, ignoring modal/overlay state.

Unlike key_code, this method bypasses the modal/overlay guard so it works even when a modal or overlay is active. Use this for global shortcuts (e.g. Esc to close a modal, Ctrl+Q to quit) that must always be reachable.

Returns true if the key event has not been consumed by another widget.

pub fn key_release(&self, c: char) -> bool

Check if a character key was released this frame.

Returns true if the key release event has not been consumed by another widget.

pub fn key_code_release(&self, code: KeyCode) -> bool

Check if a specific key code was released this frame.

Returns true if the key release event has not been consumed by another widget.

pub fn consume_key(&mut self, c: char) -> bool

Check for a character key press and consume the event, preventing other handlers from seeing it.

Returns true if the key was found unconsumed and is now consumed. Unlike key() which peeks without consuming, this claims exclusive ownership of the event.

Call after widgets if you want widgets to have priority over your handler, or before widgets to intercept first.

pub fn consume_key_code(&mut self, code: KeyCode) -> bool

Check for a special key press and consume the event, preventing other handlers from seeing it.

Returns true if the key was found unconsumed and is now consumed. Unlike key_code() which peeks without consuming, this claims exclusive ownership of the event.

Call after widgets if you want widgets to have priority over your handler, or before widgets to intercept first.

pub fn key_mod(&self, c: char, modifiers: KeyModifiers) -> bool

Check if a character key with specific modifiers was pressed this frame.

Returns true if the key event has not been consumed by another widget.

pub fn raw_key_mod(&self, c: char, modifiers: KeyModifiers) -> bool

Like key_mod but bypasses the modal/overlay guard.

pub fn mouse_down(&self) -> Option<(u32, u32)>

Return the position of a left mouse button down event this frame, if any.

Returns None if no unconsumed mouse-down event occurred.

pub fn mouse_drag(&self) -> Option<(u32, u32)>

Return the position of a left mouse button drag event this frame, if any.

Returns None if no unconsumed drag event occurred. Drag events fire while the left button is held and the cursor moves.

pub fn mouse_up(&self) -> Option<(u32, u32)>

Return the position of a left mouse button release event this frame, if any.

Returns None if no unconsumed mouse-up event occurred.

pub fn mouse_down_button(&self, button: MouseButton) -> Option<(u32, u32)>

Return the position of a mouse button down event for the specified button.

This is a generalized version of mouse_down that accepts any MouseButton.

pub fn mouse_drag_button(&self, button: MouseButton) -> Option<(u32, u32)>

Return the position of a mouse drag event for the specified button.

pub fn mouse_up_button(&self, button: MouseButton) -> Option<(u32, u32)>

Return the position of a mouse button release event for the specified button.

pub fn mouse_pos(&self) -> Option<(u32, u32)>

Return the current mouse cursor position, if known.

The position is updated on every mouse move or click event. Returns None until the first mouse event is received.

pub fn paste(&self) -> Option<&str>

Return the first unconsumed paste event text, if any.

pub fn scroll_up(&self) -> bool

Check if an unconsumed scroll-up event occurred this frame.

pub fn scroll_down(&self) -> bool

Check if an unconsumed scroll-down event occurred this frame.

pub fn scroll_left(&self) -> bool

Check if an unconsumed scroll-left event occurred this frame.

pub fn scroll_right(&self) -> bool

Check if an unconsumed scroll-right event occurred this frame.

pub fn events(&self) -> impl Iterator<Item = &Event>

Iterate over unconsumed events this frame, respecting the modal guard.

Returns an empty iterator when a modal is active and the caller is not inside an overlay. Use raw_events to bypass the modal guard (e.g., for global hotkeys).

Example

for event in ui.events() {
    if let slt::Event::Mouse(mouse) = event {
        if matches!(mouse.kind, slt::MouseKind::Down(slt::MouseButton::Right)) {
            // handle right-click
        }
    }
}

pub fn raw_events(&self) -> impl Iterator<Item = &Event> + '_

Iterate over all unconsumed events, bypassing the modal guard.

Use this for global shortcuts that must work even when a modal or overlay is active. Prefer events for normal use.

pub fn quit(&mut self)

Signal the run loop to exit after this frame.

pub fn copy_to_clipboard(&mut self, text: impl Into<String>)

Copy text to the system clipboard via OSC 52.

Works transparently over SSH connections. The text is queued and written to the terminal after the current frame renders.

Requires a terminal that supports OSC 52 (most modern terminals: Ghostty, kitty, WezTerm, iTerm2, Windows Terminal).

pub fn theme(&self) -> &Theme

Get the current theme.

pub fn color(&self, token: ThemeColor) -> Color

Resolve a ThemeColor token against the current theme.

pub fn spacing(&self) -> Spacing

Get the current spacing scale from the theme.

pub fn set_theme(&mut self, theme: Theme)

Change the theme for subsequent rendering.

All widgets rendered after this call will use the new theme’s colors.

pub fn is_dark_mode(&self) -> bool

Check if dark mode is active.

pub fn set_dark_mode(&mut self, dark: bool)

Set dark mode. When true, dark_* style variants are applied.

pub fn width(&self) -> u32

Get the terminal width in cells.

pub fn breakpoint(&self) -> Breakpoint

Get the current terminal width breakpoint.

Returns a Breakpoint based on the terminal width:

• Xs: < 40 columns
• Sm: 40-79 columns
• Md: 80-119 columns
• Lg: 120-159 columns
• Xl: >= 160 columns

Use this for responsive layouts that adapt to terminal size:

match ui.breakpoint() {
    Breakpoint::Xs | Breakpoint::Sm => {
        ui.col(|ui| { ui.text("Stacked layout"); });
    }
    _ => {
        ui.row(|ui| { ui.text("Side-by-side layout"); });
    }
}

pub fn height(&self) -> u32

Get the terminal height in cells.

pub fn tick(&self) -> u64

Get the current tick count (increments each frame).

Useful for animations and time-based logic. The tick starts at 0 and increases by 1 on every rendered frame.

pub fn debug_enabled(&self) -> bool

Return whether the layout debugger is enabled.

The debugger is toggled with F12 at runtime.

pub fn debug_layer(&self) -> DebugLayer

Return which layers the F12 debug overlay outlines (issue #201).

Default is crate::DebugLayer::All, which outlines the base tree plus any active overlays/modals. See set_debug_layer to narrow the outline to a specific layer.

Example

use slt::{Context, DebugLayer};

slt::run(|ui: &mut Context| {
    // Read the current layer to drive a UI badge or debug toolbar.
    match ui.debug_layer() {
        DebugLayer::All => ui.text("layer: all"),
        DebugLayer::TopMost => ui.text("layer: topmost"),
        DebugLayer::BaseOnly => ui.text("layer: base"),
    };
}).unwrap();

pub fn set_debug_layer(&mut self, layer: DebugLayer)

Choose which layers the F12 debug overlay outlines (issue #201).

Persists across frames. The default (crate::DebugLayer::All) matches the reporter’s expectation that F12 reflects everything the renderer is drawing. Use crate::DebugLayer::TopMost to focus on the active modal / overlay only, or crate::DebugLayer::BaseOnly to keep the legacy behavior of skipping overlays.

Runtime keybinding

At runtime, Shift+F12 cycles through All → TopMost → BaseOnly → All. Plain F12 still toggles the overlay on/off. The two keys are independent: enabling the overlay does not change the active layer, and cycling layers does not enable the overlay.

Example

use slt::{Context, DebugLayer};

slt::run(|ui: &mut Context| {
    // Toggle between viewing only the base tree and viewing all
    // layers, e.g. from a custom debug menu.
    let next = match ui.debug_layer() {
        DebugLayer::All => DebugLayer::BaseOnly,
        DebugLayer::BaseOnly => DebugLayer::TopMost,
        DebugLayer::TopMost => DebugLayer::All,
    };
    ui.set_debug_layer(next);
}).unwrap();

impl Context

pub fn rich_log(&mut self, state: &mut RichLogState) -> Response

Render a scrollable rich log view with styled entries.

pub fn virtual_list( &mut self, state: &mut ListState, visible_height: u32, f: impl Fn(&mut Context, usize), ) -> Response

Render a virtual list that only renders visible items.

total is the number of items. visible_height limits how many rows are rendered. The closure f is called only for visible indices.

pub fn command_palette(&mut self, state: &mut CommandPaletteState) -> Response

Render a command palette overlay.

pub fn markdown(&mut self, text: &str) -> Response

Render a markdown string with basic formatting.

Supports headers (#), bold (**), italic (*), inline code (`), unordered lists (-/*), ordered lists (1.), blockquotes (>), horizontal rules (---), links ([text](url)), image placeholders (![alt](url)), code blocks with syntax highlighting, and GFM-style pipe tables. Paragraph text auto-wraps to container width.

pub fn key_seq(&self, seq: &str) -> bool

Check if a sequence of character keys was pressed across recent frames.

Matches when each character in seq appears in consecutive unconsumed key events within this frame. For single-frame sequences only (e.g., “gg”).

impl Context

pub fn table(&mut self, state: &mut TableState) -> Response

Render a data table with sortable columns and row selection.

Handles Up/Down selection when focused. Column widths are computed automatically from header and cell content. The selected row is highlighted with the theme’s selection colors.

pub fn table_colored( &mut self, state: &mut TableState, colors: &WidgetColors, ) -> Response

Render a data table with custom widget colors.

pub fn tabs(&mut self, state: &mut TabsState) -> Response

Render a horizontal tab bar. Handles Left/Right navigation when focused.

The active tab is rendered in the theme’s primary color. If the labels list is empty, nothing is rendered.

pub fn tabs_colored( &mut self, state: &mut TabsState, colors: &WidgetColors, ) -> Response

Render a horizontal tab bar with custom widget colors.

pub fn button(&mut self, label: impl Into<String>) -> Response

Render a clickable button. Activation fires via Enter, Space, or mouse click.

The returned Response::clicked flag is set on activation. The button is styled with the theme’s primary color when focused and the accent color when hovered.

pub fn button_colored( &mut self, label: impl Into<String>, colors: &WidgetColors, ) -> Response

Render a clickable button with custom widget colors.

pub fn button_with( &mut self, label: impl Into<String>, variant: ButtonVariant, ) -> Response

Render a styled button variant. Returns true when activated.

Use ButtonVariant::Primary for call-to-action, ButtonVariant::Danger for destructive actions, or ButtonVariant::Outline for secondary actions.

pub fn checkbox( &mut self, label: impl Into<String>, checked: &mut bool, ) -> Response

Render a checkbox. Toggles the bool on Enter, Space, or click.

The checked state is shown with the theme’s success color. When focused, a ▸ prefix is added. Render a checkbox toggle.

pub fn checkbox_colored( &mut self, label: impl Into<String>, checked: &mut bool, colors: &WidgetColors, ) -> Response

Render a checkbox toggle with custom widget colors.

pub fn toggle(&mut self, label: impl Into<String>, on: &mut bool) -> Response

Render an on/off toggle switch.

Toggles on when activated via Enter, Space, or click. The switch renders as ●━━ ON or ━━● OFF colored with the theme’s success or dim color respectively. Render an on/off toggle switch.

pub fn toggle_colored( &mut self, label: impl Into<String>, on: &mut bool, colors: &WidgetColors, ) -> Response

Render an on/off toggle switch with custom widget colors.

pub fn select(&mut self, state: &mut SelectState) -> Response

Render a dropdown select. Shows the selected item; expands on activation.

Returns true when the selection changed this frame. Render a dropdown select widget.

pub fn select_colored( &mut self, state: &mut SelectState, colors: &WidgetColors, ) -> Response

Render a dropdown select widget with custom widget colors.

pub fn radio(&mut self, state: &mut RadioState) -> Response

Render a radio button group. Returns true when selection changed. Render a radio button group.

pub fn radio_colored( &mut self, state: &mut RadioState, colors: &WidgetColors, ) -> Response

Render a radio button group with custom widget colors.

pub fn multi_select(&mut self, state: &mut MultiSelectState) -> Response

Render a multi-select list. Space toggles, Up/Down navigates.

impl Context

pub fn tree(&mut self, state: &mut TreeState) -> Response

Render a tree view. Left/Right to collapse/expand, Up/Down to navigate.

pub fn directory_tree(&mut self, state: &mut DirectoryTreeState) -> Response

Render a directory tree with guide lines and tree connectors.

impl Context

pub fn bar_chart(&mut self, data: &[(&str, f64)], max_width: u32) -> Response

Render a horizontal bar chart from (label, value) pairs.

Bars are normalized against the largest value and rendered with █ up to max_width characters.

Example

let data = [
    ("Sales", 160.0),
    ("Revenue", 120.0),
    ("Users", 220.0),
    ("Costs", 60.0),
];
ui.bar_chart(&data, 24);

For styled bars with per-bar colors, see bar_chart_with.

pub fn bar_chart_with( &mut self, bars: &[Bar], configure: impl FnOnce(&mut BarChartConfig), max_size: u32, ) -> Response

Render a bar chart with custom configuration.

pub fn bar_chart_grouped( &mut self, groups: &[BarGroup], max_width: u32, ) -> Response

Render a grouped bar chart.

Each group contains multiple bars rendered side by side. Useful for comparing categories across groups (e.g., quarterly revenue by product).

Example

use slt::{Bar, BarGroup, Color};
let groups = vec![
    BarGroup::new("2023", vec![Bar::new("Rev", 100.0).color(Color::Cyan), Bar::new("Cost", 60.0).color(Color::Red)]),
    BarGroup::new("2024", vec![Bar::new("Rev", 140.0).color(Color::Cyan), Bar::new("Cost", 80.0).color(Color::Red)]),
];
ui.bar_chart_grouped(&groups, 40);

pub fn bar_chart_grouped_with( &mut self, groups: &[BarGroup], configure: impl FnOnce(&mut BarChartConfig), max_size: u32, ) -> Response

Render a grouped bar chart with custom configuration.

pub fn sparkline(&mut self, data: &[f64], width: u32) -> Response

Render a single-line sparkline from numeric data.

Uses the last width points (or fewer if the data is shorter) and maps each point to one of ▁▂▃▄▅▆▇█.

Example

let samples = [12.0, 9.0, 14.0, 18.0, 16.0, 21.0, 20.0, 24.0];
ui.sparkline(&samples, 16);

For per-point colors and missing values, see sparkline_styled.

pub fn sparkline_styled( &mut self, data: &[(f64, Option<Color>)], width: u32, ) -> Response

Render a sparkline with per-point colors.

Each point can have its own color via (f64, Option<Color>) tuples. Use f64::NAN for absent values (rendered as spaces).

Example

use slt::Color;
let data: Vec<(f64, Option<Color>)> = vec![
    (12.0, Some(Color::Green)),
    (9.0, Some(Color::Red)),
    (14.0, Some(Color::Green)),
    (f64::NAN, None),
    (18.0, Some(Color::Cyan)),
];
ui.sparkline_styled(&data, 16);

pub fn line_chart(&mut self, data: &[f64], width: u32, height: u32) -> Response

Render a multi-row line chart using braille characters.

width and height are terminal cell dimensions. Internally this uses braille dot resolution (width*2 x height*4) for smoother plotting.

Example

let data = [1.0, 3.0, 2.0, 5.0, 4.0, 6.0, 3.0, 7.0];
ui.line_chart(&data, 40, 8);

pub fn line_chart_colored( &mut self, data: &[f64], width: u32, height: u32, color: Color, ) -> Response

Render a multi-row line chart using a custom color.

pub fn area_chart(&mut self, data: &[f64], width: u32, height: u32) -> Response

Render a multi-row area chart using the primary theme color.

pub fn area_chart_colored( &mut self, data: &[f64], width: u32, height: u32, color: Color, ) -> Response

Render a multi-row area chart using a custom color.

pub fn candlestick( &mut self, candles: &[Candle], up_color: Color, down_color: Color, ) -> Response

Render an OHLC candlestick chart.

pub fn heatmap( &mut self, data: &[Vec<f64>], width: u32, height: u32, low_color: Color, high_color: Color, ) -> Response

Render a heatmap from a 2D data grid.

Each cell maps to a block character with color intensity: low values -> dim/dark, high values -> bright/saturated.

Arguments

• data - Row-major 2D grid (outer = rows, inner = columns)
• width - Widget width in terminal cells
• height - Widget height in terminal cells
• low_color - Color for minimum values
• high_color - Color for maximum values

pub fn canvas( &mut self, width: u32, height: u32, draw: impl FnOnce(&mut CanvasContext), ) -> Response

Render a braille drawing canvas.

The closure receives a CanvasContext for pixel-level drawing. Each terminal cell maps to a 2x4 braille dot matrix, giving width*2 x height*4 pixel resolution.

Example

ui.canvas(40, 10, |cv| {
    cv.line(0, 0, cv.width() - 1, cv.height() - 1);
    cv.circle(40, 20, 15);
});

pub fn chart( &mut self, configure: impl FnOnce(&mut ChartBuilder), width: u32, height: u32, ) -> Response

Render a multi-series chart with axes, legend, and auto-scaling.

width and height must be non-zero. For dynamic sizing, read terminal dimensions first (for example via ui.width() / ui.height()) and pass the computed values to this method.

pub fn scatter( &mut self, data: &[(f64, f64)], width: u32, height: u32, ) -> Response

Renders a scatter plot.

Each point is a (x, y) tuple. Uses braille markers.

pub fn histogram(&mut self, data: &[f64], width: u32, height: u32) -> Response

Render a histogram from raw data with auto-binning.

pub fn histogram_with( &mut self, data: &[f64], configure: impl FnOnce(&mut HistogramBuilder), width: u32, height: u32, ) -> Response

Render a histogram with configuration options.

pub fn qr_code(&mut self, data: impl AsRef<str>) -> Response

Available on crate feature qrcode only.

Render a QR code using half-block characters.

pub fn heatmap_halfblock( &mut self, data: &[Vec<f64>], width: u32, height: u32, low_color: Color, high_color: Color, ) -> Response

Render a heatmap using half-block characters for 2× vertical resolution.

Each terminal cell packs two data rows using ▀ with fg for the upper half and bg for the lower half. This doubles the effective vertical resolution compared to heatmap.

Example

use slt::Color;
let data: Vec<Vec<f64>> = (0..20)
    .map(|r| (0..40).map(|c| ((r * 3 + c * 7) % 20) as f64).collect())
    .collect();
ui.heatmap_halfblock(&data, 40, 10, Color::Rgb(10, 10, 40), Color::Rgb(255, 80, 30));

pub fn candlestick_hd( &mut self, candles: &[Candle], up_color: Color, down_color: Color, ) -> Response

Render a candlestick chart with heavy box-drawing and half-block precision.

Uses ┃ for wicks (heavier than │) and ▀/▄ at body edges for sub-cell vertical precision, effectively doubling the price resolution.

Each terminal cell represents two half-cells vertically: the body’s open and close prices snap to the nearest half-cell, so a body that covers an odd number of half-cells terminates with ▀ (top half only) or ▄ (bottom half only) rather than rounding to a full cell.

Example

use slt::{Candle, Color};
let candles = vec![
    Candle { open: 100.0, high: 108.0, low: 98.0, close: 105.0 },
    Candle { open: 105.0, high: 112.0, low: 103.0, close: 110.0 },
];
ui.candlestick_hd(&candles, Color::Rgb(38, 166, 91), Color::Rgb(234, 57, 67));

pub fn treemap(&mut self, items: &[TreemapItem]) -> Response

Render a treemap using the squarified layout algorithm.

Each item occupies a rectangle proportional to its value, filled with the item’s color and labeled when space permits.

Example

use slt::{TreemapItem, Color};
let items = vec![
    TreemapItem::new("Rust", 40.0, Color::Cyan),
    TreemapItem::new("Go", 25.0, Color::Blue),
    TreemapItem::new("Python", 20.0, Color::Yellow),
    TreemapItem::new("Java", 15.0, Color::Red),
];
ui.treemap(&items);

pub fn bar_chart_stacked( &mut self, groups: &[BarGroup], max_height: u32, ) -> Response

Render a stacked bar chart with custom configuration.

Each group’s bars are stacked on top of each other rather than placed side-by-side.

Example

use slt::{Bar, BarGroup, Color};
let groups = vec![
    BarGroup::new("2023", vec![
        Bar::new("Rev", 100.0).color(Color::Cyan),
        Bar::new("Cost", 60.0).color(Color::Red),
    ]),
    BarGroup::new("2024", vec![
        Bar::new("Rev", 140.0).color(Color::Cyan),
        Bar::new("Cost", 80.0).color(Color::Red),
    ]),
];
ui.bar_chart_stacked(&groups, 20);

pub fn bar_chart_stacked_with( &mut self, groups: &[BarGroup], configure: impl FnOnce(&mut BarChartConfig), max_height: u32, ) -> Response

Render a stacked bar chart with custom configuration.

Uses BarChartConfig for bar width, gap, and max value settings.

impl Context

pub fn set_scroll_speed(&mut self, lines: u32)

Set how many lines each scroll event moves. Default is 1.

pub fn scroll_speed(&self) -> u32

Get the current scroll speed (lines per scroll event).

pub fn focus_index(&self) -> usize

Get the current focus index.

Widget indices are assigned in the order register_focusable() is called. Indices are 0-based and wrap at focus_count().

pub fn set_focus_index(&mut self, index: usize)

Set the focus index to a specific focusable widget.

Widget indices are assigned in the order register_focusable() is called (0-based). If index exceeds the number of focusable widgets it will be clamped by the modulo in register_focusable.

Example

// Focus the second focusable widget (index 1)
ui.set_focus_index(1);

pub fn focus_count(&self) -> usize

Get the number of focusable widgets registered in the previous frame.

Returns 0 on the very first frame. Useful together with set_focus_index() for programmatic focus control.

Note: this intentionally reads prev_focus_count (the settled count from the last completed frame) rather than focus_count (the still-incrementing counter for the current frame).

pub fn widget<W: Widget>(&mut self, w: &mut W) -> W::Response

Render a custom Widget.

Calls Widget::ui with this context and returns the widget’s response.

pub fn error_boundary(&mut self, f: impl FnOnce(&mut Context))

Wrap child widgets in a panic boundary.

If the closure panics, the panic is caught and an error message is rendered in place of the children. The app continues running.

Example

ui.error_boundary(|ui| {
    ui.text("risky widget");
});

pub fn error_boundary_with( &mut self, f: impl FnOnce(&mut Context), fallback: impl FnOnce(&mut Context, String), )

Like error_boundary, but renders a custom fallback instead of the default error message.

The fallback closure receives the panic message as a String.

Example

ui.error_boundary_with(
    |ui| {
        ui.text("risky widget");
    },
    |ui, msg| {
        ui.text(format!("Recovered from panic: {msg}"));
    },
);

pub fn interaction(&mut self) -> Response

Allocate a click/hover interaction slot and return the Response.

Use this in custom widgets to detect mouse clicks and hovers without wrapping content in a container. Call it immediately before the text, rich text, link, or container that should own the interaction rect. Each call reserves one slot in the hit-test map, so the call order must be stable across frames.

pub fn register_focusable(&mut self) -> bool

Register a widget as focusable and return whether it currently has focus.

Call this in custom widgets that need keyboard focus. Each call increments the internal focus counter, so the call order must be stable across frames.

Slot reservation by register_focusable_named

If register_focusable_named was called immediately before this call, it has already allocated a slot and bound a name to it; this call reuses that slot instead of allocating a fresh one. That keeps the name binding pointed at the widget the user sees rather than at a dummy slot.

pub fn use_state<T: 'static>(&mut self, init: impl FnOnce() -> T) -> State<T>

Create persistent state that survives across frames.

Returns a State<T> handle. Access with state.get(ui) / state.get_mut(ui).

Rules

• Must be called in the same order every frame (like React hooks)
• Do NOT call inside if/else that changes between frames

Example

let count = ui.use_state(|| 0i32);
let val = count.get(ui);
ui.text(format!("Count: {val}"));
if ui.button("+1").clicked {
    *count.get_mut(ui) += 1;
}

pub fn use_state_named_with<T: 'static>( &mut self, id: &'static str, init: impl FnOnce() -> T, ) -> State<T>

Component-local persistent state keyed by a stable id.

Unlike use_state, this is not order-dependent — the value is looked up by id instead of call position. Safe to call inside conditional branches or reusable component functions.

Returns a State<T> handle. Access with state.get(ui) / state.get_mut(ui). Persists across frames.

Scoping

Keys are &'static str and live in a single global namespace per Context (no automatic per-component scoping). Two calls with the same id in the same frame share the same value, regardless of where they occur in the tree. Pick unique ids — for example, prefix with a component name ("counter::value").

Example

fn counter(ui: &mut slt::Context) {
    let count = ui.use_state_named_with("counter::value", || 0i32);
    ui.text(format!("Count: {}", count.get(ui)));
    if ui.button("+1").clicked {
        *count.get_mut(ui) += 1;
    }
}

pub fn use_state_named<T: 'static + Default>( &mut self, id: &'static str, ) -> State<T>

Like use_state_named_with, but uses Default::default() to initialize the value on first call.

Example

let value = ui.use_state_named::<i32>("counter::value");

pub fn animate_bool(&mut self, id: &'static str, value: bool) -> f64

Smoothly animate between 0.0 and 1.0 driven by a boolean.

Returns the current interpolated value (0.0..=1.0). When value is true the result tweens toward 1.0; when false it tweens back toward 0.0. The transition duration defaults to DEFAULT_ANIMATE_TICKS (12 ticks ≈ 200 ms at 60 Hz). Use Context::animate_value for custom duration or non-binary targets.

State is stored in the per-context named-state map under id. The id is &'static str (single global namespace per context), matching Context::use_state_named. Pick a unique key per call site — two animate_bool calls with the same id share state.

On the first call, the value snaps to the target with no visible transition (so widgets that mount in their final state don’t pop).

Example

let opacity = ui.animate_bool("sidebar::visible", is_open);
// 0.0 ≤ opacity ≤ 1.0; use as alpha or visibility threshold.

pub fn animate_value( &mut self, id: &'static str, target: f64, duration_ticks: u64, ) -> f64

Smoothly animate a f64 value toward target over duration_ticks.

Uses a linear-easing crate::Tween stored implicitly in the per-context named-state map under id. Returns the current interpolated value. On the first call the value snaps to target with no visible transition; on subsequent calls when target changes the tween is rebuilt starting from the current interpolated value, so retargeting mid-flight does not produce a jump.

duration_ticks == 0 snaps immediately to the new target.

Example

let bar_height = ui.animate_value("loading::bar", target_height, 30);
ui.bar(bar_height);

Comparison with Tween

Use this shorthand when you want zero boilerplate and linear easing is acceptable. For custom easing, a non-static key, or non-tick-based control, construct a crate::Tween explicitly via Context::use_state_named_with.

pub fn provide<T: 'static, R>( &mut self, value: T, body: impl FnOnce(&mut Context) -> R, ) -> R

Push a value onto the context stack for the duration of body.

Inside body, child widgets can call use_context::<T>() or try_use_context::<T>() to look up the nearest provided value of type T. Provides cascade in LIFO order: nested calls with the same T shadow outer ones.

The value is automatically popped when body returns — including on panic, so the context stack is always restored.

Example

struct Theme { accent: slt::Color }
ui.provide(Theme { accent: slt::Color::Red }, |ui| {
    // Any widget here can `let theme = ui.use_context::<Theme>();`
    render_button(ui);
});

pub fn use_context<T: 'static>(&self) -> &T

Look up the nearest provided value of type T on the context stack.

Searches from the top of the stack (most-recent provide) downward. Returns the first match.

Panics

Panics if no value of type T is currently provided. Use try_use_context for a non-panicking variant.

pub fn try_use_context<T: 'static>(&self) -> Option<&T>

Like use_context, but returns None instead of panicking when no value of type T is on the stack.

pub fn use_memo<T: 'static, D: PartialEq + Clone + 'static>( &mut self, deps: &D, compute: impl FnOnce(&D) -> T, ) -> &T

Memoize a computed value. Recomputes only when deps changes.

Example

let doubled = ui.use_memo(&count, |c| c * 2);
ui.text(format!("Doubled: {doubled}"));

pub fn light_dark(&self, light: Color, dark: Color) -> Color

Returns light color if current theme is light mode, dark color if dark mode.

pub fn notify(&mut self, message: &str, level: ToastLevel)

Show a toast notification without managing ToastState.

Examples

ui.notify("File saved!", ToastLevel::Success);

pub fn use_state_keyed<T: 'static>( &mut self, id: impl Into<String>, init: impl FnOnce() -> T, ) -> State<T>

Component-local persistent state keyed by a runtime string.

Unlike use_state_named, id can be a runtime value such as format!("row-{i}"). The key is converted to String once per call. The hot path (key already present) performs zero string allocations beyond the Into<String> conversion at the call site — first looking up by &str, only allocating a fresh map key on first insert. Together: at most one allocation per call, regardless of cache state.

When to use

• Per-item state in a dynamic list where positional use_state would break if items are reordered or filtered.
• Reusable component functions called with a runtime discriminator.

Namespace

Keys live in a single global namespace per Context. Prefix them to avoid collisions: format!("my_component::item-{i}").

Stale entries

Removed items leak their state until the Context is dropped (or the program exits). For long-running sessions with churn, manage state externally via a single Vec<T> in use_state.

Example

for (i, item) in items.iter().enumerate() {
    let row_state = ui.use_state_keyed(format!("row-{i}"), || ItemState::default());
    // ...
}

pub fn use_state_keyed_default<T: Default + 'static>( &mut self, id: impl Into<String>, ) -> State<T>

Like use_state_keyed, but uses Default::default() to initialize the value on first call.

Example

let counter = ui.use_state_keyed_default::<i32>(format!("c-{i}"));

pub fn use_effect<D: PartialEq + Clone + 'static>( &mut self, f: impl FnOnce(&D), deps: &D, )

Run a side-effecting closure when deps changes.

On the first frame the hook slot is encountered, f is called unconditionally. On subsequent frames, f is only called when *deps != stored_deps. The hook is positional (same ordering rules as use_state).

Fire-and-forget semantics

There is no cleanup callback. If setup resources need teardown, store a handle in use_state and drop it on a later frame.

Caveat: error_boundary re-fire

Effects placed inside an error_boundary scope can re-fire when the boundary catches a panic and rolls back the hook slots. For non-idempotent side effects (network requests, payments) put the effect outside the boundary or guard with an idempotency key.

Common patterns

// Run once on first frame:
ui.use_effect(|_| initialize_logger(), &());

// Run when `selected_tab` changes:
ui.use_effect(|tab| load_tab_data(*tab), &selected_tab);

pub fn register_focusable_named(&mut self, name: &str) -> bool

Register a focusable slot bound to a stable string name.

Returns true if the registered slot currently has focus, exactly like register_focusable — but also records the name → slot mapping so other code can later call focus_by_name and focused_name.

How the slot is shared with the widget that follows

Every SLT widget that takes focus (button, text_input, tabs, …) internally calls register_focusable() to claim its own slot. To keep the name pointed at the widget the user sees, this call:

1. allocates a slot eagerly (so the name binding works even when no widget follows — useful for tests and for custom focusable regions),
2. records the name → slot mapping into the frame’s focus_name_map (first-write-wins on duplicate names within a frame),
3. reserves the slot id so the next register_focusable() on the same frame reuses it instead of allocating a fresh slot — that’s how text_input(&mut state) placed right after inherits the name.

Names are re-registered each frame; the previous frame’s map is kept under focus_name_map_prev so [focus_by_name] can resolve a name that has already been registered.

Two valid usage shapes

Shape A — name a widget that follows immediately (the common pattern; the widget reuses the reserved slot):

let _ = ui.register_focusable_named("search");
let _ = ui.text_input(&mut search_state);
// later: ui.focus_by_name("search") jumps to the text_input

Shape B — register a named focusable region with no inner widget (e.g. a custom render area that handles its own keys when focused):

let focused = ui.register_focusable_named("canvas");
if focused { /* react to keys via key_presses_when */ }

pub fn focus_by_name(&mut self, name: &str) -> bool

Request focus on the named widget.

If the named widget was registered last frame the focus change takes effect at the start of the next frame (one-frame delay is the deferred-command pattern used throughout SLT). If the name has never been registered, the request stays pending: the next frame to register that name receives focus.

Returns true if the call will resolve — i.e. the name was either registered earlier in this frame (via register_focusable_named) or in the previous frame. Returns false only when the name has not been seen by either frame, in which case the request stays pending until some future frame registers the name.

Example

if ui.button("Find").clicked {
    ui.focus_by_name("search");
}

pub fn focused_name(&self) -> Option<&str>

Return the name of the currently focused widget, if it was registered with register_focusable_named this frame.

Returns None if the focused widget used the unnamed register_focusable API or if no widget has focus.

pub fn key_presses_when( &self, active: bool, ) -> impl Iterator<Item = (usize, &KeyEvent)> + '_

Iterate unconsumed key-press events, gated on active.

When active is false, returns an empty iterator. When active is true, behaves identically to the internal available_key_presses. The returned indices are valid for consume_event.

This is the preferred pattern for focus-gated keyboard handling in custom widgets. Because the iterator borrows self.events immutably, collect the indices first and consume them after the loop:

let focused = ui.register_focusable();
let mut hits: Vec<usize> = Vec::new();
for (i, key) in ui.key_presses_when(focused) {
    if key.code == slt::KeyCode::Enter {
        hits.push(i);
        // ... handle Enter ...
    }
}
for i in hits { ui.consume_event(i); }

pub fn consume_event(&mut self, index: usize)

Mark the event at index as consumed.

Public counterpart to the crate-internal consume_indices. Use this in custom widgets after handling an event yielded by key_presses_when so subsequent widgets don’t react to the same key. Out-of-range indices are silently ignored (matching the iterator-pair semantics).

pub fn static_log(&mut self, line: impl Into<String>)

Append a line that will be flushed to terminal scrollback before the dynamic frame content (issue #233).

Lines accumulated this frame are written via the active runtime — for crate::run_static / crate::run_static_with, they are printed above the inline dynamic area as committed scrollback. For full-screen runtimes (crate::run, crate::run_async) and inline mode (crate::run_inline), the buffer is silently dropped after a debug warning is emitted on the first call per frame, since those modes have no scrollback area to write to.

The headless crate::TestBackend accumulates the lines into the frame state where they can be drained by tests via Context::take_static_log (or by inspecting the buffer when constructing a custom backend).

Order

static_log may be called any number of times per frame. Lines are flushed in call order, all before the dynamic frame for the same tick.

Example

ui.static_log("event 1");
ui.static_log(format!("event {}", 2));
ui.text("dynamic content");

pub fn take_static_log(&mut self) -> Vec<String>

Drain and return the queued static-log lines for the current frame (issue #233). Used by tests / external backends to inspect what ui.static_log(...) emitted during a crate::TestBackend::render call.

pub fn publish_keymap( &mut self, name: &'static str, bindings: &'static [(&'static str, &'static str)], )

Publish a widget’s keymap so the framework can show it in the help overlay (issue #236).

Each call registers (name, bindings) for the current frame. Widgets implementing crate::keymap::WidgetKeyHelp typically forward their key_help() slice here:

struct Counter;
impl WidgetKeyHelp for Counter {
    fn key_help(&self) -> &'static [(&'static str, &'static str)] {
        const HELP: &[(&str, &str)] = &[("↑", "increment"), ("↓", "decrement")];
        HELP
    }
}
let counter = Counter;
ui.publish_keymap("counter", counter.key_help());

The registry is reset at the start of every frame (the first call on a new tick clears stale entries). Both calls in the same frame accumulate; calls across frames do not leak.

pub fn published_keymaps(&self) -> &[PublishedKeymap]

Return all keymaps published this frame (issue #236).

Empty if no widget called Context::publish_keymap yet on the current frame. The registry is reset at the start of every frame.

pub fn keymap_help_overlay(&mut self, open: bool)

Render an automatic keymap-help overlay listing every widget keymap published this frame (issue #236).

Pass open = true to render the overlay (typically gated on a ? / F1 keypress). When open is false, this method is a no-op. The overlay groups bindings by widget name and dismisses when the next frame is rendered with open = false.

Example

const RICHLOG: &[(&str, &str)] = &[("↑/k", "scroll up"), ("↓/j", "scroll down")];
ui.publish_keymap("rich_log", RICHLOG);
// Show the help overlay when '?' is pressed
let show = ui.key('?');
ui.keymap_help_overlay(show);