Skip to content

Commit

Permalink
docs(vx-tooltip): add relative wrapper note in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
williaster committed May 11, 2020
1 parent 31baa7c commit 18aab2d
Showing 1 changed file with 32 additions and 11 deletions.
43 changes: 32 additions & 11 deletions packages/vx-tooltip/Readme.md
Expand Up @@ -4,16 +4,19 @@
npm install --save @vx/tooltip
```

The `@vx/tooltip` package provides utilities for making it easy to add `Tooltip`s to a visualization and includes hooks, higher-order component (HOC) enhancers and Tooltip components.
The `@vx/tooltip` package provides utilities for making it easy to add `Tooltip`s to a visualization
and includes hooks, higher-order component (HOC) enhancers and Tooltip components.

### Hooks and Enhancers

This package provides two ways to add tooltip state logic to your chart components:

- a hook: `useTooltip()`
- a hook: `useTooltip()`
- a higher order component (HOC): `withTooltip()`

The `useTooltip` hook is the recommended way to add tooltip state logic to your components, but can only be used in functional components. The `withTooltip` HOC can be used with both functional and class components, and is the recommended way to add tooltip state logic to class components.
The `useTooltip` hook is the recommended way to add tooltip state logic to your components, but can
only be used in functional components. The `withTooltip` HOC can be used with both functional and
class components, and is the recommended way to add tooltip state logic to class components.

Both `useTooltip` and `withTooltip` expose the same values and functions for use in your component:

Expand All @@ -27,24 +30,37 @@ Both `useTooltip` and `withTooltip` expose the same values and functions for use
| tooltipData | any | The `tooltipData` value passed to the `showTooltip` func, intended to be used for any data that your tooltip might need to render |
| updateTooltip | func | Call this function with the signature `func({ tooltipOpen, tooltipLeft, tooltipTop, tooltipData })` to set the tooltip state to the specified values. |

In the case of `useTooltip`, these will be returned from the `useTooltip()` call in your component. In the case of `withTooltip`, they will be passed as props to your wrapped component. Refer to the [Examples](#examples) section for a basic demo of each approach.
In the case of `useTooltip`, these will be returned from the `useTooltip()` call in your component.
In the case of `withTooltip`, they will be passed as props to your wrapped component. Refer to the
[Examples](#examples) section for a basic demo of each approach.

#### useTooltip()

If you would like to add tooltip state logic to a functional component, you may use the `useTooltip()` hook which will return an object with several properties that you can use to manage the tooltip state of your component.
If you would like to add tooltip state logic to a functional component, you may use the
`useTooltip()` hook which will return an object with several properties that you can use to manage
the tooltip state of your component. **For correct tooltip positioning, it is important to wrap your
component in an element (e.g., `div`) with `relative` positioning**. This is handled for you by the
`withTooltip` HOC, but not with the `useTooltip()` hook.

#### withTooltip(BaseComponent [, containerProps [, renderContainer]])

If you would like to add tooltip state logic to a class component, you may wrap it in `withTooltip(BaseComponent [, containerProps [, renderContainer])`.
If you would like to add tooltip state logic to a class component, you may wrap it in
`withTooltip(BaseComponent [, containerProps [, renderContainer])`.

The HOC will wrap your component in a `div` with `relative` positioning by default and handle state for tooltip positioning, visibility, and content by injecting the following props into your `BaseComponent`:
The HOC will wrap your component in a `div` with `relative` positioning by default and handle state
for tooltip positioning, visibility, and content by injecting the following props into your
`BaseComponent`:

You may override the container by specifying `containerProps` as the second argument to `withTooltip`, or by specifying `renderContainer` as the third argument to `withTooltip`.
You may override the container by specifying `containerProps` as the second argument to
`withTooltip`, or by specifying `renderContainer` as the third argument to `withTooltip`.

### Components

#### Tooltip

This is a simple Tooltip container component meant to be used to actually render a Tooltip. It accepts the following props, and will spread any additional props on the tooltip container div (i.e., ...restProps):
This is a simple Tooltip container component meant to be used to actually render a Tooltip. It
accepts the following props, and will spread any additional props on the tooltip container div
(i.e., ...restProps):

| Name | Type | Default | Description |
| :-------- | :--------------- | :------ | :---------------------------------------------------------------------------- |
Expand All @@ -57,7 +73,10 @@ This is a simple Tooltip container component meant to be used to actually render

#### TooltipWithBounds

This tooltip component is exactly the same as `Tooltip` above, but it is aware of its boundaries meaning that it will flip left/right and bottom/top based on whether it would overflow its parent's boundaries. It accepts the following props, and will spread any additional props on the Tooltip component (i.e., ...restProps):
This tooltip component is exactly the same as `Tooltip` above, but it is aware of its boundaries
meaning that it will flip left/right and bottom/top based on whether it would overflow its parent's
boundaries. It accepts the following props, and will spread any additional props on the Tooltip
component (i.e., ...restProps):

| Name | Type | Default | Description |
| :---------- | :----- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -68,9 +87,11 @@ This tooltip component is exactly the same as `Tooltip` above, but it is aware o
| style | object | -- | Sets / overrides any styles on the tooltip container (including top and left) |
| children | node | -- | Sets the children of the tooltip, i.e., the actual content |

Note that this component is positioned using a `transform`, so overriding `left` and `top` via styles may have no effect.
Note that this component is positioned using a `transform`, so overriding `left` and `top` via
styles may have no effect.

### Examples

#### useTooltip For Functional Components

```js
Expand Down

0 comments on commit 18aab2d

Please sign in to comment.