https://github.com/gilbarbara/react-floater
Advanced tooltips for React
https://github.com/gilbarbara/react-floater
Last synced: 9 months ago
JSON representation
Advanced tooltips for React
- Host: GitHub
- URL: https://github.com/gilbarbara/react-floater
- Owner: gilbarbara
- License: mit
- Created: 2017-11-30T22:29:34.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2024-09-11T23:09:51.000Z (over 1 year ago)
- Last Synced: 2025-04-02T01:36:00.543Z (10 months ago)
- Language: TypeScript
- Homepage: https://codesandbox.io/s/github/gilbarbara/react-floater/tree/main/demo
- Size: 2.47 MB
- Stars: 220
- Watchers: 6
- Forks: 41
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# React Floater
[](https://www.npmjs.com/package/react-floater) [](https://github.com/gilbarbara/react-floater/actions/workflows/main.yml) [](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-floater) [](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-floater)
Advanced tooltips for React!
View the [demo](https://codesandbox.io/s/github/gilbarbara/react-floater/tree/main/demo)
## Highlights
- 🏖 **Easy to use:** Just set the `content`
- 🛠 **Flexible:** Personalize the options to fit your needs
- 🟦 **Typescript:** Nicely typed
## Usage
```shell
npm install react-floater
```
Import it in your app:
```tsx
import Floater from 'react-floater';
click me
;
```
And voíla!
## Customization
You can use a custom component to render the Floater with the `component` prop.
Check `WithStyledComponents.ts` in the [demo](https://codesandbox.io/s/github/gilbarbara/react-floater/tree/main/demo) for an example.
## Props
**autoOpen** `boolean` ▶︎ false
Open the Floater automatically.
**callback** `(action: 'open' | 'close', props: Props) => void`
It will be called when the Floater changes state.
**children** `ReactNode`
An element to trigger the Floater.
**component** `ComponentType | ReactElement`
A React element or function to use as a custom UI for the Floater.
The prop `closeFn` will be available in your component.
**content** `ReactNode`
The Floater content. It can be anything that can be rendered.
_This is required unless you pass a_ `component`.
**debug** `boolean` ▶︎ false
Log some basic actions.
_You can also set a global variable_ `ReactFloaterDebug = true;`
**disableFlip** `boolean` ▶︎ false
Disable changes in the Floater position on scroll/resize.
**disableHoverToClick** `boolean` ▶︎ false
Don't convert the _hover_ event to _click_ on mobile.
**event** `'hover' | 'click'` ▶︎ click
The event that will trigger the Floater.
> This won't work in a controlled mode.
**eventDelay** `number` ▶︎ 0.4
The amount of time (in seconds) the floater should wait after a `mouseLeave` event before hiding.
> Only valid for event type `hover`.
**footer** `ReactNode`
It can be anything that can be rendered.
**getPopper** `(popper: PopperInstance, origin: 'floater' | 'wrapper') => void`
Get the popper.js instance.
**hideArrow** `boolean` ▶︎ false
Don't show the arrow. Useful for centered or modal layout.
**offset** `number` ▶︎ 15
The distance between the Floater and its target in pixels.
**open** `boolean`
The switch between normal and controlled modes.
> Setting this prop will disable normal behavior.
**modifiers** `PopperModifiers`
Customize popper.js modifiers.
Type Definition
```typescript
interface PopperModifiers {
applyStyles?: Partial;
arrow?: Partial;
computeStyles?: Partial;
eventListeners?: Partial;
flip?: Partial;
hide?: Partial;
offset?: Partial;
popperOffsets?: Partial;
preventOverflow?: Partial;
}
```
> Don't use it unless you know what you're doing
**placement** `Placement` ▶︎ `bottom`
The placement of the Floater. It will update the position if there's no space available.
Type Definition
```typescript
type Placement =
| "auto" | "auto-start" | "auto-end"
| "top" | "top-start" | "top-end"
| "bottom" | "bottom-start" | "bottom-end"
| "right"| "right-start" | "right-end"
| "left" | "left-start" | "left-end"
| "center"
```
**portalElement** `string|HTMLElement`
A css selector or element to render the tooltips
**showCloseButton** `boolean` ▶︎ false
It will show a ⨉ button to close the Floater.
This will be `true` when you change the `wrapperOptions` position.
**styles** `Styles`
Customize the UI.
Type Definition
```typescript
interface Styles {
arrow: CSSProperties & {
length: number;
spread: number;
};
close: CSSProperties;
container: CSSProperties;
content: CSSProperties;
floater: CSSProperties;
floaterCentered: CSSProperties;
floaterClosing: CSSProperties;
floaterOpening: CSSProperties;
floaterWithAnimation: CSSProperties;
floaterWithComponent: CSSProperties;
footer: CSSProperties;
options: {
zIndex: number;
};
title: CSSProperties;
wrapper: CSSProperties;
wrapperPosition: CSSProperties;
}
```
**target** `string | HTMLElement`
The target element to calculate the Floater position. It will use the children as the target if it's not set.
**title** `ReactNode`
It can be anything that can be rendered.
**wrapperOptions** `WrapperOptions`
Position the wrapper relative to the target.
_You need to set a `target` for this to work._
Type Definition
```typescript
interface WrapperOptions {
offset: number; // The distance between the wrapper and the target. It can be a negative value.
placement: string; // the same options as above, except center
position: bool; // Set to true to position the wrapper
}
```
## Styling
You can customize everything with the `styles` prop.
Only set the properties you want to change, and the default styles will be merged.
Check the [styles.ts](src/modules/styles.ts) for the syntax.
## Modes
**Default**
The wrapper will trigger the events and use itself as the Floater's target.
```tsx
click me
```
**Proxy**
The wrapper will trigger the events, but the Floater will use the **target** prop to position itself.
```tsx
click me
```
**Beacon**
It is the same as the **proxy mode,** but the wrapper will be positioned relative to the `target`.
```tsx
◉
```
**Controlled**
Setting a boolean to the open prop will enter the controlled mode and not respond to events.
In this mode, you don't even need to have `children`
```tsx
```