Skip to content

Components

Components are structs that implement Component. They hold persistent state and return an Element tree from render.

See Ctx for the full Ctx API used inside create and render, and Reactivity for signals, stores, memos, effects, and contexts.

use lurq::{
app::{component::Component, ctx::Ctx},
core::Signal,
layout::{Alignment, text_style::{FontWeight, TextStyle}},
node::{Element, color::Color},
};
struct Counter {
count: Signal<i32>,
}
impl Component for Counter {
type Props = ();
fn create(ctx: &mut Ctx) -> Self {
Self { count: ctx.signal(0) }
}
fn render(&self, _ctx: &mut Ctx) -> impl Into<Element> {
let dec = self.count.clone();
let inc = self.count.clone();
let value = self.count.get();
lurq::components::Row::new()
.spacing(12.0)
.align_items(Alignment::Center)
.child(
lurq::components::Rect::new(36.0, 36.0)
.background("#ef4444")
.rounded(6.0)
.on_click(move |_| dec.update(|n| *n -= 1)),
)
.child(lurq::components::Text::styled(
&format!("{value}"),
TextStyle {
font_size: 24.0,
weight: FontWeight::Bold,
color: Color::from_hex("#1e293b"),
..TextStyle::default()
},
))
.child(
lurq::components::Rect::new(36.0, 36.0)
.background("#22c55e")
.rounded(6.0)
.on_click(move |_| inc.update(|n| *n += 1)),
)
}
}
pub trait Component: Send + Sync + 'static {
type Props: Send + PartialEq + 'static;
fn create(ctx: &mut Ctx) -> Self;
fn render(&self, ctx: &mut Ctx) -> impl Into<Element>;
fn after_layout(&self) {}
fn on_mounted(&self) {}
fn on_unmounted(&self) {}
}
MethodCalledPurpose
createOnce, when the component is mountedInitialize persistent state
renderOn mount and when the component is dirtyReturn the current element tree
after_layoutAfter a committed layout, with element refs updatedRead measurements or initialize Canvas drawing
on_mountedAfter first renderSetup hooks that need a mounted component
on_unmountedBefore the component is removedCleanup

Components receive props through the Props associated type. The current props are stored on the component context and can be read with ctx.props::<Self::Props>().

struct Greeting;
#[derive(Clone, PartialEq, lurq::DevtoolsInspectable)]
struct GreetingProps {
name: String,
}
impl Component for Greeting {
type Props = GreetingProps;
fn create(_ctx: &mut Ctx) -> Self {
Self
}
fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
let props = ctx.props::<Self::Props>();
lurq::components::Text::new(&format!("Hello, {}!", props.name))
}
}

Use () for components with no props. Reused components rerender when their props compare unequal, so custom props must implement PartialEq.

Read changing props in render; copying them into the struct only in create would keep the initial value after a parent updates them.

When the devtools feature is enabled, props must also implement DevtoolsInspectable.

#[derive(Clone, PartialEq, lurq::DevtoolsInspectable)]
struct GreetingProps {
name: String,
}

Mount child components inside render with Ctx.

fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
lurq::components::Column::new()
.spacing(16.0)
.child(ctx.mount::<Header>(HeaderProps { title: "App" }))
.child(ctx.mount::<Counter>(()))
.child(ctx.mount::<Footer>(()))
}

ctx.mount::<C>(props) matches children by position and component type. If the same component type stays at the same slot, its instance is reused. The child rerenders when its props change or its own context is dirty.

ctx.mount_keyed::<C>(key, props) matches children by key and type. Use keyed mounts for lists that can reorder.

lurq::components::Column::new().with_children(
self.items.get().iter().map(|item| {
ctx.mount_keyed::<TodoItem>(&item.id, item.clone())
}),
)

Element::component::<C>(props) is the element of a component with no Ctx at hand: what a builder, or a function that is given no Ctx, puts in a tree. The component whose render returns the element mounts it once the render has returned, as ctx.mount::<C>(props) would have, and keeps its slot: C is created once, keeps its signals between renders, and is unmounted when a render no longer returns it.

fn avatar(user: &User) -> Element {
Element::component::<Avatar>(AvatarProps { user: user.id })
}
fn render(&self, _ctx: &mut Ctx) -> impl Into<Element> {
lurq::components::Row::new().with_children(self.users.get().iter().map(avatar))
}
  • It is told from its siblings as an unkeyed mount is: by its order among what the component mounts, the declared ones after those mounted with ctx, in the order of the tree. In a list that changes give it a key: Element::component_keyed::<C>(key, props), or .key(..) on the element.
  • .id(..), .key(..) and .class(..) on the element go to the component’s root, as on an element ctx.mount returned.
  • The props are cloned for the mount, so they are Clone.
  • An element handed down to another component (slot children, an element in its props) is mounted by the component whose render returns it.
  • A tree no component renders, Tree::set_root with an element, has nothing to mount it in: it shows nothing there, and a warning says so. Give the window a root component.

Use mount_with or mount_keyed_with when a component needs children supplied by its parent.

ctx.mount_with::<Panel>(PanelProps { title: "Tools" }, vec![
lurq::components::Text::new("content").into(),
])

WindowChrome is a strict wrapper for custom desktop chrome. It disables native decorations when custom chrome is active, renders the title bar and content area, owns the draggable title-bar behavior, adds resize hit zones, and provides standard window controls.

use lurq::{
components::{ChromeTitleBar, Text, WindowChrome, WindowControls},
node::color::Color,
};
fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
WindowChrome::new()
.title_bar(
ChromeTitleBar::new()
.leading(Text::new("My App").padding_horizontal(12.0))
.trailing(Text::new("ready").color(Color::from_hex("#94a3b8")))
.controls(WindowControls::new().on_close(|| {
// Optional app cleanup before the window closes.
})),
)
.content(app_content(ctx))
.overlay(fullscreen_modal_layer(ctx))
.mount(ctx)
}

WindowControls::on_close is a cleanup callback before unconditional close. For a confirmation dialog, use a custom button calling window.request_close() as shown in Window lifecycle.

Apps provide title-bar slots and content. They should not manually call window.start_drag() or render resize handles for normal custom chrome. WindowChrome handles title-bar drag, double-click maximize, the system’s menu of the window on a right press (WindowHandle::show_system_menu, which only Windows has: Restore, Move, Size, Minimize, Maximize, Close), resize edge and corner hit zones, control-button event propagation, and platform drag/resize fallbacks in the active shell. The system knows the three controls too: WindowControls marks each with .window_control(..), so on Windows 11 the system’s snap layouts open over the maximize control as the pointer rests on it, as over a title bar the system draws. A title bar the app draws in its own way marks its controls the same way; see The Window’s Controls In A Title Bar Of Your Own.

ChromeTitleBar::draw(|window, height| ..) draws the whole bar from the app’s own element in place of its leading, title, center, trailing and controls, given the window (to read whether it is maximized or in front, and to minimize, maximize and close it) and the bar’s height; the bar still drags the window wherever nothing in it takes the press. ui::WindowChrome draws its bar so, on the design system’s recipe, as Windows, macOS, GNOME and KDE draw theirs: see Window Chrome.

Use WindowChrome::overlay(...) for fullscreen modals or app-level overlay layers that should cover content but stay below chrome resize hit zones. WindowChrome renders content first, then overlays, then chrome borders and resize handles, so modal layers do not make an undecorated window impossible to resize.

ChromeBorderPolicy decides the frame outline. PlatformDefault paints a 1px line in the theme’s Border on Windows and none elsewhere; Visible { size, color } paints the given line; Hidden paints none. Custom chrome also sets WindowBorderColor::None on the window, because Windows 11 DWM otherwise draws its own 1px border around undecorated windows, which would show even with Hidden. The title bar is the theme’s Muted, and its bottom line is separate: ChromeTitleBar::new() draws a 1px Border bottom border, and border_bottom(None) removes it.

Use WindowChromeProps for policy-level changes:

use lurq::{
components::{ChromeBorderPolicy, ResizeHandlePlacement, ResizeHandlePolicy, WindowChromeMode, WindowChromeProps},
node::color::Color,
};
let props = WindowChromeProps::new()
.mode(WindowChromeMode::AlwaysCustom)
.resize_handles(ResizeHandlePolicy::Enabled { size: 6.0 })
.resize_placement(ResizeHandlePlacement::Overlay)
.border(ChromeBorderPolicy::Visible {
size: 1.0,
color: Color::from_hex("#252a32").into(),
});

Resize hit zones are invisible strips (3 px by default) along each edge and corner. With the default ResizeHandlePlacement::Overlay, they cover the outermost pixels of the content, and the content fills the window below the title bar: a 1440 px wide window gives 1440 px of content. A press in those pixels starts a resize instead of reaching the content. ResizeHandlePlacement::Inset reserves a gutter instead: content and overlays are inset by the handle size on the left, right, and bottom, and the gutter is painted with WindowChrome::frame_background (or the content background). Maximized and fullscreen windows have no resize handles or gutter.

WindowChrome::metrics() returns WindowChromeMetrics, which can be used for modal or overlay coordinate adjustment when a component needs to reason about the custom chrome content area. Metrics include whether custom chrome is enabled, the title-bar height, resize handle size and placement, and border size. content_x, content_width, and content_height subtract the resize gutter only with ResizeHandlePlacement::Inset.

The Window’s Controls In A Title Bar Of Your Own

Section titled “The Window’s Controls In A Title Bar Of Your Own”

A window with no system decorations (with_decorations(false)) whose title bar the app draws has controls the system knows nothing of: to Windows they are client area like the rest, and Windows 11 opens its snap layouts only over what the window says is its maximize button. An element says which of the window’s controls it is with .window_control(..), which every element has:

use lurq::{
app::events::{MouseButton, MouseEvent},
components::{Row, Text},
node::{CursorIcon, Style, WindowControl, color::Color},
};
let window = ctx.window();
let maximized = window.is_maximized;
let control = |glyph: &str, control: WindowControl| {
Row::new()
.width(46.0)
.height(36.0)
.cursor(CursorIcon::Pointer)
.hovered_style(Style::new().background(Color::from_hex("#232934")))
// The minimize, the maximize or the close control of the window.
.window_control(control)
// A press of a control is the control's: it does not drag the window.
.on_mouse_down(|event: MouseEvent| event.stop_propagation())
.child(Text::new(glyph))
};
let (drag, minimize, maximize, close) = (window.clone(), window.clone(), window.clone(), window);
Row::new()
.height(36.0)
.on_mouse_down(move |event: MouseEvent| {
if event.button == MouseButton::Left {
drag.start_drag();
}
})
.child(Row::new().flex(1.0).child(Text::new("My App")))
.child(control("-", WindowControl::Minimize).on_click(move |_| minimize.set_minimized(true)))
.child(control("□", WindowControl::Maximize).on_click(move |_| maximize.set_maximized(!maximized)))
.child(control("x", WindowControl::Close).on_click(move |_| close.request_close()))

WindowControl is Minimize, Maximize (the control that maximizes the window and restores it) or Close.

  • The mark tells the system, and does nothing else. The element is under the pointer, held down, clicked, focused and given its cursor as any other element is, and it is its own on_click that acts on the window: an element marked Close that closes nothing closes nothing.
  • With the winit shell on Windows, the window answers the system’s hit test (WM_NCHITTEST) with HTMINBUTTON, HTMAXBUTTON or HTCLOSE where a marked element is. Windows 11 then opens its snap layouts over the maximize control as the pointer rests on it, and a press on it still reaches the element. The pointer over a control is, to the system, out of the client area; the shell gives the element what the system sends there, so nothing changes for the app.
  • The answer is given where the element takes the pointer: over its box as it is laid out, cut by what clips it, and not where something over it takes the pointer in its place (a zone along the window’s edge that resizes it, the backdrop of a dialog). It follows a layout, a scroll and the display’s scale. A disabled element, or one that takes no pointer (HitTestBehavior::None), is no control. Like an element ref’s bounds, the box is the layout’s: a transform is not followed.
  • On macOS and Linux the mark does nothing, and costs nothing.
  • A shell that drives a Tree itself asks tree.window_control_at(x, y), with the point in physical pixels as the pointer’s are, and gets the WindowControl there or None: what to answer its own window’s hit test with.

WindowControls and the design system’s ui::WindowChrome mark their controls, so an app that uses them has this with no change.

By default, Windows-style controls are 46 px wide text glyphs in the theme’s Foreground, on SecondaryHover under the pointer, and the close one on Destructive (DestructiveHover held down) with its glyph in DestructiveForeground. Each control’s content and colors can be replaced. Colors accept Color, hex strings, and PaletteColor roles, including PaletteColor::Extra:

use lurq::{
app::theme::{PaletteColor, TypographyStyle},
components::{WindowControlContent, WindowControlKind, WindowControls},
};
// "icon" is an app typography role that selects the icon font at 14 px;
// the ICON_* constants are that font's code points.
let icon = |glyph: &str| WindowControlContent::glyph(glyph, TypographyStyle::extra("icon"));
let controls = WindowControls::new()
.button_size(46.0, 32.0)
.content(WindowControlKind::Minimize, icon(ICON_MINIMIZE))
.content(WindowControlKind::Maximize, icon(ICON_MAXIMIZE))
.content(WindowControlKind::Restore, icon(ICON_RESTORE))
.content(WindowControlKind::Close, icon(ICON_CLOSE))
.foreground(PaletteColor::MutedForeground)
.hover_background(PaletteColor::extra("chrome_hover"))
.active_background(PaletteColor::extra("chrome_active"));

hover_background and active_background apply to every control, close included. To style one control, for example to keep a red close hover, use control_colors(kind, WindowControlColors { .. }). WindowControlContent::element(|foreground| ...) builds any other content, such as an SVG icon, and receives the configured foreground color. Hover and active change the background; hover_foreground(kind, color) gives one control another foreground under the pointer and while pressed, for a close control that turns white on its red. A glyph follows it, and so does content of WindowControlContent::element that names no color of its own, which is drawn in the foreground of its control; content drawn in the color the supplier was given keeps that color. Maximize content is shown while the window is restored and Restore content while it is maximized.

macOS traffic lights use TrafficLightColors. The defaults are the macOS 11+ colors sampled from the system controls, because Apple does not publish them: close #FF5F57, minimize #FEBC2E, zoom #28C840. Override them with WindowControls::traffic_lights(TrafficLightColors { .. }).

DragContainer, Draggable, and DropZone are real components. Use their mount helpers for the explicit one-child API.

Draggable and DropZone are blank behavior wrappers. Each requires exactly one slot child and leaves layout, sizing, and initial positioning to that child.

DragContainer requires exactly one slot child as the drag surface. By default, DragContainerProps::new() bounds descendant draggables to that surface.

use lurq::components::{DragContainer, DragContainerProps, Draggable, DraggableProps, Rect, Stack};
fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
let card = Draggable::mount(
ctx,
DraggableProps::new().on_drag_move(|event| {
println!("drag delta: {}, {}", event.delta_x, event.delta_y);
}),
Rect::new(64.0, 64.0)
.background("#3b82f6")
.absolute_position(24.0, 24.0),
);
DragContainer::mount(
ctx,
DragContainerProps::new(),
Stack::new()
.size(360.0, 220.0)
.child(card),
)
}

Use DragContainerProps::new().bounds(DragBounds::None) for an unbounded drag surface.

DropZone marks its single child as a drop target. Visual styling is supplied by that child.

use lurq::components::{DropZone, DropZoneProps, Rect};
fn render(&self, ctx: &mut Ctx) -> impl Into<Element> {
DropZone::mount(
ctx,
DropZoneProps::new().on_drop(|event| {
println!("dropped from {:?} onto {:?}", event.source_id, event.target_id);
}),
Rect::new(140.0, 80.0)
.background("#22c55e33")
.border_inside(1.0, lurq::node::color::Color::from_hex("#22c55e")),
)
}

Use DraggableProps::on_drag_start, on_drag_move, and on_drag_end for high-level draggable callbacks. Low-level node handlers with the same names remain available for custom behavior. The runtime keeps the active drag captured across rerenders and dispatches on_drop to the hit DropZone on release.

let count = ctx.signal(0);
count.get(); // tracked read
count.get_untracked(); // untracked read
count.set(42); // replace
count.update( | n| * n += 1); // mutate in place
count.with( | n| format!("{n}")); // tracked borrow

Writing to a signal marks the owning component dirty. Runtime rebuilds dirty component output before layout, rendering, event dispatch, and by-ID/by-class element lookup.

let count = ctx.signal(0);
let doubled = ctx.memo({
let count = count.clone();
move | | count.get() * 2
});
let value = doubled.get();

A memo tracks signals read during computation and updates dependents only when its value changes.

let handle = ctx.create_ref::<Option<u64> > (None);
handle.set(Some(123));
let current = handle.get();

Refs persist across renders but are not reactive.

Create signals, stores, memos, refs, effects, and watchers in create and retain their handles on the component. Calling these constructors repeatedly during render creates new state or subscriptions. Render-scoped APIs such as ctx.future, ctx.stream, ctx.future_action, and ctx.query retain their own call slots.

Use stores and lenses for structured reactive state.

let user = ctx.store(User { name: "Ada".into(), age: 36 });
let name = user.lens(
| u| u.name.clone(),
| u, name| u.name = name,
);
name.set("Grace".into());
let count = ctx.signal(0);
ctx.on_effect({
let count = count.clone();
move | | println ! ("count = {}", count.get())
});

Effects run immediately and rerun when any tracked signal read inside the effect changes.

ctx.watch( & count, | value| {
println ! ("count changed to {value}");
});

Watchers run when the watched signal changes.

The high-level cycle is:

  1. Component reads reactive state during render.
  2. A signal/store/memo update marks the component dirty.
  3. Runtime detects dirty components before work that needs a fresh tree.
  4. Dirty component subtrees are rendered again.
  5. Layout/render/event lookup use the updated internal tree.

Parent components do not force child components to recreate if the child slot still matches.

impl Component for MyComponent {
type Props = ();
fn create(_ctx: &mut Ctx) -> Self {
Self
}
fn render(&self, _ctx: &mut Ctx) -> impl Into<Element> {
lurq::components::Text::new("mounted")
}
fn on_mounted(&self) {
println!("mounted");
}
fn on_unmounted(&self) {
println!("unmounted");
}
}
ctx.batch(| | {
signal_a.set(1);
signal_b.set(2);
signal_c.set(3);
});

Batching coalesces context dirty propagation until the batch ends.