Repository navigation
Description
This issue tracks the essential refactoring work required to strengthen the core widgets library before decoupling the material and cupertino libraries (#101479).
We will prioritize net-new additions after decoupling.
🔍 For feedback on net-new widgets to strengthen the core, see: link
Our goal is to identify and move foundational, style-agnostic logic out of the existing design system libraries and into the core framework. This will ensure the core is robust enough to support multiple high-quality design systems and will provide a richer set of primitives for all developers.
Note
It is important to note that not everything in the design libraries will be refactored into the core. Some widgets are too heavily tied to their design language to extract a meaningful, un-opinionated API that would satisfy developer needs. One of our guiding principles is to avoid the "lowest common denominator" problem, ensuring that any new core widget is genuinely powerful and flexible.
Community Feedback Needed 🗣️
This is a critical opportunity for community input. Please use this issue to provide feedback and suggest other widgets or functionalities you believe are fundamental and should be moved into the core widgets library before the main decoupling occurs.
Last update Mar 4, 2026
So far, we have investigated many of the existing design components to determine if any refactoring can be done before decoupling, moving existing APIs to the widgets layer to a common surface. In some cases, we have decided not to break widgets in the design libraries to try to accomplish this, which leaves the opportunity for new, more generic APIs to be introduced in the widgets layer later. As we have been focused on the opportunity to refactor here ahead of actually separating the libraries, expect the work to add new widgets (tracked in #97496) to continue after the design libraries land in their new packages.
To check out all the issues and aspects of the decoupling effort, see the github project, and root parent issue: #101479
Status:
- What's landed or being worked on wrt refactoring to raw widgets:
- Menus
- Radios
- Tooltips
- Page transitions
- Other
- Widgets that we decided not to refactor, will migrate as-is:
- ColorScheme
- Very material, uses material color utilities package to generate material spec color scheme.
- InkWell
- Relies on Material ancestor to paint, too complex to refactor to a basic component that paints in response to a gesture, which could be done in a different/simpler way
- Scaffold
- Very material specific for layout. We discussed focusing on simple app bar, bottom bar widgets might be nice to have instead with built in safe area handling. A column could compose something similar to a Scaffold layout if the simple *bar components handled things like SafeArea out of the box. Simple composition from the widgets layer is still our focus.
- SliverAppBar
- Highly complex and material-specific
- SliverPersistentHeader, its base class is already in widgets, We added several atomic sliver header widgets last year that are meant to replace the SliverAppBar behemoth through composition in the widgets layer.
- SliverResizingHeader: Pins its child and resizes it from its max extent to its min extent when scrolled
- SliverFloatingHeader: Hides the child when the user scrolls backwards and shows its child when the user scrolls forward
- PinnedHeaderSliver: Keeps its child pinned to the top of the scroll view.
- TabBar
- Does not implement navigation, instead a scrolling PageView under the hood. Could develop something simpler in the widgets layer, but the current material implementation does not appear to have a clear common base. Very specific to material design (similar assumptions in AppBar, SliverAppBar) with regards to preferred size. We should consider the opportunity for a net-new base component in ☂️ Reinforcement: Add more basic components to the core framework #97496.
- Theming
- design doc, we'll revisit this for a generic solution in the framework after decoupling lands.
- We discussed a new base theme object as making sense. For use in the WidgetsApp, containing:
- ThemeExtensions, or something similar
- High contrast (a11y)
- Brightness (dark mode)
- defaultTargetPlatform
- Font family and fallback
- Perhaps others…
- Text input and selection stack
- flutter.dev/go/decoupling-design-from-text
- Evaluate decoupling text stack from Material and Cupertino #172930
- We discussed:
- The future of SelectableText
- Here we discussed the state of text selection components in the widgets library without SelectableText after decoupling Material and Cupertino from the framework.
- The recommendation here was to move forward with SelectableText leaving the framework with Material, and to continue working on fixing critical bugs in SelectableRegion + Text.
- Design agnostic text selection UI
- This discussion was around whether it was feasible to move text selection UI such as context menus and selection handles to the widgets library.
- The recommendation here was to not move forward with text selection UI in the widgets library at this time due to the heavy dependencies on Material and Cupertino. Bringing these components into the widgets library would result in a less stable framework as it will still be susceptible to design changes.
- The default out of the box experience for text
- Here we discussed the API usability between the framework’s text and text input offerings with Material and Cupertino’s. Specifically we looked at EditableText vs TextField and SelectionArea vs SelectableRegion.
- We are not making any changes at the moment but have identified some areas to explore after decoupling.
- The future of SelectableText
- Colors
- ColorScheme
Raw- widgets that pre-date this effort
This is not an exhaustive list of components available in the widgets library, but specifically those with Raw prefixes. 🙂
OP
Use case
The number of platforms that Flutter officially targets to a reasonable level of stability has grown beyond just Android and iOS to include the web, Windows, macOS, and Linux. Yet most of the widgets the SDK provides are still tied to the design guidelines/systems of those two mobile OSes. This seriously impacts the out-of-box usability of the widget library for developers who are using Flutter for other platforms/who do not necessarily prioritise mobile.
I think there is a strong case to be made that there are a lot of widgets in flutter/material and flutter/cupertino that really should be/be based on flexible, extensible widgets in flutter/widgets so that developers can take direct advantage of logic that's often hidden away in private classes and hardcoded constants, rather than having to duplicate it.
Proposal
Much like with the new plugin system, I think it would be a great idea if certain Material/Cupertino widgets were rewritten to decouple the general "behaviour" of the widget from design-specific guidelines (and probably make more use of delegates and painters). A prime candidate would be Slider and CupertinoSlider, for example.
One set of widgets that I think already does this decently well is the set of Scrollbar (from flutter/material), CupertinoScrollbar (from flutter/cupertino) and ScrollbarPainter (from flutter/widgets). With the latter it is easy to build a custom scrollbar without having to think too much about (or copy the logic of) how a scrollbar should work, and you also have built-in scrollbars that follow Material guidelines or HIG if that's what you want. The only thing I would change about this set is to update the documentation of ScrollbarPainter with a minimal example of how to put together a scrollbar with it.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
HansMuller commentedon Mar 25, 2020
We've often talked about creating a "building blocks" library in between widgets and material/cupertino/etc, to make it easier to build things like the components in the material/cupertino/etc libraries. That said, at the moment there's no such project in the plan, but we have been thinking about it :-).
That said, appreciate the feedback about
ScrollbarPainter; an example sounds like a good idea.CC @justinmc
justinmc commentedon Mar 25, 2020
I definitely agree with this! I think this is going to become more and more important for Flutter over time. I will try to update this issue if I see any concrete steps happening anywhere.
lukepighetti commentedon Mar 26, 2020
I am of the opinion that
materialandcupertinoshould be pub packages and flutter should expose a mid-level API for widgets and especially sliversjustinmc commentedon Mar 27, 2020
That was one of my first thoughts when I started working with Flutter. There might be more support for that kind of move as we add more platform design styles. A big positive of keeping them in the library now is that it's so easy to write a Flutter app with everything you need right out of the box. Maybe we'd have to include the material library by default but make it really easy and obvious to swap in/out Cupertino or others.
lukepighetti commentedon Mar 27, 2020
@justinmc They can just add
materialandcupertinoto pubspec.yaml dependencies by default if they want to, like they do withcupertino_icons. And get rid of that "uses-material-design: true" flag.satvikpendem commentedon Apr 9, 2020
I also agree, a lot of values are hard-coded into certain widgets without a way to overwrite them, such as the box shadow with
ReorderableListView, which shouldn't be a Material widget but more a generalized list widget that supports different theming.darrenaustin commentedon Sep 18, 2020
Hey folks, we are ramping up a design to try to address this and other issues with
ReorderableListView. We are tracking it with #66080 and in a design doc. Feedback welcome.Hixie commentedon Nov 26, 2022
I've been noodling on this topic recently and wrote some thoughts up here: https://flutter.dev/go/blankcanvas
Comments welcome.
18 remaining items
mglsj commentedon Sep 13, 2025
How about moving the (Material) Icons out to a separate package like
cupertino_iconsflutter-triage-bot commentedon Dec 4, 2025
This issue is marked P1 but has had no recent status updates.
The P1 label indicates high-priority issues that are at the top of the work list. This is the highest priority level a bug can have if it isn't affecting a top-tier customer or breaking the build. Bugs marked P1 are generally actively being worked on unless the assignee is dealing with a P0 bug (or another P1 bug). Issues at this level should be resolved in a matter of months and should have monthly updates on GitHub.
Please consider where this bug really falls in our current priorities, and label it or assign it accordingly. This allows people to have a clearer picture of what work is actually planned. Thanks!
Piinks commentedon Dec 4, 2025
Thanks bot. Still P1, and actively being worked on. 😁
This is an umbrella issues covering several other issues.
Raw tooltip with smaller API surface that exposes tooltip widget (#17…
Piinks commentedon Mar 5, 2026
Hi everyone!
We've been so heads down on this work, if you haven't been keeping up with the individual issues, pull requests, and design documents, I thought an update was needed here. :)
This issue represents one of the 4 pillars of this effort (see parent issue), refactoring existing design widgets into basic components in the core framework where we can. I have updated the OP to cover a lot of the work that has been done as part of this pillar.
During this period that the libraries are still together, we've been primarily focused on this, and as a result, we already have some new components in the widgets layer!
Once we land the libraries in their new packages (hello, material_ui and cupertino_ui 👋 ), this will be closed and we'll continue to work on adding more widgets to the core (tracked in #97496). Thanks all, keep the feedback coming!
Raw tooltip with smaller API surface that exposes tooltip widget (#17…
Piinks commentedon Jul 7, 2026
Closing this, as this specific period of decoupling (refactoring while all the code is together before moving the libraries to the new packages) is now ended.
Piinks commentedon Jul 7, 2026
Good question! I don't know that there is a final list yet, we'll continue this work by adding new core widgets to the framework going forward and roll out a full catalog. This primarily focused on what we wanted to keep before moving the libraries out, most listed above in the OP or visible as linked PRs. See #97496 for continued tracking on core widgets.
github-actions commentedon Jul 21, 2026
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.