Tooltip class

A Material Design tooltip.

Tooltips provide text labels which help explain the function of a button or other user interface action. Wrap the button in a Tooltip widget and provide a message which will be shown when the widget is long pressed.

Many widgets, such as IconButton, FloatingActionButton, and PopupMenuButton have a tooltip property that, when non-null, causes the widget to include a Tooltip in its build.

Tooltips improve the accessibility of visual widgets by proving a textual representation of the widget, which, for example, can be vocalized by a screen reader.

Learn more about Tooltip on the Flutter YouTube channel.

This example show a basic Tooltip which has a Text as child. message contains your label to be shown by the tooltip when the child that Tooltip wraps is hovered over on web or desktop. On mobile, the tooltip is shown when the widget is long pressed.

This tooltip will default to showing above the Text instead of below because its ambient TooltipThemeData.preferBelow is false. (See the use of MaterialApp.theme.) Setting that piece of theme data is recommended to avoid having a finger or cursor hide the tooltip. For other ways to set that piece of theme data see:

• Theme.data, ThemeData.tooltipTheme
• TooltipTheme.data

or it can be set directly on each tooltip with Tooltip.preferBelow.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Tooltip].

void main() => runApp(const TooltipExampleApp());

class TooltipExampleApp extends StatelessWidget {
  const TooltipExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        tooltipTheme: const TooltipThemeData(preferBelow: false),
      ),
      home: Scaffold(
        appBar: AppBar(title: const Text('Tooltip Sample')),
        body: const Center(child: TooltipSample()),
      ),
    );
  }
}

class TooltipSample extends StatelessWidget {
  const TooltipSample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Tooltip(
      message: 'I am a Tooltip',
      child: Text('Hover over the text to show a tooltip.'),
    );
  }
}

This example covers most of the attributes available in Tooltip. decoration has been used to give a gradient and borderRadius to Tooltip. constraints has been used to set the minimum width of the Tooltip. preferBelow is true; the tooltip will prefer showing below Tooltip's child widget. However, it may show the tooltip above if there's not enough space below the widget. textStyle has been used to set the font size of the 'message'. showDuration accepts a Duration to continue showing the message after the long press has been released or the mouse pointer exits the child widget. waitDuration accepts a Duration for which a mouse pointer has to hover over the child widget before the tooltip is shown.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Tooltip].

void main() => runApp(const TooltipExampleApp());

class TooltipExampleApp extends StatelessWidget {
  const TooltipExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        tooltipTheme: const TooltipThemeData(preferBelow: false),
      ),
      home: Scaffold(
        appBar: AppBar(title: const Text('Tooltip Sample')),
        body: const Center(child: TooltipSample()),
      ),
    );
  }
}

class TooltipSample extends StatelessWidget {
  const TooltipSample({super.key});

  @override
  Widget build(BuildContext context) {
    return Tooltip(
      message: 'I am a Tooltip',
      decoration: BoxDecoration(
        borderRadius: .circular(25),
        gradient: const LinearGradient(
          colors: <Color>[Colors.amber, Colors.red],
        ),
      ),
      constraints: const BoxConstraints(minWidth: 250),
      padding: const .all(8.0),
      preferBelow: true,
      textStyle: const TextStyle(fontSize: 24),
      showDuration: const Duration(seconds: 2),
      waitDuration: const Duration(seconds: 1),
      child: const Text('Tap this text and hold down to show a tooltip.'),
    );
  }
}

This example shows a rich Tooltip that specifies the richMessage parameter instead of the message parameter (only one of these may be non-null. Any InlineSpan can be specified for the richMessage attribute, including WidgetSpan.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Tooltip].

void main() => runApp(const TooltipExampleApp());

class TooltipExampleApp extends StatelessWidget {
  const TooltipExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        tooltipTheme: const TooltipThemeData(preferBelow: false),
      ),
      home: Scaffold(
        appBar: AppBar(title: const Text('Tooltip Sample')),
        body: const Center(child: TooltipSample()),
      ),
    );
  }
}

class TooltipSample extends StatelessWidget {
  const TooltipSample({super.key});

  @override
  Widget build(BuildContext context) {
    return const Tooltip(
      richMessage: TextSpan(
        text: 'I am a rich tooltip. ',
        style: TextStyle(color: Colors.red),
        children: <InlineSpan>[
          TextSpan(
            text: 'I am another span of this rich tooltip',
            style: TextStyle(fontWeight: .bold),
          ),
        ],
      ),
      child: Text('Tap this text and hold down to show a tooltip.'),
    );
  }
}

This example shows how Tooltip can be shown manually with TooltipTriggerMode.manual by calling the TooltipState.ensureTooltipVisible function.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [Tooltip].

void main() => runApp(const TooltipExampleApp());

class TooltipExampleApp extends StatelessWidget {
  const TooltipExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        tooltipTheme: const TooltipThemeData(preferBelow: false),
      ),
      home: const TooltipSample(title: 'Tooltip Sample'),
    );
  }
}

class TooltipSample extends StatelessWidget {
  const TooltipSample({super.key, required this.title});

  final String title;

  @override
  Widget build(BuildContext context) {
    final GlobalKey<TooltipState> tooltipkey = GlobalKey<TooltipState>();

    return Scaffold(
      appBar: AppBar(title: Text(title)),
      body: Center(
        child: Tooltip(
          // Provide a global key with the "TooltipState" type to show
          // the tooltip manually when trigger mode is set to manual.
          key: tooltipkey,
          triggerMode: .manual,
          showDuration: const Duration(seconds: 1),
          message: 'I am a Tooltip',
          child: const Text('Tap on the FAB'),
        ),
      ),
      floatingActionButton: FloatingActionButton.extended(
        onPressed: () {
          // Show Tooltip programmatically on button tap.
          tooltipkey.currentState?.ensureTooltipVisible();
        },
        label: const Text('Show Tooltip'),
      ),
    );
  }
}

See also:

• material.io/design/components/tooltips.html
• TooltipTheme or ThemeData.tooltipTheme
• TooltipVisibility

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatefulWidget
• Tooltip

Constructors

Tooltip({Key? key, String? message, InlineSpan? richMessage, @Deprecated('Use Tooltip.constraints instead. ' 'This feature was deprecated after v3.30.0-0.1.pre.') double? height, BoxConstraints? constraints, EdgeInsetsGeometry? padding, EdgeInsetsGeometry? margin, double? verticalOffset, bool? preferBelow, bool? excludeFromSemantics, Decoration? decoration, TextStyle? textStyle, TextAlign? textAlign, Duration? waitDuration, Duration? showDuration, Duration? exitDuration, bool enableTapToDismiss = true, TooltipTriggerMode? triggerMode, bool? enableFeedback, TooltipTriggeredCallback? onTriggered, MouseCursor? mouseCursor, bool? ignorePointer, TooltipPositionDelegate? positionDelegate, Widget? child})

Creates a tooltip.

const

Properties

child → Widget?

The widget below this widget in the tree.

final

constraints → BoxConstraints?

Constrains the size of the Tooltip's message.

final

decoration → Decoration?

Specifies the tooltip's shape and background color.

final

enableFeedback → bool?

Whether the tooltip should provide acoustic and/or haptic feedback.

final

enableTapToDismiss → bool

Whether the tooltip can be dismissed by tap.

final

excludeFromSemantics → bool?

Whether the tooltip's message or richMessage should be excluded from the semantics tree.

final

exitDuration → Duration?

The length of time that a pointer must have stopped hovering over a tooltip's widget before the tooltip will be hidden.

final

hashCode → int

The hash code for this object.

no setter, inherited

height → double?

The minimum height of the Tooltip's message.

final

ignorePointer → bool?

Whether this tooltip should be invisible to hit testing.

final

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

margin → EdgeInsetsGeometry?

The empty space that surrounds the tooltip.

final

message → String?

The text to display in the tooltip.

final

mouseCursor → MouseCursor?

The cursor for a mouse pointer when it enters or is hovering over the widget.

final

onTriggered → TooltipTriggeredCallback?

Called when the RawTooltip is triggered programmatically, on tap, or on long press.

final

padding → EdgeInsetsGeometry?

The amount of space by which to inset the Tooltip's message.

final

positionDelegate → TooltipPositionDelegate?

A custom position delegate function for computing where the tooltip should be positioned.

final

preferBelow → bool?

Whether the tooltip defaults to being displayed below the widget.

final

richMessage → InlineSpan?

The rich text to display in the tooltip.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

showDuration → Duration?

The length of time that the tooltip will be shown after a long press is released (if triggerMode is TooltipTriggerMode.longPress) or a tap is released (if triggerMode is TooltipTriggerMode.tap).

final

textAlign → TextAlign?

How the message of the tooltip is aligned horizontally.

final

textStyle → TextStyle?

The style to use for the message of the tooltip.

final

triggerMode → TooltipTriggerMode?

The TooltipTriggerMode that will show the tooltip.

final

verticalOffset → double?

The vertical gap between the widget and the displayed tooltip.

final

waitDuration → Duration?

The length of time that a pointer must hover over a tooltip's widget before the tooltip will be shown.

final

Methods

createElement() → StatefulElement

Creates a StatefulElement to manage this widget's location in the tree.

inherited

createState() → State<Tooltip>

Creates the mutable state for this widget at a given location in the tree.

override

debugDescribeChildren() → List<DiagnosticsNode>

Returns a list of DiagnosticsNode objects describing this node's children.

inherited

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String

Returns a string representation of this node and its descendants.

inherited

toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a one-line detailed description of the object.

inherited

toStringShort() → String

A short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

dismissAllToolTips() → bool

Dismiss all of the tooltips that are currently shown on the screen, including those with mouse cursors currently hovering over them.