catalyst_ui library

A flexible, theme-driven UI component library for Flutter.

No Material or Cupertino dependency. All design tokens — colours, typography, spacing, radius, motion, and shadows — are fully customisable via ThemeData. Component variants (e.g. ButtonVariant, ChipVariant, BadgeVariant) are abstract classes that you can subclass to define your own styles.

Quick start

import 'package:catalyst_ui/catalyst_ui.dart';

Theme(
  data: ThemeData.light(
    fontFamily: 'Inter',
    colorScheme: const ColorScheme.light().copyWith(
      brand: Color(0xFF7C3AED),
      brandSoft: Color(0xFFEDE9FE),
    ),
  ),
  child: MyApp(),
)

Custom button variant

class OutlineButtonVariant extends ButtonVariant {
  const OutlineButtonVariant();

  @override
  ButtonVariantStyle resolve(ColorScheme cs) => ButtonVariantStyle(
    backgroundColor: Colors.transparent,
    foregroundColor: cs.brand,
    borderColor: cs.brand,
  );
}

Classes

ActionTile
A tappable tile with a circular icon, title, optional subtitle, and optional badge.
Alert
An inline notification banner used to convey contextual feedback.
AlertTone
Defines the colour of an Alert.
AlertToneStyle
The resolved visual properties for a single AlertTone.
AppBar
A top application bar for mobile screens.
Avatar
A circular or rounded-square avatar displaying initials or a network image.
AvatarStack
A horizontal stack of overlapping Avatar widgets.
Badge
A small pill-shaped label conveying status, category, or count.
BadgeVariant
Defines the visual appearance of a Badge.
BadgeVariantStyle
The resolved visual properties for a single BadgeVariant.
BottomNav<T>
A bottom navigation bar for mobile screens.
BottomNavDestination<T>
A single destination entry in a BottomNav bar.
BottomSheet
A modal bottom sheet with a drag handle, title, body, and footer.
A horizontal breadcrumb trail for communicating navigational hierarchy.
Breakpoints
The minimum widths (in logical pixels) at which each named breakpoint becomes active.
Button
A pressable button supporting labels, icons, loading states, and user-defined visual variants.
ButtonVariant
Defines the visual appearance of a Button.
ButtonVariantStyle
The resolved visual properties for a single ButtonVariant.
Card
A rounded container that groups related content.
CardTone
Defines the background and border of a Card.
CardToneStyle
The resolved visual properties for a single CardTone.
CatalystProvider
Convenience widget that sets up the full Catalyst UI scope in one step.
Checkbox
A toggleable checkbox control with an optional text label.
Chip
A compact, pill-shaped selection or filtering control.
ChipVariant
Defines the visual appearance of a Chip in resting and selected states.
ChipVariantStyle
The resolved visual properties for a single ChipVariant.
ColorScheme
The full set of semantic colours consumed by all Catalyst components.
Divider
A thin horizontal or vertical rule used to separate content.
Drawer
A side panel that slides in from the edge of the screen.
EmptyState
A centred illustration and message shown when a list or page has no data.
ErrorState
An error state widget for showing failure feedback with an optional retry.
FormLayout
Displays a series of FormLayoutGroups in a particular layout style.
FormLayoutGroup
Defines the contents of a single group in a FormLayout.
Iconography
Defines common icons used throughout the component library.
ListItem
A single row in a list with optional leading icon, title, subtitle, and trailing widget.
A button that opens a contextual dropdown menu when tapped.
A visual divider that can be placed between groups of items in a MenuButton dropdown.
A sealed base class for items that can appear in a MenuButton dropdown.
A single actionable item in a MenuButton dropdown.
A dialog modal with a title, body, and row of action buttons.
Motion
The set of animation presets used by Catalyst components.
Pagination
A row of page-number buttons with optional ellipsis collapse.
ProgressBar
An animated horizontal progress bar.
ProgressBarTone
Defines the fill colour of a ProgressBar.
ProgressBarToneStyle
The resolved visual properties for a single ProgressBarTone.
Radii
Standard border-radius values used across Catalyst components.
Radio
A single radio button control with an optional text label.
RadioGroup<T>
A collection of selectable options rendered as a radio group.
RadioGroupCardOption<T>
An option for a RadioGroup displayed as a card.
RadioGroupOption<T>
An option for a RadioGroup with a label and optional description.
RadioGroupTableOption<T>
An option for a RadioGroup displayed as a table row.
RadioIndicator
An indicator used in Radio to show whether it is selected or not.
ResponsiveBuilder
A layout builder that resolves the current Breakpoint from the available width and passes it to builder.
SegmentedControl<T>
A horizontal group of mutually exclusive toggle buttons.
SegmentedControlOption<T>
A single option in a SegmentedControl.
Select<T>
A dropdown field for selecting a single value from a list of options.
SelectDivider<T>
A visual divider that can be placed between groups of options in a Select dropdown.
SelectItem<T>
A sealed base class for items that can appear in a Select dropdown.
SelectOption<T>
A single selectable item in a Select dropdown.
Shadows
Shadow presets for elevating surfaces.
SideNav<T>
A collapsible vertical navigation rail for desktop/web layouts.
SideNavDestination<T>
A tappable navigation destination in a SideNav.
SideNavGroupTitle<T>
A non-interactive group heading between destinations.
SideNavItem<T>
Base class for items that can appear in a SideNav.
Slider
A draggable horizontal slider for selecting a value within a range.
Snackbar
A brief overlay notification typically shown at the bottom of the screen.
SnackbarAction
An optional call-to-action embedded in a Snackbar.
SnackbarHandler
A widget that manages Snackbar overlays for its subtree.
SnackbarHandlerState
State for SnackbarHandler. Use show to display a snackbar.
SnackbarTone
Defines the background and foreground colours of a Snackbar.
SnackbarToneStyle
The resolved visual properties for a single SnackbarTone.
Spacing
Standard spacing values on a 4 px base grid.
Spinner
An animated circular loading indicator.
StatCard
A compact card displaying a metric with a title, value, trend, and icon.
StatusDot
A small coloured dot used to communicate status at a glance.
StatusTone
Defines the colour of a StatusDot.
StatusToneStyle
The resolved visual properties for a single StatusTone.
Stepper
A horizontal step indicator showing progress through a multi-step flow.
Switch
A toggleable on/off switch control.
TabOption<T>
A single option in a Tabs bar.
Tabs<T>
A horizontal tab bar that switches between named sections.
TextField
A styled single- or multi-line text input field.
Theme
An InheritedWidget that provides ThemeData to its subtree.
ThemeData
Aggregates all design tokens and theme sub-objects for Catalyst.
Tooltip
A small informational overlay that appears on hover or long-press.
TopBar<T>
A horizontal top navigation bar for desktop/web layouts.
TopBarDestination<T>
A single destination in a TopBar.
Typography
The typographic scale used by Catalyst components.
ValueRow
A single label–value pair row, typically used in a details section.

Enums

AvatarStatus
The presence/availability status shown on an Avatar.
BadgeSize
Controls the height and font size of a Badge.
Breakpoint
A named breakpoint resolved from the available width.
ButtonSize
Controls the height, padding, and font size of a Button.
CheckboxSize
Controls the size of a Checkbox.
FormLayoutStyle
Styles for FormLayout
ProgressBarSize
Controls the height of a ProgressBar.
RadioSize
Controls the size of a Radio.
SelectSize
The height variant of a Select field.
StatDelta
The direction of a metric trend shown on a StatCard.
SwitchSize
Controls the size of a Switch.
TextFieldSize
Controls the height of a TextField.
ThemeMode
Controls which theme CatalystProvider applies when both theme and darkTheme are supplied.
TooltipSide
The side on which a Tooltip appears relative to its child.

Extensions

BrightnessFilter on Widget
Brightness manipulation for widgets via a colour-matrix filter.
SnackbarContext on BuildContext
Snackbar display helper on BuildContext.
ThemeContext on BuildContext
Convenience accessors for ThemeData on BuildContext.

Functions

showBottomSheet<T>(BuildContext context, WidgetBuilder builder, {bool barrierDismissible = true, bool useRootNavigator = true, bool draggable = true}) → Future<T?>
Displays a bottom sheet sliding up from the bottom of the screen.
showDrawer<T>(BuildContext context, WidgetBuilder builder, {bool barrierDismissible = true, bool useRootNavigator = true}) → Future<T?>
Displays a drawer panel sliding in from the right edge.
showModal<T>(BuildContext context, WidgetBuilder builder, {bool barrierDismissible = true, bool useRootNavigator = true}) → Future<T?>
Displays a modal dialog centred on screen with a fade + scale transition.

Typedefs

MotionSpec = ({Curve curve, Duration duration})
A pair of duration and easing curve describing one animation preset.
SwitchDimens = ({double height, double knob, double width})
The physical dimensions of a Switch knob and track.