One set of widgets that feels native everywhere, Cupertino on iOS and macOS, Material on
everything else, without a single Platform.isIOS check in your own code.
You write PlatformButton once. Android users get a real Material button, iOS users get a real
CupertinoButton, and neither group feels like they wandered into the other platform's app. When a
platform genuinely needs special treatment, there's a typed knob for it, used only when you reach
for one.
| Material (Android) | Cupertino |
|---|---|
![]() |
![]() |
- Why you'd want it
- How it compares
- Getting started
- See it live
- Widget catalog
- Customizing per platform
- Compile-time platform pruning, verified
- Coming from flutter_platform_widgets?
- Contributing
- Contributors
- Authors
- Used By
Why you'd want it
Flutter ships both Material and Cupertino widgets, but it leaves the choosing to you. So apps tend
to drift one of 2 ways: all-Material everywhere (which looks a little off on iOS), or a slowly
growing tangle of if (Platform.isIOS) branches you'll be maintaining for years.
This package makes that call for you, one widget at a time. Each PlatformXxx checks the platform
and builds the right native widget underneath, so your tree stays readable and the branching lives
in one tested place instead of sprinkled across the codebase.
It also picks by the job, not just the look. Asking before a delete, offering a few choices or picking from a list each get the component that platform's guidelines name for it, and the package handles the details they ask for: where Cancel goes, a destructive action turning red, a confirm before it runs.
2 things it goes out of its way to avoid:
- Lock-in. The shared parts (your callbacks, values, controllers) sit right on the widget.
Anything platform-specific goes in optional
MaterialXxxData/CupertinoXxxDatarecords you can happily ignore until you actually want to tweak one side. - Dead weight. Release builds leave behind the platform you're not on: no Cupertino code tags along on Android, no Material code on iOS. And that isn't wishful thinking. CI checks it on every PR.
// The usual way: branch by hand, and remember to do it everywhere.
Widget build(BuildContext context) {
if (defaultTargetPlatform == TargetPlatform.iOS) {
return CupertinoButton.filled(onPressed: _save, child: const Text('Save'));
}
return FilledButton(onPressed: _save, child: const Text('Save'));
}
// With this package: one widget, the right look on each platform.
PlatformButton(onPressed: _save, emphasis: .high, child: const Text('Save'));
How it compares
Flutter ships Material and Cupertino but won't pick between them for you, and the packages that fill that gap fall into 2 camps. Pure-Dart dispatch renders Flutter's own Material/Cupertino widgets per platform. Native bridging embeds real platform UI through platform views and method channels. This package is firmly pure-Dart.
The trade is architectural rather than better-or-worse. Bridging gets you pixel-authentic native chrome that Flutter's Cupertino widgets can't reproduce, and pays for it with platform-view compositing, channel round-trips, an OS-version gate, native setup, and a dependency that can't be tree-shaken. This package takes the other side: Flutter's Cupertino rather than real UIKit, no channels, no native setup, and the unused platform pruned out of your binary.
Want the latest native iOS chrome? Go native. Want a light, no-bridge, prunable adaptive layer across a broad widget set? That's this. For who's active in either camp right now, search pub.dev.
Getting started
flutter pub add platform_adaptive_widgets
Wrap your app in a PlatformApp and start using PlatformXxx widgets anywhere you'd normally reach
for a Material or Cupertino one:
import 'package:flutter/widgets.dart';
import 'package:platform_adaptive_widgets/platform_adaptive_widgets.dart';
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) => PlatformApp(
title: 'Adaptive Demo',
home: PlatformScaffold(
appBarData: const PlatformAppBar(title: Text('Adaptive Demo')),
body: Center(
child: PlatformButton(
onPressed: () {},
emphasis: .high,
child: const Text('Tap me'),
),
),
),
);
}
Run that on an Android phone, and it's Material from top to bottom. Run the exact same code on an iPhone and it's Cupertino. That's the whole trick.
Heads up: iOS and macOS get Cupertino, every other platform gets Material, and on the web it goes by the browser's OS.
APPENDIX.mdhas the reasoning.
See it live
Honestly, the quickest way to get a feel for it is to play with it. The example/ app
is a little interactive catalog: every widget gets its own card, and most come with a built-in
property editor so you can flip isEnabled, drag a slider, or pick a color and watch the widget
react right there on the device. There's also an About tab that swaps the rendered platform and
theme on the fly, which makes it easy to hold Material and Cupertino up next to each other without
ever rebuilding.
cd example
flutter run
It comes with 2 entry points, depending on how you like to route:
lib/main.dart for plain navigator routing, and
lib/main_go_router.dart for the declarative router.
Widget catalog
Here's everything in the box. Each widget renders the native counterpart listed, and the *Data
column shows what you can pass to tune each side. See
Customizing per platform for how those work.
Dialogs
| Widget / Function | Material | Cupertino | Data Classes |
|---|---|---|---|
showPlatformDatePicker() |
showDatePicker |
CupertinoDatePicker + showCupertinoModalPopup |
MaterialDatePickerData, CupertinoDatePickerData |
showPlatformTimePicker() |
showTimePicker |
CupertinoDatePicker (time mode) + showCupertinoModalPopup |
MaterialTimePickerData, CupertinoDatePickerData |
PlatformMenuPicker<T> |
DropdownMenu + DropdownMenuEntry |
CupertinoMenuAnchor (≤5 items), CupertinoPicker in a popup (≤250) or a CupertinoPageRoute list (>250) |
MaterialMenuPickerData, CupertinoMenuPickerData |
PlatformActionsMenu + PlatformMenuAction |
MenuAnchor, icons first, delete and discard in the error colour and confirmed in a dialog |
CupertinoMenuAnchor, icons last, delete and discard in red and confirmed in an action sheet |
N/A |
showPlatformSheet<T>() + PlatformUnsavedChanges |
showModalBottomSheet, sized to its content |
showCupertinoSheet + CupertinoPageScaffold |
N/A |
showPlatformFullscreenDialog<T>() |
showDialog + Dialog.fullscreen + Scaffold |
CupertinoPageRoute (fullscreenDialog: true) + CupertinoPageScaffold |
MaterialFullscreenDialogData |
showPlatformConfirm() + PlatformActionKind |
AlertDialog, Cancel + a confirming action styled by actionKind |
CupertinoAlertDialog, Cancel + a confirming action styled by actionKind |
MaterialAlertDialogData, CupertinoAlertDialogData |
showPlatformRawDialog<T>() |
showDialog (no surface wrap) |
showCupertinoDialog (no surface wrap) |
N/A (caller owns the surface) |
showPlatformRawModalBottomSheet<T>() |
showModalBottomSheet (native Material) |
showCupertinoModalPopup (no surface wrap) |
MaterialModalBottomSheetData, CupertinoModalPopupData |
showPlatformChoices<T>() + PlatformChoice |
showModalBottomSheet, a ListTile per choice, delete and discard in the error colour |
CupertinoActionSheet, delete and discard on top in red, Cancel added |
MaterialModalBottomSheetData, CupertinoModalPopupData |
showPlatformToast() + PlatformToastAction |
SnackBar + SnackBarAction via ScaffoldMessenger |
A banner the package draws, since iOS has no toast. Prefer showing the change itself there | MaterialToastData, CupertinoToastData |
showPlatformAcknowledge() |
AlertDialog + single OK action |
CupertinoAlertDialog + single OK action |
MaterialAlertDialogData, CupertinoAlertDialogData |
Interaction
| Widget | Material | Cupertino | Data Classes |
|---|---|---|---|
PlatformButton + PlatformButtonEmphasis |
FilledButton, FilledButton.tonal, OutlinedButton or TextButton by emphasis, the error colours for a delete or discard, through their .icon factories for PlatformButton.icon, and IconButton's matching style for PlatformButton.iconOnly |
CupertinoButton.filled, .tinted, .tinted in systemGrey or plain by emphasis, red for a delete or discard. PlatformButton.icon puts the icon and label in a Row, PlatformButton.iconOnly holds the icon alone |
MaterialButtonData, CupertinoButtonData |
PlatformExpansionTile |
ExpansionTile |
CupertinoExpansionTile |
MaterialExpansionTileData, CupertinoExpansionTileData |
PlatformMultiSelectList<T> |
CheckboxListTiles, the box leading |
CupertinoListTiles with a trailing checkmark in a CupertinoListSection.insetGrouped |
N/A (flat params, no data classes) |
PlatformScrollbar |
Scrollbar |
CupertinoScrollbar |
MaterialScrollbarData, CupertinoScrollbarData |
PlatformSearchBar |
SearchBar |
CupertinoSearchTextField |
MaterialSearchBarData, CupertinoSearchBarData |
PlatformSegmentButton<T> |
SegmentedButton + ButtonSegment |
CupertinoSlidingSegmentedControl |
MaterialSegmentButtonData, CupertinoSegmentButtonData |
PlatformSingleSelectList<T> |
RadioListTiles in a RadioGroup |
CupertinoListTiles with a trailing checkmark in a CupertinoListSection.insetGrouped |
N/A (flat params, no data classes) |
PlatformSlider |
Slider |
CupertinoSlider |
MaterialSliderData, CupertinoSliderData |
PlatformSwitch |
Switch |
CupertinoSwitch |
MaterialSwitchData, CupertinoSwitchData |
PlatformTextField |
TextField |
CupertinoTextField |
MaterialTextFieldData, CupertinoTextFieldData |
Layout
| Widget | Material | Cupertino | Data Classes |
|---|---|---|---|
PlatformApp / PlatformApp.router |
MaterialApp / MaterialApp.router |
CupertinoApp / CupertinoApp.router |
MaterialAppData, CupertinoAppData (shared config is flat on the widget) |
PlatformAppBar + PlatformBarAction |
AppBar, each action an IconButton with its label as the tooltip, or a TextButton |
CupertinoNavigationBar, each action a flush CupertinoButton, the primary one semibold |
MaterialAppBarData, CupertinoNavigationBarData |
PlatformScaffold |
Scaffold |
CupertinoPageScaffold |
MaterialScaffoldData, CupertinoScaffoldData |
PlatformTabScaffold |
Scaffold + NavigationBar + NavigationDestination |
CupertinoTabScaffold + CupertinoTabBar + CupertinoTabView |
MaterialTabScaffoldData, TabDestination |
Painting
| Widget | Material | Cupertino | Data Classes |
|---|---|---|---|
PlatformListTile |
ListTile |
CupertinoListTile / CupertinoListTile.notched |
MaterialListTileData, CupertinoListTileData |
PlatformProgressBar |
LinearProgressIndicator |
CupertinoLinearActivityIndicator |
MaterialProgressBarData, CupertinoProgressBarData |
PlatformProgressIndicator |
CircularProgressIndicator |
CupertinoActivityIndicator |
MaterialProgressIndicatorData, CupertinoProgressIndicatorData |
Utilities: generic platform widgets, theme access, value selectors, extensions, and models
Generic Platform Widgets
| Widget | Description |
|---|---|
PlatformWidget |
Takes materialBuilder and cupertinoBuilder callbacks to render any custom widget per platform. |
PlatformWidgetBuilder |
Same as PlatformWidget but also passes a shared child widget to both builders. |
Platform Theme
PlatformTheme.of(context): provides unified access to theme properties across platforms:
| Property | Material | Cupertino |
|---|---|---|
barBackgroundColor |
Theme.of(context).appBarTheme.backgroundColor |
CupertinoTheme.of(context).barBackgroundColor |
primaryColor |
Theme.of(context).primaryColor |
CupertinoTheme.of(context).primaryColor |
primaryContrastingColor |
Theme.of(context).colorScheme.onPrimary |
CupertinoTheme.of(context).primaryContrastingColor |
scaffoldBackgroundColor |
Theme.of(context).scaffoldBackgroundColor |
CupertinoTheme.of(context).scaffoldBackgroundColor |
selectionHandleColor |
Theme.of(context).colorScheme.onSurface |
CupertinoTheme.of(context).selectionHandleColor |
Platform value selectors
These build both arms, so the unused one stays in release builds
(measured).
Prefer an inline switch (designLanguage), one look per case, when an arm builds a widget:
| Helper | Description |
|---|---|
designLanguage |
Which look the widgets use. Switch on it to match them. |
platformValue<T>(material:, cupertino:) |
Returns the value matching the current platform. |
platformValueNullable<T>(material:, cupertino:) |
Nullable variant of platformValue. |
platformLazyValue<T>(material:, cupertino:) |
Lazily evaluates only the callback for the current platform. |
platformLazyNullable<T>(material:, cupertino:) |
Nullable variant of platformLazyValue. |
platformIcon(material:, cupertino:) |
BuildContext extension for platform-specific IconData. |
Other Extensions
| Extension | Description |
|---|---|
TimeOfDayExtensions.toDateTime() |
Converts TimeOfDay → DateTime. |
Models
| Model | Description |
|---|---|
Date, Month, Weekday |
Calendar value types taken by showPlatformDatePicker. Re-exported from minted_chronology, which refuses impossible dates instead of rolling them over. |
PlatformAdaptiveIcons |
A class that provides adaptive icons based on the current platform. |
Customizing per platform
The mental model is short. Whatever both platforms share, your callbacks, values, controllers, plus
the odd visual that genuinely means the same thing on each side (a tint color, say), lives right on
the widget, so there's one source of truth and nothing to keep in sync. Whatever is truly
platform-specific lives in optional typed records: hand a MaterialXxxData to the Material branch,
a CupertinoXxxData to the Cupertino one. For most widgets, most of the time, you'll touch neither,
they're there for the moments you want one platform to behave a little differently.
PlatformButton.icon(
onPressed: _add,
emphasis: .high, // FilledButton.icon on Material, CupertinoButton.filled on Cupertino
icon: const Icon(Icons.add),
label: const Text('Add'),
cupertinoButtonData: const CupertinoButtonData(pressedOpacity: 0.6), // Cupertino-only tuning
)
If you're ever unsure where a given property belongs,
APPENDIX.md spells out the rule the package follows.
Compile-time platform pruning, verified
This is the part people tend not to believe at first: the platform you're not on actually disappears
from your release build. Under AOT, designLanguage is a compile-time constant, so on Android the
Cupertino branches are dead code that the compiler tree-shakes away, and the same in reverse on iOS.
Since "trust me" is a weak engineering argument, 2 CI checks keep it honest on every PR:
- a static AST guard
(
test/guards/aot_pruning.dart) that fails the build if anyone reintroduces the closure-style dispatch that quietly defeats pruning, and - a real size benchmark (
tool/check_size_regression.dart) that builds an app for Android and iOS with--analyze-size, and trips if either keeps more of the other look than a calibrated budget allows.
Want the full mechanism and the actual byte counts? They're in
APPENDIX.md#aot-pruning-rules.
Coming from flutter_platform_widgets?
You'll feel right at home. This package is a spiritual continuation of
flutter_platform_widgets, and the PlatformXxx
naming carries straight over. The biggest change is that some jobs have their own entry point
instead of a generic dialog or sheet: showPlatformConfirm, showPlatformChoices,
PlatformActionsMenu. Per-platform tweaks go through typed MaterialXxxData / CupertinoXxxData
records (see Customizing per platform), the scope is intentionally
Material and Cupertino only, and the AOT-pruning promise is checked by CI rather than taken on
faith. Skim the widget catalog to find the equivalent of whatever you're using
today.
Contributing
Issues and PRs welcome at github.com/LahaLuhem/platform_adaptive_widgets. Before sending a
non-trivial change, read CODESTYLE.md for the house style,
.ai/AGENTS.md for the hard rules and contributor / AI-agent guidelines, and
APPENDIX.md for the design rationale.
Optional: AI-agent discovery symlinks
The canonical text for AGENTS.md and CLAUDE.md lives under .ai/. The repo root holds
gitignored symlinks (AGENTS.md → .ai/AGENTS.md, CLAUDE.md → .ai/CLAUDE.md,
example/AGENTS.md → example/.ai/AGENTS.md) so coding agents that auto-discover root-level guidance
files (Claude Code, Codex, Cursor, Copilot, …) find them without polluting the file tree with 2
extra Markdown files at each level. The arrangement is opt-in per contributor:
-
If you use a coding agent, set the symlinks up once from the repo root:
ln -s .ai/AGENTS.md AGENTS.md ln -s .ai/CLAUDE.md CLAUDE.md ln -s .ai/AGENTS.md example/AGENTS.md -
If you don't use one, skip the step entirely. The canonical files under
.ai/are committed. Nothing in the build, lint, or test pipeline depends on the symlinks existing. -
If you want different agent guidance for your own workflow, drop a real
AGENTS.mdorCLAUDE.mdat the repo root. A real file beats the symlink convention, your agent reads the root file you put there instead of the canonical one under.ai/. The committed.ai/copies remain the project default for everyone else.
The CODESTYLE.md files are not symlinked, they sit directly at the repo root and at example/,
since style serves humans and agents alike and is not AI-specific. See
APPENDIX.md for the rationale behind the .ai/ arrangement.
Contributors
Made with contrib.rocks.
Authors
Used By
This project is used by the following companies:
- Didata Automatisering B.V
- Dimerce B.V

