Tether Documentation

Tethers may fail to position correctly if the target or the element is display: none or not yet in the DOM.

To resolve this, you can:

1. Ensure a position call happens after layouts have finished using setTimeout.
2. Create the Tether with the enabled: false option, and then enable it once the elements are visible and in the DOM.

myElement.style.display = 'block'

tether = new Tether({ ... })

setTimeout(function(){
  tether.position();
})

Tether provides several basic use cases to help you get started:

• simple: A basic implementation to understand core tethering.
• out-of-bounds: Techniques for hiding an element when it would otherwise be positioned offscreen.
• pin: How to pin an element so it remains visible and never goes offscreen.
• enable-disable: How to programmatically enable and disable Tethering using JavaScript.

Tether provides a module system to modify positioning or execute logic whenever a Tether instance moves. To add a module, push an object containing module lifecycle methods onto the Tether.modules array.

Tether.modules.push
  position: ({top, left}) ->
    top += 10

    {top, left}

For complex positioning requirements, Tether offers advanced patterns:

• content-visible: Uses the 'visible' targetModifier to align an element with the visible portion of a target.
• dolls: A performance test involving multiple elements tethered in a chain (each tethered to the previous).
• element-scroll: Uses the 'scroll-handle' targetModifier to align an element with the scrollbar of a specific element.
• scroll: Uses the 'scroll-handle' targetModifier to align an element with the body's scroll handle.
• viewport: Aligns an element with the viewport by using the 'visible' targetModifier while tethered to the body.

To prevent CSS class collisions when embedding Tether into another library, you should customize the generated class names.

Use the classPrefix option to provide a custom prefix. This prefix will replace the default 'tether' string in all generated classes. Additionally, you can use the classes option to disable specific classes that your implementation does not require.

Tether includes optimizations for performance and smoothness. You can control these via the optimizations object:

• moveElement: (Boolean) If true, Tether may move the element's DOM node inside its scroll parent to avoid repaints. For this to work best, the scroll parent should be position: relative, fixed, or absolute. Set to false to disable.
• gpu: (Boolean) If true, Tether uses CSS transforms for positioning to allow the element to move on its own layer. If you experience color shifts or artifacts, set this to false.

new Tether({
  element: yellowBox,
  target: greenBox,
  optimizations: {
    moveElement: false,
    gpu: false
  }
});

Tether provides six built-in attachment positions. You can specify these for both the element and the target. If targetAttachment is omitted, it defaults to the mirror image of attachment.

Available positions:

• left
• center
• right
• top
• middle
• bottom

Example usage:

new Tether({
  element: yellowBox,
  target: greenBox,
  attachment: 'middle center',
  targetAttachment: 'middle center'
});

Tether extends an Evented class, allowing you to listen to the following events:

• repositioned: Fired whenever the tethered element is moved.
• update: Fired whenever the Tether instance runs into a constraint (useful for manual UI tweaks like flipping arrows).