Widget Field Guide

Install

flutter pub add welkui_flutter

Latest release: welkui_flutter 0.2.0 on pub.dev. Requires Dart 3.13.4+ and Flutter 3.35.0+.

Usage

import 'package:flutter/material.dart';
import 'package:welkui_flutter/welkui_flutter.dart';

Scaffold(
  appBar: WelkAppBar(
    title: 'Comic studio',
    logo: const Icon(Icons.bolt),
    layout: WelkAppBarLayout.sticker,
    floating: true,
    actions: [
      IconButton(
        tooltip: 'Search',
        icon: const Icon(Icons.search),
        onPressed: () {},
      ),
    ],
  ),
  body: const Center(child: Text('Your next adventure starts here.')),
)

Variants and behavior

• Layouts: comicStrip, sticker, bubble and split
• Optional logo with leading-edge or centered placement
• Automatically implies a back or drawer button; supports up to three actions
• Floating card appearance is separate from scroll behavior; use WelkSliverAppBar for pinned or scroll-away layouts

Usage notes and accessibility

• Available since 0.2.0.
• Provide either title or titleWidget, but not both. Supply leading to replace the inferred back or drawer button.
• At most three actions are supported. Keep action tooltips meaningful for accessible names.
• floating controls the detached card appearance, not scroll behavior. Use WelkSliverAppBar inside CustomScrollView for pinned or scroll-away behavior.
• Colors inherit from WelkTheme. Set primary: false when using the bar inline without status-bar padding.

Dark mode

Control all widgets, pickers, and overlays with WelkThemeData.darkMode: set it to true to enable dark mode or false to disable it. When left null (the default), widgets follow Flutter's ThemeData.brightness. To follow the device setting, provide light and dark themes on MaterialApp and use ThemeMode.system.

Place WelkTheme above MaterialApp so open popups and overlays also follow global updates. Rebuild it with data.copyWith(darkMode: true) or data.copyWith(darkMode: false) to switch modes. This example also switches the Material theme to keep the app's scaffold and other Material widgets in sync:

import 'package:flutter/material.dart';
import 'package:welkui_flutter/welkui_flutter.dart';

class DarkModeExample extends StatefulWidget {
  const DarkModeExample({super.key});

  @override
  State<DarkModeExample> createState() => _DarkModeExampleState();
}

class _DarkModeExampleState extends State<DarkModeExample> {
  WelkThemeData _theme = const WelkThemeData(darkMode: false);

  @override
  Widget build(BuildContext context) {
    return WelkTheme(
      data: _theme,
      child: MaterialApp(
        theme: ThemeData.light(),
        darkTheme: ThemeData.dark(),
        themeMode: _theme.darkMode == true ? ThemeMode.dark : ThemeMode.light,
        home: Scaffold(
          body: Center(
            child: WelkSwitch(
              label: 'Dark mode',
              value: _theme.darkMode == true,
              onChanged: (enabled) {
                setState(() {
                  _theme = _theme.copyWith(darkMode: enabled);
                });
              },
            ),
          ),
        ),
      ),
    );
  }
}

Override a widget

Set overRideDarkMode: true to force dark mode or overRideDarkMode: false to force light mode, regardless of the global setting. Omit it (or pass null) to inherit. Container overrides flow into nested WelkUI widgets, and dialog, drawer, and snackbar show functions accept the same override. Local themes are carried into overlays when opened.

WelkButton(
  overRideDarkMode: true,
  variant: WelkButtonVariant.secondary,
  onPressed: () {},
  child: const Text('Always dark'),
)

WelkButton(
  overRideDarkMode: false,
  onPressed: () {},
  child: const Text('Always light'),
)

Dark palette and appearance

Neutral surfaces, text, and icons adapt automatically. Semantic variant fills receive a 10% black tint, with black borders and whitish-gray hard shadows. Secondary buttons use charcoal-gray surfaces; ghost buttons stay transparent. QR codes keep a light backing and dark modules for scanning. Built-in avatar portraits switch to white assets in dark mode; custom icons and profile images are not filtered.

Customize the palette through WelkThemeData using darkPaper, darkMuted, darkInk, darkOutline, darkShadow, darkButtonTint, and darkFocus. See the Flutter README's global dark mode guide for the package reference.

Constructor parameters

Required parameters are marked in the default column. Other parameters are optional.

WelkTheme(
  data: const WelkThemeData().copyWith(
    accent: const Color(0xFFFFD166),
    ink: const Color(0xFF202020),
    paper: const Color(0xFFFFFDF5),
  ),
  child: WelkButton(
    onPressed: () {},
    child: const Text('Your colors. WelkUI character.'),
  ),
)

const Text(
  'Made with WelkUI',
  style: TextStyle(
    fontFamily: 'ShortStack',
    package: 'welkui_flutter',
    fontSize: 20,
  ),
)