# react-tether

> A positioning engine to make overlays, tooltips and dropdowns better

Latest version **3.0.3** (published 2023-10-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-tether
pnpm add react-tether
yarn add react-tether
bun add react-tether
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2023-10-10 |
| First published | 2015-11-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 84.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 387 |
| Author | Dan Reeves |
| Maintainers | danreeves, souporserious |
| Keywords | react, react-tether, tether, component, drop |

## Links

- npm: https://www.npmjs.com/package/react-tether
- Repository: https://github.com/danreeves/react-tether
- Issues: https://github.com/danreeves/react-tether/issues
- npm.io page: https://npm.io/package/react-tether

## Dependencies (2)

- [tether](https://npm.io/package/tether.md) ^1.4.7
- [@types/tether](https://npm.io/package/@types/tether.md) ^1.4.6

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 3.0.3 (latest) — 2023-10-10
- 3.0.2 — 2023-10-10
- 3.0.1 — 2022-09-29
- 3.0.0 — 2022-09-16
- 2.0.8 — 2021-05-05
- 2.0.7 — 2020-01-13
- 2.0.6 — 2019-12-04
- 2.0.5 — 2019-10-29
- 1.0.5 — 2019-10-29
- 2.0.4 — 2019-09-10
- 2.0.3 — 2019-05-07
- 2.0.2 — 2019-04-24
- 2.0.1 — 2019-03-22
- 2.0.0 — 2019-01-11
- 1.0.4 — 2018-11-17
- … 22 more at https://npm.io/package/react-tether/versions

## README

# React Tether

![CI Status](https://github.com/danreeves/react-tether/actions/workflows/main.yml/badge.svg)
[![Sauce Test Status](https://app.saucelabs.com/buildstatus/react-tether)](https://app.saucelabs.com/u/react-tether)

> Cross-browser Testing Platform and Open Source <3 Provided by [Sauce Labs](https://saucelabs.com/).

---

React wrapper around [Tether](https://github.com/shipshapecode/tether), a positioning engine to make overlays, tooltips and dropdowns better

![React Tether](images/tether-header.png)

## Install

`npm install react-tether`

**As of version 2, a minimum of React 16.3 is required. If you need support for React < 16.3 please use the [1.x branch](https://github.com/danreeves/react-tether/tree/1.x).**

## Example Usage

```javascript
import TetherComponent from "react-tether";

class SimpleDemo extends React.Component {
	constructor(props) {
		super(props);
		this.state = {
			isOpen: false,
		};
	}

	render() {
		const { isOpen } = this.state;

		return (
			<TetherComponent
				attachment="top center"
				constraints={[
					{
						to: "scrollParent",
						attachment: "together",
					},
				]}
				/* renderTarget: This is what the item will be tethered to, make sure to attach the ref */
				renderTarget={(ref) => (
					<button
						ref={ref}
						onClick={() => {
							this.setState({ isOpen: !isOpen });
						}}
					>
						Toggle Tethered Content
					</button>
				)}
				/* renderElement: If present, this item will be tethered to the the component returned by renderTarget */
				renderElement={(ref) =>
					isOpen && (
						<div ref={ref}>
							<h2>Tethered Content</h2>
							<p>A paragraph to accompany the title.</p>
						</div>
					)
				}
			/>
		);
	}
}
```

## Props

#### `renderTarget`: PropTypes.func

This is a [render prop](https://reactjs.org/docs/render-props.html), the component returned from this function will be Tether's `target`. One argument, ref, is passed into this function. This is a ref that must be attached to the highest possible DOM node in the tree. If this is not done the element will not render.

#### `renderElement`: PropTypes.func

This is a [render prop](https://reactjs.org/docs/render-props.html), the component returned from this function will be Tether's `element`, that will be moved. If no component is returned, the target will still render, but with no element tethered. One argument, ref, is passed into this function. This is a ref that must be attached to the highest possible DOM node in the tree. If this is not done the element will not render.

#### `renderElementTag`: PropTypes.string

The tag that is used to render the Tether element, defaults to `div`.

#### `renderElementTo`: PropTypes.string

Where in the DOM the Tether element is appended. Passes in any valid selector to `document.querySelector`. Defaults to `document.body`.

Tether requires this element to be `position: static;`, otherwise it will default to `document.body`. See [this example](https://danreeves.github.io/react-tether/tests/renderelementto/) for more information.

#### `Tether Options`:

Any valid [Tether options](https://tetherjs.dev/#usage).

#### `children`:

Previous versions of react-tether used children to render the target and component, using children will now throw an error. Please use renderTarget and renderElement instead

## Imperative API

The following methods are exposed on the component instance:

- `getTetherInstance(): Tether`
- `disable(): void`
- `enable(): void`
- `on(event: string, handler: function, ctx: any): void`
- `once(event: string, handler: function, ctx: any): void`
- `off(event: string, handler: function): void`
- `position(): void`

#### Example usage:

```javascript
<TetherComponent
	ref={(tether) => (this.tether = tether)}
	renderTarget={(ref) => <Target ref={ref} />}
	renderElement={(ref) => (
		<Element ref={ref} onResize={() => this.tether && this.tether.position()} />
	)}
/>
```

## Run Example

clone repo

`git clone git@github.com:danreeves/react-tether.git`

move into folder

`cd ~/react-tether`

install dependencies

`npm install`

run dev mode

`npm run demo`

open your browser and visit: `http://localhost:1234/`

---
_Source: https://npm.io/package/react-tether · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._