tui-slider

A highly customizable and configurable slider widget for ratatui that puts you in full control of every visual aspect.

Whether you're building music players, audio mixers, settings panels, or progress indicators, tui-slider adapts to your needs with extensive customization options. Configure colors, symbols, orientations, alignments, borders, and behavior—all through a clean, intuitive API. From minimalist progress bars to feature-rich interactive sliders, you decide exactly how your UI looks and feels.

✨ Features

• 🎚️ Horizontal and Vertical sliders - Support for both orientations
• 🎨 Border styles - Multiple border style options with customizable symbols
• 🎯 Title alignment - Left, center, and right title positioning
• 📊 Value alignment - Flexible value display positioning
• 📍 Vertical positioning - Label and value positioning for vertical sliders
• 🎨 Progress bars - Use as progress indicators without handles
• 🎨 Optional theming - Shared tui-nuances themes behind the theme feature
• 🔧 Easy to use - Minimal configuration required
• 📊 State management - Built-in state for value tracking

📦 Installation

Add to your Cargo.toml:

[dependencies]
tui-slider = "0.4"
ratatui = "0.30"

Optional features:

Feature	Adds
theme	shared theming via tui-nuances (.theme(), Themed)
crossterm	SliderState::handle_key / handle_mouse for crossterm events

tui-slider = { version = "0.4", features = ["crossterm"] }

match event::read()? {
    Event::Key(key) => { state.handle_key(key); }
    Event::Mouse(m) => { state.handle_mouse(m, slider_area, SliderOrientation::Horizontal); }
    _ => {}
}

Keys: arrows step, PageUp/PageDown move 10 steps, Home/End jump to min/max. Mouse: click or drag to set, scroll wheel to step.

Minimum supported Rust version: 1.88.

🚀 Quick Start

use ratatui::prelude::*;
use tui_slider::{Slider, SliderState, SliderOrientation};

fn main() {
    // Create a slider state
    let mut state = SliderState::new(50.0, 0.0, 100.0);
    
    // Create and render a slider
    let slider = Slider::from_state(&state)
        .orientation(SliderOrientation::Horizontal)
        .label("Volume")
        .show_value(true);
    
    // In your render loop
    frame.render_widget(slider, area);
    
    // Update the value
    state.set_value(75.0);
}

📖 Examples

📚 Examples Source Code → - View all example implementations

🎛️ Comprehensive Demo

A small studio mixer: vertical channel faders, horizontal controls (negative range, 0.1 steps, segmented bars), keyboard and mouse control via the crossterm feature, and theme switching.

🚀 cargo run --example comprehensive --features theme,crossterm | 📄 View Source

🎯 Quick Navigation

• Comprehensive Demo

• Horizontal Sliders

• Vertical Sliders

• Styling & Customization

• Interactive Features

• Layout & Positioning

• Complete Example Index

---

Horizontal Sliders

Horizontal Slider Styles

Comprehensive horizontal slider styles organized into two pages:

• Page 1: Standard Styles - Basic lines, blocks, gradients, progress bars (9 styles)
• Page 2: Specialty Styles - Segmented, dots, squares, stars (7 styles)

use tui_slider::{Slider, SliderState, SliderOrientation};

let state = SliderState::new(75.0, 0.0, 100.0);
let slider = Slider::from_state(&state)
    .orientation(SliderOrientation::Horizontal)
    .filled_symbol("━")
    .empty_symbol("─")
    .handle_symbol("●")
    .show_value(true);

🚀 cargo run --example horizontal | 📄 View Source

Use n/PageDown and p/PageUp to navigate between style pages.

---

Vertical Sliders

Basic Vertical Styles

Vertical slider orientation with various visual styles, perfect for mixer interfaces.

let slider = Slider::from_state(&state)
    .orientation(SliderOrientation::Vertical)
    .filled_symbol("█")
    .empty_symbol("░")
    .handle_symbol("▬");

🚀 cargo run --example vertical | 📄 View Source

---

Vertical Positioning

Layout strategies and positioning techniques for vertical sliders.

Labels and values are centred on the bar itself, so they stay aligned at any area width (even-width text on a one-column bar sits half a cell to the left, consistently).

🚀 cargo run --example vertical_positioning | 📄 View Source

---

Styling & Customization

Custom Styles

Create your own slider styles with custom RGB colors and symbol combinations.

use tui_slider::SliderStyle;

let style = SliderStyle::horizontal_thick();
let slider = Slider::from_state(&state).style(&style);

🚀 cargo run --example custom | 📄 View Source

---

Borders

Border types, styles, and color theming - including Plain, Rounded, Double, Thick borders with full, segmented, and sides-only variations.

🚀 cargo run --example borders | 📄 View Source

---

Interactive Features

Handle/Thumb Visibility

Side-by-side comparison of sliders with handles (interactive controls) vs without handles (progress bars). Shows the same sliders in both modes to clearly demonstrate the difference.

🚀 cargo run --example handles | 📄 View Source

Use Tab to switch between left (with handles) and right (without handles) sections.

---

Step Sizes

Configurable step intervals for fine or coarse value adjustments.

🚀 cargo run --example step_sizes | 📄 View Source

---

Layout & Positioning

Title Alignment

Position slider titles left, center, or right.

🚀 cargo run --example title_alignment | 📄 View Source

---

Value Alignment

Control value display positioning for optimal layout.

🚀 cargo run --example value_alignment | 📄 View Source

---

Horizontal Bar Alignment

Position horizontal slider bars at the top, center, or bottom of the container.

🚀 cargo run --example horizontal_bar_alignment | 📄 View Source

---

📋 Complete Example Index

Example	Category	Description	Demo	Source
horizontal.rs	Horizontal	Comprehensive horizontal styles (2 pages: Standard & Specialty)	GIF	Code
vertical.rs	Vertical	Various vertical slider styles	GIF	Code
vertical_positioning.rs	Vertical	Vertical layout strategies	GIF	Code
custom_symbols.rs	Styling	Custom RGB colors and symbols	GIF	Code
borders.rs	Styling	Border types, styles, and colors	GIF	Code
handles.rs	Interactive	Handle visibility comparison (with/without)	GIF	Code
step_sizes.rs	Interactive	Configurable step intervals	GIF	Code
title_alignment.rs	Layout	Title positioning options	GIF	Code
value_alignment.rs	Layout	Value display positioning	GIF	Code
horizontal_bar_alignment.rs	Layout	Horizontal bar vertical positioning (top/center/bottom)	GIF	Code

---

🎨 Theming

tui-slider shares one Theme with the other components via the tui-nuances crate. Theming is optional and off by default; enable the theme feature to use it. Without it the look is unchanged and tui-nuances is not built.

[dependencies]
tui-slider = { version = "0.4", features = ["theme"] }

use tui_slider::{Slider, SliderStyle, Theme, Themed};

let theme = Theme::by_name("tokyo-night").unwrap();
let slider = Slider::from_state(&state).theme(&theme);   // filled=primary, empty=disabled, handle/text=foreground
let style = SliderStyle::blocks().theme(&theme);          // themed reusable style

// Pass your app's theme through ThemeProvider (or `impl From<&AppTheme> for Theme`):
let slider = Slider::from_state(&state).themed(&app_theme);

Precedence: colors set explicitly (filled_color, empty_color, handle_color, style) win over the theme, before or after .theme(). A Block gets the theme's border/surface as its base style; its own border_style/title_style still win. SliderStyle::theme overrides all three colors, so call its color setters afterwards.

🎮 Common Controls

Most examples share similar keyboard controls:

• ↑/↓ or j/k - Navigate between sliders
• ←/→ or h/l - Adjust slider values
• t / T - Next / previous theme (all built-in tui-nuances themes; examples need --features theme)
• q or ESC - Quit the example

Check each example's source code for specific controls and features.

🎮 Interactive Usage

use tui_slider::SliderState;

let mut state = SliderState::new(50.0, 0.0, 100.0);

// Increase/decrease by a step
state.increase(5.0);
state.decrease(5.0);

// Set exact value
state.set_value(75.0);

// Get current value
let current = state.value();

// Get as percentage (0.0 to 1.0)
let percentage = state.percentage();

// Mouse support: map a terminal column to a value and back.
// Cell 0 is min and the last cell (width - 1) is max, matching the rendered handle.
let bar_width = 40;
state.set_from_cell(39, bar_width); // click on last cell -> 100%
let handle_column = state.cell(bar_width); // 39

// Vertical sliders: row 0 is the top (max), the last row is the bottom (min)
state.set_from_cell_vertical(0, 12); // click on top row -> 100%
let handle_row = state.cell_vertical(12); // 0

set_from_position / position map 0..=length instead, so the last cell of a bar never reaches 100%. Prefer set_from_cell / cell for terminal columns.

🎯 API Overview

Slider Widget

• new(value, min, max) - Create a new slider
• from_state(&state) - Create from a state
• orientation(orientation) - Set horizontal or vertical
• label(text) - Set label text
• show_value(bool) - Show/hide value display
• show_handle(bool) - Show/hide handle
• style(&SliderStyle) - Apply symbols, colors, and segmented rendering
• segmented(bool) - Enable/disable one-cell gaps between bar symbols
• filled_symbol(symbol) - Set filled bar symbol
• empty_symbol(symbol) - Set empty bar symbol
• handle_symbol(symbol) - Set handle symbol
• filled_color(color) - Set filled bar color
• empty_color(color) - Set empty bar color
• handle_color(color) - Set handle color
• show_thumb(bool) - Alias for show_handle
• vertical_label_position(position) - Set label position for vertical sliders
• vertical_value_position(position) - Set value position for vertical sliders
• vertical_value_alignment(alignment) - Set value alignment for vertical sliders
• horizontal_bar_alignment(alignment) - Set bar row for horizontal sliders
• block(block) - Add border block

SliderState

• new(value, min, max) - Create new state
• value() - Get current value
• set_value(value) - Set value
• increase(step) - Increase by step
• decrease(step) - Decrease by step
• min() / max() - Get bounds
• set_min(min) / set_max(max) - Set bounds
• percentage() - Get value as percentage (0.0-1.0)
• set_percentage(percentage) - Set from percentage

🏗️ Architecture

The library consists of reusable components:

• Slider - Widget rendering, layout, symbols, colors, and handles
• SliderState - Value, bounds, steps, percentages, and position conversion
• SliderStyle - Reusable style presets and custom style configuration
• SliderOrientation - Horizontal or vertical orientation
• Position types - Label, value, and horizontal-bar alignment
• Border helpers - Border sets, title alignment, and title positioning

🛠️ Development

This project uses just as a command runner for common development tasks.

Quick Setup

Install development tools through the checked-in justfile:

cargo install just
just install-tools

Manual Setup

If you prefer manual installation:

# Install just
cargo install just

# Install git-cliff (optional, for changelogs)
cargo install git-cliff

# View available commands
just --list

Common Commands

just build              # Build the project
just test               # Run tests
just check-all          # Run all checks (fmt, clippy, test)
just run                # Run horizontal slider example
just examples           # Run all examples
just bump <version>     # Bump version (runs checks first)

For a complete list of available commands, run just --list or see the justfile.

Justfile Patterns

This project follows the "fail early" pattern for version bumps and releases:

• just bump <version> runs all checks (fmt, clippy, test) before bumping
• just release <version> depends on bump, ensuring quality before release
• All destructive operations have quality gates

See Justfile Best Practices & Patterns for detailed documentation.

🧪 Fuzzing

Coverage-guided fuzz targets live in fuzz/ (needs nightly + cargo install cargo-fuzz):

cargo +nightly fuzz list
cargo +nightly fuzz run slider_render

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ratatui
• Inspired by various TUI music players and audio applications

📝 Changelog

See CHANGELOG.md for a list of changes.