# azul

> azul is a cross-platform, MIT-licensed GUI framework for building native desktop (and, soon, web) applications. It pairs a retained DOM/CSS UI model with an immediate-mode-style developer experience: a `LayoutCallback` maps your application data to a `Dom`, CSS styles it, and event callbacks mutate the data and request a re-layout. The whole API is exposed over a stable `repr(C)` ABI, so the same concepts are available from Rust (native) plus 30+ generated language bindings (C, C++, Python, and more). It ships headless rendering and a JSON-driven E2E test runner for windowless verification.

## Guide (concept pages, raw markdown)

- [Application Architecture](https://azul.rs/guide/architecture.md): Explains the concepts of architecting a larger Azul application
- [Document Object Model](https://azul.rs/guide/dom.md): Node types, hierarchy, and CSS scoping
- [Hello World](https://azul.rs/guide/hello-world.md): Window setup, state management, DOM creation, handling mouse clicks for a "counter" app
- [Callbacks](https://azul.rs/guide/callbacks.md): What CallbackInfo exposes — state, DOM mutation, focus, async work
- [Built-in Widgets](https://azul.rs/guide/widgets.md): Built-in widgets and how to write your own
- [Styling with CSS](https://azul.rs/guide/styling.md): Stylesheets, selectors, and the cascade
- [Layout](https://azul.rs/guide/layout.md): Overview of the layout solver
- [Text Input](https://azul.rs/guide/text-input.md): Editable text, IME, and the selection model
- [Images](https://azul.rs/guide/images.md): Loading raster images and CSS backgrounds
- [Accessibility](https://azul.rs/guide/accessibility.md): Screen reader integration and ARIA roles
- [Clipboard](https://azul.rs/guide/clipboard.md): Reading and writing the system clipboard
- [File Dialogs](https://azul.rs/guide/file-dialogs.md): Native open/save dialogs and folder pickers
- [Networking](https://azul.rs/guide/networking.md): HTTP from a callback
- [Background Tasks](https://azul.rs/guide/background-tasks.md): Running long jobs off the layout thread
- [Realtime Media and Devices](https://azul.rs/guide/realtime-media.md): Camera/mic capture, audio playback, and sharing A/V over UDP (the azul-meet pattern)
- [Routing](https://azul.rs/guide/routing.md): URL patterns, route params, and per-route layout callbacks
- [Windows, Menus, Decorations](https://azul.rs/guide/windowing.md): Windows, menus, decorations, and per-window state
- [Web Deployment](https://azul.rs/guide/web-deployment.md): Building for the browser via WASM
- [Mobile Deployment (iOS and Android)](https://azul.rs/guide/mobile-deployment.md): How to cross-compile, package, and deploy an Azul app on iOS and Android
- [Headless Rendering](https://azul.rs/guide/headless-rendering.md): Running the pipeline without a window
- [End-to-End Testing](https://azul.rs/guide/e2e-testing.md): Driving an Azul app from a script for tests
- [Documentation Reference Backlog](https://azul.rs/guide/reference.md)
- [Hello World [Rust]](https://azul.rs/guide/hello-world/rust.md)
- [Hello World [C]](https://azul.rs/guide/hello-world/c.md)
- [Hello World [C++]](https://azul.rs/guide/hello-world/cpp.md)
- [Hello World [Python]](https://azul.rs/guide/hello-world/python.md)
- [Understanding RefAny](https://azul.rs/guide/architecture/understanding-refany.md): RefAny helps you to share and store type-erased data between callbacks and threads
- [Reconciliation](https://azul.rs/guide/dom/reconciliation.md): Diffing, restyle scope, and damage-rect repaint
- [Datasets](https://azul.rs/guide/dom/datasets.md): Attaching state to a node for navigation and per-instance state
- [Merge Callbacks](https://azul.rs/guide/dom/merge-callbacks.md): How widgets keep heavy resources across a layout rebuild
- [Virtual Views](https://azul.rs/guide/dom/virtual-views.md): A node that materialises lazily, for infinite lists and embedded sub-DOMs
- [Components](https://azul.rs/guide/dom/components.md): Reusable UI fragments - named functions of (args) -> Dom
- [CSS Properties](https://azul.rs/guide/styling/properties.md): Reference of every CSS property azul recognises
- [System Themes](https://azul.rs/guide/styling/themes.md): System colors, `@theme`, `@os`, and accessibility queries
- [Styling Text](https://azul.rs/guide/styling/text-and-fonts.md): Font family, size, weight, alignment, decoration, and the system font keywords
- [Icon Packs](https://azul.rs/guide/styling/icon-packs.md): Register icons and use them with `Dom::create_icon` or `<icon>`
- [Simple Layout](https://azul.rs/guide/layout/blocks.md): Explains block formatting, sizing, positioning, the box model and how to handle overflowing content
- [Inline Layout](https://azul.rs/guide/layout/inline.md): Text flow, word breaks, writing modes, multi-column
- [Flexbox](https://azul.rs/guide/layout/flex.md): One-axis container layout with grow/shrink/basis
- [Grid](https://azul.rs/guide/layout/grid.md): Two-axis container layout with tracks and areas
- [SVG](https://azul.rs/guide/images/svg.md): Parsing and rendering SVG documents
- [GL Canvas](https://azul.rs/guide/images/canvas-gl.md): Embedding an OpenGL canvas inside a Dom node
- [Events](https://azul.rs/guide/events.md): Callbacks, event filters, and how state triggers relayout
- [Text Selection](https://azul.rs/guide/text-selection.md): Selection ranges, cursors, and copy/paste
- [Timers](https://azul.rs/guide/timers.md): Timers, threads, and scheduled work
- [Animations](https://azul.rs/guide/animations.md): CSS transitions and @keyframes
- [Scrolling](https://azul.rs/guide/scrolling-and-drag.md): Scroll containers, drag-and-drop, hit testing
- [Input Widgets](https://azul.rs/guide/widgets/inputs.md): Text fields, checkboxes, radios, sliders, dropdowns
- [Structural Widgets](https://azul.rs/guide/widgets/structural.md): Panels, splitters, tab views, list views, tree views
- [Debugging](https://azul.rs/guide/debugging.md): Debug overlays, the inspector, and structured logging
- [Profiling](https://azul.rs/guide/memory-profiling.md): Tracking allocations and per-frame budgets
- [XML Parsing (Standalone)](https://azul.rs/guide/xml.md): Loading a Dom from an XML string
- [Maps (MapWidget)](https://azul.rs/guide/maps.md): A slippy map widget with pan/zoom, tap-to-pin hooks, and lat/lon projection
- [Generating PDFs (HTML-to-PDF)](https://azul.rs/guide/pdf.md): Render a styled Dom to PDF bytes - headless, no window, no file I/O
- [SQL Database (Db)](https://azul.rs/guide/database.md): A bundled-SQLite handle - execute/query with typed value arrays
- [Device Input (Sensors, Gamepad, Geolocation)](https://azul.rs/guide/device-input.md): React to motion sensors, gamepads, and location as events - no polling
- [Code Generation](https://azul.rs/guide/code-generation.md): How `azul-doc` regenerates bindings from `api.json`
- [Deploying azul web apps with the pre-lifted base image](https://azul.rs/guide/deploying-web.md): Fast cold starts via a pre-lifted WASM Docker base image
- [Security Model](https://azul.rs/guide/security.md): What azul does and doesn't defend against

## Internals (contributor docs)

- [Async, Timers, Threading](https://azul.rs/guide/internals/async.md)
- [FFI Codegen](https://azul.rs/guide/internals/build-and-codegen.md)
- [Code Organization](https://azul.rs/guide/internals/code-organization.md)
- [DOM Internals](https://azul.rs/guide/internals/dom.md)
- [Component Type System](https://azul.rs/guide/internals/dom/component-types.md)
- [IFrame Scroll and Display Lists](https://azul.rs/guide/internals/dom/iframe-scroll.md)
- [VirtualView Lazy Loading](https://azul.rs/guide/internals/dom/virtual-view.md)
- [Events](https://azul.rs/guide/internals/events.md)
- [Hit Testing](https://azul.rs/guide/internals/events/hit-testing.md)
- [Host-Invoker Pattern (managed-FFI callbacks)](https://azul.rs/guide/internals/host-invoker.md)
- [Layout](https://azul.rs/guide/internals/layout.md)
- [Fragmentation](https://azul.rs/guide/internals/layout/fragmentation.md)
- [Inline Text](https://azul.rs/guide/internals/layout/inline-text.md)
- [Rendering](https://azul.rs/guide/internals/rendering.md)
- [GL Function Loading](https://azul.rs/guide/internals/rendering/gl-loading.md)
- [Image Pipeline](https://azul.rs/guide/internals/rendering/image-pipeline.md)
- [Text Pipeline](https://azul.rs/guide/internals/rendering/text-pipeline.md)
- [WebRender Bridge](https://azul.rs/guide/internals/rendering/webrender-bridge.md)
- [Styling Subsystem](https://azul.rs/guide/internals/styling.md)
- [Cascade, Inheritance, Restyle](https://azul.rs/guide/internals/styling/cascade.md)
- [Compact Property Cache](https://azul.rs/guide/internals/styling/compact-cache.md)
- [CSS Parser](https://azul.rs/guide/internals/styling/css-parser.md)
- [System Style Discovery](https://azul.rs/guide/internals/styling/system-style.md)
- [Web Backend Internals](https://azul.rs/guide/internals/web.md)
- [Windowing](https://azul.rs/guide/internals/windowing.md)
- [Windowing — Accessibility](https://azul.rs/guide/internals/windowing/accessibility.md)
- [Windowing — Common](https://azul.rs/guide/internals/windowing/common.md)
- [Windowing — Linux DBus](https://azul.rs/guide/internals/windowing/linux-dbus.md)
- [Windowing — Linux Wayland](https://azul.rs/guide/internals/windowing/linux-wayland.md)
- [Windowing — Linux X11](https://azul.rs/guide/internals/windowing/linux-x11.md)
- [Windowing — macOS](https://azul.rs/guide/internals/windowing/macos.md)
- [Windowing — Menus and CSD](https://azul.rs/guide/internals/windowing/menus-and-csd.md)
- [Windowing — Windows](https://azul.rs/guide/internals/windowing/windows.md)

## API reference

- [API reference (HTML)](https://azul.rs/api.html): full rendered reference for the latest version
- [Version manifest](https://azul.rs/api/index.json): JSON `{ "latest": "0.2.0", "versions": [...] }`
- [Per-version reference](https://azul.rs/api/0.2.0.html)
- [Search index (JSON)](https://azul.rs/api/0.2.0.search.json): compact searchable index over the whole API. Each entry has short keys — `k` kind (`m` module, `s` struct, `e` enum, `fp` fnptr, `ev` enum variant, `f` struct field, `fn` method, `cn` constructor), `n` name, `m` module, `p` parent class, `a` anchor, `d` doc text, `s` signature.

## Hello world (per language)

- [rust hello world](https://azul.rs/guide/hello-world/rust.md)
- [c hello world](https://azul.rs/guide/hello-world/c.md)
- [cpp hello world](https://azul.rs/guide/hello-world/cpp.md)
- [python hello world](https://azul.rs/guide/hello-world/python.md)

## Agent skill

- [azul-gui skill file](https://azul.rs/skill.md): install once to make a coding agent ready to build azul apps; also at https://azul.rs/.well-known/azul-skill.md
- [llms-full.txt](https://azul.rs/llms-full.txt): every guide page concatenated