> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tooltip
> Display helpful information when hovering over or long-pressing on widgets
# Overview
`HuxTooltip` component provides additional context when hovering over or long-pressing on widgets. It automatically adapts to light and dark themes and provides various positioning and styling options.
## Basic Usage
The simplest way to use a tooltip is to wrap any widget with `HuxTooltip`:
```dart theme={null}
HuxTooltip(
message: 'This is a helpful tooltip',
child: Icon(Icons.info),
)
```
## Variants
### Standard Tooltip
The basic tooltip with customizable styling:
```dart theme={null}
HuxTooltip(
message: 'This is a tooltip message',
child: HuxButton(
onPressed: () {},
child: Text('Save'),
),
)
```
### Tooltip with Icon
For enhanced visual context, add an icon parameter to `HuxTooltip`.
```dart theme={null}
HuxTooltip(
message: 'New feature',
icon: Icons.info_outline, // Icon appears inside the tooltip
child: HuxButton(
onPressed: () {},
child: Text('Help'),
),
)
// Or with Lucide/Feather icons
HuxTooltip(
message: 'Help information',
icon: FeatherIcons.info, // Lucide/Feather icons
child: Icon(FeatherIcons.help),
)
```
## Customization
### Colors
Customize the tooltip appearance with your own colors:
```dart theme={null}
HuxTooltip(
message: 'Custom styled tooltip',
backgroundColor: Colors.deepPurple,
textColor: Colors.white,
child: Text('Hover me'),
)
```
### Positioning
Control where the tooltip appears relative to the child:
```dart theme={null}
HuxTooltip(
message: 'Tooltip above the element',
preferBelow: false, // Show above instead of below
verticalOffset: 20.0, // Increase distance from child
child: Icon(Icons.info),
)
```
### Timing
Adjust when and how long the tooltip appears:
```dart theme={null}
HuxTooltip(
message: 'Quick tooltip',
waitDuration: Duration(milliseconds: 200), // Show faster
showDuration: Duration(seconds: 5), // Show longer
child: Icon(Icons.info),
)
```
### Advanced Styling
For complete control over the tooltip appearance:
```dart theme={null}
HuxTooltip(
message: 'Custom styled tooltip',
decoration: BoxDecoration(
color: Colors.blue,
borderRadius: BorderRadius.circular(16),
border: Border.all(color: Colors.white, width: 2),
),
textStyle: TextStyle(
color: Colors.white,
fontSize: 16,
fontWeight: FontWeight.bold,
),
padding: EdgeInsets.all(16),
child: Icon(Icons.info),
)
```
## Props
### HuxTooltip
| Prop | Type | Default | Description |
| ---------------------- | --------------------- | ------------- | ----------------------------------------- |
| `message` | `String` | **required** | The text to display in the tooltip |
| `child` | `Widget` | **required** | The widget below this tooltip |
| `backgroundColor` | `Color?` | Theme surface | Background color of the tooltip |
| `textColor` | `Color?` | Theme text | Text color of the tooltip |
| `preferBelow` | `bool` | `true` | Whether to prefer showing below the child |
| `excludeFromSemantics` | `bool` | `false` | Whether to exclude from semantics tree |
| `verticalOffset` | `double` | `10.0` | Vertical offset from the child |
| `waitDuration` | `Duration` | `500ms` | How long to wait before showing |
| `showDuration` | `Duration` | `3000ms` | How long to show the tooltip |
| `decoration` | `Decoration?` | Default theme | Custom decoration for the tooltip |
| `textStyle` | `TextStyle?` | Default theme | Custom text style |
| `height` | `double?` | Auto | Height of the tooltip |
| `padding` | `EdgeInsetsGeometry?` | `12x8` | Padding inside the tooltip |
| `margin` | `EdgeInsetsGeometry?` | `8` | Margin around the tooltip |
| `richMessage` | `InlineSpan?` | `null` | Rich text message (overrides message) |
### HuxTooltip Icon Parameters
| Prop | Type | Default | Description |
| ----------- | ----------- | ---------------- | ---------------------------------------------------------------------- |
| `icon` | `IconData?` | `null` | The icon to display alongside the message (rendered as an Icon widget) |
| `iconColor` | `Color?` | Theme text color | Color of the icon |
| `iconSize` | `double` | `16.0` | Size of the icon |
## Examples
Provide context for form inputs:
```dart theme={null}
Row(
children: [
Expanded(
child: HuxInput(
label: 'Email Address',
hintText: 'Enter your email',
),
),
HuxTooltip(
message: 'We\'ll use this to send you important updates',
child: Icon(Icons.help_outline, color: Colors.grey),
),
],
)
```
### Button Explanations
Explain button actions:
```dart theme={null}
HuxTooltip(
message: 'This will permanently delete your account',
icon: Icons.warning,
child: HuxButton(
onPressed: () {},
variant: HuxButtonVariant.destructive,
child: Text('Delete Account'),
),
)
```
### Navigation Hints
Guide users through complex interfaces:
```dart theme={null}
HuxTooltip(
message: 'Click to expand this section and see more options',
child: HuxButton(
onPressed: () {},
variant: HuxButtonVariant.ghost,
child: Icon(Icons.expand_more),
),
)
```
## Best Practices
### Content Guidelines
* **Keep messages concise**: Tooltips should be brief and to the point
* **Use clear language**: Avoid technical jargon unless necessary
* **Provide value**: Only show tooltips when they add meaningful context
### Accessibility
* **Semantic content**: Tooltips are automatically included in the accessibility tree
* **Keyboard navigation**: Tooltips work with keyboard navigation
* **Screen readers**: Content is properly announced to assistive technologies
### Performance
* **Lazy loading**: Tooltips only render when needed
* **Efficient positioning**: Smart positioning algorithms minimize layout calculations
* **Memory management**: Proper cleanup when tooltips are dismissed
### Theme Integration
* **Automatic adaptation**: Tooltips automatically adapt to light/dark themes
* **Consistent styling**: Uses Hux design tokens for consistent appearance
* **Customizable**: Override theme colors when needed for specific use cases
## Related Components
* **[Button](/components/buttons)** - Add tooltips to buttons for better UX
* **[Input](/components/inputs)** - Provide help text for form fields
* **[Card](/components/cards)** - Add context to card content
* **[Badge](/components/badge)** - Explain badge meanings with tooltips