The .iru format
Learn what goes in a component file, why Inrux uses SFCs and when to move code out.
On this page
A .iru file is an Inrux single-file component, or SFC. You keep one component's UI structure, local interaction logic and optional styles in one source file. The compiler generates Rust from it before Cargo builds the application.
The Rust block is setup
Initialization statements in <rust> run once per component instance. Declare local state and computed values directly in the block; you do not write a setup function.
A top-level typed declaration such as let count: u32 = 0; becomes a retained field in the generated State. Read it as count in the view and update it through &mut State in a Rust handler. The qualified state.count spelling remains supported. An untyped let is a temporary initialization helper; it is not retained. Explicit types let rustc check the generated fields without runtime type inspection.
Imports, functions, structs and other Rust items remain at module scope. Handlers receive the generated State explicitly; they do not capture initialization locals. Child initialization can read props, and the compiler retains the latest props in state.props. Props changes, state updates and repaints do not rerun initialization.
The compiler generates an internal setup function for the existing mount API. main.rs can still call app::setup(). A manual setup function requires <rust explicit>. Do not combine it with top-level initialization; plain <rust> always uses automatic setup.
The three blocks
| Block | Put here | Example |
|---|---|---|
<view> | Component tree, bindings and event wiring | A button with @click={save} |
<rust> | Automatic setup, Rust imports, typed props, local state and UI handlers | let count: u32 = 0; |
<rust explicit> | Rust module items with an authored State and setup function | pub fn setup() -> State |
<style> / <style scoped> | Global or component-local CSS subset | A class for spacing and colors |
Use braces for Rust expressions and quotes for literal strings. Put closing SFC block tags on their own lines. Keep one root component tree in the view; use a physical container when you need several children.
<view>
<Column class="form">
<Input model:value={name} placeholder="Workspace name" />
<Button text="Use name" @click={confirm} />
<Text text={message.clone()} />
</Column>
</view>
<rust>
use inrux::prelude::*;
let name: String = String::new();
let message: String = String::new();
/// Keep this handler concerned with the current component's interaction.
fn confirm(state: &mut State, _: &Context<State>) {
state.message = format!("Selected {}", state.name);
}
</rust>
<style scoped>
.form {
gap: 12px;
padding: 24px;
}
</style>
Direct bindings in the view
Use retained names directly: <Text text={count} />, <Text text={counter.count} /> or <Input model:value={name} />. In automatic setup these names come from typed top-level declarations. In explicit setup they come from the declared State fields. Both forms use the same view syntax.
A complete direct value binding reads Signal and Computed handles automatically and tracks the read. Ordinary owned props are cloned when ownership is required; plain text is formatted without an extra clone. A plain collection used as <For each={rows}> is borrowed rather than cloned. Computed getters remain cached and initialization still runs once per mount. A failed computed read produces a diagnostic text node for that render. To pass a Signal or Computed handle itself to another component, use an ordinary Rust method expression such as count.clone().
Normal Rust expressions retain Rust semantics. For example, use format!("Count: {}", count.get()) when count is a Signal, and keep .get() in method-call expressions. Fully qualified state.count and props.title expressions keep their existing behavior. Custom macro bodies should use qualified state/props paths. Loop items, closure parameters and block-local variables shadow component names.
Props can also be read by name. A local state field wins when it shares a name with a prop; use props.title to select the prop explicitly. Props cannot be used as model targets. Nested composable fields such as counter.name can be model targets when they belong to retained state; calls and indexed expressions are not writable model targets. Rust functions and handlers continue to use explicit state parameters, such as state.count.update(...).
Manual setup with rust explicit
Use <rust explicit> when you want to declare State and its setup function yourself. The compiler uses that function and does not generate a second State or constructor. An explicit block accepts Rust module items, not top-level initialization statements. A stateful child declares Props, stores current props in State.props, and uses pub fn setup(props: Props) -> State.
This complete root component uses the manual form:
<view>
<Column class="counter">
<Text text={format!("Count: {}", count)} />
<Button text="Increment" @click={increment} />
</Column>
</view>
<rust explicit>
use inrux::prelude::*;
#[derive(Clone)]
pub struct State {
count: u32,
}
/// Initialize this component once for each mount.
pub fn setup() -> State {
State { count: 0 }
}
/// Handle clicks through the same state/event API as automatic setup.
fn increment(state: &mut State, _: &Context<State>) {
state.count += 1;
}
</rust>
<style scoped>
.counter {
padding: 24px;
gap: 16px;
}
</style>
Changing only the opening tag does not convert between the two forms: automatic setup uses typed top-level declarations; manual setup uses State and a setup function. The closing tag is </rust> in both forms. The language server, formatter and embedded Rust highlighting support both.
Why Inrux uses .iru
When you change a control, you often need to inspect its value, event handler and visual structure together. An SFC keeps those component-level details nearby. You can see which field an Input binds to and which function a Button calls without finding a second file.
This helps with local tasks such as adding validation feedback, changing a dialog's internal state, or extracting a reusable field. It does not require putting an application's logic in one file.
Why not a separate XML or layout file?
Separate layout and logic files are a valid way to build a GUI. We chose SFCs as Inrux's default workflow so you can read one component's structure, local state, event bindings and scoped styles together. For example, when a Save button changes a form's saved flag, you can inspect the button, its binding and its handler in the same file.
A separate layout file would put that wiring and its Rust definitions in different places. Keeping them together reduces file switching for component-level changes. This is a workflow choice, not a claim that separate files are wrong or that SFCs suit every developer.
The boundary is the component, not the whole application. Split large views into reusable components and move logic into Rust modules when that makes ownership or reuse clearer.
You can still write code in .rs files
Keep component and GUI logic in .iru when that makes the component easier to understand. Keep business rules, persistence, network services and reusable domain code in ordinary .rs modules or Cargo libraries. The <rust> block accepts ordinary Rust imports; it does not require you to inline those implementations.
For example, declare a module in the scaffold's entry point:
mod domain;
// Keep the scaffold's generated include and mount code.
Define reusable logic in that module:
/// Validate a name without depending on the UI.
pub fn workspace_name_is_valid(name: &str) -> bool {
!name.trim().is_empty() && name.chars().count() <= 80
}
Then add this import inside your component's <rust> block:
use crate::domain::workspace_name_is_valid;
Your UI handler can call the function with &state.name and update its local validation message. You can also move UI handlers into accessible .rs modules, write reusable composables there, or build Node descriptions with Rust functions. Use normal Rust visibility rules for any state those helpers access. The business-logic guide shows the handler and module wiring together.
Why a separate extension
The syntax is XML-like, but it is not standard XML. Rust expressions use braces; bindings and events use names such as model:value and @click. A generic XML parser does not understand the complete file or its Rust type relationships.
The .iru extension lets Cargo integration and the editor identify this format. The compiler validates component imports and markup, generates typed Rust calls, and leaves Rust type checking to rustc. The VS Code extension recognizes the block boundaries and forwards embedded Rust features to rust-analyzer.
Renaming a file to .xml would not make it valid XML. Supporting standard XML would require another syntax design and different tooling.
The tradeoffs
Some Rust developers prefer layouts written in Rust. The extra syntax introduces a compiler, generated-source diagnostics and editor tooling to maintain. Inrux has not proven that SFCs are the best choice for every application.
You can use ordinary Rust functions to construct Node descriptions and import them into component logic. The playground specimens use that approach alongside .iru views. The goal is to keep Rust reusable, not to replace it with a separate business-logic language.
Current syntax limits
Use capitalized <Children /> for default child content and <If> / <For> for control flow. Attribute-first conditionals/loops, transparent nested <view> groups, named/scoped content and animation refs are not implemented. <template> and <Slot /> remain compatibility aliases. See alpha status before copying examples from older discussions.