---

What this is

beUI is a Flutter widget library that ports the beUI React motion library. Version 3.0.0 covers four families — expressive Components (motion primitives with composable APIs), product-ready Blocks, AI Agents (conversational and agent-reasoning surfaces), and Charts (animated data visualizations).

The port's defining goal is motion fidelity. Framer Motion springs are parameterized by stiffness, damping, and mass — the exact same physical parameters as Flutter's SpringDescription — so the source's spring tokens carry over unchanged (trajectories validated within tolerance, not pixel-matched to Framer). Components don't approximate the feel with Curves.elasticOut; they use the real physics through motor.

• 🎬 Spring-accurate motion — five spring tokens + three easings ported verbatim from the source's ease.ts.
• 🎨 Themeable — BeuiColors for palette, BeuiAgentTheme for AI-agent typography/shape/layout/icons, and ThemeData.fontFamily for the typeface.
• ♿ Reduced-motion aware — one resolver drops movement while keeping opacity/color feedback (not a blanket duration-zeroing).
• 🧩 Native APIs — controlled/uncontrolled value + onChanged pairs, framework-native IconData/Widget icon props, variants as Dart enums.
• 🪟 One overlay foundation — every floating surface (tooltip, drawer, sheet, modal, command palette) builds on a shared BeuiOverlay.

Status: 3.0.0. This release adds 17 motion components, six blocks, Voice Orb, and a new Charts family of 14 animated charts. It requires Flutter 3.44.2 or later. See the changelog for compatibility changes and the one known issue.

What's new in 3.0.0

Voice Orb — breathing liquid voice visualization	Sankey Chart — weighted flows with hover inspection	Treemap — proportional tiles with path tooltips
Donut Chart — sweep-in ring with a live center	Color Picker — trigger chip that morphs into a spectrum	Card Folder — card in a stitched pocket with DigitSwap details

The gallery now has a Charts section next to Components, Blocks and AI Agents:

Live gallery

The example/ app is a beui.dev-style component explorer — sidebar, card grid, per-component detail pages with live Preview / Usage / Code tabs, and a Motion Guides page. It's deployed to GitHub Pages on every push to main:

👉 codenameakshay.github.io/beui

Blocks — composed, product-ready motion patterns	AI Agents — conversational and agent-reasoning surfaces
Detail page — live Preview / Usage / Code tabs	Motion Guides — when to move, which token, how to fall back
Light & dark — every screen renders in both	Compact — sidebar collapses below 1000px

Install

dependencies:
  beui: ^3.0.0

Or from Git:

dependencies:
  beui:
    git:
      url: https://github.com/codenameakshay/beui.git

Then import the single public entrypoint:

import 'package:beui/beui.dart';

Quick start

1. Register the theme

Components read their colors from a BeuiColors ThemeExtension, so install it on your ThemeData. Color theme and brightness are independent axes — any of the 11 themes works in light or dark.

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

ThemeData beuiTheme(Brightness brightness) {
  final colors = BeuiColors.of(BeuiColorTheme.violet, brightness);
  final base = ThemeData(brightness: brightness, useMaterial3: true);
  return BeuiTextTheme.trackingNormal(
    base.copyWith(
      scaffoldBackgroundColor: colors.background,
      extensions: [
        colors,
        const BeuiAgentTheme(), // optional — omit to keep source-fidelity agent styling
      ],
    ),
  );
}

MaterialApp(
  theme: beuiTheme(Brightness.light),
  darkTheme: beuiTheme(Brightness.dark),
  home: const MyHomePage(),
);

2. Drop in a component

Every stateful component mirrors Flutter's controlled + uncontrolled convention — pass value + onChanged to control it, or omit value to let it hold its own state.

// A spring-thumbed switch
bool wifi = true;
BeuiSwitch(
  value: wifi,
  label: const Text('Wi-Fi'),
  onChanged: (v) => setState(() => wifi = v),
);

// Tabs with a gliding indicator — pill / segment / underline
BeuiTabs<String>(
  variant: BeuiTabsVariant.underline,
  tabs: const [
    BeuiTab(value: 'overview', label: Text('Overview')),
    BeuiTab(value: 'activity', label: Text('Activity')),
  ],
  defaultValue: 'overview',
  onChanged: (v) => print(v),
);

// A spring-pressed button
BeuiButton(
  variant: BeuiButtonVariant.primary,
  onPressed: () {},
  child: const Text('Continue'),
);

// A hover/focus tooltip with a blur enter/exit
BeuiTooltip(
  content: const Text('Copy to clipboard'),
  side: BeuiTooltipSide.top,
  child: const Icon(LucideIcons.copy),
);

// A GPU shader background (mesh, grain, warp, waves, voronoi…)
BeuiShaderBackground(
  variant: BeuiShaderVariant.meshGradient,
  speed: 0.6,
);

Component catalog

Mirrors the beui.dev sidebar order. ✨ marks entries new in 3.0.0.

Components — motion primitives

Component	Widget(s)	What it does
Timeline ✨	BeuiTimeline	Draggable dated-event track around a focused card
Animated Alert ✨	BeuiAlert	Composable dismissible feedback with five variants
Animated Collapsible ✨	BeuiCollapsible	Height-spring disclosure with a rotating chevron
Aspect Ratio ✨	BeuiAspectRatio, BeuiAspectRatioImage	Media frame that morphs between ratios
Arc Picker ✨	BeuiArcPicker	Radial text picker with a growing selection bracket
Sortable List ✨	BeuiSortableList	Composable sortable list with group, item, handle and undo
Image Viewer ✨	BeuiImageViewer	Gallery lightbox with zoom, pan and keyboard navigation
Date Range Picker ✨	BeuiDateRangePicker	Composable calendar with presets and keyboard navigation
Card ✨	BeuiCard	Outlined or muted composable card with optional press
Color Picker ✨	BeuiColorPicker	Saturation area, hue, alpha, hex, channels and presets
Animated Color Selector ✨	BeuiColorSelector	Swatches with a spring-gliding selection ring
Animated Breadcrumb ✨	BeuiBreadcrumb	Path trail with overflow ellipsis and custom separators
Tilt Card	BeuiTiltCard	3D perspective tilt on hover with a cursor-tracked glare
Button	BeuiButton, BeuiStatefulButton, BeuiMagneticButton, BeuiMetallicButton	Spring-pressed Button plus Stateful, Magnetic and Metallic variants
Animated CTA Buttons	BeuiExpandingArrowButton, BeuiHoldActionButton, BeuiSlideActionButton	CTA buttons with expanding, hold-to-confirm and slide-to-confirm interactions
Expandable Control ✨	BeuiExpandableButton, BeuiExpandableChip	Icon button and chip that expand with layout continuity
Adaptive Stepper ✨	BeuiAdaptiveStepper	Quantity stepper whose footprint adapts at min/max
Marquee	BeuiMarquee	Infinite horizontal/vertical scroll with pause-on-hover
Tabs	BeuiTabs	Pill, segment or underline tabs with a spring indicator and optional icons
Switch	BeuiSwitch	Toggle with a spring-driven thumb and press feedback
Input	BeuiInput	Text field with icons, optional stable error row, error-shake replay and a success check draw
Select	BeuiSelect, BeuiMorphSelect	Panel that bouncily unfolds from the trigger, plus a Morph variant
Combobox ✨	BeuiCombobox	Searchable grouped picker with a morphing panel
Multi Select ✨	BeuiMultiSelect	Searchable options that become removable tokens
Checkbox	BeuiCheckbox	Draw-on checkmark with spring press feedback and indeterminate
Radio Group	BeuiRadioGroup	Single-select with a gliding indicator dot and spring feedback
Bottom Sheet	BeuiBottomSheet	Draggable sheet with snap points, inertia and a glass surface
Pull to Refresh	BeuiPullToRefresh	Pull-to-refresh with drag resistance and async handling
Shared Layout Background	BeuiSharedLayoutBg	A pill that glides between hovered items with a blur enter/exit
Bounce Sidebar	BeuiBounceSidebar	Vertical rail whose active dot jumps between destinations on a curved path
Animated Sidebar	BeuiAnimatedSidebar	App sidebar that folds to an icon rail, in sidebar, floating or inset chrome
File Tree ✨	BeuiFileTree	File and folder tree with springing branches and keyboard navigation
Preview Rail	BeuiPreviewRail	Navigation rail of ticks that reveal a destination preview — hover on pointer, tap-to-preview on touch
Dock	BeuiDock	macOS-style dock with separator-grouped actions and a gliding active pill
Tooltip	BeuiTooltip, BeuiTooltipProvider	Hover or focus tooltip with arrow, followCursor, collision flip and a shared warm window
Context Menu	BeuiContextMenu	Pointer-origin clip morph with checkbox/radio rows, keyboard nav and typeahead
Popover	BeuiPopover, BeuiMorphPopover	Gooey popover that oozes from the trigger, plus a Morph variant
Morphing Modal	BeuiMorphingModal	A panel that morphs its height between inner views, blur cross-fade
Center Morph Modal	BeuiCenterMorphModal	A surface that unfolds from its exact center toward every edge
Text Animation	BeuiTextScramble, BeuiTextReveal, BeuiTextShimmer, BeuiTextCascade, BeuiChromaticTextReveal	Scramble, reveal, shimmer, letter-cascade and a chromatic sweep over cycling words
Number Animation	BeuiDigitSwap, BeuiAnimatedNumber, BeuiNumberTicker	Fixed-slot digit swap, count-up values and rolling digit tickers
Animated Badge	BeuiAnimatedBadge	Status badge with animated state icons and pulse feedback
Action Swap	BeuiActionSwapButton	Swap a button's text and icons with blur, roll or cascade motion
Animated Toast Stack	BeuiAnimatedToastStack	Stacked toasts with status morphs, swipe dismissal and actions
Theme Toggle	BeuiThemeToggle, BeuiThemeSwitcher	Theme toggle with a full-page clip-path reveal
Bouncy Accordion	BeuiBouncyAccordion	Single-open accordion with a weighted spring layout
Drawer	BeuiDrawer	Side panel that springs in with a backdrop blur and esc-to-close
Scroll Animation	BeuiSmoothScroll, BeuiScrollProgress, BeuiScrollReveal, BeuiScrollTo, BeuiParallax	Smooth-scroll provider (vertical or horizontal), reading-progress indicator, reveal, scroll-to and parallax
Range Slider	BeuiInlineSlider, BeuiRangeSlider, BeuiFluidSlider, BeuiWaveSlider, BeuiBubbleSlider, BeuiRulerSlider	Six sliders: inline label/value, ticked bar thumb, thumbless liquid fill, equalizer wave, velocity-leaning bubble, and a scale that scrolls under a fixed needle
Wheel Picker	BeuiWheelPicker	iOS-style 3D picker drum with momentum snap
Table	BeuiTable	Virtualized table smooth at 10k+ rows: sort, select, resize, reorder, edit, async
Shader Background	BeuiShaderBackground	21 GPU shader backgrounds (mesh, grain, warp, waves, voronoi…)
Cylinder Carousel	BeuiCylinderCarousel	Items line the inside of a cylinder; drag or scroll with springy snap
Loader	BeuiLoader	Loading indicator with seventeen variants from one size prop

Blocks — composed patterns

Block	Widget	What it does
Infinite Masonry	BeuiInfiniteMasonry	Masonry grid that lazily appends tiles as you scroll
Notification Stack	BeuiNotificationStack	Collapsed notification stack that expands with layout-aware motion
Project Folder ✨	BeuiProjectFolder	Folder that fans file previews on hover or focus, then morphs into an overlay grid
Card Folder ✨	BeuiCardFolder	Landscape card tucked in a stitched purse pocket, with DigitSwap details
Fixtures	BeuiKnockoutBracket, BeuiKnockoutWheel	Tournament fixtures: a paging knockout bracket and a wheel around the champion
Availability Scheduler	BeuiAvailabilityScheduler	Weekly availability grid with per-day time ranges
Multi-chain Swap	BeuiMultiChainSwap	Token swap card with chain switching and an animated quote
Dynamic Island	BeuiDynamicIsland	iOS-style island that morphs between compact and expanded views
Command Palette	BeuiCommandPalette	⌘K palette with fuzzy search and spring-animated results
Morphing Search ✨	BeuiMorphingSearch, BeuiMorphingSearchChips	Search field or icon that morphs into results, plus a chip search bar (morphing-search-chips)
Expandable Action Bar	BeuiExpandableActionBar	Icon rail whose segments expand to reveal a label on hover
Overflow Actions	BeuiOverflowActions	Primary actions with an overflow that fans out from a ⋯ toggle
Expandable Tabs	BeuiExpandableTabs	Icon tabs where the active tab expands to show its label
Morphing Tabs ✨	BeuiMorphingTabs	Reorderable tabs whose selected item grows into a cream content surface
Swipeable List	BeuiSwipeableList	List rows with spring-backed swipe-to-reveal actions
File Upload	BeuiAttachmentUpload, BeuiFileUpload	Attachment workspace plus a progress queue with retry and removal
Prediction Market ✨	BeuiPredictionMarketCard, BeuiPredictionMarket	Listing cards with percent-to-Yes/No odds pills and bookmarks, plus a trade ticket
Wallet Card	BeuiWalletCard	Wallet card with an account switcher and morphing search
OTP Input	BeuiOtpInput	One-time-code field with per-cell focus and a success check
Sign Up Form ✨	BeuiSignUpForm	Registration form with punish-late errors, strength meter, and stateful submit
Bloom Menu	BeuiBloomMenu	Radial action menu that blooms open from a floating trigger
Feedback Widget	BeuiFeedbackWidget	Feedback popover that keeps drafts, validates inline and morphs to a success state
404 / Not Found	BeuiNotFoundGlitch, …Magnetic, …Spotlight, …Stacked, …Terminal	Five expressive 404 treatments

AI Agents — conversational and agent-reasoning interfaces

Component	Widget(s)	What it does
Prompt Input	BeuiPromptInput	Auto-growing composer with attachment chips, a keyboarded model picker and animated send/stop
Message	BeuiMessage	Primitives for rows, avatars, metadata, live markers and a mount-only pop-up
Message Bubble	BeuiMessageBubble	Conversational surface with tones, alignment, grouping and expandable content
Message Scroller	BeuiMessageScroller	Viewport that follows streamed output, releases when the reader scrolls away, and offers a jump-to-latest pill
Streaming Response	BeuiStreamingResponse	Response surface with completion actions, a visible failed state and a stopped/continue path
Image Generation	BeuiImageGeneration	Queued → refining → complete image surface with determinate progress and cancel
Citations	BeuiCitations	Inline markers plus a collapsible, progressively rendered reference list
Agent Loading States	BeuiThinkingShimmer, BeuiAgentProgress, BeuiReasoningText	Shimmering status text, live progress and cycling reasoning phrases
Todo List	BeuiTodoList	Collapsible task plan with morphing status marks and a completion count
Agent Activity	BeuiAgentActivity	One adaptive stream for reasoning, searches, tool calls and traces — including failed and cancelled runs
Tool Result	BeuiToolResult	Execution disclosure for terminal or request output that collapses when done
Code Block	BeuiCodeBlock	Highlighted code that stays stable while streaming, with copy feedback
File Diff	BeuiFileDiff	Change disclosure with wrap or horizontal scroll, hunk-gap markers and live counts
Tool Approval	BeuiToolApproval	Permission card: allow once, remember access, or deny — with a destructive severity tier
Approval Card	BeuiApprovalCard	Human-in-the-loop surface for approvals, questions, and compact-to-expanded proposals
AI Sidebar	BeuiAiSidebar	Workspace sidebar for folders, projects, files and bookmarks with inline rename
Chat App	BeuiChatApp	A complete conversation workspace composing the widgets above, with a responsive sidebar
Voice Orb ✨	BeuiVoiceOrb	Breathing liquid voice visualization with custom pigments, a voice-reactive silhouette, and a size override
Agent Theme	—	Gallery route that installs a custom BeuiAgentTheme on the real widgets

Charts — animated data visualizations

The whole family is new in 3.0.0.

Chart	Widget(s)	What it does
Sankey Chart	BeuiSankeyChart, BeuiSankeyData, BeuiSankeyNode, BeuiSankeyLink	Weighted flows between stages that draw in and morph with the data
Treemap	BeuiTreemap, BeuiTreemapPlot, BeuiTreemapTooltip, BeuiTreemapLegend	Proportional tiles that morph with the data, with value and share tooltips
Candlestick Chart	BeuiCandlestickChart, BeuiCandlestickPlot, BeuiCandlestickLegend	OHLC candles with a live last price and volume
Donut Chart	BeuiDonutChart, BeuiDonutPlot, BeuiDonutCenter, BeuiDonutLegend	Round-capped ring with a live center and sweep-in motion
Volume Profile	BeuiVolumeProfile, BeuiVolumeProfilePlot, BeuiVolumeProfileSummary	Volume-by-price with POC and a value-area highlight
Status Bar	BeuiStatusBar, BeuiStatusBarPlot, BeuiStatusBarLegend	Proportional incident bar with operational / degraded / outage statuses
Composition Chart	BeuiCompositionChart, BeuiCompositionPlot, BeuiCompositionLegend	100% stacked bar or area composition across periods
Funnel Chart	BeuiFunnelChart, BeuiFunnelPlot, BeuiFunnelSummary	Conversion funnel with curved morphs and drop-off
Liquidity Heatmap	BeuiLiquidityHeatmap, BeuiLiquidityPlot, BeuiLiquidityLegend	Order-book liquidity bands over time with a price trace
Bump Chart	BeuiBumpChart, BeuiBumpPlot, BeuiBumpLegend	Ranking bump chart with curved series that break on missing periods
Order Book	BeuiOrderBook, BeuiOrderBookSide, BeuiOrderBookSpread	Live bid/ask depth tables, spread, and a balance bar
Heat Calendar	BeuiHeatCalendar, BeuiHeatCalendarGrid, BeuiHeatCalendarLegend	GitHub-style contribution heatmap with range selection and filter fade
Returns Calendar	BeuiReturnsCalendar, BeuiReturnsCalendarGrid	Monthly returns grid with gain/loss tint and compounded totals
Price Target Fan	BeuiPriceTargetFan, BeuiPriceTargetPlot, BeuiPriceTargetTooltip	High/mean/low target fan over a history path

Also exported as standalone primitives: BeuiMagnetic (cursor-follow pull) and the BeuiOverlay foundation.

Theming

Three layers, installed once on ThemeData. Ordinary widgets then pick the values up — no per-component style wrappers.

Layer	Owns	Install
ThemeData.fontFamily / BeuiTextTheme	Global sans/mono family names and Material letter-spacing normalisation. The package ships no font files.	ThemeData(fontFamily: 'General Sans') plus BeuiTextTheme.trackingNormal(...)
BeuiColors	Palette: core tokens, brand themes, BeuiGlass, and focusRing (WCAG 2.2 3:1 non-text contrast). Not typography, radii, or spacing.	extensions: [BeuiColors.of(theme, brightness)]
BeuiAgentTheme	AI-agent semantics: type roles, bubble/card radii, conversation spacing, borders, optional glass cards, default icons, status palettes, and localizable BeuiAgentStrings.	extensions: [BeuiAgentTheme(...)] — omit it and widgets use source-fidelity defaults

ThemeData(
  fontFamily: 'General Sans',
  extensions: [
    BeuiColors.of(BeuiColorTheme.green, Brightness.light).copyWith(
      primary: Color(0xFF3D6B2F),
    ),
    BeuiAgentTheme(
      shapes: BeuiAgentShapes(
        userBubble: BorderRadius.circular(20),
        assistantBubble: BorderRadius.circular(12),
        card: BorderRadius.circular(18),
      ),
      layout: BeuiAgentLayout(
        turnSpacing: 12,
        bubblePadding: EdgeInsets.fromLTRB(12, 8, 12, 8),
      ),
      icons: BeuiAgentIcons(edit: Icons.edit_outlined),
    ),
  ],
);

BeuiMessageBubble(...);
BeuiApprovalCard(
  expandedChild: ..., // compact-to-expanded; omit to keep the 1.0.0 API
);
BeuiToolResult(...);

BeuiColors is a ThemeExtension ported from the source's design tokens. Read colors in your own widgets the same way components do:

final colors = Theme.of(context).extension<BeuiColors>()!;
Container(color: colors.card /* colors.foreground, .primary, .border, .muted, … */);

11 color themes, each valid in light and dark — resolve with BeuiColors.of(theme, brightness):

Mono (neutral base) · Violet · Blue · Green · Amber · Blood Orange · Rose · Red · Teal · Indigo · Lime

Each BeuiColorTheme value carries picker metadata (name, slug, swatch) for building a theme switcher. Overlay surfaces use a dedicated frosted-glass tier (BeuiGlass) with the source's 12–20px backdrop blur.

Agent widgets that previously hard-coded text-sm / rounded-2xl / Lucide defaults now resolve those from BeuiAgentTheme.of(context), which falls back to the same numbers and glyphs when the extension is missing. See the Agent Theme gallery route for a live custom palette, radii, icons, and an expandable approval card:

1.2.0 adds two theme roles the audit needed: BeuiColors.focusRing (a 3:1 focus halo that paints outside layout, separate from the ring hairline) and BeuiAgentTheme.strings / statusLight / statusDark so agent copy and status color can be rethemed or localized without forking a widget.

Motion system

The whole library speaks one motion language, defined once in lib/src/tokens/motion.dart and exported through the barrel:

Token	Physics	Used for
beuiSpringPress	stiffness 500 · damping 30 · mass 0.6	Button / tap press feedback
beuiSpringSwap	stiffness 460 · damping 30 · mass 0.55	Content swaps (label/icon slots)
beuiSpringPanel	stiffness 420 · damping 40 · mass 0.5	Overlay panel entrances (modals, sheets)
beuiSpringLayout	stiffness 360 · damping 32 · mass 0.6	Shared-layout glides (pills, indicators)
beuiSpringMouse	stiffness 200 · damping 15 · mass 0.3	Cursor-follow physics (magnetic, tilt)

Plus three easings — beuiEaseOut, beuiEaseInOut, beuiEaseDrawer — and helpers beuiBlurSigma(px) (CSS-blur → Flutter sigma) and motionFor(context, token, isMovement:) (the reduced-motion resolver).

Reduced motion is respected everywhere: with the OS setting on, movement-bearing tokens collapse to movement-free motion while opacity/color transitions are preserved — motion that explains rather than distracts. See the Motion Guides page in the live gallery.

Icons

beUI re-exports the flutter_lucide icon set (the Flutter equivalent of the source's lucide-react glyphs), so defaults in badges, toasts, and the command palette work out of the box — LucideIcons.* is available from the barrel.

Transitive dependency: adding beui pulls in the Lucide icon font whether or not you use a defaulted icon. Icon props accept the framework-native IconData (any glyph) or Widget (custom content), so you can override every default without depending on Lucide directly.

Develop

Uses FVM (pinned to Flutter stable in .fvmrc).

fvm flutter pub get
fvm flutter analyze          # static analysis + lints
fvm flutter test             # widget + golden tests
fvm flutter test --update-goldens   # regenerate goldens after intentional visual changes
cd example && fvm flutter run       # the component explorer

Run fvm flutter analyze && fvm flutter test before considering work done. See CLAUDE.md for architecture and conventions, and docs/PORTING_SPEC.md for the full catalog and the motion-token mapping.

Credits

A Flutter port of beUI by Saurabh Chauhan — beui.dev (starc007/ui-components). All component designs and the original motion work are his; this package brings them to Flutter.

License

MIT — see LICENSE. Both the upstream copyright (Saurabh Chauhan) and the port's copyright are preserved, as the MIT license requires for derivative works.