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

<Meta isTemplate />

# Toggletip

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

{/* <!-- 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)
  - [Toggletips vs Tooltips](#toggletips-vs-tooltips)
- [Alignment](#alignment)
- [Customizing content](#customizing-content)
- [Actions](#actions)
- [Component API](#component-api)
- [Feedback](#feedback)

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

## Overview

The `Toggletip` component provides an accessible way to render interactive
content within a popover. If you do not have any interactive content inside of
your `Toggletip`, consider using `Tooltip` instead. To use this component,
you'll need to include a `Toggletip`, `ToggletipButton` for the trigger, and
`ToggletipContent` for the content you would like to render within the popover.

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

```jsx
import { Toggletip, ToggletipButton, ToggletipContent } from '@carbon/react';
import { Information } from '@carbon/react/icons';

<Toggletip>
  <ToggletipButton label="Additional information">
    <Information />
  </ToggletipButton>
  <ToggletipContent>
    <p>Custom content here</p>
  </ToggletipContent>
</Toggletip>;
```

### 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.

## Alignment

The Toggletip component provides four options for alignment: `top`, `bottom`,
`left`, and `right`. These options will correspond to where the popover will
render relative to the ToggletipButton. For example, when choosing `align="top"`
the ToggletipContent will render above the ToggletipButton.

## Customizing content

You can customize the contents of a Toggletip with the ToggletipContent
component. You can render any kind of child element or component inside of this
component as `children`.

## Actions

If your Toggletip includes actions, you can make use of the ToggletipActions
component to render them underneath the content of your ToggletipContent. For
example:

```jsx
<Toggletip>
  <ToggletipButton label="Show information">
    <Information />
  </ToggletipButton>
  <ToggletipContent>
    <p>
      Lorem ipsum dolor sit amet, di os consectetur adipiscing elit, sed do
      eiusmod tempor incididunt ut fsil labore et dolore magna aliqua.
    </p>
    <ToggletipActions>
      <Link href="custom-link">Custom link</Link>
      <Button size="sm">Custom action</Button>
    </ToggletipActions>
  </ToggletipContent>
</Toggletip>
```

## 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/Toggletip/Toggletip.mdx).
