import { Story, ArgTypes, Canvas, Meta } from '@storybook/addon-docs/blocks';
import * as TooltipStories from './Tooltip.stories';
import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';

<Meta isTemplate />

# Tooltip

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Tooltip)
&nbsp;|&nbsp;
[Usage guidelines](https://www.carbondesignsystem.com/components/tooltip/usage)
&nbsp;|&nbsp;
[Accessibility](https://www.carbondesignsystem.com/components/tooltip/accessibility)

{/* <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> */}

## Table of Contents

- [Overview](#overview)
  - [Usage](#usage)
  - [Toggletips vs Tooltips](#toggletips-vs-tooltips)
  - [Customizing the content of a tooltip](#customizing-the-content-of-a-tooltip)
  - [Tooltip alignment](#tooltip-alignment)
  - [Customizing the duration of a tooltip](#customizing-the-duration-of-a-tooltip)
- [Component API](#component-api)
- [Feedback](#feedback)

{/* <!-- END doctoc generated TOC please keep comment here to allow auto update --> */}

## Overview

You can use the `Tooltip` component as a wrapper to display a popup for an
interactive element that you provide. If you are trying to place interactive
content inside of the `Tooltip` itself, consider using `Toggletip` instead.

### Usage

`Tooltip` accepts a single child for its `children` prop. It is important that
the child is an interactive element, for example:

```jsx
<Tooltip label="Close">
  <button type="button">X</button>
</Tooltip>
```

When used with a component, props need to be spread on the child component.

```jsx
export default function App() {
  return (
    <Tooltip label="Close">
      <CustomTrigger />
    </Tooltip>
  );
}

function CustomTrigger(props) {
  return (
    <button type="button" {...props}>
      X
    </button>
  );
}
```

You can specify the contents of the popup through the `label` or `description`
prop.

<Canvas
  of={TooltipStories.Default}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(TooltipStories.Default),
    },
  ]}
/>

### Toggletips vs Tooltips

Toggletips and tooltips are similar visually and both contain a popover and
interactive trigger element. The two components differ in the way they are
invoked and dismissed and if the user must interact with the contents. A tooltip
is exposed on hover or focus when you need to expose brief, supplemental
information that is not interactive. A toggletip is used on click or enter when
you need to expose interactive elements, such as button, that a user needs to
interact with.

### Customizing the content of a tooltip

The `Tooltip` component supports tooltip customization through the `label` and
`description` props. Under the hood, `label` will map to `aria-labelledby` and
`description` will map to `aria-describedby`.

It's important to consider the type of content that you provide through the
tooltip in order to know whether to use `label` or `description`. If the
information shown is the only content that describes your component, you should
use a `label`. If the information is secondary or adds additional information,
`description` would be a good pick.

While the `label` and `description` props accept any arbitrary React element,
it's important that the value you pass to either prop has no interactive
content. This will cause a violation in the component as the semantics of this
content will not be accessible to users of screen reader software.

### Tooltip alignment

The `align` prop allows you to specify where your content should be placed
relative to the tooltip. For example, if you provide `align="top"` to the
`Tooltip` component then the tooltip will render above your component.
Similarly, if you provide `align="bottom"` then the tooltip will render below
your component.

<Canvas
  of={TooltipStories.Alignment}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(TooltipStories.Alignment),
    },
  ]}
/>

You can also configure the placement of the caret, if it is enabled, by choosing
between `left` and `right` or `bottom` and `top`, depending on where your
tooltip is being rendered.

If you are using `align="top"`, then you can choose between `align="top-left"`
and `align="top-right"`. These options will place the caret closer to the left
or right edges of the tooltip.

If you are using `align="left"` or `align="right"`, you can use `top` or
`bottom` to control this alignment.

### Customizing the duration of a tooltip

You can customize the delay between when a tooltip is invoked and its contents
are shown. You can also customize the delay between when a tooltip is dismissed
and its contents are hidden.

<Canvas
  of={TooltipStories.Duration}
  additionalActions={[
    {
      title: 'Open in Stackblitz',
      onClick: () => stackblitzPrefillConfig(TooltipStories.Duration),
    },
  ]}
/>

The `enterDelayMs` prop allows you to provide a time, in milliseconds, that the
component will wait before showing the tooltip. The `exitDelayMs` prop allows
you to provide a time, in milliseconds, that the component will wait before
hiding the tooltip.

By default, these values are set to 100ms for `enterDelayMs` and 300ms for
`exitDelayMs`.

## Component API

<ArgTypes />

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/Tooltip/Tooltip.mdx).
