{{project-name}}

A ratatui-kit component crate.

The gif above is produced by vhs tapes/demo.tape. Until you record it once, the image link is expected to be broken — see Record the demo gif.

---

What's inside

This crate was generated from the official ratatui-kit-component-template. It ships a small, working shape you can replace with your own component:

• Badge — a colored tag component (#[component] + #[with_layout_style] + #[derive(Props)]), with a BadgeTone enum for its color palette.
• use_render_count — a custom hook (a Hook impl exposed through an extension trait) that counts how many times a component has rendered.
• examples/demo.rs — a runnable Tokio app that renders every badge tone and the render counter.

Everything follows the framework's authoring contract (see COMPONENT_GUIDE.md and EXTENSION_API.md in the framework repo).

Install

[dependencies]
{{project-name}} = "0.1"

Usage

use ratatui_kit::prelude::*;
use {{crate_name}}::{Badge, BadgeTone};

#[tokio::main]
async fn main() {
    element!(Badge(label: "ready".to_string(), tone: BadgeTone::Success))
        .fullscreen()
        .await
        .expect("failed to run the application");
}

Badge is a transparent-layout function component: it inherits the layout of the element it returns. Its layout props (width, height, margin, …) are forwarded onto the returned root, so Badge(width: Constraint::Length(10)) works as you'd expect.

Develop

Run the demo (press q to quit, Ctrl+C to force-exit):

cargo run --example demo

Run the same checks CI runs:

cargo test --all-features --lib --tests --examples
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items --all-features --examples

Record the demo gif

The demo gif is recorded with VHS, using the same recording standard as the main ratatui-kit docs (Catppuccin Mocha theme, 1000x600, font size 18, truecolor env). The tape lives at tapes/demo.tape:

Output assets/demo.gif

Set Width 1000
Set Height 600
Set FontSize 18
Set Theme "Catppuccin Mocha"
Set TypingSpeed 30ms

Env TERM "xterm-256color"
Env COLORTERM "truecolor"
Env NO_COLOR ""

Type "cargo run --quiet --example demo"
Enter
Sleep 5s
Type "q"
Sleep 1s

Install VHS (brew install vhs, or see the VHS README), then record:

vhs tapes/demo.tape          # writes assets/demo.gif

Commit the resulting assets/demo.gif so it renders at the top of this README and on your repo page. Tweak the Sleep durations if your demo needs more time on screen.

Generated from the template

To scaffold another component crate from the same template:

cargo generate yexiyue/ratatui-kit-component-template --name ratatui-kit-<name>

Name your crate ratatui-kit-<name> (e.g. ratatui-kit-markdown) so it is discoverable in the ecosystem.

Rename escape hatch

The element! / #[component] macros expand to absolute ::ratatui_kit::… paths, which resolve as long as the dependency is named ratatui-kit. If you rename it via Cargo:

[dependencies]
rk = { package = "ratatui-kit", version = ">=0.8, <0.9" }

add this at your crate root so the macro paths resolve again (a standard Rust mechanism):

extern crate rk as ratatui_kit;

Publish checklist

Follow the COMPONENT_GUIDE.md checklist before publishing:

• Depends only on the Extension API surface; ratatui / crossterm reached via ratatui_kit::ratatui / ratatui_kit::crossterm (no direct ratatui dependency)
• Heavy deps are optional + feature-gated; default features stay minimal
• Runtime panic / error messages are English
• All examples and doctests compile (cargo test --all-features)
• ratatui-kit pinned with a version range (ratatui-kit = ">=0.8, <0.9")
• keywords include ratatui-kit
• Layout props live on the returned root element (transparent-layout)
• assets/demo.gif recorded and committed

Then release:

# bump version in Cargo.toml, commit, then:
git tag v0.1.0
git push --tags        # the release workflow runs `cargo publish`

cargo publish needs a CARGO_REGISTRY_TOKEN repository secret (a crates.io API token). Consider listing your crate in awesome-ratatui-kit.

License

Released under the MIT License.