flutter_tilt

0

? Easily apply tilt parallax hover effects on Flutter! | 在 Flutter 上轻松创建倾斜视差悬停效果!

Productivity

flutter
hover
parallax
tilt

GitHub stars Pub.dev likes

📓 Language: English | 中文
🎁 Check out the Live Demo.
💡 See the Migration Guide to learn how to migrate between breaking changes.



Flutter Tilt

stable package dev package pub points CodeFactor codecov top language

Easily Apply Tilt Parallax Hover Effects for Flutter!


Example Preview GIF - Parallax image
Example Preview GIF
Example Preview GIF - Parallax card
Example Preview GIF - Layout

Check out the Live Demo.


Table of contents 🪄


Features ✨

  • 📦 Tilt effect
  • 🔦 Light effect
  • 💡 Shadow effect
  • 👀 Parallax effect
  • 📱 Gyroscope sensor support (Sensors compatibility)
  • 🧱 Multiple layouts
  • 👇 Supports hover, touch and sensors events
  • 🖼️ Smooth animation
  • ⚙️ Many custom parameters

Install 🎯

Versions compatibility 🐦

Flutter3.0.0+3.10.0+3.19.0+
flutter_tilt 3.0.0+
flutter_tilt 2.0.0+
flutter_tilt 1.0.0+

Add package 📦

Run this command with Flutter,

$ flutter pub add flutter_tilt

or add flutter_tilt to pubspec.yaml dependencies manually.

dependencies:
  flutter_tilt: ^latest_version

Sensors compatibility 📱

Sensors are triggered only on these platforms.

AndroidiOSWeb (HTTPS)macOSLinuxWindows
Browser compatibility

[!NOTE]
Currently Web uses the Sensor API - Gyroscope, but it is not compatible with some of the major browsers, such as Safari, Firefox.

Gesture priority 📱

When multiple gestures are enabled, they are triggered based on priority:

Touch > Hover > Controller > Sensors

Simple usage 📖

Example: flutter_tilt/example

Tilt 📦

Tilt widget will have default tilt, shadow, and light effects.

/// Import flutter_tilt
import 'package:flutter_tilt/flutter_tilt.dart';

Tilt(
  child: Container(
    width: 150.0,
    height: 300.0,
    color: Colors.grey,
  ),
),

Parallax 👀

TiltParallax widget can only be used in the childLayout of Tilt widget.

/// Import flutter_tilt
import 'package:flutter_tilt/flutter_tilt.dart';

Tilt(
  childLayout: const ChildLayout(
    outer: [
      /// Parallax here
      Positioned(
        child: TiltParallax(
          child: Text('Parallax'),
        ),
      ),
      /// Parallax here
      Positioned(
        top: 20.0,
        left: 20.0,
        child: TiltParallax(
          size: Offset(-10.0, -10.0),
          child: Text('Tilt'),
        ),
      ),
    ],
  ),
  child: Container(
    width: 150.0,
    height: 300.0,
    color: Colors.brown,
  ),
),

Usage 📖

Tilt widget parameters 🤖

ParameterTypeDefaultDescription
child requiredWidget-Create a widget that its child widget can be tilted.
childLayoutChildLayoutChildLayout()Other child layouts.
e.g. parallax outer, inner, behind.
tiltStreamControllerStreamController<TiltStreamModel>?nullStreamController<TiltStreamModel>.broadcast() to control the tilt.
disableboolfalseDisable all effects.
fpsint60Gesture triggered frames.
borderBoxBorder?nullBoxDecoration border.
borderRadiusBorderRadiusGeometry?nullBoxDecoration borderRadius.
clipBehaviorClipClip.antiAliasFlutter clipBehavior.
tiltConfigTiltConfigTiltConfig()Tilt effect config.
lightConfigLightConfigLightConfig()Light effect config.
shadowConfigShadowConfigShadowConfig()Shadow effect config.
onGestureMovevoid Function(TiltDataModel, GesturesType)?nullGesture move callback.
onGestureLeavevoid Function(TiltDataModel, GesturesType)?nullGesture leave callback.

TiltParallax widget parameters 🤖

ParameterTypeDefaultDescription
child requiredWidget-Create a widget with parallax.
sizeOffsetOffset(10.0, 10.0)Parallax size.
filterQualityFilterQualitynullFlutter FilterQuality.

ChildLayout 📄

ParameterTypeDefaultDescription
outerList<Widget><Widget>[]As with Stack, you can use the Stack layout to create widgets that are outer of the child.
e.g. parallax effects.
innerList<Widget><Widget>[]As with Stack, you can use the Stack layout to create widgets that are inner of the child.
e.g. parallax effects.
behindList<Widget><Widget>[]As with Stack, you can use the Stack layout to create widgets that are behind of the child.
e.g. parallax effects.

StreamController<TiltStreamModel> 📄


final StreamController<TiltStreamModel> tiltStreamController =
      StreamController<TiltStreamModel>.broadcast();

/// The current gesture is being used
tiltStreamController.add(
  TiltStreamModel(
    position: Offset(xx, xx),
  ),
);

/// Stop using the current gesture
tiltStreamController.add(
  TiltStreamModel(
    position: Offset(xx, xx),
    gestureUse: false,
  ),
);

ParameterTypeDefaultDescription
position requiredOffset-The current trigger position,
It will have the tilt effect of the corresponding position.
e.g.
There is a widget size, width: 10, height: 10,
(0, 0): Maximum tilt top left.
(10, 10): Maximum tilt bottom right.
gesturesTypeGesturesTypeGesturesType.controllerTrigger gesture type.
It is triggered according to the gesture priority.
If you need to customize the control with animation or other means.
Recommended use of GesturesType.controller.
If other types are used for triggering,
Then it will be affected by the configuration and effects associated with that type.
e.g.
When custom triggering GesturesType.sensors.
If TiltConfig.enableSensorRevert is configured to be false,
it will also not revert to the initial state.
gestureUsebooltrueWhether the gesture is being used.
It is used to determine if the gesture is being used and will be processed according to the gesture priority.
e.g.
If GesturesType.touch is never assigned false when triggered, gestures with a lower priority than GesturesType.touch will never be triggered.

TiltConfig 📄

ParameterTypeDefaultDescription
disableboolfalseOnly disable the tilt effect.
initialOffset?nullInitial tilt progress, range (x, y): (1, 1) to (-1, -1),
you can exceed the range, but the maximum tilt angle during gesture movement is always tilted according to [TiltConfig.angle].
e.g. (0.0, 0.0) center
(1.0, 1.0) Maximum tilt top left [TiltConfig.angle].
angledouble10.0Maximum tilt angle.
e.g. 180 will flip.
directionList<TiltDirection>?nullTilt Direction, multiple directions, customized direction values.
enableReverseboolfalseTilt reverse, can be tilted up or down.
filterQualityFilterQualitynullFlutter FilterQuality.
enableGestureSensorsbooltrueGyroscope sensor triggered tilt.
Only the following gestures:
GesturesType.sensors
sensorFactordouble10.0Sensor trigger factor (sensitivity).
Only the following gestures:
GesturesType.sensors
enableSensorRevertbooltrueEnable sensor tilt revert, will revert to the initial state.
Only the following gestures:
GesturesType.sensors
sensorRevertFactordouble0.05Sensor revert factor (damping), range of values: 0-1.
Only the following gestures:
GesturesType.sensors
sensorMoveDurationDurationDuration(milliseconds: 50)Animation duration during sensor move.
Only the following gestures:
GesturesType.sensors
enableGestureHoverbooltrueHover gesture triggered tilt.
Only the following gestures:
GesturesType.hover
enableGestureTouchbooltrueTouch gesture triggered tilt.
Only the following gestures:
GesturesType.touch
enableRevertbooltrueEnable tilt revert, will revert to the initial state.
Only the following gestures:
GesturesType.touch
GesturesType.hover
GesturesType.controller
enableOutsideAreaMovebooltrueTilt can continue to be triggered outside the area.
Only the following gestures:
GesturesType.touch
GesturesType.controller
moveDurationDurationDuration(milliseconds: 100)Animation duration during gesture move.
Only the following gestures:
GesturesType.touch
GesturesType.hover
leaveDurationDurationDuration(milliseconds: 300)Animation duration after gesture leave.
Only the following gestures:
GesturesType.touch
GesturesType.hover
moveCurveCurveCurves.linearAnimation curve during gesture move.
Only the following gestures:
GesturesType.touch
GesturesType.hover
leaveCurveCurveCurves.linearAnimation curve after gesture leave.
Only the following gestures:
GesturesType.touch
GesturesType.hover
controllerMoveDurationDurationDuration(milliseconds: 100)Animation duration during controller gesture move.
Only the following gestures:
GesturesType.controller
controllerLeaveDurationDurationDuration(milliseconds: 300)Animation duration after controller gesture leave.
Only the following gestures:
GesturesType.controller

LightConfig 📄

ParameterTypeDefaultDescription
disableboolfalseOnly disable the light effect.
colorColorColor(0xFFFFFFFF)Light color.
minIntensitydouble0.0Color minimum opacity, also initial opacity.
maxIntensitydouble0.5Color maximum opacity for tilt progresses.
spreadFactordouble4.0Light spread factor, relative to current widget size.
directionLightDirectionLightDirection.aroundLight direction.
Affects:
[ShadowConfig.direction] (not affected after configuration).
enableReverseboolfalseReverse light direction.
Affects:
[ShadowConfig.direction] (not affected after configuration).
[ShadowConfig.enableReverse] (not affected after configuration).

ShadowConfig 📄

ParameterTypeDefaultDescription
disableboolfalseOnly disable the shadow effect.
colorColorColor(0xFF9E9E9E)Shadow color.
minIntensitydouble0.0Color minimum opacity, also initial opacity.
maxIntensitydouble0.5Color maximum opacity as tilt progresses.
offsetInitialOffsetOffset(0.0, 0.0)Initial value of shadow offset.
e.g. (0.0, 0.0) center.
(40.0, 40.0) Offset 40 to the top left.
offsetFactordouble0.1Shadow offset factor, relative to current widget size.
spreadInitialdouble0.0Initial value of shadow spread radius.
spreadFactordouble0.0Shadow spread radius factor, relative to current widget size.
minBlurRadiusdouble10.0Minimum blur radius, also initial blur radius.
maxBlurRadiusdouble20.0Maximum blur radius for tilt progresses.
directionShadowDirection?nullShadow direction.
enableReversebool?nullReverse shadow direction.

Contributors ✨

AmosHuKe
AmosHuKe

License 📄

MIT License
Open sourced under the MIT license.

© AmosHuKe