LayrzApp

LayrzApp

Root application widget for layrz_ui. Every app must wrap its content in a LayrzApp or LayrzApp.router to install the theme system, default text styles, and icon rendering.

---

Overview

LayrzApp is the entry point to the layrz_ui design system. It wraps the Flutter SDK's WidgetsApp to provide:

• Theme Installation — installs a LayrzTheme ancestor with design tokens and color values
• Default Text Style — sets a DefaultTextStyle with the theme's base text style
• Icon Theme — sets an IconTheme for the app's icon color and size
• Background Color — wraps content in a ColoredBox with the theme's background color
• Scroll Behavior — optionally applies a custom scroll behavior to the entire app

LayrzApp is light-mode-only. Dark mode is not supported. See decision D7 for details.

---

Two Constructors

Imperative Routing (Default Constructor)

Use the default constructor for apps with imperative navigation (Navigator.push, named routes, etc.):

LayrzApp(
  home: MyHomePage(),
  title: 'My App',
  theme: LayrzThemeData.light(),
)

All routing parameters ([home], [routes], [onGenerateRoute], [navigatorObservers]) are passed to the internal WidgetsApp.

Declarative Routing (LayrzApp.router)

Use LayrzApp.router for apps using a declarative router like go_router or auto_route:

LayrzApp.router(
  routerConfig: myRouter,
  title: 'My App',
  theme: LayrzThemeData.light(),
)

Parameters [routerConfig], [routerDelegate], [routeInformationParser], [routeInformationProvider], and [backButtonDispatcher] are passed to WidgetsApp.router.

---

API Reference

Routing (Imperative)

Parameter	Type	Default	Description
home	Widget?	null	The default route (/) of the app. Used only with the default constructor.
routes	Map<String, WidgetBuilder>?	null	A map of named routes. Used only with the default constructor.
onGenerateRoute	RouteFactory?	null	Callback to generate a route for the given RouteSettings. Used only with the default constructor.
onUnknownRoute	RouteFactory?	null	Callback when no matching route is found. Used only with the default constructor.
navigatorObservers	List<NavigatorObserver>	[]	Observers for the Navigator. Used only with the default constructor.
initialRoute	String?	null	The name of the first route to show. Defaults to /. Used only with the default constructor.

Routing (Declarative)

Parameter	Type	Default	Description
routerConfig	RouterConfig<Object>?	null	A RouterConfig that configures the Router widget. Used only with LayrzApp.router.
routerDelegate	RouterDelegate<Object>?	null	A delegate that provides a widget tree for the current RouteInformation. Used only with LayrzApp.router.
routeInformationParser	RouteInformationParser<Object>?	null	Restores RouteInformation from and to the platform. Used only with LayrzApp.router.
routeInformationProvider	RouteInformationProvider?	null	Provides RouteInformation to the Router. Used only with LayrzApp.router.
backButtonDispatcher	BackButtonDispatcher?	null	Handles the platform back button. Used only with LayrzApp.router.

Theme

Parameter	Type	Default	Description
theme	LayrzThemeData?	LayrzThemeData.light()	The light theme data. If not provided, a default light theme is created.

App Metadata

Parameter	Type	Default	Description
title	String	''	The one-line description of the app, shown in the OS task switcher.
onGenerateTitle	GenerateAppTitle?	null	Callback to generate a localized title. Takes precedence over title.
color	Color?	null	Primary color surfaced to the host OS (Android task-switcher, iOS, etc.). Defaults to theme.primaryColor if not supplied.
debugShowCheckedModeBanner	bool	true	Whether to show the debug banner in the top-right corner.
showSemanticsDebugger	bool	false	Whether to show the semantics debugger overlay.
debugShowWidgetInspector	bool	false	Whether to show the widget inspector overlay.

Localizations

Parameter	Type	Default	Description
locale	Locale?	null	The initial locale for the app. Defaults to the system locale.
localizationsDelegates	Iterable<LocalizationsDelegate<dynamic>>?	null	Delegates for localizing the app's content.
supportedLocales	Iterable<Locale>	[Locale('en')]	The locales the app supports.
localeListResolutionCallback	LocaleListResolutionCallback?	null	Callback to select a locale from the device's preferred list.
localeResolutionCallback	LocaleResolutionCallback?	null	Callback to select a locale given a single requested locale.

Builder and Scroll Behavior

Parameter	Type	Default	Description
builder	TransitionBuilder?	null	A widget builder inserted between LayrzApp and the route content. Receives the resolved child; return a new widget wrapping it.
scrollBehavior	ScrollBehavior?	null	Overrides the default scroll behavior for the entire app. When provided, the app is wrapped in a ScrollConfiguration with this behavior.

Shortcuts and Actions

Parameter	Type	Default	Description
shortcuts	Map<ShortcutActivator, Intent>?	null	A map of keyboard shortcut activators to Intents.
actions	Map<Type, Action<Intent>>?	null	A map of Intent types to Actions.
restorationScopeId	String?	null	The identifier for state restoration.

---

Theme Installation

LayrzApp installs the following widget tree around your app:

LayrzApp
├── LayrzTheme (installs theme data)
│   └── DefaultTextStyle (applies theme's base text style)
│       └── IconTheme (applies theme's icon theme)
│           └── ColoredBox (fills background with theme's background color)
│               ├── ScrollConfiguration (optional, if scrollBehavior is supplied)
│               └── [your app content]

This means:

• Every widget in the tree can access the theme via BuildContext.theme, BuildContext.tokens, and BuildContext.tokenizer.
• All text renders in the theme's default text style unless overridden.
• All icons render in the theme's icon color (default: primary text color) unless overridden.
• The background is painted with the theme's background color.

---

Example: Full App Setup

import 'package:flutter/widgets.dart';
import 'package:layrz_ui/layrz_ui.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return LayrzApp(
      title: 'My Application',
      theme: LayrzThemeData.light(
        primaryColor: const Color(0xFF001E60), // Deep navy blue
      ),
      home: const HomePage(),
      debugShowCheckedModeBanner: false, // Hide debug banner in debug mode
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      color: context.theme.backgroundColor,
      child: Center(
        child: Text(
          'Hello!',
          style: context.theme.textStyle,
        ),
      ),
    );
  }
}

---

Important Notes

No Dark Theme / Theme Mode

LayrzApp does not support darkTheme or themeMode parameters. layrz_ui is light-mode-only. See decision D7 for the architectural rationale.

If your app needs dark mode, you must implement it outside layrz_ui or wait for a future layrz_ui dark theme (not currently planned).

The Theme Never Changes

The theme parameter is immutable. If you need to change the app's theme at runtime, wrap LayrzApp in a widget that owns the theme state and rebuilds LayrzApp when it changes.

---

Last updated: 2026-08-13
Related pages: Theming, Getting-Started, Design-Tokens