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 #

ShakeText #

ShakeConfig #

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.