beui 3.1.0
beui: ^3.1.0 copied to clipboard
Spring-physics motion components for Flutter — a one-to-one port of the beUI React library, from switches and docks to shader backgrounds.
beUI #
Motion components for Flutter — a one-to-one port of beUI (starc007/ui-components).
Spring-physics UI primitives, composed blocks, AI-agent surfaces and animated charts, built on the motor motion engine so the original's exact spring feel carries over — not just its look.
What this is #
beUI is a Flutter widget library that ports the beUI React motion library. Version 3.1.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 — eight spring tokens + three easings ported verbatim from the source, including snap and scroll springs for reduced motion and scroll-linked effects.
- 🎨 Themeable —
BeuiColorsfor palette,BeuiAgentThemefor AI-agent typography/shape/layout/icons, andThemeData.fontFamilyfor the typeface. - ♿ Reduced-motion aware — one resolver drops movement while keeping opacity/color feedback (not a blanket duration-zeroing).
- 🧩 Native APIs — controlled/uncontrolled
value+onChangedpairs, framework-nativeIconData/Widgeticon props, variants as Dart enums. - 🪟 One overlay foundation — every floating surface (tooltip, drawer, sheet, modal, command palette) builds on a shared
BeuiOverlay.
Status: 3.1.0. This release adds Avatar Group, Pagination, three game and card blocks, and Line, Bar and Sparkline charts. It requires Flutter 3.44.2 or later. See the changelog for changed defaults and the new platform dependencies.
What's new in 3.1.0 #
- Components: Avatar Group and Pagination. Adaptive Stepper accepts custom value content, Number Ticker supports
decimalsandformatNumber, and Select, Sidebar, Tooltip and focus handling are repaired. - Blocks: Card Dealer, Mines and Plinko. File Upload and Attachment Upload use the platform file picker and drag and drop.
- Agents:
BeuiMessage.animateInandBeuiMessageBubble.animateInnow default tofalse; uncontrolled Tool Approval starts closed. PassanimateIn: trueordefaultOpen: trueto opt in. Citations take item icons and accessible marker labels, and Thinking Shimmer can shimmer rich content. - Charts: Line Chart, Bar Chart and Sparkline. Donut, Price Target Fan and Returns Calendar match the source.
![]() Line Chart — crosshair inspection and morphing data |
![]() Bar Chart — grouped, stacked, horizontal and sorted |
![]() Plinko — animated balls, peg flashes and payouts |
![]() Card Dealer — deal, play, shuffle and sort a hand |
![]() Pagination — spring indicator with page jumps |
![]() Mines — reveal gems, then cash out |
Using the 3.1.0 APIs #
- Avatar Group takes
List<BeuiAvatarGroupMember>with stableidvalues, names and optional image URLs.maxdefaults to 4. Useexpanded/onExpandedChangefor controlled expansion ordefaultExpandedfor internal state. - Pagination uses one-based
page/onPageChangeordefaultPage, withsiblings,boundariesandjumpcontrols.beuiPaginationRangereturns typed page and ellipsis entries.getHrefsupplies destinations;linkBuildersupplies the actual link widget. The consumer owns navigation. BeuiAdaptiveStepperValue.builderreceives the clamped numeric value and builds decorative content. Use the parent stepper'sformatValueTextfor spoken text. The builder's content does not receive pointer input, focus or semantics.BeuiNumberTicker.decimalsdefaults to 0.formatNumberreceives the rounded numeric value and takes precedence over the legacy integerformatcallback. The legacy callback ignoresdecimals.BeuiTextShimmer.child(widget)andBeuiThinkingShimmer.child(widget)mask arbitrary painted content, not only text.- Card Dealer takes caller-owned
cardsimplementingBeuiCardDealerCard, with stable IDs, azoneand a label. SupplyrenderFace; update the card list afteronCardSelectto move cards between deck, hand and pile. - Mines also exports the UI-independent
MinesRound, result types and multiplier helpers. Plinko accepts customslotsand reports the landing slot and value throughonLand. - Line and Bar charts expose series, plot, tooltip and legend APIs. Line adds line/area variants, interpolation,
domainandstatus; Bar addslayout,orientationandsort. Sparkline sample inspection is opt-in withinteractive: true;showDeltais also opt-in. BeuiSelectVariant.compactprovides the borderless 32px trigger used by Prompt Input's model picker.- Tooltip's
externalAnchorandanchorLinkmust be supplied together.BeuiTooltip.composedacceptsBeuiTooltipTriggerandBeuiTooltipContentslots.
BeuiPagination(totalPages: 20, defaultPage: 1, jump: 5);
BeuiAdaptiveStepper(
formatValueText: (value) => '${value.toInt()} items',
children: [
const BeuiAdaptiveStepperDecrement(),
BeuiAdaptiveStepperValue(
builder: (context, value) => Text('${value.toInt()} items'),
),
const BeuiAdaptiveStepperIncrement(),
],
);
BeuiNumberTicker(value: 12.34, decimals: 2);
BeuiTextShimmer.child(const Text.rich(TextSpan(text: 'Working')));
BeuiLineChart(
categories: const ['Mon', 'Tue'],
series: const [
BeuiLineChartSeries(
id: 'visits', name: 'Visits', color: '#14b8a6', values: [10, 15],
),
],
);
BeuiSparkline(data: const [10, 15, 12], label: 'Visits', interactive: true);
File acquisition and upload ownership #
BeuiFileUpload and BeuiAttachmentUpload include a platform file picker and desktop/web drop target. onBrowse replaces only the picker action. enableDrop: false disables the built-in drop target. accept is a picker hint, not drop validation; multiple controls picker selection.
Use onFilesAdded to receive accepted items and their BeuiUploadFile descriptors. Each descriptor has name, size, optional mimeType, readAsBytes() and openRead(). Reads are lazy and repeatable. Retain the descriptor yourself if you need it after the widget is disposed. onAcquisitionError reports picker/drop failures, not errors thrown by your callbacks. Attachment Upload also has onFilesRejected with a rejection reason.
These widgets do not send files to a server. Provide your own transport and update the controlled value list through onValueChange to report progress, completion or failure. Attachment previews are bounded; they are not a replacement for validating the complete file.
The package now directly depends on file_selector, super_drag_and_drop and web, in addition to its existing dependencies. Native plugin build requirements apply even if your app does not display an upload widget. See pubspec.yaml for exact constraints and the changelog for compatibility notes. Dart 3.12.2 or a compatible later 3.x SDK and Flutter 3.44.2 or later are required.
3.0.0 highlights #
![]() 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.1.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,
fontFamily: 'Geist', // bundle it first; see Fonts below
);
return BeuiTextTheme.trackingNormal(
base.copyWith(
scaffoldBackgroundColor: colors.background,
extensions: [
colors,
const BeuiAgentTheme(), // optional — omit to keep source-fidelity agent styling
],
),
);
}
void main() {
runApp(
MaterialApp(
theme: beuiTheme(Brightness.light),
darkTheme: beuiTheme(Brightness.dark),
home: const Scaffold(body: Center(child: Text('Hello, beUI'))),
),
);
}
Fonts #
The package bundles no font files. BeuiTextTheme defaults to the source's families, Geist and Geist Mono, and some components ask for Geist Mono by name. If your app does not provide them, Flutter silently falls back to a platform font with different metrics, so labels and layouts drift from beui.dev.
Bundle both families (SIL OFL 1.1, from vercel/geist-font) in your app's pubspec.yaml, then set fontFamily: 'Geist' on your ThemeData as in step 1:
flutter:
fonts:
- family: Geist
fonts:
- asset: assets/fonts/Geist-Regular.ttf
weight: 400
- asset: assets/fonts/Geist-Medium.ttf
weight: 500
- asset: assets/fonts/Geist-SemiBold.ttf
weight: 600
- asset: assets/fonts/Geist-Bold.ttf
weight: 700
- family: Geist Mono
fonts:
- asset: assets/fonts/GeistMono-Regular.ttf
weight: 400
- asset: assets/fonts/GeistMono-Medium.ttf
weight: 500
Code surfaces ask for the generic monospace family. Native platforms resolve it to their system monospace. Flutter web cannot, so on web also register the Geist Mono files under family: monospace, as the example app does.
2. Drop in a component #
Most interactive components mirror Flutter's controlled + uncontrolled convention. Pass the value and its callback (value + onChanged, open + onOpenChange, …) to control the component. Omit the value to let it hold its own state, seeded from defaultValue / defaultOpen where the component has one. These are controlled-only and require both: BeuiSwitch and BeuiCheckbox (value + onChanged), and BeuiDrawer, BeuiBottomSheet and BeuiCenterMorphModal (open + onOpenChange). The BeuiOverlay foundation is controlled-only by design, and display widgets such as BeuiAnimatedNumber simply require value.
// A spring-thumbed switch. Controlled-only: keep `wifi` in your State.
bool wifi = true;
BeuiSwitch(
value: wifi,
label: '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…)
SizedBox(
height: 240,
child: BeuiShaderBackground(
variant: BeuiShaderVariant.meshGradient,
speed: 0.6,
),
);
Component catalog #
Mirrors the beui.dev sidebar order. ✨ marks entries new in 3.1.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 |
| Pagination ✨ | BeuiPagination |
Spring-animated pagination with page ranges and jump controls |
| Avatar Group ✨ | BeuiAvatarGroup, BeuiAvatar |
Overlapping member avatars with an expandable overflow group |
| 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 with sorting, selection, resizing, reordering, editing and async loading |
| 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 |
| Plinko ✨ | BeuiPlinko |
Plinko board with animated balls, peg flashes and payouts |
| Card Dealer ✨ | BeuiCardDealer |
Card table with a deck, a fanned hand and a discard pile |
| 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 retains rejected submissions, clears drafts on close and morphs to a success state |
| Mines ✨ | BeuiMines |
Mines board with payout readouts and a cash-out flow |
| 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 an opt-in 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 family arrived in 3.0.0. ✨ marks charts added in 3.1.0.
| Chart | Widget(s) | What it does |
|---|---|---|
| Line Chart ✨ | BeuiLineChart, BeuiLineChartPlot, BeuiLineChartTooltip |
Multi-series line or area chart with a crosshair inspector |
| Bar Chart ✨ | BeuiBarChart, BeuiBarChartPlot, BeuiBarChartLegend |
Grouped or stacked bars, vertical or horizontal, with sorting |
| Sparkline ✨ | BeuiSparkline |
Compact trend line with a live value, optional delta and sample inspection |
| 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(
child: BeuiMessageBubbleContent(child: Text('Ship it?')),
);
BeuiApprovalCard(
title: 'Deploy to production',
compactChild: Text('3 services changed'),
expandedChild: Text('api, web and worker'), // compact-to-expanded; omit to keep the 1.0.0 API
);
BeuiToolResult(
tool: 'bash',
title: 'Run tests',
status: BeuiToolResultStatus.success,
child: Text('All tests passed'),
);
BeuiColors is a ThemeExtension ported from the source's design tokens. Read colors in your own widgets the same way components do:
final colors = BeuiColors.resolve(context);
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) |
beuiSpringGlide |
stiffness 700 · damping 50 · mass 0.5 | Slider thumb and fill |
beuiSpringSnap |
stiffness 700 · damping 60 · mass 1 | Reduced-motion settle |
beuiSpringScroll |
stiffness 120 · damping 30 · mass 0.6 | Scroll-linked follow motion |
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: motionFor replaces movement-bearing tokens with movement-free motion while preserving opacity/color transitions. Individual effects can freeze or snap instead; text shimmer holds a static highlight and Number Ticker snaps its digits. 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
beuipulls in the Lucide icon font whether or not you use a defaulted icon. Icon props accept the framework-nativeIconData(any glyph) orWidget(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.

















