Mix
Type-safe styling for Flutter, with styles defined separately from widget structure.
Documentation · Source · BSD 3-Clause license
Core concepts
- Styler → Spec → Widget: a typed style resolves to data that a widget renders.
- Styles are values: fluent methods return new merged styles, so bases can be reused.
- Props defer values: concrete values, tokens, and Mix values resolve with context; plain values replace, while Mix values accumulate fieldwise.
- Tokens name values:
MixScopesupplies them;ContextTokencan compute a default. - Variants are conditional patches: state-dependent patches have higher priority, with declaration order preserved within each priority group.
- Modifiers wrap widgets; directives transform values during resolution or rendering.
- Animation interpolates resolved specs: implicit, phase, and keyframe modes.
- Annotations generate typed plumbing and widgets from style recipes.
The decision log record the rationale behind the model.
Install
flutter pub add mix
Current sources require Dart 3.12+ and Flutter 3.44+; check pubspec.yaml for this package's constraints.
import 'package:flutter/material.dart';
import 'package:mix/mix.dart';
final cardStyle = BoxStyler()
.size(240, 100)
.color(Colors.blue)
.alignment(.center)
.borderRadius(.circular(12));
final card = Box(
style: cardStyle,
child: StyledText(
'Hello Mix',
style: TextStyler().color(Colors.white).fontSize(18),
),
);
Compose styles
final base = BoxStyler().padding(.all(16)).borderRadius(.circular(8));
final highlighted = base.color(Colors.blue);
final interactive = highlighted
.onDark(.color(Colors.blue.shade200))
.onHovered(.color(Colors.blue.shade700));
base retains its original style. Later plain values replace earlier values;
partial Mix values merge their fields. Use .create() when supplying explicit
Prop values rather than the normal fluent surface.
For interactive surfaces, use PressableBox or BoxStyler.pressable(...) so
state variants have a shared interaction owner.
Choose a layout
| Need | Widget |
|---|---|
| One styled child | Box |
| Non-wrapping row or column | RowBox, ColumnBox, FlexBox |
| Items flowing across runs | WrapBox |
| Explicit two-dimensional tracks | GridBox |
| Overlays | StackBox |
GridBox has no outer Box chrome. Wrap it in Box for padding or decoration.
Its local onConstraints patches change geometry; onBreakpoint uses viewport
width. Fixed/fractional columns and content-sized rows have different measurement
costs; see the Grid guide.
final GridBoxStyler grid = .equalColumns(3).gap(16).onConstraints(
.maxWidth(720),
.equalColumns(1).gap(12),
);
WrapBox combines outer Box styling with inner Wrap layout. Use
wrapAlignment and wrapClipBehavior for the inner layout; alignment and
clipBehavior apply to the outer Box. .flow(WrapStyler(...)) supplies a
nested Wrap style.
Tokens and theming
const primary = ColorToken('brand.primary');
const spacing = SpaceToken('space.md');
final themedCard = MixScope(
colors: {primary: Colors.blue},
spaces: {spacing: 16.0},
child: Box(style: BoxStyler().color(primary()).padding(.all(spacing()))),
);
Calling a token creates a deferred reference; token.resolve(context) retrieves
a value. A plain nested MixScope shadows its ancestor; use MixScope.inherit
for partial overrides. ContextToken computes a fallback even without a scope.
See scope and theming.
Animation, modifiers and directives
.animate(...)interpolates compatible resolved specs..phaseAnimation(...)and.keyframeAnimation(...)express sequenced changes..wrap(...)composes widget modifiers such as opacity and clipping.- Directives transform resolved values, for example text casing.
These compose with variants; consult the versioned API for exact signatures.
Learn and extend
- Styling, variants, tokens, animations.
- Runnable showcase and layout examples.
- Token migration.
- mix_annotations and mix_generator: specs and recipe widgets.
- mix_protocol: optional JSON boundary.
- mix_winds: Tailwind-style classes.
- mix_chart: Mix-styled charts; mix_chart_protocol adds serialization.
- mix_lint: analyzer rules.
- Mix skill: agent API references.
Libraries
- mix
- /\\ /\\ /\\\\\\ /\\ /\
/\\\ /\\\ /////\/// ///\\ /\/ /\//\\ /\//\\ /\\ ///\\\/ /\\///\/\/ /\\ /\\ //\\ /\\ ///\/ /\\ /\\ /\\ /\\ /// /\\ /\\ /\\\ /\\ /\\ /\\ /\////\
/\\ /\\ /\\\\\\ /\/ ///\
/// /// /////////// /// ///