Component catalog#

Leptoskit's primary components are native primitive builders exported by leptoskit::components and leptoskit::prelude. Each returns an Element and understands Tailwind. View, Text, Image, ScrollView, editable inputs, buttons, and native controls provide the building blocks for shared screens.

The primary API has 16 primitive builders, including optional Rive. Another 31 layout and presentation builders are optional helpers under leptoskit::components::helpers. Import them explicitly when useful. They compose the same primitives and introduce no native widget kinds. New primitive behavior follows React Native and Lynx; the contracts below do not reproduce every upstream property.

View() is a column container, Text(content) displays inherited system-font text, Image(source) displays a host-resolvable image, Vector(view_box) draws filled and stroked paths, and ScrollView() contains scrolling children. The controls section lists the other primitives.

Write screens with PascalCase tags in view!, and mark reusable UI functions with #[component]. The tables below list the underlying builder signatures as an API reference; the markup reference shows their tag syntax.

Optional layout and presentation helpers#

Use View plus Tailwind for rows, grids, and layered content. Helpers remain available through an explicit import such as use leptoskit::components::helpers::Stack;. The table includes the basic primitives for comparison; all other builders in this section belong to helpers.

BoxConstraints::new(min_width, max_width, min_height, max_height) accepts finite nonnegative minima and optional finite maxima. A maximum cannot be smaller than its minimum. BoxConstraints::tight(width, height) fixes both dimensions. These constraints apply to the CSS box, rather than Flutter's parent-to-child constraint protocol.

AspectRatio, ClipRRect, and Opacity return Result<Element, LayoutError>. Ratios range from 1e-6 through 1e6. Radii must be finite and nonnegative. Opacity must be finite and between zero and one.

Align has no Flutter widthFactor or heightFactor. Give the wrapper dimensions or a flex allocation when it needs extra space. Expanded must be a direct child of a flex container. It implements a tight flex allocation, with no Flexible loose-fit equivalent.

Stack assigns overlap placement to the collection passed to its constructor. Appending .child(...) afterward uses ordinary grid placement. Positioned children do not contribute to intrinsic size. A stack containing only positioned children needs explicit dimensions or a parent allocation.

Controls#

Applications own control values. Handlers receive proposed values. Rebuilding the tree commits an accepted value. Both adapters restore the last committed value when the application rejects a proposal, including a proposal that triggers no rebuild.

RadioGroup::new(name) validates a nonempty name of at most 128 bytes with no control characters. A group is scoped to one rendered tree, and at most one member can be selected. Applications update all related radio values together. Arrow keys move among enabled group members and propose selection.

SliderState::new(min, max, value, step) validates finite increasing bounds and an in-range value. None selects continuous values. A step must be positive and no larger than the range. At the endpoint with the largest magnitude, a step must span at least 16 adjacent representable f64 values. This precision margin makes stepping and reconstruction stable throughout the range. A stepped value must lie on min + n * step, with one representable value of tolerance for rounding. The upper bound need not lie on that grid. Native, web, wire decoding, and the widget tester use the same quantization.

Progress::Determinate(ProgressValue::new(fraction)?) validates a finite fraction between zero and one. Progress::Indeterminate animates without a completion value. Hidden or stopped activity indicators do not animate. Browser animation respects reduced-motion preferences.

Checkboxes support boolean state. Mixed state, vertical sliders, multiple slider thumbs, multiline text, text selection APIs, and input-purpose configuration are not implemented. Password display masking does not encrypt application state or wire data.

Pressable provides activation, keyboard focus, an accessible name, and decorative child content. Pointer activation stays within its bounds. While it is held down, it shows its active: utilities, or dims without them, as Button does; Style the pressed state explains when each platform starts and ends a press. Handlers don't receive press-in or press-out, and there are no long-press, hit-slop, or gesture cancellation events. Its accessible label must contain a non-whitespace character. Its content cannot contain interactive widgets, event handlers, custom platform widgets, or scrolling descendants. Button also rejects nested controls and scrolling descendants. Other leaf controls cannot contain children. Element::validate and NativeSurface::try_set_root report invalid trees before replacing the committed UI.

Native toolkit controls retain their platform appearance and keyboard behavior. Tailwind controls the shared layout and common paint properties. Platform control chrome is not pixel-identical to browser controls. Use accessibility_label for controls without a visible textual name.

AppKit inherits the system appearance until the host calls NativeSurface::set_dark_mode. A host with a fixed light theme should call set_dark_mode(false) before mounting. Later calls update existing controls and the appearance used by newly created controls. Native controls own their internal content layout; use a styled View around an input for portable outer padding, as the component studio does.

Vector drawings#

Icons, hand-drawn underlines, and chart lines are shapes, not pictures, and a file-based Image can't draw them on native platforms. Vector(view_box) draws SVG-style paths directly, as native shapes on macOS, iOS, Android, Linux, and Windows, and as inline SVG on the web:

use leptoskit::prelude::*;

#[component]
fn Underline() -> Element {
	let ink = Color::rgba(0x1e, 0x40, 0xaf, 0xff);
	let stroke = Stroke::new(ink, 3.0).expect("a positive width").round();
	let wave = PathData::parse("M2 6 C20 2 38 9 56 5 S86 2 98 6").expect("valid path data");

	view! {
		<View class="w-[180px] h-[12px]">
			<Vector
				view_box=ViewBox::new(0.0, 0.0, 100.0, 10.0).expect("a positive size")
				scaling=VectorScaling::Stretch
				path=VectorPath::new(wave).stroke(stroke)
				class="absolute inset-0"
			/>
		</View>
	}
}

Paths are written in the view box's coordinates and mapped onto the element's frame:

• VectorScaling::Fit, the default, scales both axes by the same factor so the whole drawing shows, like SVG's meet. Use it for icons and doodles that must keep their shape.
• VectorScaling::Fill scales both axes by the same factor so the drawing covers the frame, like slice. Add overflow-hidden to crop what overflows.
• VectorScaling::Stretch scales each axis on its own to fill the frame, like preserveAspectRatio="none". Use it for borders, underlines, and other ink that follows a box of any size.

.align(VectorAlignment::new(x, y)) places a fitted or filled drawing at the start, centre, or end of each axis, like SVG's xMinYMax and its siblings. The element has no size of its own: give it one with classes, or absolute inset-0 to cover its parent.

Paths#

PathData::parse accepts all of SVG's path data: M, L, H, V, C, S, Q, T, A, and Z, absolute and relative, with SVG's number syntax and packed arc flags. Elliptical arcs become cubic curves of at most a quarter turn, following the SVG specification's arc rules, including growing radii that are too small to reach the end point. Malformed data is reported with its byte offset.

Basic shapes need no path data: PathData::rect, rounded_rect, circle, ellipse, line, polyline, and polygon. PathData::from_commands builds a path from absolute PathCommands, for generated geometry such as hand-drawn ink, without formatting a string. .transform(Affine) moves, scales, rotates, or skews a path exactly, and Affine::parse reads an SVG transform list such as rotate(45 12 12) translate(2).

Painting#

Each VectorPath takes an optional fill(...) and an optional stroke(...). Both take a Color or Paint::CurrentColor, which paints with the element's text color, as SVG's currentColor does: give the Vector a class such as text-indigo-600, or let it inherit its parent's, and the icon follows. .fill_rule(FillRule::Evenodd) punches holes where shapes nest; the default is SVG's nonzero rule.

Stroke::new(paint, width)? has butt caps, miter joins, and a miter limit of 4 unless you set .cap(...), .join(...), .round() for both, or .miter_limit(...)?. .dashes(&[4.0, 2.0], offset)? dashes it, as SVG's stroke-dasharray and stroke-dashoffset; an odd list repeats, and every dash gets the line's caps. Stroke widths and dashes are in layout units and never scale, so a stretched line stays the same thickness along its length. .scaling(StrokeScaling::Drawing) makes them scale with the drawing instead, as SVG strokes do by default; under uneven Stretch scaling, native platforms grow them by the square root of the area scale, while the web distorts them with the stretch.

Add several paths with repeated .path(...) calls or one .paths(...); later paths paint over earlier ones, and each path paints its fill before its stroke.

SVG documents#

With the svg feature, Drawing::parse_svg(document) turns an SVG file, such as an icon from your design tool, into a drawing, and .drawing(...) puts it on a Vector:

use std::sync::LazyLock;

use leptoskit::prelude::*;

static CHECK: LazyLock<Drawing> =
	LazyLock::new(|| Drawing::parse_svg(include_str!("check.svg")).expect("the icon imports"));

#[component]
fn Check() -> Element {
	view! { <Vector drawing=CHECK.clone() class="size-6 text-emerald-600" /> }
}

The importer reads <svg>, <g>, <path>, <rect>, <circle>, <ellipse>, <line>, <polyline>, and <polygon>, with viewBox, preserveAspectRatio, nested transforms, presentation attributes and style declarations, CSS colors (hex, rgb(), hsl(), and named), currentColor, opacity, fill-opacity and stroke-opacity, fill rules, every stroke property, vector-effect="non-scaling-stroke", absolute units, and percentages. <defs>, <title>, <desc>, <metadata>, and other tools' namespaces are skipped. Group opacity is folded into each shape's colors, which differs from SVG only where shapes in one translucent group overlap.

Anything else that would change how the document looks is an error that names it, never a silently different drawing: gradients and patterns used as paints, text, <use>, images, clipping paths, masks, filters, markers, <style> sheets, and font-relative units.

Performance#

Parse a path or import a document once, for example in a LazyLock, and reuse it. Paths and drawings are shared, immutable values: cloning one copies a pointer, a screen that reuses the same drawing diffs it with a pointer comparison, and native platforms skip redrawing a drawing that hasn't changed. Path data is formatted for the web and the wire once per path, not once per render.

Frames, clipping, and accessibility#

Drawings are not clipped to their frame, so a stroke on the edge of the view box shows in full. Add overflow-hidden or a corner radius to clip. A Vector cannot have children. Backgrounds, borders, and opacity apply to it as to a View; on the web, a border on the Vector itself shrinks the drawing's frame to the inside of the border, while native platforms map the drawing onto the whole frame, so draw outlines as paths instead.

A drawing with an aria_label is an image to screen readers. One without a label is decoration, and assistive technology skips it.

React Native mapping#

This table covers all 24 entries in the React Native core component catalog, checked on 20 October 2026. An equivalent names a useful shared contract, rather than full React Native property compatibility.

Lynx mapping#

Lynx separates its small built-in element vocabulary from composed UI and extended native elements. Leptoskit uses the same distinction between primitive rendering behavior and optional composition helpers.

Optional Flutter-inspired helpers#

The table groups the Flutter widget index and widget catalog by family and says what leptoskit offers for each.

Backend availability#

Web renders semantic DOM controls through Leptos, including server rendering and hydration. macOS renders real AppKit widgets, iOS renders UIKit views, Android renders Android views, Linux renders GTK 4 widgets, and Windows renders Win32 common controls. The headless backend verifies the shared tree and layout without OS widgets.

Every backend crate renders every primitive above, and each is checked in CI on a simulator, an emulator, or a desktop runner. The apps leptoskit new generates for macOS, iOS, and Android draw only View, Text, Button, Pressable, TextInput, PasswordInput, ScrollView, Image, Vector, and Rive for now. HarmonyOS draws neither Pressable nor Vector. Platforms lists each platform's gaps.

The CSS coverage reference records engine and utility limits. In particular, the grid engine does not yet implement full right-to-left grid placement. Flex cross-axis alignment does follow its direction.