tui-checkbox

A customizable checkbox widget for Ratatui TUI applications.

🏠 Hosting

This project is hosted on multiple platforms for redundancy:

• 🐙 GitHub - sorinirimies/tui-checkbox

  • Primary public repository
  • CI/CD with GitHub Actions
  • Issue tracking and discussions

• 🍵 Gitea - Self-hosted mirror (optional)

  • Full backup and redundancy
  • CI/CD with Gitea Actions
  • Independent deployment option

Both repositories are kept in sync automatically. See DUAL_HOSTING.md for setup details.

Preview

Features

• ☑️ Simple checkbox with label
• 🎨 Customizable styling for checkbox and label separately
• 🔤 Custom symbols (unicode, emoji, ASCII)
• 📦 Optional block wrapper
• ⚡ 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"));

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 DUAL_HOSTING.md for complete dual hosting setup guide.

See all available commands:

just --list

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

This widget was created for the Ratatui ecosystem.

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