Skip to main content

platform_adaptive_widgets 3.1.0 copy "platform_adaptive_widgets: ^3.1.0" to clipboard
platform_adaptive_widgets: ^3.1.0 copied to clipboard

A spiritual continuation of flutter_platform_widgets library

CI Coverage Status Pub Version PRs Welcome Pub Points License: MIT GitHub issues GitHub closed issues GitHub pull requests GitHub closed pull requests

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.

The live property editor on the same button, Material and Cupertino side by side
Material (Android) Cupertino
The actions menu as an M3 menu, Delete in the error colour The same menu as a Cupertino pull-down, Delete in red

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 / CupertinoXxxData records 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.md has 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 https://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.

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.md or CLAUDE.md at 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 #

Contributors

Made with contrib.rocks.

Authors #

Used By #

This project is used by the following companies:

  • Didata Automatisering B.V
  • Dimerce B.V
4
likes
160
points
1.55k
downloads
screenshot

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

A spiritual continuation of flutter_platform_widgets library

Homepage
Repository (GitHub)
View/report issues

Topics

#adaptive #widget #material-design #material3 #cupertino

License

MIT (license)

Dependencies

cupertino_ui, flutter, material_ui, minted_chronology

More

Packages that depend on platform_adaptive_widgets