Crate iocraft

Expand description

§iocraft

iocraft is a library for crafting beautiful text output and interfaces for the terminal or logs. It allows you to easily build complex layouts and interactive elements using a declarative API.

§Features

Define your UI using a clean, highly readable syntax.
Organize your UI using flexbox layouts powered by taffy.
Output colored and styled UIs to the terminal or ASCII output anywhere else.
Create animated or interactive elements with event handling and hooks.
Build fullscreen terminal applications with ease.
Pass props and context by reference to avoid unnecessary cloning.

§Getting Started

If you’re familiar with React, you’ll feel right at home with iocraft. It uses all the same concepts, but is text-focused and made for Rust.

Here’s your first iocraft program:

use iocraft::prelude::*;

fn main() {
    element! {
        View(
            border_style: BorderStyle::Round,
            border_color: Color::Blue,
        ) {
            Text(content: "Hello, world!")
        }
    }
    .print();
}

Your UI is composed primarily via the element! macro, which allows you to declare your UI elements in a React/SwiftUI-like syntax.

iocraft provides a few built-in components in the components module, such as View, Text, and TextInput, but you can also create your own using the component macro.

For example, here’s a custom component that uses a hook to display a counter which increments every 100ms:

#[component]
fn Counter(mut hooks: Hooks) -> impl Into<AnyElement<'static>> {
    let mut count = hooks.use_state(|| 0);

    hooks.use_future(async move {
        loop {
            smol::Timer::after(Duration::from_millis(100)).await;
            count += 1;
        }
    });

    element! {
        Text(color: Color::Blue, content: format!("counter: {}", count))
    }
}

§More Examples

There are many examples on GitHub which demonstrate various concepts such as tables, progress bars, full screen apps, forms, and more!.

§Shoutouts

iocraft was inspired by Dioxus and Ink, which you should also check out, especially if you’re building graphical interfaces or interested in using JavaScript/TypeScript.

You may also want to check out Ratatui, which serves a similar purpose with a less declarative API.

Modules§

components: Components for crafting your UI.
hooks: This module contains hooks that can be used to add behavior to components.
prelude: By importing this module, you’ll bring all of the crate’s commonly used types into scope.

Macros§

element: Used to declare an element and its properties.

Structs§

AnyElement: A type-erased element that can be created from any Element.
Canvas: Canvas is the medium that output is drawn to before being rendered to the terminal or other destinations.
CanvasSubviewMut: Represents a writeable region of a Canvas. All coordinates provided to functions of this type are relative to the region’s top-left corner.
CanvasTextStyle: Describes the style of text to be rendered via a Canvas.
ComponentDrawer: Provides information and operations that low level component implementations may need to utilize during the draw phase.
ComponentUpdater: Provides information and operations that low level component implementations may need to utilize during the update phase.
Edges: Defines the edges of an element, e.g. for border styling.
Element: An element is a description of an uninstantiated component, including its key and properties.
ElementKey: Used to identify an element within the scope of its parent. This is used to minimize the number of times components are destroyed and recreated from render-to-render.
FullscreenMouseEvent: An event fired when the mouse is moved, clicked, scrolled, etc. in fullscreen mode.
Handler: Handler is a type representing an optional event handler, commonly used for component properties.
Hooks: A collection of hooks attached to a component.
KeyEvent: An event fired when a key is pressed.
KeyEventState: Represents extra state about the key event.
KeyModifiers: Represents key modifiers (shift, control, alt, etc.).
MockTerminalConfig: Used to provide the configuration for a mock terminal which can be used for testing.
Percent: Defines a type that represents a percentage [0.0-100.0] and is convertible to any of the libary’s other percent types. As a shorthand, you can express this in the element! macro using the pct suffix, e.g. 50pct.
SystemContext: The system context, which is always available to all components.
TerminalEvents: A stream of terminal events.

Enums§

AlignContent: Sets the distribution of space between and around content items For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis
AlignItems: Used to control how child nodes are aligned. For Flexbox it controls alignment in the cross axis For Grid it controls alignment in the block axis
Color: Represents a color.
Context: A context that can be passed to components.
Display: Sets the layout used for the children of this node
FlexBasis: Sets the initial main size of a flex item.
FlexDirection: The direction of the flexbox layout main axis.
FlexWrap: Controls whether flex items are forced onto one line or can wrap onto multiple lines.
Gap: Defines the gaps in between rows or columns of flex items.
Inset: Sets the position of a positioned element.
KeyCode: Represents a key.
KeyEventKind: Represents a keyboard event kind.
Margin: Defines the area to reserve around the element’s content, but outside the border.
MouseEventKind: A mouse event kind.
Overflow: How children overflowing their container should affect layout
Padding: Defines the area to reserve around the element’s content, but inside the border.
Position: The positioning strategy for this item.
Size: Defines a width or height of an element.
TerminalEvent: An event fired by the terminal.
Weight: A weight which can be applied to text.

Traits§

Component: Component defines a component type and the methods required for instantiating and rendering the component.
ElementExt: A trait implemented by all element types, providing methods for common operations on them.
ElementType: A trait implemented by all element types to define the properties that can be passed to them.
Hook: A hook is a way to add behavior to a component. Hooks are called at various points in the update and draw cycle.
Props: This trait makes a struct available for use as component properties.

Type Aliases§

JustifyContent: Sets the distribution of space between and around content items For Flexbox it controls alignment in the main axis For Grid it controls alignment in the inline axis
MeasureFunc: The measure function of the current component, which is invoked to calculate the area that the component’s content should occupy.

Attribute Macros§

component: Defines a custom component type.

Derive Macros§

Props: Makes a struct available for use as component properties.

Crate iocraftCopy item path