Headless Guide#
Build Flutter UI with consistent behavior, accessibility, and fully swappable visuals. This hub links every guide, recipe, and reference you need.
Learning Path#
Follow these steps to go from zero to production:
- Why Headless? - understand the architecture and when it makes sense
- Users Guide - install, configure, and build your first app
- Recipes - common patterns and a hands-on cookbook
- Customize - style tweaks, slots, scoped themes, and guardrails
Getting Started#
First time here?
Head straight to the Users Guide for a step-by-step walkthrough covering installation, renderer setup, and your first component.
Recipes#
| Recipe | What you will find |
|---|---|
| Common Recipes | Buttons, inputs, dropdowns, and everyday patterns |
| TextField Recipes | Validation, formatting, and controller wiring |
| Autocomplete Recipes | Async data sources, filtering, and custom layouts |
| Advanced Patterns | Scoped overrides, custom renderers, and large-app strategies |
Reference#
- Guardrails - safe customization boundaries and what to avoid
- Changelog - what changed between versions
Key Concepts
- Behavior vs Visuals - Headless separates what a component does (focus, keyboard, state, a11y) from how it looks. Behavior lives in
headless_foundation; visuals are pluggable. - Renderers - a renderer decides the structure and appearance. Headless ships Material 3 and Cupertino presets, and you can create your own.
- Customization levels - Style (quick visual tweaks) -> Slots (per-instance structure) -> Scoped Theme (subtree overrides) -> Custom Renderer (full control).