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
• 🔧 Easy to use - Minimal configuration required
• 📊 State management - Built-in state for value tracking
• ⚡ Lightweight - No complex dependencies

📦 Installation

Add to your Cargo.toml:

[dependencies]
tui-slider = "0.1"
ratatui = "0.28"

🚀 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

🎯 Quick Navigation

• 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 Style Variations

Various vertical slider styles optimized for different use cases.

🚀 cargo run --example vertical | 📄 View Source

---

Vertical Positioning

Layout strategies and positioning techniques for vertical sliders.

🚀 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::style::SliderStyle;

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

🚀 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

---

🎮 Common Controls

Most examples share similar keyboard controls:

• ↑/↓ or j/k - Navigate between sliders
• ←/→ or h/l - Adjust slider values
• 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();

🎯 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
• 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_handle(bool) - Show/hide thumb indicator
• 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
• 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 three main components:

• Slider - The widget that renders the slider
• SliderState - Manages value, bounds, and state
• SliderOrientation - Horizontal or Vertical orientation

🛠️ Development

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

Quick Setup

Run the interactive setup script to install just and configure your environment:

./scripts/setup-just.sh

This script will:

• Install just command runner (if not already installed)
• Create a new justfile if one doesn't exist (with common commands)
• Enhance existing justfile with missing commands (optional)
• Install optional tools like git-cliff for changelog generation
• Set up shell completion
• Create backups before modifying files

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.

🤝 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.