RemixRemix

Build a settings screen

Use Remix CLI recipes to build, customize, and test a Flutter settings screen

Build Launchpad, a desktop-browser settings screen with a form, save state, dialog, and sidebar. You write the application; the CLI installs editable component recipes and their theme.

Launchpad with the Vanilla preset

The finished screenshot includes the medium Button height edit below. It is an application example, not a screen the CLI generates for you.

This walkthrough includes the complete application and test source below. The sample download contains both projects, generated adapters, and their tests. Its default_demo directory holds the Vanilla project.

Before you start

Use Flutter 3.44 or newer, which bundles Dart 3.12, Git, and a desktop browser. Check your SDK with flutter --version. The samples use local state, with no backend or responsive mobile layout. Both hosts explicitly use Geist from remix_ui_fonts, so app text and owned recipes share a reproducible font.

Prepare the project and CLI

In the directory where you keep applications:

flutter create --empty --platforms=web remix_default_demo
cd remix_default_demo

Install the CLI release candidate globally and confirm its version:

dart pub global activate remix_cli '^1.0.0-rc.1'
remix --version

Add Pub's bin directory to PATH if needed; Pub prints the instructions. The printed version should satisfy the release-candidate constraint above. Keep running CLI commands from the project root, beside pubspec.yaml.

Initialize and install Button

remix init --prefix Acme --preset vanilla

Acme controls local names such as AcmeButton and acmeButtonStyle. Initialization resolves the official registry's stable branch to a commit, records it in remix.yaml, and writes a managed barrel at lib/ui/ui.dart. It does not install a component yet.

Preview the first install:

remix add button --dry-run

The plan should install theme before button and list the dependencies the CLI will add, including remix and remix_ui_fonts. No source is written by --dry-run. Install when the plan matches:

remix add button

Inspect lib/ui/components/button.dart, the recipe you own, and button.g.dart, the adapter produced by the generator. Edit the recipe, not the generated file. The CLI also adds the required dependencies and exports.

Render the first button

Replace lib/main.dart with this complete example:

import 'package:flutter/widgets.dart';

import 'ui/ui.dart';

void main() => runApp(const AcmeApp());

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

  @override
  Widget build(BuildContext context) {
    return WidgetsApp(
      color: const Color(0xFF000000),
      builder: (_, _) => Overlay(
        initialEntries: [
          OverlayEntry(
            builder: (_) => const AcmeTheme(
              theme: AcmeThemeData.light(),
              child: HomePage(),
            ),
          ),
        ],
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    final theme = AcmeTheme.of(context);
    return ColoredBox(
      color: theme.background,
      child: Center(
        child: AcmeButton.primary(
          label: 'Continue',
          onPressed: () {},
        ),
      ),
    );
  }
}
flutter run -d chrome

The default Continue button on a white surface

You should see Continue centered in the app. Its callback is deliberately empty at this stage. Keep this terminal open; use another terminal in the same sample directory for the remaining CLI commands.

Build the settings screen

Install the remaining recipes, one item per command:

remix add checkbox
remix add textfield
remix add dialog
remix add card
remix add sidebar
remix add sidebar_layout

The existing theme is preserved. Sidebar also installs its toggle and tooltip dependencies. Sidebar Layout is a plain shell layout with no Spec and no generated adapter. It pairs an installed sidebar with a header and body, and switches to a start-edge sheet below its compact breakpoint. Each command updates the barrel and generates the needed adapters.

Replace your application's lib/main.dart with the complete Vanilla source below. The same file is default_demo/lib/main.dart in the sample download. Keep your CLI-installed lib/ui files; the next step changes one of them.

The complete app owns the form values, save counter, loading flag, dialog result, and sidebar selection. It uses WidgetsApp with a Navigator as the application host. Keep its host builder and scope placement together: the text field needs an overlay, and the dialog needs the invoking context's navigator and text defaults.

Customize your recipe

Open lib/ui/components/button.dart. In _metricsFor, change the medium minHeight from AcmeTokens.controlMd (36 pixels) to 44.0:

  .medium => (
    minHeight: 44.0,
    paddingX: AcmeTokens.s4,
    gap: AcmeTokens.s2,
  ),

Reload the app. All medium default buttons should use the taller recipe, while the cyan preview button keeps its instance-specific colors and rounded shape.

This changes a recipe value, not the generated widget signature. If you change recipe parameters, enums, or annotations, regenerate the adapter as described in the customization reference.

Check behavior and preserve edits

  1. Reload to reset local state. Enter Launchpad Studio as the workspace name.
  2. Clear Send a weekly summary, then press Save changes twice while loading.
  3. Confirm Save count: 1 and Summary: off when the save completes.
  4. Open and confirm the invitation dialog. Check that its result reaches the screen.
  5. Change the sidebar selection and test the preview button's callback.

Saved form values with one completed save and summary off

Now compare your edited Button with its registry recipe:

remix add button --diff

The diff's current side contains your 44.0 edit; proposed contains the registry token AcmeTokens.controlMd. The command does not replace your source. Repeat ordinary add:

remix add button

Confirm the medium height remains 44.0. --overwrite is an explicit replacement operation; do not use it to inspect an update. See source-preservation details before trying it.

Try Fortal separately

Do not switch the Vanilla project's preset. From its directory, create a second application:

cd ..
flutter create --empty --platforms=web remix_fortal_demo
cd remix_fortal_demo

Initialize Fortal and install its recipes using the same global CLI. The Fortal theme does not depend on remix_ui_fonts, so the last command adds Geist for the application:

remix init --prefix Acme --preset fortal
remix add button
remix add checkbox
remix add textfield
remix add dialog
remix add card
remix add sidebar
remix add sidebar_layout
flutter pub add 'remix_ui_fonts:^0.1.0'

Replace this app's lib/main.dart with the complete Fortal source below, also available as fortal_demo/lib/main.dart in the download.

The Fortal example uses AcmeTheme with the Mar accent and AcmeButton.solid, rather than AcmeButton.primary. Keep its complete host configuration. Do not apply the Vanilla preset's Button metrics edit to Fortal.

Launchpad with the Fortal preset, Mar accent, in dark mode

Fortal supplies a different theme and recipe vocabulary, not a second runtime for your form. Repeat the same behavior checks. Neither preset adds a remix_fortal package dependency to the consumer application.

Run the tests

Copy test/workflow_test.dart from the matching downloaded project into each sample. Keep the project names used above; the tests import those names.

Replace analysis_options.yaml with the reviewed configuration:

include: package:flutter_lints/flutter.yaml

analyzer:
  exclude:
    - lib/ui/**/*.g.dart

This excludes generated adapters from lint findings, not your authored recipes. Run from each sample directory:

flutter analyze
flutter test
flutter build web --release

The four workflow tests cover form and save behavior, disabled controls, callbacks, dialog results and text decoration, and sidebar selection. The download also carries theme-mode tests for each sample. Fix failures before treating a screenshot as evidence that the sample works.

Troubleshooting

  • Pub cannot resolve remix_cli: the CLI needs Dart 3.12. Check that flutter --version reports Flutter 3.44 or newer.
  • Missing generated class: inspect the add command's generation error and the recipe's part declaration.
  • Missing overlay or incorrect dialog text: restore the complete sample's application host and scope placement.
  • No primary constructor: use the Vanilla sample, selected with --preset vanilla, or the solid constructor with fortal.

See the CLI reference for configuration and command details.

View page source on GitHub

On this page