simple_parallax 2.3.2

Parallax widgets for Flutter, in pure Dart with no dependencies. A container mode and a per-item mode, either axis, with a drift, a zoom, a blur and an overlay set on their own.

Simple Parallax

Parallax backgrounds for Flutter, in pure Dart with no dependencies. Put one background behind a whole page, or give each block of a list its own.

 

 

 

Install

flutter pub add simple_parallax

Requires Flutter 3.22 or later.

One background behind a page

SimpleParallaxContainer(
  image: const AssetImage('assets/images/background.webp'),
  child: Column(children: items),
);

A background per block

ListView(
  children: <Widget>[
    SimpleParallaxItem(
      image: const NetworkImage('https://example.com/cover.jpg'),
      height: 300,
      child: const Center(child: Text('Chapter one')),
    ),
  ],
);

That is all it takes. Everything below is optional.

Effects

Both widgets take the same four, each set on its own:

SimpleParallaxItem(
  image: const AssetImage('assets/images/background.webp'),
  height: 620,
  parallax: const ParallaxProperties(speed: 0.4),
  zoom: const ZoomProperties(0.6),
  blur: const BlurProperties(-16),
  overlay: const OverlayProperties.darken(0.45),
);

Parameter	Effect
parallax	The drift. speed goes from 0 to 1, overscan is how much larger than the view the background is drawn.
zoom	Grows as it crosses: 0.25 ends a quarter larger. Negative runs it the other way.
blur	Softens as it crosses, as a sigma in pixels. Negative sharpens instead.
overlay	A fixed tint: .darken, .lighten, a colour or a .gradient.

zoom and blur also take reach and back, to finish part way, 0.5 being the middle of the screen, then hold there or turn back.

Good to know

• background takes a widget instead of an image: a gradient, a video, or an Image you set up yourself, with cacheHeight or an errorBuilder.
• The container scrolls sideways with scrollDirection: Axis.horizontal. Items read the axis of the list they sit in.
• SimpleParallaxContainer.slivers takes slivers, for a long list or a SliverAppBar over the background.
• SimpleParallaxWidget, and SimpleParallaxWidget.builder for long lists, is a ready-made scroll view for items.
• Items take borderRadius for a rounded card, and alignment to keep the top of a portrait in the frame.
• For an image that loads over the network, placeholderColor fills the block meanwhile, fadeIn brings the picture in, and errorBuilder takes its place if it fails.
• In nested scrollables, scrollAxis picks the one an item follows, for instance the page around a carousel, and crossParallax has it follow the other one as well.
• The mouse wheel is eased on desktop and the web. To drive the view from outside and keep that, pass a SmoothScrollController as its controller.
• The platform's reduced motion setting is followed: backgrounds hold still. Pass respectReducedMotion: false to keep the effect regardless.

Every parameter is documented in the API reference.

Performance

Scrolling repaints the background and rebuilds no widget, and lists build as they scroll. Images are decoded at the size they are drawn, not at full resolution. The drift and the zoom cost next to nothing; the blur is the one effect worth profiling on an older phone.

Example

example/ is the app behind the live demo, one screen per feature.

cd example && flutter run

It also shows how to let a mouse drag a list, which Flutter does not allow by default: _DragScrollBehavior.

Upgrading

Coming from 1.x or 0.1.x, see the CHANGELOG.

License

MIT, see LICENSE.