Getting Started

This guide assumes you have a basic understanding of Flutter and have already set up your development environment. If you're new to Flutter, you may follow the official installation guide.

Installation

From your Flutter project directory, run the following command to install Forui.

Forui 0.18.0+ requires Flutter 3.41.0+. Run flutter --version to check your Flutter version.

flutter pub add forui

Upgrading

Flutter does not automatically upgrade minor versions of packages prior to 1.0.0.

This means that that following entry in your pubspec.yaml file will not automatically upgrade to 0.20.0:

dependencies:
  forui: ^0.19.0 // ❌ will not upgrade to 0.20.0

To upgrade to the latest version of Forui, run the following command:

flutter pub upgrade forui --major-versions

From 0.17.0 onwards, Forui provides data driven fixes. This means that you can automate some of the migration by running dart fix --apply.

Forui Icons

Forui Icons is bundled with the forui package. You don't need to install it separately if you install forui.

If you would like to only use the icons, run the following command from your Flutter project's directory.

flutter pub add forui_assets

Usage

To use Forui widgets in your Flutter app, import the Forui package and place the FTheme widget underneath CupertinoApp, MaterialApp, or WidgetsApp at the root of the widget tree.

To generate a basic Forui app structure in your project, run:

dart run forui init

dart run forui init --template=router

Or copy & paste the following code snippet:

1import 'package:flutter/foundation.dart';
2import 'package:flutter/material.dart';
3
4import 'package:forui/forui.dart';
5
6void main() {
7  runApp(const Application());
8}
9
10class Application extends StatelessWidget {
11  const Application({super.key});
12
13  @override
14  Widget build(BuildContext context) {
15    /// Try changing this and hot reloading the application.
16    ///
17    /// To create a custom theme:
18    /// ```shell
19    /// dart forui theme create [theme template].
20    /// ```
21    final theme =
22        const <TargetPlatform>{
23          .android,
24          .iOS,
25          .fuchsia,
26        }.contains(defaultTargetPlatform)
27        ? FThemes.neutral.dark.touch
28        : FThemes.neutral.dark.desktop;
29
30    return MaterialApp(
31      // TODO: replace with your application's supported locales.
32      supportedLocales: FLocalizations.supportedLocales,
33      // TODO: add your application's localizations delegates.
34      localizationsDelegates: const [...FLocalizations.localizationsDelegates],
35      // MaterialApp's theme is also animated by default with the same duration and curve.
36      // See https://api.flutter.dev/flutter/material/MaterialApp/themeAnimationStyle.html
37      // for how to configure this.
38      //
39      // There is a known issue with implicitly animated widgets where their transition
40      // occurs AFTER the theme's. See https://github.com/duobaseio/forui/issues/670.
41      theme: theme.toApproximateMaterialTheme(),
42      builder: (_, child) => FTheme(
43        data: theme,
44        child: FToaster(child: FTooltipGroup(child: child!)),
45      ),
46      // You can also replace FScaffold with Material Scaffold.
47      home: const FScaffold(
48        // TODO: replace with your widget.
49        child: Example(),
50      ),
51    );
52  }
53}
54
55class Example extends StatefulWidget {
56  const Example({super.key});
57
58  @override
59  State<Example> createState() => _ExampleState();
60}
61
62class _ExampleState extends State<Example> {
63  int _count = 0;
64
65  @override
66  Widget build(BuildContext context) => Center(
67    child: Column(
68      mainAxisSize: .min,
69      spacing: 10,
70      children: [
71        Text('Count: $_count'),
72        FButton(
73          onPress: () => setState(() => _count++),
74          suffix: const Icon(FIcons.chevronsUp),
75          child: const Text('Increase'),
76        ),
77      ],
78    ),
79  );
80}
81

1import 'package:flutter/foundation.dart';
2import 'package:flutter/material.dart';
3
4import 'package:forui/forui.dart';
5
6void main() {
7  runApp(const Application());
8}
9
10class Application extends StatelessWidget {
11  const Application({super.key});
12
13  @override
14  Widget build(BuildContext context) {
15    /// Try changing this and hot reloading the application.
16    ///
17    /// To create a custom theme:
18    /// ```shell
19    /// dart forui theme create [theme template].
20    /// ```
21    final theme =
22        const <TargetPlatform>{
23          .android,
24          .iOS,
25          .fuchsia,
26        }.contains(defaultTargetPlatform)
27        ? FThemes.neutral.dark.touch
28        : FThemes.neutral.dark.desktop;
29
30    return MaterialApp.router(
31      // TODO: replace with your application's supported locales.
32      supportedLocales: FLocalizations.supportedLocales,
33      // TODO: add your application's localizations delegates.
34      localizationsDelegates: const [...FLocalizations.localizationsDelegates],
35      // MaterialApp's theme is also animated by default with the same duration and curve.
36      // See https://api.flutter.dev/flutter/material/MaterialApp/themeAnimationStyle.html
37      // for how to configure this.
38      //
39      // There is a known issue with implicitly animated widgets where their transition
40      // occurs AFTER the theme's. See https://github.com/duobaseio/forui/issues/670.
41      theme: theme.toApproximateMaterialTheme(),
42      builder: (_, child) => FTheme(
43        data: theme,
44        child: FToaster(child: FTooltipGroup(child: child!)),
45      ),
46      // TODO: Add your router configuration here.
47    );
48  }
49}
50

It is perfectly fine to use Cupertino/Material widgets alongside Forui widgets!

1import 'package:flutter/cupertino.dart';
2
3import 'package:forui/forui.dart';
4
5
6void main() {
7  runApp(const Application());
8}
9
10class Application extends StatelessWidget {
11  const Application({super.key});
12
13  @override
14  Widget build(BuildContext context) => CupertinoApp(
15    builder: (context, child) => FTheme(
16      data: FThemes.neutral.light.touch,
17      child: FToaster(child: FTooltipGroup(child: child!)),
18    ),
19    home: const FScaffold(child: Placeholder()),
20  );
21}
22

Themes

Forui provides a set of predefined themes that you can use out of the box. In the example above, we used the FThemes.neutral.light theme, which is a light theme variant of the neutral color scheme.

Themes are a very powerful building block in Forui, allowing you to customize the look and feel of your app. To learn more about themes, refer to the Themes page.