Crate artbox 

artbox

ASCII art toolkit: FIGlet text, sprites, and image rendering with colors, gradients, and ratatui integration.

artbox renders text using FIGlet fonts with automatic font selection, layered sprites with per-layer fills, and image-to-ASCII conversion — all into bounded rectangles with alignment and color support.

Quick Start

use artbox::{render, Renderer, Alignment};

// Simple rendering with defaults
let result = render("Hello", 40, 10).unwrap();
println!("{}", result.to_plain_string());

// Custom renderer with alignment
let renderer = Renderer::default()
    .with_alignment(Alignment::Center);
let result = renderer.render("Hi", 20, 5).unwrap();

Font Selection

The renderer tries fonts in order until one fits within the specified bounds. The default font stack progresses from large to small: big → standard → small → mini.

use artbox::{Renderer, fonts};

// Use a specific font family
let renderer = Renderer::new(fonts::family("blocky").unwrap());

// Or build a custom stack
let renderer = Renderer::new(fonts::stack(&["slant", "small_slant"]));

Features

• images - Image-to-ASCII conversion and terminal image protocols (kitty, iTerm2).
• ratatui - ArtBox and SpriteBox widgets for TUI applications.
• cli - Enables the artbox binary (requires images).

Colors and Gradients

artbox supports solid colors, linear gradients, and radial gradients:

use artbox::{Renderer, Fill, LinearGradient, ColorStop, Color};

let renderer = Renderer::default()
    .with_fill(Fill::Linear(LinearGradient {
        angle: 45.0,
        stops: vec![
            ColorStop::new(0.0, Color::rgb(255, 0, 0)),
            ColorStop::new(1.0, Color::rgb(0, 0, 255)),
        ],
    }));

let styled = renderer.render_grid("Hi", 20, 5).unwrap();
println!("{}", styled.to_ansi_string());

Re-exports

pub use color::Color;

pub use color::ColorStop;

pub use color::Fill;

pub use color::Hsl;

pub use color::LinearGradient;

pub use color::RadialGradient;

pub use color::Rgb;

pub use sprites::Sprite;

pub use sprites::SpriteError;

pub use sprites::SpriteLayer;

pub use sprites::SpriteMetrics;

pub use sprites::SpriteRendered;

pub use sprites::SpriteSelection;

pub use sprites::SpriteSize;

pub use sprites::SpriteVariant;

Modules

color

Color types and gradient definitions for styled ASCII art rendering.

fonts

Embedded FIGlet fonts and font management utilities.

integrations

Framework integrations for artbox.

sprites

Sprite rendering for ASCII art images with layered colors and size variants.

Structs

Artbox

Unified entrypoint for text, sprite, and image rendering.

Font

A font that can be used to render text as ASCII art.

GridRendered

The result of a render operation that yields a styled character grid.

RenderMetrics

Metrics about a rendered result without the text content.

RenderTarget

A shared render target for text, sprites, and images.

Renderer

Renders text as ASCII art within specified bounds.

StyledChar

A single character with optional foreground color.

TextRendered

Lightweight text-only render result.

Enums

Alignment

Specifies how rendered text is aligned within the bounding box.

Error

Unified error type for all artbox operations.

FontError

Errors that can occur when loading or parsing fonts.

RenderError

Errors that can occur during rendering.

Rendered

Unified render output for text, sprites, and images.

Functions

render

Renders text using the default renderer.