flutter_smooth asks Flutter itself to schedule the work, and that is why it needs a custom engine

Six characters is the entire API for common cases

The usage section offers two ways in, and the first one is deliberately almost invisible. For common scenarios you add the word Smooth to a widget name: `ListView` becomes `SmoothListView`, and `MaterialPageRoute` becomes `SmoothMaterialPageRoute`. That is six characters, and it is the whole migration for a lot of cases.

The design intent is that you do not restructure your widget tree to adopt this. If a scroll view janks because the children it builds are expensive, you swap the class name and the scheduling behaviour changes underneath. The same pattern applies to routes, which is the more interesting of the two examples: a route transition is a moment where the framework is building a tree while also animating, so spreading that work is exactly where the technique pays off.

The repository has a packages directory rather than a single package at the root, which fits an approach that offers parallel widget families rather than one entry point.

The README does not describe a configuration surface, a switch to disable smoothing, or a cost knob. If you adopt it, you adopt the behaviour it ships with.

SmoothBuilder for the cases a renamed widget cannot cover

The second option is the escape hatch: `SmoothBuilder(builder: ...)` takes whatever you want to be smooth and puts it inside the builder. Everything you place there is inside the smoothed region.

That is the more general mechanism and the one to reach for when the expensive thing is not a widget you can rename. A custom layout, a third-party component with its own build cost, a subtree assembled from parts you do not control: wrapping it in SmoothBuilder is the way to bring it into scope.

The README describes this as arbitrarily flexible builder, and the phrasing is accurate in a narrow sense. The flexibility is in what you can place inside, not in how the smoothing is configured. There is no knob described for granularity, budget, or priority between competing regions.

Practically, this gives you a migration strategy with two rungs: rename where a drop-in exists, wrap where it does not. Both are small edits, which is why the package can be tried on one screen of an existing application rather than adopted wholesale.

Why the fix lives in the engine instead of the framework

The current status section is the most important paragraph in the README, and it is easy to skim past. The author states he is working on pull requests to the Flutter framework and engine, explicitly not modifying code in this repository, with the goal being that you can use the package with standard stable Flutter.

Read that carefully. The package depends on scheduling behaviour that stock Flutter does not yet have. Today, using it means running a patched engine, which means a fork to build, to track and to rebase on every Flutter release. That is the real cost of this package, and it dwarfs the six characters in a widget name.

The transparency is good, though. Two linked pages exist for the upstream work: an auto-generated list of the pull requests, and a page of conversations. So you can inspect exactly which engine-side change you would be depending on rather than taking it on trust.

The repository is not archived and the last push was on 2026-10-11, so the work is current. It is also, by the author's own account, incomplete until those pull requests land.

No GitHub releases exist for this repository, so there is no tagged version to pin, and the changelog lives at the repository root.

What the evidence in the repository does and does not show

The README's demonstration is a short video shot with an external camera, showing the same scene without smoothing on the left and with it on the right. The caption is candid about two things: the capture method was chosen to demonstrate end-user perception rather than to flatter the result, and the scene was deliberately made extra janky so the difference is visible.

That is honest framing, and it is also a small controlled demo. A jank comparison on a deliberately bad tree does not tell you what your tree will do.

The quantitative material is elsewhere, on the project documentation site, which lists usage, a demo, benchmark pages, insights, and more. The README states the goal in performance terms, roughly full FPS with zero uncomfortable janks and negligible overhead, and points at the benchmark page for detailed reports. Those numbers come from the project itself rather than from an independent measurement, and the README does not restate them, so treat them as a starting point for your own measurement rather than as a specification.

The mechanism behind the claim is discussed in the insights material, and the contributor credits hint at where the theory went: one contributor is thanked for a theory that slowness is caused by memory locality, which the author describes as indicating another potential application.

How it differs from the usual answers to jank

Most Flutter performance work starts with the widget tree itself. You move work out of build into a constructor, replace an expensive widget with a cheaper one, add const constructors, or reduce the number of items laid out. Those techniques reduce the work; flutter_smooth changes when the work happens.

The difference matters when the work is irreducible. If a subtree must be built, the question is not whether to skip it but whether to do it all in one frame or spread it across several. The README's framing, that the tree can be as heavy as it likes and still render smoothly, is a claim about scheduling rather than about efficiency.

The alternative worth naming is shrinking the tree. Those are the defaults you should exhaust first, because they carry no engine dependency.

flutter_smooth earns its place when the tree cannot be made cheap: a heavy third-party widget, a canvas or chart library, an inherited-widget pattern that forces broad rebuilds. In that situation it is one of the few approaches that does not require rewriting the offending code, which is exactly the situation it was built for.

Editorial conclusion

flutter_smooth fits a developer whose jank comes from an expensive build or layout pass, particularly someone building a heavy widget tree, and who is willing to run a patched Flutter until the upstream work lands. It does not fit a team shipping on stock stable Flutter today, because the README states the author is still working on pull requests to the framework and engine rather than modifying this repository. Verify first by reading the auto-generated pull request status list linked from the README to see which engine-side change you would actually be depending on, and measure your own tree before and after rather than trusting the demo video.

Frequently asked questions

Official sources

1. fzyzcjy/flutter_smooth on GitHub
2. Issues
3. License: MIT
4. Project website
5. README