tui-checkbox

A customizable checkbox widget for Ratatui TUI applications.

Preview

Features

• ☑️ Simple checkbox with label
• 🎨 Customizable styling for checkbox and label separately
• 🔤 Custom symbols (unicode, emoji, ASCII)
• 📦 Block wrapper - optional
• 📍 Label positioning (right, left, top, bottom) - optional
• ↔️ Horizontal & vertical alignment - optional
• 📏 Width constraints (min/max) - optional
• 📝 Text wrapping for long labels - optional
• ⚡ Zero-cost abstractions

Installation

Add this to your Cargo.toml:

[dependencies]
tui-checkbox = "0.2.0"
ratatui = "0.29"

Or install with cargo:

cargo add tui-checkbox

Quick Start

use ratatui::style::{Color, Style, Modifier};
use tui_checkbox::Checkbox;

// Basic checkbox
let checkbox = Checkbox::new("Enable feature", true);

// Styled checkbox
let checkbox = Checkbox::new("Enable feature", true)
    .style(Style::default().fg(Color::White))
    .checkbox_style(Style::default().fg(Color::Green).add_modifier(Modifier::BOLD))
    .label_style(Style::default().fg(Color::Gray));

// Custom symbols
let checkbox = Checkbox::new("Task", false)
    .checked_symbol("✅ ")
    .unchecked_symbol("⬜ ");

// With a block
use ratatui::widgets::Block;

let checkbox = Checkbox::new("Accept terms", false)
    .block(Block::bordered().title("Settings"));

Label Positioning

Control where the label appears relative to the checkbox symbol.

Note: All layout features are optional! The checkbox works perfectly with sensible defaults. Only use these methods when you need to customize the layout.

use tui_checkbox::{Checkbox, LabelPosition};

// Simple checkbox - works great with defaults!
Checkbox::new("Enable feature", true);

// Label on the left (optional customization)
Checkbox::new("Enable feature", true)
    .label_position(LabelPosition::Left);

// Label on top (optional customization)
Checkbox::new("Enable feature", false)
    .label_position(LabelPosition::Top);

// Label on bottom (optional customization)
Checkbox::new("Enable feature", false)
    .label_position(LabelPosition::Bottom);

Defaults: Label on the right (standard checkbox style)

Alignment (Optional)

Align the checkbox content within its area. Only needed for specific layouts.

use tui_checkbox::{Checkbox, HorizontalAlignment, VerticalAlignment};

// Horizontal alignment (optional)
Checkbox::new("Centered", true)
    .horizontal_alignment(HorizontalAlignment::Center);

Checkbox::new("Right", true)
    .horizontal_alignment(HorizontalAlignment::Right);

// Vertical alignment (optional)
Checkbox::new("Middle", false)
    .vertical_alignment(VerticalAlignment::Center);

Checkbox::new("Bottom", false)
    .vertical_alignment(VerticalAlignment::Bottom);

Defaults: Left and top aligned

Width Constraints & Text Wrapping (Optional)

Set minimum and maximum width constraints, and enable text wrapping when needed.

// Minimum width (optional)
Checkbox::new("Small label", true)
    .min_width(30);

// Maximum width (optional)
Checkbox::new("This is a very long label that will be constrained", false)
    .max_width(25);

// Text wrapping (optional - for long labels)
Checkbox::new("This is a very long label that demonstrates text wrapping", true)
    .wrap_label(true)
    .max_width(30);

Defaults: No width constraints, no wrapping

Layout Examples

Label Position Example

See all four label positions in action:

cargo run --example checkbox_label_position

This demonstrates: right, left, top, and bottom label positions.

Alignment Example

See horizontal and vertical alignment:

cargo run --example checkbox_alignment

This demonstrates:

• Horizontal alignment: left, center, right
• Vertical alignment: top, center, bottom

Width & Wrapping Example

See width constraints and text wrapping:

cargo run --example checkbox_width_wrapping

This demonstrates:

• Minimum and maximum width constraints
• Text wrapping (enabled vs disabled)
• Combined features

Examples

Run the included example with two modes:

cargo run --example checkbox

Interactive Mode (Default)

Navigate and toggle checkboxes with your keyboard:

• ↑/↓ or k/j - Navigate between checkboxes
• Space - Toggle checkbox state
• Tab - Switch to API Showcase mode
• q or Esc - Quit

The interactive mode demonstrates:

• Basic checkbox with default styling
• Styled checkboxes with colors (Info, Warning, Error)
• Emoji and Unicode symbols (✅, ●, ◆)
• Custom ASCII symbols ([X], [*], [+]/[-], (X)/(O))

API Showcase Mode

Press Tab to switch to the API showcase view, which displays all available features:

• All core API methods (new(), default(), label(), checked())
• All styling methods (style(), checkbox_style(), label_style())
• Symbol customization (checked_symbol(), unchecked_symbol())
• All predefined symbols from the symbols module
• Advanced usage (blocks, Styled trait, method chaining)

Styling

The widget supports multiple styling options:

• style(): Sets the base style for the entire widget
• checkbox_style(): Sets the style specifically for the checkbox symbol
• label_style(): Sets the style specifically for the label text

Styles are applied in order: base style, then specific styles override it.

Custom Symbols

The widget comes with default Unicode checkbox symbols (☐ and ☑), but you can use any symbols:

// Emoji style
Checkbox::new("Task", true)
    .checked_symbol("✅ ")
    .unchecked_symbol("⬜ ");

// ASCII style
Checkbox::new("Task", false)
    .checked_symbol("[X]")
    .unchecked_symbol("[ ]");

// Circle style
Checkbox::new("Task", true)
    .checked_symbol("● ")
    .unchecked_symbol("○ ");

Predefined Symbols

The symbols module provides some common checkbox symbols:

• symbols::CHECKED - ☑
• symbols::UNCHECKED - ☐
• symbols::CHECKED_X - [X]
• symbols::UNCHECKED_SPACE - [ ]
• symbols::CHECKED_ASTERISK - [*]
• symbols::CHECKED_PLUS - [+]
• symbols::UNCHECKED_MINUS - [-]
• symbols::CHECKED_PARENTHESIS_X - (X)
• symbols::UNCHECKED_PARENTHESIS_O - (O)

Development

Prerequisites

• Rust 1.74.0 or later
• just - command runner (optional)
• git-cliff - changelog generator (optional)

Install tools:

just install-tools

Common Tasks

# Run example
just run

# Run tests
just test

# Format and lint
just fmt
just clippy

# Check all (format, clippy, tests)
just check-all

# Release check (format, clippy, test, build)
just release-check

# Generate demo GIF (requires VHS)
just vhs

Release Workflow

# Release to GitHub only
just release 0.2.0

# Release to Gitea only (if configured)
just release-gitea 0.2.0

# Release to both GitHub and Gitea
just release-all 0.2.0

The release commands automatically:

1. Bump version in Cargo.toml
2. Update Cargo.lock
3. Generate changelog with git-cliff
4. Create git commit and tag
5. Push to the selected remote(s)

Dual Hosting Commands

If you have a Gitea instance configured:

# Setup Gitea remote
just setup-gitea git@gitea.yourdomain.com:username/tui-checkbox.git

# Push to both GitHub and Gitea
just push-all

# Sync Gitea with GitHub
just sync-gitea

# Show configured remotes
just remotes

See all available commands:

just --list

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository on GitHub
2. Create a feature branch from main
3. Make your changes with clear commit messages
4. Submit a pull request to the main repository

All contributions must be made through GitHub pull requests from your fork. Please see CONTRIBUTING.md for detailed guidelines.

Acknowledgments

This widget was created for the Ratatui ecosystem.

Special thanks to the Ratatui team for creating such an amazing TUI framework.