Telar
A modular Rust UI framework with its own template language, reactive signals and a self-contained renderer.
Telar draws every pixel itself — there is no webview and no native widget toolkit underneath. Components are written in .rsx, an indentation-based template language that compiles to plain Rust at build time, so what ships is a single binary with no runtime interpreter.
Early days. Telar is at
0.2.2. The APIs work and are exercised by the apps in this repo, but they will keep moving before1.0.
A component
[logic]
#[derive(Default)]
pub struct Props {
pub icon: &'static str,
pub title: &'static str,
pub body: &'static str,
}
[view]
box fill:$theme.surface stroke:$theme.border radius:16 width:300 pad:24 gap:10 axis:col
text "{props.icon}" font_size:32
text "{props.title}" font_size:18 color:$theme.dark
text "{props.body}" font_size:14 color:$theme.muted
[preview "Fast"]
feature_card icon:"⚡" title:"Fast" body:"Software and wgpu renderers with dirty tracking."
A .rsx file has up to four sections: [logic] for verbatim Rust (a pub struct Props declares the component's props), [style] for reusable style classes, [view] for the node tree, and [preview] blocks that the tooling renders in isolation, with live controls, a [play] that drives them and snapshots that guard them (docs/previews.md).
[logic] is Rust at two levels. An item written at its left margin — use, const, static, fn, struct, enum, impl, trait, type, mod, macro_rules! — is an item of the file's module, so a [style] class, a [preview], a #[cfg(test)] mod tests and another module can name it. A statement — a let, an effect(…) — runs in the component each time it is built, where props is in scope.
Quick start
That is the whole of the setup. cargo telar new writes the manifest, the build profiles, a theme, an app root and one .rsx component, with one target already named — there is nothing to wire up and no feature list to read first.
Already have a directory — a fresh git init, a Nix flake, a README you wrote first? cargo telar init writes the same files into it in place. It never overwrites anything: a name it would itself write that already exists is a conflict, and it refuses the whole write and lists every one rather than touching any of them (an existing Cargo.toml included — merge one by hand, or start from an empty directory instead).
my-app/
Cargo.toml # one target under [features], the widget catalogue, and the build profiles
telar.toml # renderer backend, the components .rsx sees, theme, catalogs, the dev window
src/main.rs # fn main() { my_app::run(); }
src/lib.rs # telar::app!(…) — theme, startup hook, config, root
src/theme.rs # the design tokens every component reads
src/app.rs # the root component
src/home.rsx # one page
src/lib.rs is the whole of the wiring:
app!;
and telar.toml sits next to Cargo.toml:
[]
= "auto"
= ["telar_components"]
[]
= "my-app"
= 1000
= 700
Then:
One target, one word
Telar is a set of small crates behind one facade, and a build carries the target it named and nothing else:
| Your app runs in | default = [...] |
Crates compiled |
|---|---|---|
| A desktop window (Linux, macOS, Windows) | ["desktop"] |
397 |
| The terminal it was launched from | ["tui"] |
102 |
| A browser, drawing as a document | ["web-dom"] |
77 |
| A browser, document and WebGPU canvas | ["web"] |
210 |
| Android | ["android"] |
299 |
| Nothing — draw commands in, pixels out | ["headless"] |
174 |
Counted with cargo tree -p telar --no-default-features --features "<target>" -e normal --target all, so every platform's dependencies are in the figure at once. Every row is complete on its own: naming it is the whole of the choice, and no row pays for another — a desktop build is mostly wgpu and its shader toolchain, and a terminal build links neither. Switching later is one word in Cargo.toml.
Per-target guides, and how to ship two targets from one codebase, are in docs/targets.md.
One value grammar
An attribute is key — a flag that asserts itself — or key:<rust expression>, read to the next space at
delimiter depth 0. Every value is Rust, evaluated in the generated scope, so a call, a path, a method
chain, a macro or a closure is itself and rustc judges it against the line you wrote:
col gap:8 pad:(space::lg() * 2.0) align:center
btn "Save" on_press:(|| draft.save()) fill:$theme.primary
text "Hola {name}" font_size:14
A quoted value is text, as a text's content is: {expr} interpolates and {{/}} is a brace, whether it is the
content, a label: or a component's prop (button label:"Open {name}"). A closure that formats it borrows what it
reads, and copies in a [logic] binding — or the field of props it reads — that another part of the view still
needs, so text "{props.detail}" and text "{project()}" need no re-binding first. What an if let or a match
arm binds is copied into the closures under it, so if let Some(place) = &location can be read by a text below.
Parenthesise an expression that holds a space — (a + b) is an expression, so nothing new is invented.
Four sugars survive, because each is a token shape rather than a second language:
| written | means |
|---|---|
50% |
SizeDimension::Percent(0.5) |
50sw 50sh 50smin 50smax |
a fraction of the surface: SizeDimension::SurfaceWidth(0.5) and its siblings — see docs/surface-size.md |
#3d78fa |
Color::rgba(…) |
$sig |
sig.get() — a read of anything reactive, including the theme handle the view binds |
key(…) is reserved for the handful of directives that have a grammar of their own and are not Rust at
all: transition(fill 250ms ease-out) is a clause list, hover_style(fill:$theme.accent) a nested
attribute list. The spelling says which world you are in.
Reactivity is reading, not marking. A layout value that can change is re-resolved whenever what it
reads changes — pad:$theme.gutter follows a theme switch, and so does pad:gutter(). One that cannot — a literal,
or arithmetic on constants spelled as constants are, gap:(GRID * 2.0) — costs nothing to keep. A component's prop
follows what it reads the same way: a $ read, a use_…() hook read through (color:(use_workbench_tokens().accent))
or a signal's .get() hands the prop a Reactive that re-reads it, and a plain value, or a hook's handle passed on,
is handed over as it is. The $ is .get() sugar; it does not decide anything.
Components are Rust paths
A .rsx file is a module, and its component is the pub fn named after the file. Import what you call:
[logic]
use crate::ui::card::{card, CardProps};
[view]
card pad:20
text "inside" font_size:14
Every .rsx already sees telar's items and your crate root's. Components that ship in a crate of their own are made visible the same way by naming that crate once, in telar.toml:
[]
= ["telar-components"] # a package name, or a path inside one: "my_plugin::prelude"
Each entry is glob-imported after telar's glob and before your crate's, so it has to be a dependency of the package. An explicit use in [logic] shadows every glob, which is how one file picks a name two crates both export. A workspace telar.toml can declare the list for every package; a package that sets its own, [] included, replaces it.
A directory is a module too, and mod.rsx is that module's file — mod.rs in the other language. Its [logic] is Rust at module level, which is where a //! and a #![…] belong; it takes no [view], because a module is not callable. Give a directory one and telar declares it and everything under it, so nothing in it has to be placed by hand:
src/media/
mod.rsx # the module: docs, attributes, and Rust items
mod.rs # optional, and kept as it is: included into the same module
media.rsx # crate::media::media
state.rs # crate::media::state
Without a mod.rsx, a directory that holds both .rsx files and a hand-written mod.rs places them from that file with a telar::rsx_modules!(); of its own — only a module's own file can add items to it.
A module written as keymap.rs beside keymap/ cannot place the .rsx in keymap/: the macro reaches its declarations through an include! resolved beside the file that invokes it, which for keymap.rs is its parent's directory, and a proc macro cannot tell which file it was written in under rust-analyzer. The build names every such .rsx instead of leaving it out; move keymap.rs to keymap/mod.rs, or give the directory a mod.rsx.
apps/sandbox in this repo is the reference app and covers most of the surface.
Shared classes
A class is the file's own until it says otherwise. pub @name shares it, and a use in another file's [style]
brings it in by its module path, Rust's own spelling with class names where Rust has items:
[style]
pub @mono
font_family: telar_devtools::use_workbench_tokens().mono_family
font_size: telar_devtools::use_workbench_tokens().mono_size
[style]
use crate::styles::{mono, line as rule};
use super::cards::*;
[view]
row @rule align:center
text @mono "{seq}"
A .rsx with classes and no [view] — src/styles.rsx above — is a module of them rather than a component, and a
directory's mod.rsx may hold the classes its modules share. A class is a bundle of attributes written onto each
element that names it, so its values are Rust read where it is used, the way a macro_rules! macro's paths are: a
shared class names what it reads by a path any file can reach, or each file that uses it imports that name. A class
no [style] declares or imports is an error on the element naming it, and so is an import of a module that is not
there, of a class it does not declare, or of one it keeps private.
What's in the box
Everything here is either always present or one word away. Nothing is bundled.
- Reactive signals — a fine-grained graph of signals, memos and effects; no virtual DOM, no diffing.
- Flexbox and grid layout on top of Taffy, with reactive writing direction (LTR/RTL), lengths relative to the surface, and width breakpoints that re-resolve only across a threshold. → docs/surface-size.md
- Sticky positioning —
sticky inset_top:0holds a box at a scroll viewport's edge inside its parent, placed by Telar on every target and by nativeposition: stickyon web-dom.sticky:$onandclip:$onswitch it, or a clip, by state without a rebuild. → docs/sticky.md - Primary scroll — a root
ScrollPageis the page's own scroll: the document's scroll on web-dom, a drawn scroll area elsewhere, readable and movable by platform code.use_primary_scroll()reads it reactively from anywhere, anduse_anchor_at(line)the anchor under a line of its view. Its arrival margin, taken from the bars of the layers fixed over it or declared, keeps an anchor followed or a control focused clear of them (scroll-paddingon web-dom). → docs/primary-scroll.md - Fixed layer —
layerstands boxes against the surface over the page: out of its flow and its scroll, drawn over its sticky boxes and under every overlay, taking the pointer only over its own boxes and keeping its place in the Tab order.position: fixedin place on web-dom, a layout root of its own elsewhere. → docs/fixed-layer.md - Motion — tweens and springs driven by one frame ticker, with colors interpolated in Oklch.
- Theming — theme tokens plus light/dark mode, reduced motion and high contrast that can follow the OS, and the user's preferred locales, read the same way on every target. → docs/system-preferences.md
- Keyboard — each focusable control declares the keys it keeps, so a browser build shares Tab and scrolling with the host page instead of fighting it for them. → docs/keyboard.md
- Internationalization — translation catalogs baked at build time;
t!validates keys and arguments at compile time. Full CLDR plural rules and locale-aware number and date formatting are in the plugintelar-i18n. - Two renderers — a CPU rasterizer on
tiny-skiaand a GPU one onwgpu, behind the same drawing vocabulary.desktopandandroidbring both, andbackend = "auto"picks per machine. - A widget catalogue — buttons, fields, selects, menus, modals, tabs, sliders, and the rest — in the plugin
telar-components: add it with the groups you draw (overlays,chrome,advanced) and list it as apreludeintelar.toml. → docs/targets.md - Navigation — a reactive page stack with animated transitions, or one stack per tab, that follows the app's address — in the plugin
telar-navigate: add it and list it as apreludeintelar.toml. → docs/targets.md - Location — one address per app on every target: browser history with scroll restoration,
--locationdeep links remembered between runs, AndroidACTION_VIEWand the back button. → docs/location.md - Surface title — the window, tab, recents label or terminal title is derived from the app's title, the current route's title and the locale, and follows all three. → docs/surface-title.md
- Links —
to:makes a box a link to a route, an anchor on the page or a URI outside the app: a real<a href>on web-dom,open_urithrough the system everywhere else, OSC 8 in a terminal.current:marks the current one (aria-current). → docs/links.md - Dashed strokes —
stroke_dash:"1 4"on apath, orStroke::with_dashin acanvas, dashes an outline on every renderer: SVGstroke-dasharrayon web-dom,tiny-skia's own dashing on the CPU, dashes cut before tessellation on the GPU, dashed line characters in a terminal. → docs/dashed-strokes.md - Images and SVG — baked into the binary at build time out of
src:"…", with no parser in the binary. →svg - Icons —
icon name:"mdi:home", orname:"home"with a default set, draws an Iconify icon: a monochrome one in the colour of the text around it, a palette one in its own colours. Icons are baked at build time from Iconify sets on disk, your own SVGs or a provider you name, with each set's licence recorded in a notice — in the plugintelar-icons. - Translation catalogs baked the same way, with
t!validating keys and arguments at compile time.
Both are baked by the CLI, and so is the .rsx itself: build through cargo telar check/dev/build/test, or run cargo telar transpile first. A plain cargo build fails with a message naming that command rather than compiling something stale, which is what keeps the decoders, the parser and the code generator out of every project's own build. A project that will not install the CLI produces the artifact itself from a build.rs, which is one call into telar-transpiler and gets real cargo:rerun-if-changed out of it.
- Assets that arrive later, behind a transport-agnostic reactive seam: a signal that advances
Loading→Ready/Failed, with the transport, the cache and the decoder each yours to choose. →async-assets - Decoders and transports for that seam — SVG, bitmaps, translation catalogs, over HTTP or from a directory — in the companion crate
telar-dynamic, one feature each. Yours plugs in the same way. - Hot reload in
cargo telar dev, and an in-app devtools overlay for inspecting the live component tree — the plugintelar-devtools, an optional dependencycargo telar newdeclares andcargo telar devturns on — or one of your own, through the same seam. (the CLI sets this one) - Previews and a component workshop: write a component in a state once, as a
[preview]in.rsxorpreview!in Rust, and see it in the workshop with live controls, across themes, languages and sizes, play it, check it for accessibility, and snapshot it. →cargo telar preview,cargo telar test(docs/previews.md) - Packaging to native installers per platform, plus Android APKs. →
cargo telar build --format …For the browser, a static site from a page template with content-hashed assets, anasset-manifest.jsonand a verbatimweb/public/→cargo telar build --target web, configured under[telar.web](docs/web-packaging.md). With--prerender, every page and locale written ahead of time, readable before the module loads and naming each element for the client that takes it over → docs/prerender.md. Each page carries its description, canonical, alternate-language and link-preview tags, derived from[telar.web], the catalogs and the routes, with asitemap.xml, a root that negotiates the reader's locale, and host profiles (static,cloudflare-pages) for the files a host reads beside the site.
The complete list, with what each feature pulls in and why, is on docs.rs.
Editor support
The VS Code extension provides syntax highlighting, snippets, diagnostics, completion and component preview, backed by the telar-analyzer language server. A component's attribute keys are completed from its props struct — names, types and doc comments — through an embedded rust-analyzer, and a diagnostic about a value lands on the .rsx line and column you wrote it on. The extension bundles a prebuilt server binary, so no extra install step is needed.
Build tuning
cargo telar new writes profiles that keep dev builds fast and release builds small. Adding Telar to an existing workspace, wanting a faster linker, or wanting to know why panic = "abort" must stay off [profile.dev]/[profile.release] but is fine in [profile.web]: see docs/build-tuning.md.
Crates
You depend on one:
[]
= "0.2.2"
Everything behind it — the reactive graph, the layout engine, the renderers, the platform backends, the .rsx pipeline — is a separate telar-* crate. They are published because Cargo requires every dependency of a published crate to be published too, not because an application names them; the split is what lets a terminal build skip a GPU renderer. Reach for one directly only if you are writing a frontend or a tool against Telar's internals.
Two exceptions. cargo-telar is a binary you install rather than a dependency. telar-embed is for hosting a separately-compiled Telar UI inside your own — or for being one. The rest is opt-in, and it is a plugin.
Plugins
telar is the mechanism: traits, protocols and registries. The batteries an application may want are plugins, crates you add to your own Cargo.toml beside the facade, which carries none of them:
| Plugin | What it adds |
|---|---|
telar-components |
The widget catalogue. No default features; groups overlays, chrome and advanced |
telar-navigate |
The page stack: Navigator, the host that animates between pages, per-tab stacks |
telar-watch |
Filesystem watching delivered on the UI thread: watch_path |
telar-dynamic |
Decoders and transports for assets that arrive at run time, one feature each |
telar-icons |
The icon tag for Iconify set:name ids, baked from local sets, your own SVGs or a provider you name, with each set's licence recorded; feature runtime resolves ids as the app runs |
telar-i18n |
CLDR plural rules for catalogs, and number and date formatting in the active locale, from ICU4X |
telar-expression |
A typed, pure expression language bound to signals |
telar-devtools |
The dev overlay: FPS counter, node inspector, build-error banner — an optional dependency cargo telar dev turns on, so no shipping build compiles it |
telar-workshop |
The component workshop cargo telar preview opens: a sidebar of every preview, a canvas of its own for each, live controls, a matrix view and the panels that review a play and a snapshot — an optional dependency cargo telar preview turns on, so no shipping build compiles it |
The layout rule. plugins/ holds every crate built on top of the facade, including what the tooling adds on its own, such as the devtools overlay cargo telar dev turns on and the workshop cargo telar preview opens. crates/ holds telar, the kernel crates behind it and host-side tooling (crates/tools/); a crate a telar feature pulls in and compiles into the target is core, even when it is opt-in. Nothing under crates/ depends on plugins/, which .github/scripts/check-layering.sh enforces in CI.
Adding one. Add the crate, name the feature groups you draw, and, for a plugin that ships .rsx tags, list it in telar.toml so every .rsx file sees them without a use:
# telar.toml
[]
= ["telar_components", "telar_navigate"]
Keep every plugin on the same version as telar: two copies of the kernel resolve to incompatible types. A tag missing from every prelude, an unknown crate and a name two entries both export are each reported on the telar.toml or .rsx line that caused them.
Writing one. A plugin is a Rust crate that depends on telar and follows the component protocol, or a [telar] library written in .rsx and published with cargo telar package and cargo telar publish. Both are covered in docs/plugins.md.
| Crate | Purpose |
|---|---|
telar-reactive-core |
Signals, memos, effects, batching |
telar-geometry-core |
Points, rects, transforms, border radii, Oklch color |
telar-layout-core · telar-layout-reactive |
Flexbox/grid engine and its reactive context |
telar-motion-core |
Tweens, springs, the frame ticker |
telar-theme-core |
Theme tokens, light/dark mode |
telar-semantics-core |
What a thing in an interface is, for screen readers, documents and terminals |
telar-ui-core · telar-ui-tree |
Widget kernel, component tree |
telar-renderer-core |
Draw commands, culling, dirty tracking |
telar-renderer-software · telar-renderer-hardware |
CPU and wgpu backends |
telar-renderer-tui · telar-renderer-dom · telar-renderer-web |
Terminal cells, browser elements, browser canvas |
telar-renderer-text · telar-renderer-assets |
Text shaping and glyph atlas; SVG parsing and build-time asset baking |
telar-embed |
Embedding a separately-compiled UI, or being one — a crate an application depends on directly |
telar-renderer-cache · telar-renderer-record |
The shared byte-budgeted cache; a backend that records instead of drawing |
telar-wire-core |
The byte spelling of what crosses between a host and a guest library |
telar-platform-core and telar-platform-{winit,desktop,android,tui,web,headless} |
Window/event abstraction and its backends |
telar-preferences-core |
The user's system preferences as reactive state, which theme, motion and plugins follow |
telar-parser · telar-transpiler · telar-macros |
The .rsx pipeline |
telar-project |
What a project is: telar.toml, source discovery, output paths, and the build artifacts a transpile leaves behind |
telar-i18n-core · telar-services-core |
i18n runtime, platform paths and DI |
telar-reactive-local |
Per-surface thread-local slots, split out so platform-core need not link the reactive runtime |
telar-icons-core |
Iconify ids, sets, sources and licence policy, shared by telar-icons and the baker |
The plugins are in the table above; plugins/telar-rsx-fixture is an unpublished test fixture, a [telar] library the test suite packages, unpacks read-only and compiles as a dependency.
telar-analyzer and telar-diagnostics live in this repo but are distributed through GitHub Releases and the VS Code extension rather than crates.io.
Minimum supported Rust version
Rust 1.95. Bumping it is a minor-version change.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.