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.15.0+ requires Flutter 3.35.0+. Run flutter --version to check your Flutter version.

bash


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.15.0:

pubspec.yaml


dependencies:
  forui: ^0.15.0 // ❌ will not upgrade to 0.16.0

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

bash


flutter pub upgrade forui --major-versions

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.

bash


flutter pub add forui_assets

Usage

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

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

bash


dart run forui init

Or copy & paste the following code snippet:


import 'package:flutter/material.dart';
import 'package:forui/forui.dart';
 
void main() {
  runApp(const Application());
}
 
class Application extends StatelessWidget {
  const Application({super.key});
 
  @override
  Widget build(BuildContext context) {
    /// Try changing this and hot reloading the application.
    ///
    /// To create a custom theme:
    /// ```shell
    /// dart forui theme create [theme template].
    /// ```
    final theme = FThemes.zinc.dark;
 
    return MaterialApp(
      // TODO: replace with your application's supported locales.
      supportedLocales: FLocalizations.supportedLocales,
      // TODO: add your application's localizations delegates.
      localizationsDelegates: const [...FLocalizations.localizationsDelegates],
      // MaterialApp's theme is also animated by default with the same duration and curve.
      // See https://api.flutter.dev/flutter/material/MaterialApp/themeAnimationStyle.html for how to configure this.
      //
      // There is a known issue with implicitly animated widgets where their transition occurs AFTER the theme's.
      // See https://github.com/forus-labs/forui/issues/670.
      theme: theme.toApproximateMaterialTheme(),
      builder: (_, child) => FAnimatedTheme(data: theme, child: child!),
      // You can also replace FScaffold with Material Scaffold.
      home: const FScaffold(
        // TODO: replace with your widget.
        child: Example(),
      ),
    );
  }
}
 
class Example extends StatefulWidget {
  const Example({super.key});
 
  @override
  State<Example> createState() => _ExampleState();
}
 
class _ExampleState extends State<Example> {
  int _count = 0;
 
  @override
  Widget build(BuildContext context) => Center(
    child: Column(
      mainAxisSize: MainAxisSize.min,
      spacing: 10,
      children: [
        Text('Count: $_count'),
        FButton(
          onPress: () => setState(() => _count++),
          suffix: const Icon(FIcons.chevronsUp),
          child: const Text('Increase'),
        ),
      ],
    ),
  );
}

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

main.dart


import 'package:flutter/cupertino.dart';
 
import 'package:forui/forui.dart';
 
void main() {
  runApp(const Application());
}
 
class Application extends StatelessWidget {
  const Application({super.key});
 
  Widget build(BuildContext context) => CupertinoApp(
    builder: (context, child) => FAnimatedTheme(
      data: FThemes.zinc.light,
      child: child!,
    ),
    home: FScaffold(...)
  );
}

Themes

Forui provides a set of predefined themes that you can use out of the box. In the example above, we used the FThemes.zinc.light theme, which is a light theme variant of the zinc 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.