# Tether

The Tether library makes it possible to visually maintain the position of an element next to another regardless of source-order or changes to the viewport.

## Examples

Javascript

```
import Tether from 'dom/Tether'

const tether = new Tether(referenceElem, elem)
```

or

```
import Tether from 'dom/Tether'

Tether.toggle(referenceElem, elem, () => {...})
```

## Custom CSS Properties

| Name          | Description                                           |
| ------------- | ----------------------------------------------------- |
| `--Tether-rh` | Height (in pixels) of the reference element.          |
| `--Tether-rl` | Left coordinate (in pixels) of the reference element. |
| `--Tether-rt` | Top coordinate (in pixels) of the reference element.  |
| `--Tether-rw` | Width (in pixels) of the reference element.           |

## Attributes

| Name             | Values              | Description                                                                                                                                                                          |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-tether-rx` | `l`, `r` (readonly) | Indicates the tether placement on the x-axis relative to the reference. `l` means "left", or, to the left of the reference and `r` means "right", or, to the right of the reference. |
| `data-tether-ry` | `b`, `t` (readonly) | Indicates the tether placement on the y-axis relative to the reference. `b` means "bottom", or, below the reference and `t` means "top", or, above the reference.                    |

## Properties

| Name        | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `element`   | Returns the Tethered dom element.                                 |
| `reference` | Returns the reference dom element which `element` is tethered to. |

## Methods

| Name        | Description                 |
| ----------- | --------------------------- |
| `destroy()` | Destroys the Tether layout. |

## Static Properties

| Name             | Description                                 |
| ---------------- | ------------------------------------------- |
| `Tether.toggles` | Returns a Map of all Tether toggle objects. |

## Static Methods

| Name                                        | Params                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tether.getReference(element)`              | `element`: DOMElement                                                           | Returns the reference dom element which the provided element is tethered to.                                                                                                                                                                                                                                                                                                                                               |
| `Tether.toggle(reference, element, toggle)` | `reference`: DOMElement, `element`: DOMElement, `toggle`: A function or boolean | Handles toggling between creating a new tether or destroying one. Also handles how to auto-close the tethered element when an outside click occurs. If the `toggle` argument is a boolean then the Tether class will either create a new tether (true) or destroy and existing tether (false). If the argument is a function then it must return a boolean and it is used to toggle in the same manner as described above. |
