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.

Live gallery Flutter License: MIT


beUI component explorer

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 — 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.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 decimals and formatNumber, 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.animateIn and BeuiMessageBubble.animateIn now default to false; uncontrolled Tool Approval starts closed. Pass animateIn: true or defaultOpen: true to 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
Line Chart — crosshair inspection and morphing data
Bar Chart
Bar Chart — grouped, stacked, horizontal and sorted
Plinko
Plinko — animated balls, peg flashes and payouts
Card Dealer
Card Dealer — deal, play, shuffle and sort a hand
Pagination
Pagination — spring indicator with page jumps
Mines
Mines — reveal gems, then cash out

Using the 3.1.0 APIs

  • Avatar Group takes List<BeuiAvatarGroupMember> with stable id values, names and optional image URLs. max defaults to 4. Use expanded / onExpandedChange for controlled expansion or defaultExpanded for internal state.
  • Pagination uses one-based page / onPageChange or defaultPage, with siblings, boundaries and jump controls. beuiPaginationRange returns typed page and ellipsis entries. getHref supplies destinations; linkBuilder supplies the actual link widget. The consumer owns navigation.
  • BeuiAdaptiveStepperValue.builder receives the clamped numeric value and builds decorative content. Use the parent stepper's formatValueText for spoken text. The builder's content does not receive pointer input, focus or semantics.
  • BeuiNumberTicker.decimals defaults to 0. formatNumber receives the rounded numeric value and takes precedence over the legacy integer format callback. The legacy callback ignores decimals.
  • BeuiTextShimmer.child(widget) and BeuiThinkingShimmer.child(widget) mask arbitrary painted content, not only text.
  • Card Dealer takes caller-owned cards implementing BeuiCardDealerCard, with stable IDs, a zone and a label. Supply renderFace; update the card list after onCardSelect to move cards between deck, hand and pile.
  • Mines also exports the UI-independent MinesRound, result types and multiplier helpers. Plinko accepts custom slots and reports the landing slot and value through onLand.
  • Line and Bar charts expose series, plot, tooltip and legend APIs. Line adds line/area variants, interpolation, domain and status; Bar adds layout, orientation and sort. Sparkline sample inspection is opt-in with interactive: true; showDelta is also opt-in.
  • BeuiSelectVariant.compact provides the borderless 32px trigger used by Prompt Input's model picker.
  • Tooltip's externalAnchor and anchorLink must be supplied together. BeuiTooltip.composed accepts BeuiTooltipTrigger and BeuiTooltipContent slots.
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
Voice Orb — breathing liquid voice visualization
Sankey Chart
Sankey Chart — weighted flows with hover inspection
Treemap
Treemap — proportional tiles with path tooltips
Donut Chart
Donut Chart — sweep-in ring with a live center
Color Picker
Color Picker — trigger chip that morphs into a spectrum
Card Folder
Card Folder — card in a stitched pocket with DigitSwap details

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

Charts index

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 index
Blocks — composed, product-ready motion patterns
AI Agents index
AI Agents — conversational and agent-reasoning surfaces
Component detail page
Detail page — live Preview / Usage / Code tabs
Motion guides
Motion Guides — when to move, which token, how to fall back
Light theme
Light & dark — every screen renders in both
Compact gallery
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:

Custom BeuiAgentTheme applied to real agent widgets

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 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.

Libraries

beui
beUI — a one-to-one Flutter port of beUI v2 motion components.