Crate tessera_ui

Expand description

Tessera is a cross-platform declarative & functional UI library for rust, focused on performance and extensibility.

§Guide

We recommend reading the Quick Start to learn how to use tessera.

§Component Library

The tessera-ui crate itself does not contain built-in components, but the official project provides a basic component library.

It contains commonly used UI components such as buttons, text boxes, labels, etc., which help developers quickly build user interfaces.

§Components

To define a component in tessera, write it like this:

use tessera_ui::tessera;

#[tessera]
fn my_component() {
    // component implementation
}

Functions marked with the #[tessera] macro are tessera components.

Component functions may contain other component functions, enabling nesting and composition.

use tessera_ui::tessera;

#[tessera]
fn child() {
    // child component implementation
}

#[tessera]
fn parent() {
    child();
}

§Memoized state

Components in tessera are functions. To persist state across frames within a component, use the memoization API.

There are two primary primitives for memoized state depending on lifetime: remember and retain. The following sections describe their behavior and usage.

§remember

The remember and remember_with_key functions can be used to create persistent state across frames within a component.

use tessera_ui::{remember, tessera};

#[tessera]
fn counter() {
    let count = remember(|| 0);
    count.with_mut(|c| *c += 1);
}

Memoized state is implemented via macro-based control-flow analysis and cannot be used outside of functions marked with #[tessera]. It also must not be used inside layout policies or event handler implementations.

remember handles most control flow situations, but it cannot guarantee stable identity inside loops. If you need to use memoized state within a loop, use remember_with_key and provide a stable key.

use tessera_ui::{tessera, remember_with_key};

struct User {
    id: i32,
    name: String,
}

#[tessera]
fn user_list() {
    let users = vec![
        User { id: 101, name: "Alice".to_string() },
        User { id: 205, name: "Bob".to_string() },
        User { id: 33,  name: "Charlie".to_string() },
    ];

    for user in users.iter() {
        // Regardless of the user's position in the list, this `likes` state will follow the user.id
        let likes = remember_with_key(user.id, || 0);

        /* component implementation */
    }
}

Or use the key function to influence the remember calls inside it.

use tessera_ui::{key, remember, tessera};

#[tessera]
fn my_list(items: Vec<String>) {
    for item in items.iter() {
        key(item.clone(), || {
            let state = remember(|| 0);
        });
    }
}

This is equivalent to using remember_with_key(item.clone(), || 0), but it is transparent to child components and necessary for virtual container-like components.

However, remember_with_key is a litte cheaper than key + remember, so prefer it in simple cases.

§retain

retain just work as remember but is not dropped when a component becomes invisible; use it for state that should persist for the lifetime of the process (for example, scroll position).

It has the same API and typical usage as remember, except that its value is retained across the entire lifetime of the process.

use tessera_ui::{retain, tessera};

#[tessera]
fn scrollable_page(page_id: String) {
    // Scroll position persists even when navigating away and returning
    let scroll_offset = retain(|| 0.0f32);
    let _ = page_id;

    /* component implementation */
}

There is also a key variant for retain, called retain_with_key. Use it when you need to retain state in a loop or similar scenarios.

use tessera_ui::{tessera, retain_with_key};

struct User {
    id: i32,
    name: String,
}

#[tessera]
fn user_list() {
    let users = vec![
        User { id: 101, name: "Alice".to_string() },
        User { id: 205, name: "Bob".to_string() },
        User { id: 33,  name: "Charlie".to_string() },
    ];

    for user in users.iter() {
        // Regardless of the user's position in the list, this `likes` state will follow the user.id
        let likes = retain_with_key(user.id, || 0);

        /* component implementation */
    }
}

Or use the key function to influence the retain calls inside it.

use tessera_ui::{key, retain, tessera};

#[tessera]
fn my_list(items: Vec<String>) {
    for item in items.iter() {
        key(item.clone(), || {
            let state = retain(|| 0);
        });
    }
}

§Context

The context mechanism is used to pass data down the component tree, avoiding the need to thread it through parameters.

use tessera_ui::{Color, provide_context, tessera, use_context};

#[derive(Clone, PartialEq)]
struct Theme {
    color: Color,
}

#[tessera]
fn parent() {
    provide_context(
        || Theme { color: Color::RED },
        || {
            child();
        },
    );
}

#[tessera]
fn child() {
    let theme = use_context::<Theme>().expect("Theme must be provided");
    theme.with(|t| assert_eq!(t.color, Color::RED));
}

A context corresponds to a type. In the component tree, a component will receive the nearest parent-provided context of the same type.

use tessera_ui::{Color, provide_context, tessera, use_context};

#[derive(Clone, PartialEq)]
struct Theme {
    color: Color,
}

#[tessera]
fn parent() {
    provide_context(
        || Theme { color: Color::RED },
        || {
            child();
        },
    );
}

#[tessera]
fn child() {
    let theme = use_context::<Theme>().expect("Theme must be provided");
    theme.with(|t| assert_eq!(t.color, Color::RED));
    provide_context(
        || Theme {
            color: Color::GREEN,
        },
        || {
            grandchild();
        },
    );
}

#[tessera]
fn grandchild() {
    let theme = use_context::<Theme>().expect("Theme must be provided");
    theme.with(|t| assert_eq!(t.color, Color::GREEN));
}

§Layout

Tessera layout behavior is expressed through layout policies attached to the current node. Framework and component crates do this through internal layout primitives, while application code typically composes existing components and modifiers.

For more details, see the Layout Guide.

Re-exports§

pub use crate::accessibility::AccessibilityActionHandler;
pub use crate::accessibility::AccessibilityId;
pub use crate::accessibility::AccessibilityNode;
pub use crate::asset::AssetExt;
pub use crate::color::Color;
pub use crate::context::Context;
pub use crate::context::provide_context;
pub use crate::context::use_context;
pub use crate::dp::Dp;
pub use crate::entry_point::EntryPoint;
pub use crate::entry_registry::EntryRegistry;
pub use crate::entry_registry::TesseraPackage;
pub use crate::focus::FocusDirection;
pub use crate::focus::FocusGroupNode;
pub use crate::focus::FocusManager;
pub use crate::focus::FocusProperties;
pub use crate::focus::FocusRequester;
pub use crate::focus::FocusScopeNode;
pub use crate::focus::FocusState;
pub use crate::focus::FocusTraversalPolicy;
pub use crate::focus::FocusTraversalStrategy;
pub use crate::layout::DefaultLayoutPolicy;
pub use crate::layout::LayoutInput;
pub use crate::layout::LayoutOutput;
pub use crate::layout::LayoutPolicy;
pub use crate::layout::LayoutResult;
pub use crate::layout::NoopRenderPolicy;
pub use crate::layout::RenderInput;
pub use crate::layout::RenderMetadataMut;
pub use crate::layout::RenderPolicy;
pub use crate::modifier::BuildModifierNode;
pub use crate::modifier::CursorModifierExt;
pub use crate::modifier::CursorModifierNode;
pub use crate::modifier::DrawModifierContent;
pub use crate::modifier::DrawModifierContext;
pub use crate::modifier::DrawModifierNode;
pub use crate::modifier::FocusModifierExt;
pub use crate::modifier::ImeInputModifierNode;
pub use crate::modifier::KeyboardInputModifierNode;
pub use crate::modifier::LayoutModifierChild;
pub use crate::modifier::LayoutModifierInput;
pub use crate::modifier::LayoutModifierNode;
pub use crate::modifier::LayoutModifierOutput;
pub use crate::modifier::Modifier;
pub use crate::modifier::ParentDataMap;
pub use crate::modifier::ParentDataModifierNode;
pub use crate::modifier::PointerInputModifierNode;
pub use crate::modifier::SemanticsModifierNode;
pub use crate::pipeline_context::PipelineContext;
pub use crate::plugin::Plugin;
pub use crate::plugin::PluginContext;
pub use crate::plugin::PluginResult;
pub use crate::plugin::register_plugin;
pub use crate::plugin::register_plugin_boxed;
pub use crate::plugin::with_plugin;
pub use crate::plugin::with_plugin_mut;
pub use crate::px::Px;
pub use crate::px::PxPosition;
pub use crate::px::PxRect;
pub use crate::px::PxSize;
pub use crate::render_module::RenderModule;
pub use crate::render_scene::Command;
pub use crate::render_scene::CompositeCommand;
pub use crate::render_scene::DrawRegion;
pub use crate::render_scene::PaddingRect;
pub use crate::render_scene::SampleRegion;
pub use crate::renderer::Renderer;
pub use crate::renderer::composite;
pub use crate::renderer::composite::CompositeBatchItem;
pub use crate::renderer::composite::CompositeContext;
pub use crate::renderer::composite::CompositeOutput;
pub use crate::renderer::composite::CompositePipeline;
pub use crate::renderer::composite::CompositePipelineRegistry;
pub use crate::renderer::composite::CompositeReplacement;
pub use crate::renderer::compute;
pub use crate::renderer::compute::ComputablePipeline;
pub use crate::renderer::compute::ComputeCommand;
pub use crate::renderer::compute::ComputePipelineRegistry;
pub use crate::renderer::compute::ComputeResource;
pub use crate::renderer::compute::ComputeResourceManager;
pub use crate::renderer::compute::ComputeResourceRef;
pub use crate::renderer::drawer;
pub use crate::renderer::drawer::DrawCommand;
pub use crate::renderer::drawer::DrawablePipeline;
pub use crate::renderer::drawer::PipelineRegistry;
pub use crate::renderer::drawer::command;
pub use crate::renderer::external::ExternalTextureHandle;
pub use crate::renderer::external::ExternalTextureRegistry;
pub use accesskit;
pub use wgpu;
pub use winit;
pub use tessera_shard;

Modules§

accessibility: Accessibility Support
asset: Asset reading abstractions for generated resource handles.
color: Color utilities for the Tessera UI framework.
context: Context provider
dp: Density-Independent Pixels (Dp)
entry_point: Application entry builder for registering packages and launching the renderer.
entry_registry: Entry package registry for renderer startup.
focus: Focus ownership, traversal, and restoration for interactive UI.
layout: Layout policies and measurement.
modifier: Modifier chains for node-local layout, drawing, focus, semantics, and other node-scoped behavior.
pipeline_context: Pipeline registration context for renderer initialization
plugin: Plugin lifecycle hooks for Tessera platform integrations.
px: Physical Pixel Types
render_module: Render Module Interface
render_scene: Render command definitions for frame graphs
renderer: The core rendering system for the Tessera UI framework. This module provides the main Renderer struct that manages the application lifecycle, event handling, and rendering pipeline for cross-platform UI applications.
router: Controller-driven shard routing primitives.
time: Cross-platform monotonic time helpers.

Structs§

Arena: An Arena structure containing certain [Node]s.
Callback: Stable, comparable callback handle for Fn().
CallbackWith: Stable, comparable callback handle for Fn(T) -> R.
ComponentTree: Respents a component tree
ComputedData: Layout information computed at the measure stage, representing the size of a node.
Constraint: Represents layout constraints for a component node.
ExternalTextureDesc: Descriptor for a persistent external texture.
ImeInput: Input for IME handlers.
ImeRequest: A request to the windowing system to open an Input Method Editor (IME). This is typically used for text input components.
ImeSession: Frame-local IME bridge used by input handlers to publish text input state.
KeyboardInput: Input for keyboard handlers.
NodeId: A node identifier within a particular Arena.
ParentConstraint: The constraint inherited from a parent node during measurement.
PointerChange: Represents a single pointer change with timing information.
PointerInput: Input for pointer handlers.
RenderFragment: A per-component render fragment.
RenderFragmentOp: A single render op inside a fragment graph.
RenderGraph: Frame-level render graph.
RenderGraphOp: A render op after merging into the frame graph.
RenderGraphParts: Owned render graph payload for graph transforms.
RenderSlot: Stable, comparable render slot handle.
RenderSlotWith: Stable, comparable render slot handle for Fn(T).
RenderTextureDesc: Descriptor for a local render texture.
ScrollEventContent: Contains scroll movement data for scroll events.
Slot: Stable, comparable slot handle for any shared callable trait object.
State: Handle to memoized state created by remember and remember_with_key.

Enums§

CursorEventContent: Enumeration of all possible cursor event types.
DimensionValue: Defines how a dimension (width or height) should be calculated.
FrameNanosControl: Control flow for receive_frame_nanos callbacks.
GestureState: Describes the high-level gesture classification of a cursor event.
MeasurementError: Represents errors that can occur during node measurement.
PointerEventPass: Pointer input dispatch pass.
PressKeyEventType: Represents the different types of cursor buttons or touch interactions.
RenderResource: Render graph resource description.
RenderResourceId: Resource identifier used by render graph nodes.
ScrollEventSource: Indicates the input source for a scroll event.
WindowAction: Window actions that components can request.

Constants§

MOUSE_POINTER_ID: Pointer identifier reserved for mouse input.

Functions§

current_frame_nanos: Returns the current frame timestamp in nanoseconds from runtime origin.
current_frame_time: Returns the timestamp of the current frame, if available.
frame_delta: Returns the elapsed time since the previous frame.
key: Groups the execution of a block of code with a stable key.
receive_frame_nanos: Register a per-frame callback driven by the renderer’s frame clock.
remember: Remember a value across recomposition (build) passes.
remember_with_key: Remember a value across frames with an explicit key.
retain: Retain a value across recomposition (build) passes, even if unused.
retain_with_key: Retain a value across recomposition (build) passes with an explicit key, even if unused.

Type Aliases§

CursorEvent: Backward-compatible alias for older naming.
Focus: Backward-compatible alias for the primary focus requester handle.
ImeInputHandlerFn: IME-specific input handler.
KeyboardInputHandlerFn: Keyboard-specific input handler.
PointerId: Pointer identifier used by input changes.
PointerInputHandlerFn: Pointer-specific input handler.

Attribute Macros§

entry: Generates platform-specific entry points from a shared run function.
shard: Transforms a function into a shard component that can be navigated to via the routing system and (optionally) provided with a lazily‑initialized per‑shard state.
tessera: Transforms a regular Rust function into a Tessera UI component.

Crate tessera_ui

Crate tessera_ui Copy item path

§Guide

§Component Library

§Components

§Memoized state

§remember

§retain

§Context

§Layout

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Attribute Macros§

Crate tessera_ui