macos_ui

Flutter widgets and themes implementing the current macOS design language.

Check out our interactive widget gallery online at https://macosui.github.io/macos_ui/#/

Guides, codelabs, and other documentation can be found at https://macosui.dev

🚨 Usage notes

<img src="https://storage.googleapis.com/cms-storage-bucket/0dbfcc7a59cd1cf16282.png" height="14"/> Flutter channel

macos_ui is developed against Flutter's stable channel. To ensure a smooth development experience with macos_ui, you should build your application on Flutter's stable channel.

<img src="https://storage.googleapis.com/cms-storage-bucket/0dbfcc7a59cd1cf16282.png" height="14"/> Platform Compatibility

pub.dev shows that macos_ui only supports macOS. This is because macos_ui calls some native code, and therefore specifies macOS as a plugin platform in the pubspec.yaml file.

macos_ui technically will work on any platform that Flutter supports, but you will get best results on macOS. non-macOS platform support is not guaranteed.

The features of macos_ui that will not work on platforms other than macOS due to calling native code are:

Anything related to macos_window_utils
The MacosColors.controlAccentColor() function
The MacosColorWell widget

<img src="https://imgur.com/TIP0V7H.png" height="14"/> Popups & window resizing

Since at this time Flutter does not allow UI elements to overflow the bounds of the window, popups are constrained to the available space.

Therefore, if you are using widgets that create popups in your toolbar, like ToolBarPopupButton, you should avoid allowing your application window to be resized below the height of your tallest popup.

<details> <summary>Contributing & Resources</summary>

Contributing
Resources

</details> <details> <summary>Layout</summary>

Layout

</details> <details> <summary>Icons</summary>

Icons
- MacosIcon

</details> <details> <summary>Buttons</summary>

Buttons

</details> <details> <summary>Dialogs & Sheets</summary>

Dialogs & Sheets
- MacosAlertDialog
- MacosSheet

</details> <details> <summary>Fields & Labels</summary>

Fields
- MacosTextField
- MacosSearchField
Labels
- MacosTooltip

</details> <details> <summary>Indicators</summary>

Indicators
- Progress Indicators
  - ProgressCircle
  - ProgressBar
- Level Indicators
  - CapacityIndicator
  - RatingIndicator

</details> <details> <summary>Selectors</summary>

Selectors

</details>

Contributing

macos_ui welcomes contributions! Please see CONTRIBUTING.md for more information.

Resources

Layout

MacosWindow

MacosWindow is the basic frame for a macOS-style layout.

It supports a Sidebar on the left, an optional TitleBar at the top, and the rest of the window is typically filled out with a MacosScaffold.

A scope for the MacosWindow is provided by MacosWindowScope. The sidebar can be toggled with MacosWindowScope.of(context).toggleSidebar(). Please note that you must wrap your MacosScaffold in a Builder widget in order for this to work properly.

Sidebar

A sidebar enables app navigation and provides quick access to top-level collections of content in your app.

Sidebars may be placed at the left or right of your app. To place a sidebar on the left, use the MacosWindow.sidebar property. To place a sidebar on the right, use the MacosWindow.endSidebar property.

Example usage:

int pageIndex = 0;

...

MacosWindow(
  sidebar: Sidebar(
    minWidth: 200,
    builder: (context, scrollController) {
      return SidebarItems(
        currentIndex: pageIndex,
        scrollController: scrollController,
        itemSize: SidebarItemSize.large,
        onChanged: (i) {
          setState(() => pageIndex = i);
        },
        items: const [
          SidebarItem(
            label: Text('Page One'),
          ),
          SidebarItem(
            label: Text('Page Two'),
          ),
        ],
      );
    },
  ),
  endSidebar: Sidebar(
    startWidth: 200,
    minWidth: 200,
    maxWidth: 300,
    shownByDefault: false,
    builder: (context, _) {
      return const Center(
        child: Text('End Sidebar'),
      );
    },
  ),
),

MacosScaffold

The MacosScaffold is what you might call a "page".

The scaffold has a toolbar property and a children property. children accepts a ContentArea widget and multiple ResizablePane widgets. To catch navigation or routes below the scaffold, consider wrapping the MacosScaffold in a CupertinoTabView. By doing so, navigation inside the MacosScaffold will be displayed inside the MacosScaffold area instead of covering the entire window. To push a route outside a MacosScaffold wrapped in a CupertinoTabView, use the root navigator Navigator.of(context, rootNavigator: true)

See the documentation for customizations and ToolBar examples.

Modern window look

A new look for macOS apps was introduced in Big Sur (macOS 11). To match that look in your Flutter app, macos_ui relies on macos_window_utils, which requires a minimum macOS deployment target of 10.14.6. Therefore, make sure to open the macos/Runner.xcworkspace folder of your project using Xcode and search for Runner.xcodeproj. Go to Info > Deployment Target and set the macOS Deployment Target to 10.14.6 or above. Then, open your project's Podfile (if it doesn't show up in Xcode, you can find it in your project's macos directory via VS Code) and set the minimum deployment version in the first line to 10.14.6 or above:

platform :osx, '10.14.6'

You may also need to open up your app's Runner.xcodeproj in XCode and set the minimum deployment version there.

Now, configure your window inside your main() as follows:

/// This method initializes macos_window_utils and styles the window.
Future<void> _configureMacosWindowUtils() async {
  const config = MacosWindowUtilsConfig(
    toolbarStyle: NSWindowToolbarStyle.unified,
  );
  await config.apply();
}

void main() async {
  await _configureMacosWindowUtils();

  runApp(const YourAppHere());
}

Please note that if you are using a title bar (TitleBar) in your MacosWindow, you should set the toolbarStyle of your window to NSWindowToolbarStyle.expanded, in order to properly align the close, minimize, zoom window buttons:

Future<void> _configureMacosWindowUtils() async {
  const config = MacosWindowUtilsConfig(
    toolbarStyle: NSWindowToolbarStyle.expanded,
  );
  await config.apply();
}

In any other case, you should keep it as NSWindowToolbarStyle.unified.

ToolBar

Creates a toolbar in the MacosScaffold. The toolbar appears below the title bar (if present) of the macOS app or integrates with it, by using its title property.

A toolbar provides convenient access to frequently used commands and features (toolbar items). Different routes of your app could have different toolbars.

Toolbar items include ToolBarIconButton, ToolBarPulldownButton, and ToolBarSpacer widgets, and should be provided via the items property. The action of every toolbar item should also be provided as a menu bar command of your app.

Toolbars look best and are easiest to understand when they contain elements of the same type (so either use labels for every toolbar item or not).

You can use the ToolBarSpacer widgets to set the grouping of the different toolbar actions.

An example toolbar would be:

ToolBar(
  title: const Text('Untitled Document'),
  titleWidth: 200.0,
  leading: MacosBackButton(
    onPressed: () => debugPrint('click'),
    fillColor: Colors.transparent,
  ),
  actions: [
    ToolBarIconButton(
      label: "Add",
      icon: const MacosIcon(
        CupertinoIcons.add_circled,
      ),
      onPressed: () => debugPrint("Add..."),
      showLabel: true,
    ),
    const ToolBarSpacer(),
    ToolBarIconButton(
      label: "Delete",
      icon: const MacosIcon(
        CupertinoIcons.trash,
      ),
      onPressed: () => debugPrint("Delete"),
      showLabel: false,
    ),
    ToolBarPullDownButton(
      label: "Actions",
      icon: CupertinoIcons.ellipsis_circle,
      items: [
        MacosPulldownMenuItem(
          label: "New Folder",
          title: const Text("New Folder"),
          onTap: () => debugPrint("Creating new folder..."),
        ),
        MacosPulldownMenuItem(
          label: "Open",
          title: const Text("Open"),
          onTap: () => debugPrint("Opening..."),
        ),
      ],
    ),
  ]
),

This builds this simple toolbar: <img src="https://imgur.com/BDUdQkj.png"/>

Other toolbar examples:

Toolbar with icon buttons (no labels):
<img src="https://imgur.com/PtrjhPx.png"/>
Toolbar with icon buttons and labels:
<img src="https://imgur.com/Ouaud12.png"/>
Toolbar with a pulldown button open:
<img src="https://imgur.com/msGmcNY.png"/>
Toolbar with title bar above (also see the note above):
<img src="https://imgur.com/eAgcsKY.png"/>

You can also create your own CustomToolbarItem to include any type of widget in the toolbar:

// Add a grey vertical line as a custom toolbar item:
CustomToolbarItem(
  inToolbarBuilder: (context) => Padding(
    padding: const EdgeInsets.all(8.0),
    child: Container(color: Colors.grey, width: 1, height: 30),
  ),
  inOverflowedBuilder: (context) =>
      Container(color: Colors.grey, width: 30, height: 1),
),

`SliverToolBar`

SliverToolbar is a variant of the standard ToolBar, with the key difference being that (as the name implies), it is compatible with scrollable widgets like CustomScrollView and NestedScrollView. There are three additional properties on SliverToolBar:

pinned, which determines if the toolbar should remain visible while scrolling
floating, which determines if the toolbar should become visible as soon as the use starts scrolling upwards
opacity, which manages the translucency effect of the toolbar

This widget enables developers to achieve the toolbar behaviors seen in Apple's App Store.

Sample usage:

return CustomScrollView(
  controller: scrollController,
  slivers: [
    SliverToolBar(
      title: const Text('SliverToolbar'),
      pinned: true,
      toolbarOpacity: 0.75,
    ),
    // Other slivers below  
  ],
);

MacosListTile

A widget that aims to approximate the ListTile widget found in Flutter's material library.

MacosListTile

Sample usage:

MacosListTile(
  leading: const Icon(CupertinoIcons.lightbulb),
  title: Text(
    'A robust library of Flutter components for macOS',
    style: MacosTheme.of(context).typography.headline,
  ),
  subtitle: Text(
    'Create native looking macOS applications using Flutter',
    style: MacosTheme.of(context).typography.subheadline.copyWith(
      color: MacosColors.systemGrayColor,
    ),
  ),
),

MacosTabView

A multipage interface that displays one page at a time. Must be used in a StatefulWidget.

You can control the placement of the tabs using the position property.

Usage:

final _controller = MacosTabController(
  initialIndex: 0,
  length: 3,
);

...

MacosTabView(
  controller: _controller,
  tabs: const [
    MacosTab(
      label: 'Tab 1',
    ),
    MacosTab(
      label: 'Tab 2',
    ),
    MacosTab(
      label: 'Tab 3',
    ),
  ],
  children: const [
    Center(
      child: Text('Tab 1'),
    ),
    Center(
      child: Text('Tab 2'),
    ),
    Center(
      child: Text('Tab 3'),
    ),
  ],
),

Icons

MacosIcon

A MacosIcon is identical to a regular Icon in every way with one exception - it respects a MacosTheme. Use it the same way you would a regular icon:

MacosIcon(
  CupertinoIcons.add,
  // color: CupertinoColors.activeBlue.color,
  // size: 20,
),

Buttons

MacosCheckbox

A checkbox is a type of button that lets the user choose between two opposite states, actions, or values. A selected checkbox is considered on when it contains a checkmark and off when it's empty. A checkbox is almost always followed by a title unless it appears in a checklist. Learn more