DOCSEARCHbyAlgolia
Submit Docs

SuperTooltip

repository·master·Indexed 42 days ago

https://github.com/bensonarafat/super_tooltip

A highly customizable Flutter tooltip widget providing advanced features such as flexible positioning, backdrop effects (blur/barriers), and rich interaction patterns like hover and tap-to-toggle. It includes a SuperTooltipController for programmatic control and specialized configuration objects for styling, positioning, arrows, and animations.

Tokens
6.8K
Snippets
24
Records
32
Agent score
50%

What's inside SuperTooltip

  1. Migrate from old API to new Configuration Objects

    master

    The API has moved from a flat list of parameters to organized configuration objects.

    Old API (Flat):

    SuperTooltip(
  popupDirection: TooltipDirection.up,
  backgroundColor: Colors.blue,
  // ...
)

    New API (Config Objects):

    • Use positionConfig: PositionConfiguration(preferredDirection: ...) instead of popupDirection.
    • Use style: TooltipStyle(...) for visual properties like backgroundColor, borderColor, and borderWidth.
    • Use closeButtonConfig: CloseButtonConfiguration(...) for close button settings.
    • Use barrierConfig: BarrierConfiguration(...) for backdrop settings.
    • Use interactionConfig: InteractionConfiguration(...) for hover/interaction settings.
    SuperTooltip(
  positionConfig: PositionConfiguration(
    preferredDirection: TooltipDirection.up,
  ),
  style: TooltipStyle(
    backgroundColor: Colors.blue,
    borderColor: Colors.black,
    borderWidth: 2.0,
  ),
  closeButtonConfig: CloseButtonConfiguration(
    show: true,
    color: Colors.white,
  ),
  barrierConfig: BarrierConfiguration(
    show: true,
    color: Colors.black54,
  ),
  interactionConfig: InteractionConfiguration(
    showOnHover: true,
  ),
)

  2. Install super_tooltip

    master

    To add super_tooltip to your Flutter project, run the following command in your terminal:

    flutter pub add super_tooltip

    This will update your pubspec.yaml with the latest version. You can then import the package in your Dart code:

    import 'package:super_tooltip/super_tooltip.dart';

  3. Best practices for using SuperTooltip

    master

    To ensure a maintainable and performant implementation:

    1. Use Configuration Objects: Group related settings into TooltipStyle, PositionConfiguration, etc., rather than passing many individual parameters.
    2. Reuse Configurations: Define app-wide styles in a central class to ensure consistency.
      class AppTooltipStyles {
  static const primary = TooltipStyle(backgroundColor: Colors.blue, borderRadius: 8.0);
}
    3. Handle Controller Lifecycle: Always call _controller.dispose() in your widget's dispose() method to prevent memory leaks.
    4. Use Auto Direction: Set preferredDirection: TooltipDirection.auto in PositionConfiguration to let the library automatically determine the best position.

  4. Basic Usage of SuperTooltip

    master

    To use SuperTooltip, you must wrap your target widget in a StatefulWidget and manage its state using a SuperTooltipController. The controller is used to programmatically show or hide the tooltip.

    Key steps:

    1. Initialize a SuperTooltipController in your State class.
    2. Pass the controller to the SuperTooltip widget.
    3. Provide the content (the widget to display inside the tooltip) and a child (the widget that triggers the tooltip).
    4. Call _controller.showTooltip() to display it.
    class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  final _controller = SuperTooltipController();

  @override
  Widget build(BuildContext context) {
    return SuperTooltip(
      controller: _controller,
      content: const Text(
        "This is a simple tooltip!",
        style: TextStyle(color: Colors.white),
      ),
      child: IconButton(
        icon: const Icon(Icons.info),
        onPressed: () => _controller.showTooltip(),
      ),
    );
  }
}

  5. Enable mouse hover support for Desktop and Web

    master

    On Web and Desktop platforms, you can enable hover-based interactions using InteractionConfiguration.

    • showOnHover: Set to true to show the tooltip when the mouse enters the child area.
    • hideOnHoverExit: Set to true to hide the tooltip when the mouse leaves.
    • animationConfig: Use AnimationConfiguration to set waitDuration (delay before showing) and exitDuration (delay before hiding).
    • mouseCursor: Set a custom SystemMouseCursor to change the cursor when hovering over the child.

    Note: Hover events are not supported on native mobile (iOS/Android) and will revert to tap-to-show behavior.

    SuperTooltip(
  controller: _controller,
  interactionConfig: const InteractionConfiguration(
    showOnHover: true,
    hideOnHoverExit: true,
  ),
  animationConfig: const AnimationConfiguration(
    waitDuration: Duration(milliseconds: 500),
    exitDuration: Duration(milliseconds: 100),
  ),
  mouseCursor: SystemMouseCursors.help,
  content: const Text("Hover tooltip"),
  child: const Icon(Icons.help),
)

  6. Dismiss tooltip with Android back button

    master

    On Android, you can prevent the app from popping the current page when the back button is pressed by checking if the tooltip is visible via its SuperTooltipController. If controller.isVisible is true, call controller.hideTooltip() and return false in a PopScope callback.

    class _MyWidgetState extends State<MyWidget> {
  final _controller = SuperTooltipController();

  Future<bool> _willPopCallback() async {
    if (_controller.isVisible) {
      await _controller.hideTooltip();
      return false;
    }
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return PopScope(
      onPopInvokedWithResult: (didPop, result) => _willPopCallback(),
      child: GestureDetector(
        onTap: () => _controller.showTooltip(),
        child: SuperTooltip(
          controller: _controller,
          content: const Text("Tooltip content"),
          child: const Icon(Icons.info),
        ),
      ),
    );
  }
}

  7. Configure SuperTooltip interaction behaviors

    master

    The interactionConfig property (of type InteractionConfiguration) defines how the tooltip responds to user input.

    Common interaction patterns include:

    • Hover: Use showOnHover and hideOnHoverExit to trigger the tooltip when a mouse enters or leaves the target area.
    • Tap: Use showOnTap to show the tooltip on tap, or toggleOnTap to switch between showing and hiding.
    • Dismissal: Use hideOnTap to hide the tooltip when the tooltip content itself is tapped, or hideOnBarrierTap to hide it when the background barrier is tapped.
    • Scrolling/Dragging: Use hideOnScroll to automatically hide the tooltip when the user performs vertical or horizontal drags.
    • Click-through: Use clickThrough to allow touch/click events to pass through the tooltip to widgets underneath.

  8. Configure InteractionConfiguration for user interaction

    master

    Use InteractionConfiguration to define how the tooltip responds to user input like hovering, tapping, or scrolling.

    SuperTooltip(
  interactionConfig: InteractionConfiguration(
    showOnHover: true,        // Show on mouse hover (Web/Desktop)
    hideOnHoverExit: true,    // Hide when mouse leaves
    toggleOnTap: true,        // Toggle on/off with taps
    hideOnTap: false,         // Hide when tooltip is tapped
    hideOnBarrierTap: true,   // Hide when barrier is tapped
    hideOnScroll: false,      // Hide on scroll
    clickThrough: false,      // Allow clicks through tooltip
  ),
  // ...
)

  9. Configure CloseButtonConfiguration for close buttons

    master

    Use CloseButtonConfiguration to add a dismiss button to the tooltip. You can choose between placing the button inside or outside the tooltip bubble.

    CloseButtonType:

    • CloseButtonType.inside
    • CloseButtonType.outside
    SuperTooltip(
  closeButtonConfig: CloseButtonConfiguration(
    show: true,
    type: CloseButtonType.inside, // or CloseButtonType.outside
    color: Colors.white,
    size: 24.0,
  ),
  // ...
)

  11. Configure TooltipStyle for visual appearance

    master

    Use the TooltipStyle configuration object to customize the visual properties of the tooltip bubble, including colors, borders, shadows, and internal padding.

    SuperTooltip(
  style: TooltipStyle(
    backgroundColor: Colors.deepPurple,
    borderColor: Colors.purpleAccent,
    borderWidth: 2.0,
    borderRadius: 15.0,
    hasShadow: true,
    shadowColor: Colors.black26,
    shadowBlurRadius: 20.0,
    bubbleDimensions: EdgeInsets.all(12),
  ),
  // ...
)

  12. Configure PositionConfiguration for positioning

    master

    Use PositionConfiguration to control where the tooltip appears relative to its child. You can specify a preferred direction or use automatic positioning.

    Available Directions (TooltipDirection):

    • TooltipDirection.auto: Automatically chooses the best direction.
    • TooltipDirection.up: Above the target.
    • TooltipDirection.down: Below the target.
    • TooltipDirection.left: To the left of target.
    • TooltipDirection.right: To the right of target.
    SuperTooltip(
  positionConfig: PositionConfiguration(
    preferredDirection: TooltipDirection.auto, // or up, down, left, right
    minimumOutsideMargin: 20.0,
    top: 10.0,  // Optional fixed positioning
    left: 10.0,
    snapsFarAwayVertically: false,
  ),
  // ...
)