welkui_flutter 0.2.2
welkui_flutter: ^0.2.2 copied to clipboard
Comic-inspired Flutter widgets for Android and iOS, with crisp outlines, hard shadows, bundled typography, and accessible mobile interactions.
WelkUI Flutter
pub.dev · Documentation · Contributing · MIT License
Familiar WelkUI. Native Flutter. #
WelkUI Flutter brings the visual identity of the WelkUI React library to mobile apps with idiomatic Dart APIs and Flutter interactions. No Material elevation, gradients, or runtime font downloads.
- Distinctive by default: asymmetric corners, crisp ink outlines, solid offset shadows, and the Short Stack typeface.
- Made for touch: at least 48 logical-pixel interactive targets, visible tap feedback, and controlled state where it matters.
- Accessibility built in: semantics, keyboard focus, RTL layout, text scaling, and reduced-motion support.
- Easy to make yours: immutable theme tokens, local styling overrides,
and locally bundled typography. QR encoding uses the pure-Dart
qrpackage.
Full documentation: ui.welkdock.com/flutter
This README covers setup and the essentials. Visit the Flutter documentation for the full guide and a live preview of each widget.
Quick start #
For Android and iOS apps, install from pub.dev:
flutter pub add welkui_flutter
Or add the dependency to pubspec.yaml and run flutter pub get:
dependencies:
welkui_flutter: ^0.1.5
Requires Dart 3.13.4+ and a compatible Flutter SDK satisfying 3.35.0+. Short Stack is bundled locally; no additional font setup is needed.
Widgets #
| Controls & forms | Content & navigation | Overlays & utilities |
|---|---|---|
WelkButton |
WelkAccordion |
WelkDialog |
WelkIconButton |
WelkAvatar |
WelkDrawer |
WelkCheckBox |
WelkBadge |
WelkTooltip |
WelkRadio |
WelkBreadCrumbs |
WelkSnackBar |
WelkRadioGroup |
WelkCard |
WelkAttachment |
WelkSwitch |
WelkDivider |
WelkQRCode |
WelkInput |
WelkImage |
WelkDateInput |
WelkOTPInput |
WelkMenu |
WelkDatePicker |
WelkDropDown |
WelkSticker |
WelkTimePicker |
WelkRangeSlider |
WelkStickerCard |
WelkTabs |
WelkBottomNavBar |
WelkBottomNavScaffold |
|
WelkAppBar |
WelkSliverAppBar |
App bars #
WelkAppBar works in Scaffold.appBar and provides four layouts:
comicStrip (accent underline), sticker (tilted title sticker), bubble
(pill title), and split (contrasting leading panel).
Scaffold(
appBar: WelkAppBar(
title: 'Comic studio', // Or titleWidget: MyCustomTitle()
logo: const Icon(Icons.bolt),
logoPosition: WelkAppBarLogoPosition.left, // Or center
layout: WelkAppBarLayout.sticker,
floating: true,
actions: [
IconButton(
tooltip: 'Search',
icon: const Icon(Icons.search),
onPressed: () {},
),
],
),
body: const MyPage(),
)
Provide either a string title or a custom titleWidget, and up to three
actions. Logo placement follows the leading edge or centers the logo/title
group; on narrow screens branding yields space to the action buttons.
Back and drawer buttons are inferred automatically, or supply leading.
floating: true draws a detached card with margins and a hard comic shadow;
it does not enable scroll-floating behavior. Customize height, margin,
padding, logoSize, titleStyle, borderRadius, borderWidth,
backgroundColor, foregroundColor, accentColor, borderColor,
shadowColor, and shadowOffset. Unset colors follow WelkTheme; use
overRideDarkMode for a local override. Set primary: false for inline
previews to avoid status-bar padding.
For sticky or scroll-away behavior, use the sliver wrapper:
CustomScrollView(
slivers: [
WelkSliverAppBar(
pinned: true, // false scrolls the bar away with the page
appBar: WelkAppBar(title: 'Adventure', floating: true),
),
SliverList.builder(
itemCount: 40,
itemBuilder: (_, index) => ListTile(title: Text('Panel $index')),
),
],
)
The example's WelkAppBar screen (/app-bar) includes every layout,
floating and attached previews, custom branding, and a launchable scrolling demo.
Bottom navigation #
WelkBottomNavScaffold is a complete app shell for 2–5 destinations. Each
destination gets its own stateful page and nested Navigator, so page state is
kept while switching tabs, and Navigator.of(context).push(...) opens a subpage
inside the current destination.
WelkBottomNavScaffold(
layout: WelkBottomNavLayout.popCircle, // blockCenter, popBlock, comicDock, bubbleRail
mode: WelkBottomNavMode.floating, // or defaultMode (anchored)
visibility: WelkBottomNavVisibility.hideOnScrollDown, // sticky, alwaysVisible
hideOnSubpages: true,
transition: WelkBottomNavTransition.fadeThrough,
initialIndex: 0,
onIndexChanged: (index) {},
style: const WelkBottomNavStyle(height: 64, activeItemSize: 60),
items: [
WelkBottomNavItem(
icon: const Icon(Icons.home_outlined),
activeIcon: const Icon(Icons.home),
label: 'Home',
builder: (_) => const HomePage(),
),
// ...up to five items
],
)
- Layouts:
popCircle,blockCenter, andpopBlockfeature the middle destination (with 3 or 5 items);comicDockraises a comic tile for the active item;bubbleRailglides a bubble between items. - Visibility:
stickystays visible while scrolling,hideOnScrollDownhides when scrolling down (tune withscrollSensitivity), andalwaysVisiblenever hides.hideOnSubpages(defaulttrue) hides the bar on pushed subpages and restores it on the destination's root page. - State: use
WelkBottomNavScaffold.of(context)toselect(index)orpopToRoot(). Tapping the active item again pops it to its root page. - Styling:
WelkBottomNavStylecovers colors, icons, typography, label behavior, height, width, margins, padding, corner radius, borders, shadows, elevation, active-item size, and animation duration and curve. Unset colors follow the WelkUI light and dark palettes.
Use the stateless WelkBottomNavBar (with currentIndex and onTap) to manage
pages yourself, for example as a Scaffold.bottomNavigationBar with
extendBody: true.
Global dark mode #
Set WelkThemeData.darkMode once in your app's WelkTheme to control dark mode
globally. Rebuild the provider with data.copyWith(darkMode: true) or false
to switch modes. When darkMode is null (the default), widgets follow
Flutter's ThemeData.brightness.
All WelkUI widgets consume the dark-mode preference, including controls,
content, pickers, and overlays. The example app includes a floating
WelkIconButton theme toggle on non-embedded screens.
WelkTheme(
data: const WelkThemeData(darkMode: true),
child: MaterialApp(home: MyHomePage()),
)
Set overRideDarkMode on any widget to force dark (true) or light (false),
regardless of the global setting. Omit it to inherit. Container overrides also
flow into nested WelkUI widgets; dialog, drawer, and snackbar show functions
accept the same override.
Place the global WelkTheme above MaterialApp so open popups and overlays
can also follow its updates. Local themes are carried into overlays when opened.
Dark mode adds a 10% black tint to semantic variant fills, with black borders,
whitish-gray hard shadows, and contrasting text and icons. Secondary buttons use
a charcoal-gray surface, and ghost buttons remain transparent.
Neutral surfaces and text adapt to dark mode. QR modules retain a light backing
and dark modules for scanning. Avatar portraits use black assets in light mode
and white assets in dark mode; custom icons and profile images are not filtered.
Customize the dark palette with darkPaper, darkMuted, darkInk, darkOutline,
darkShadow, darkButtonTint, and darkFocus design tokens.
WelkButton(
overRideDarkMode: true,
variant: WelkButtonVariant.secondary,
onPressed: () {},
child: const Text('Continue'),
)
Contributing & license #
See the contribution guidelines for setup and pull requests. Released under the MIT License; the bundled Short Stack font uses the SIL Open Font License 1.1.