flutter_shake_container 1.1.3

A lightweight shake animation widget for Flutter. Supports any widget and horizontal/vertical/both-axis shaking.

English | 中文

flutter_shake_container

A lightweight, configurable shake animation widget for Flutter.
Supports any Flutter widget.

This README documents the exact usage patterns shown in example/main.dart, including ValueNotifier, GetX, and Stream based triggers, each demonstrated with horizontal, vertical, and both-axis shake directions.

---

✨ Features

• Preset shake styles: error / warning / subtle
• Fully customizable animation via ShakeConfig
• Supports horizontal / vertical / both-axis shaking
• Queue-based triggering (no interrupted animations)
• Unified trigger abstraction (ValueNotifier / Stream / GetX)
• Text and generic widget support
• onShakeStart callback for haptic / vibration integration
• Zero external dependencies

---

📦 Installation

dependencies:
  flutter_shake_container: ^1.1.3

📥 Import

import 'package:flutter_shake_container/flutter_shake_container.dart';

📸 Demo Preview

🔧 Properties

ShakeContainer

Property	Type	Description
trigger	ShakeTrigger	The trigger that starts the shake animation. Each ShakeContainer should have its own trigger.
config	ShakeConfig	Defines the shake animation (offsets, weights, axis, curve, duration).
child	Widget	The widget to be shaken. Supports any Flutter widget.
onShakeStart	VoidCallback?	Called when the shake animation actually starts. Useful for haptic feedback or vibration.

---

ShakeText

Property	Type	Description
text	ValueListenable<String>	The text content to display and observe. A shake is triggered when the value becomes non-empty.
config	ShakeConfig	Shake animation configuration.
style	TextStyle?	Text style applied to the text widget.
autoDismiss	Duration?	Automatically clears the text after the given duration.
onAutoDismiss	VoidCallback?	Called when autoDismiss completes.
hideWhenEmpty	bool	Whether to hide the widget when the text is empty. Defaults to true.
onShakeStart	VoidCallback?	Called when the shake animation starts. Can be used for haptic feedback.

---

ShakeConfig

Property	Type	Description
offsets	List<double>	The offset values used to build the shake motion.
weights	List<double>	The weight for each shake segment. Must be offsets.length - 1.
axis	ShakeAxis	The shake direction: horizontal, vertical, or both.
curve	Curve	Animation curve. Defaults to Curves.easeOut.
duration	Duration	Total duration of the shake animation.

---

ShakeTrigger

ShakeTrigger is an abstraction over different trigger mechanisms.

Provided implementations:

• StreamShakeTrigger – Triggered by a Stream event
• Internal trigger for ShakeText (ValueListenable-based)

Each ShakeContainer should use its own trigger.

🧪 Example Usage

The following examples are copied and directly from example/main.dart.

---

✏️ ShakeText — ValueNotifier

Horizontal

final errorH = ValueNotifier('');

ShakeText(
  text: errorH,
  config: ShakePreset.error,
  style: const TextStyle(color: Colors.red),
  autoDismiss: const Duration(seconds: 2),
  onAutoDismiss: () => errorH.value = '',
  onShakeStart: () {
    print('Shaken by ValueNotifier: Horizontal');
  },
);

errorH.value = 'Horizontal shake';

Vertical

final errorV = ValueNotifier('');

ShakeText(
  text: errorV,
  config: ShakeConfig(
    offsets: [0, -10, 10, -10, 10, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.vertical,
  ),
  style: const TextStyle(color: Colors.orange),
  autoDismiss: const Duration(seconds: 3),
  onAutoDismiss: () => errorV.value = '',
  onShakeStart: () {
    print('Shaken by ValueNotifier: Vertical');
  },
);

errorV.value = 'Vertical shake';

Both Axis

final errorB = ValueNotifier('');

ShakeText(
  text: errorB,
  config: ShakeConfig(
    offsets: [0, -8, 8, -8, 8, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.both,
  ),
  style: const TextStyle(color: Colors.purple),
  autoDismiss: const Duration(milliseconds: 1200),
  onAutoDismiss: () => errorB.value = '',
  onShakeStart: () {
    print('Shaken by ValueNotifier: Both');
  },
);

errorB.value = 'Both-axis shake';

---

🟢 ShakeContainer — GetX

Each direction uses an independent trigger stream.

Horizontal

ShakeContainer(
  trigger: triggerGetxH,
  config: ShakePreset.error,
  onShakeStart: () {
    print('Shaken by GetX: Horizontal');
  },
  child: const Icon(Icons.access_alarm, color: Colors.orange),
);

demo.triggerHorizontal();

Vertical

ShakeContainer(
  trigger: triggerGetxV,
  config: ShakeConfig(
    offsets: [0, -10, 10, -10, 10, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.vertical,
  ),
  onShakeStart: () {
    print('Shaken by GetX: Vertical');
  },
  child: const Icon(Icons.accessibility_sharp, color: Colors.deepOrange),
);

demo.triggerVertical();

Both Axis

ShakeContainer(
  trigger: triggerGetxB,
  config: ShakeConfig(
    offsets: [0, -8, 8, -8, 8, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.both,
  ),
  onShakeStart: () {
    print('Shaken by GetX: Both');
  },
  child: const Icon(Icons.access_alarm, color: Colors.purple),
);

demo.triggerBoth();

---

🔄 ShakeContainer — Stream

Each direction uses its own StreamController.

Horizontal

ShakeContainer(
  trigger: triggerStreamH,
  config: ShakePreset.error,
  onShakeStart: () {
    print('Shaken by Stream: Horizontal');
  },
  child: const Text('Horizontal shake'),
);

streamH.add(null);

Vertical

ShakeContainer(
  trigger: triggerStreamV,
  config: ShakeConfig(
    offsets: [0, -10, 10, -10, 10, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.vertical,
  ),
  onShakeStart: () {
    print('Shaken by Stream: Vertical');
  },
  child: const Text('Vertical shake'),
);

streamV.add(null);

Both Axis

ShakeContainer(
  trigger: triggerStreamB,
  config: ShakeConfig(
    offsets: [0, -8, 8, -8, 8, 0],
    weights: [1, 1, 1, 1, 1],
    axis: ShakeAxis.both,
  ),
  onShakeStart: () {
    print('Shaken by Stream: Both');
  },
  child: const Text('Both-axis shake'),
);

streamB.add(null);

---

📄 License

MIT License

Copyright (c) 2026 manburenshenglu

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.