Skip to content

Commit

Permalink
update tooltip
Browse files Browse the repository at this point in the history
  • Loading branch information
@thyhmdo
thyhmdo committed Jan 28, 2025
1 parent d7a19a5 commit e9effab
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 177 deletions.
Binary file added src/pages/components/tooltip/images/tooltip-usage-anatomy.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
240 changes: 63 additions & 177 deletions src/pages/components/tooltip/usage.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,7 @@ clarity to a user.
<AnchorLink>Overview</AnchorLink>
<AnchorLink>Formatting</AnchorLink>
<AnchorLink>Content</AnchorLink>
<AnchorLink>Universal behaviors</AnchorLink>
<AnchorLink>Standard tooltip</AnchorLink>
<AnchorLink>Icon button tooltip</AnchorLink>
<AnchorLink>Definition tooltip</AnchorLink>
<AnchorLink>Behaviors</AnchorLink>
<AnchorLink>Related</AnchorLink>
<AnchorLink>References</AnchorLink>
<AnchorLink>Feedback</AnchorLink>
Expand Down Expand Up @@ -57,11 +54,9 @@ clarity to a user.

## Overview

A tooltip is a message box displayed when a user hovers over or focuses on a UI
element. A tooltip is used to provide more information and should be paired with
an interactive UI element like a button. Tooltips should be used sparingly and
contain succinct supplementary information. Do not include interactive elements
in tooltips; use the toggletip component instead.
A tooltip displays a popup with text that provides additional information when a
user hovers over or focuses on a UI element. It should be used only when
necessary to offer quick context without cluttering the interface.

<Row>
<Column colLg={8}>
Expand All @@ -71,27 +66,40 @@ in tooltips; use the toggletip component instead.
</Column>
</Row>

<Caption>Image of a tooltip</Caption>

### When to use

By default, components like icon buttons, icon tabs, icon content switchers, and
copy buttons should come with integrated tooltips. Therefore, there’s no need to
include a separate tooltip control within the component. Tooltips can be exposed
for the following reasons:

- To expose names of controls, like icon buttons, that lack visual labels
- When an element can take focus and supplying additional information is useful
in helping a user make decisions
- When an element needs more context or explanation
- Use when defining a term or inline item
- To supply additional information for focusable elements, helping users make
informed decisions
- To offer more context or explanation for specific elements
- To define a term or provide details for an inline item

#### Definition tooltip

A definition tooltip provides extra help or defines a term inline. It’s similar
to a regular tooltip but offers more alignment options and slightly different
interaction patterns. Definition tooltips can be used on UI labels, words in
paragraphs, or in compact spaces like data tables where icons can clutter the
UI. They work well on headers, body copy, or labels.

### When not to use

- Since a tooltip disappears when a user hovers away, do not include information
for the user to complete their task. Use helper text that is always visible
and accessible for vital information such as required fields.
- Do not include interactive elements within a tooltip. Interactive elements in
tooltips are inaccessible for some users and are hard to use for all users
since tooltips do not receive focus. If images, buttons, or links need to be
included in supplemental information, use the toggletip component and the
disclosure pattern that allows for better tabbing and focus structure,
improving the experience for all users.
Since a tooltip disappears when a user hovers away, do not include pertinent
information for the user to complete their task. Use helper text that is always
visible and accessible for vital information, such as required fields.

Do not include interactive elements within a tooltip. Interactive elements in
tooltips are inaccessible for some users and are hard to use for all users since
tooltips do not receive focus. If images, buttons, or links need to be included
in supplemental information, use the
[toggletip](https://carbondesignsystem.com/components/toggletip/usage/)
component and the disclosure pattern that allows for better tabbing and focus
structure, improving the experience for all users.

<DoDontRow>
<DoDont
Expand Down Expand Up @@ -131,7 +139,7 @@ caption="Do not use interactive elements within a tooltip.">
</DoDont>
</DoDontRow>

#### Tooltips versus Toggletips
#### Tooltips versus toggletips

Tooltips and toggletips look visually similar, and both have an interactive
trigger. The two components differ of how they are invoked and dismissed and if
Expand All @@ -150,72 +158,23 @@ interactive elements, such as a button, that a user needs to interact with.

<Caption>Example of a tooltip versus a toggletip</Caption>

### Variants

| Variant | Purpose |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Standard tooltip](#standard-tooltip) | Provides nonessential, supplemental information to help a user make a decision but is optional to interpret and will not prevent a user from completing a task or workflow. |
| [Icon button tooltip](#icon-button-tooltip) | Describes a button's function or action. |
| [Definition tooltip](#definition-tooltip) | Provides additional help or defines an item or term. It may be used on the label of a UI element, or on a word embedded in a paragraph. |

<Row>
<Column colLg={12}>

![Tooltip variants](images/tooltip-usage-12.png)

</Column>
</Row>

<Caption>
Image of a standard tooltip, icon button tooltip, and definition tooltip
</Caption>

## Formatting

### Standard tooltip anatomy

<Row>
<Column colLg={8}>

![Standard tooltip anatomy](images/tooltip-usage-standard.png)

</Column>
</Row>

1. **UI trigger button:** Button that triggers a tooltip on hover or focus.
2. **Caret tip:** Closely associates the container with the related trigger
element.
3. **Container:** Contains helper text.

### Icon button tooltip anatomy
### Anatomy

<Row>
<Column colLg={8}>

![Icon button tooltip anatomy](images/tooltip-usage-6.png)
![Tooltip anatomy](images/tooltip-usage-anatomy.png)

</Column>
</Row>

1. **Icon button:** Button that triggers a tooltip on hover or focus.
1. **UI trigger:** UI trigger includes any component with integrated tooltips or
definition terms with dotted underlines
2. **Caret tip:** Closely associates the container with the related trigger
element.
3. **Container:** Contains helper text.

### Definition tooltip anatomy

<Row>
<Column colLg={8}>

![Definition tooltip anatomy](images/tooltip-usage-13.png)

</Column>
</Row>

1. **UI trigger button:** The definition indicator and underline that is dotted
and can be activated on hover or focus.
2. **Caret tip:** Closely associates the container to term to be defined.
3. **Container:** Contains helper text.
element
3. **Container:** Contains short or brief text

### Alignment

Expand Down Expand Up @@ -260,20 +219,22 @@ not bleed off page or behind other content.
left, bottom, or top
</Caption>

For tooltips that are inline with other text, like a definition tooltip, do not
obstruct words to the left and right of the trigger word. When the tooltip is
active, ensure it overlays other content and is not cut off by other surrounding
components or bleeds off the page where some content is not visible.
For definition tooltip, do not obstruct words to the left and right of the
trigger word. When the tooltip is active, ensure it overlays other content and
is not cut off by other surrounding components or bleeds off the page where some
content is not visible.

<Row>
<Column colLg={8}>

![Example of a definition tooltip positioned to the top](images/tooltip-usage-14.png)
![Example of definition tooltip with the popover overlays the text](images/tooltip-usage-14.png)

</Column>
</Row>

<Caption>Example of a definition tooltip positioned to the top</Caption>
<Caption>
Example of definition tooltip with the popover overlays the text
</Caption>

## Content

Expand All @@ -284,8 +245,8 @@ components or bleeds off the page where some content is not visible.
- Should contain relevant, specific content.
- Should not contain essential task instructions since a tooltip is not
persistent.
- Icon button tooltips should only contain one or two-word descriptions of a
button's function.
- Tooltips for icon-only components, like icon buttons, should provide a concise
one- or two-word description of the button’s function.
- For definitions and instructive tooltips, use sentence-style capitalization
and write the text as complete sentences with punctuation unless space is
limited.
Expand All @@ -295,106 +256,31 @@ components or bleeds off the page where some content is not visible.
For further content guidance, see Carbon’s
[content guidelines](/guidelines/content/overview/).

## Universal behaviors
## Behaviors

### States

The tooltip component has two states: active and inactive. By default, the
tooltip is hidden and inactive. Tooltips are displayed on `hover` and `focus`.
Definition tooltips can be displayed either on `hover` and `focus` or on `click`
and `enter`.
The tooltip component has two states: active (hover and focus) and inactive. By
default, tooltip is hidden and inactive.

### Interactions

#### Mouse

Tooltips are triggered when the mouse hovers over or focuses on the UI trigger.
The tooltip persists if the mouse remains over the active container or the UI
trigger. The tooltip is dismissed by hovering away or moving focus to another
element. The definition tooltip can be activated on click or and dismissed by
clicking outside the active container or UI element.
Tooltips are triggered when the mouse hovers over the UI trigger. The tooltip
persists if the mouse remains over the active container or the UI trigger. The
tooltip is dismissed by hovering away to another element.

#### Keyboard

Users can trigger a tooltip by focusing on the element. Addtionally, a
definition tooltip can be triggered by using the `enter` key. A tooltip is
dismissible by the use of the `escape` key. For tooltips that reveal containers
on focus, the container dissapears when focus moves away.

## Standard tooltip

A standard tooltip provides additional information to further assist a user in
completing a task and is paired with an interactive UI element such as a button
or link.

### Best practices

- The content within a standard tooltip should be purely additional information
that is not critical for a user to read to complete a task. If the content is
essential for the user to interpret concerning their workflow, use a
[toggletip](https://carbondesignsystem.com/components/toggletip/usage/) for
this information instead.

<Row>
<Column colLg={8}>

![Image of a standard tooltip](images/tooltip-usage-standard-tooltip.png)

</Column>
</Row>

<Caption>Image of a standard tooltip</Caption>

## Icon button tooltip

An icon button tooltip is used to describe the function or action of an icon
button that has no label to provide clarity on what the button will do.

### Best practices

- Tooltip content should only contain one or two words.
- Use the icon button tooltip instead of the title attribute. Do not use both.
- It is required to not include interactive elements within a tooltip. If
interactive elements are needed use a toggletip instead.

<Row>
<Column colLg={8}>

![Image of an icon button tooltip](images/tooltip-usage-10.png)

</Column>
</Row>

<Caption>Image of an icon button tooltip</Caption>

## Definition tooltip

The definition tooltip provides inline additional help or defines a term. It may
be used on the label of a UI element, on a word embedded in a paragraph, or in
compact spaces such as data tables where icons clutter the UI. You can use
definition tooltips on headers, body copy, or labels.

The definition tooltip is unique in that if offers both a hover or click
interaction depending on specific use cases. If a user needs only a few seconds
to gather their information and go, use a hover interaction. If a user needs
time to think about the content or the tooltip is placed so that a user can
unintentionally trigger the tooltip, then a click interaction would be more
appropriate.
Definition tooltips can use either hover or click interactions, depending on the
situation. Users can hover if they need a quick glance at the information. Users
can click if they need more time or if the tooltip might be unintentionally
triggered.

### Best practices

- Tooltip content should contain brief, read-only text.
- Use on proper nouns, technical terms, or acronyms with two letters or more.

<Row>
<Column colLg={8}>

![Image of definition tooltip](images/tooltip-usage-15.png)

</Column>
</Row>
#### Keyboard

<Caption>Image of a definition tooltip</Caption>
Users can navigate to the UI trigger and display the tooltip by pressing `Tab`.
The tooltip can be dismissed by pressing the `Esc` key. For tooltips that reveal
containers on focus, the container disappears when focus moves away.

## Related

Expand Down

0 comments on commit e9effab

Please sign in to comment.