joshwooding/floating-ui

Powerful positioning primitives

Floating UI is a low-level library for positioning "floating" elements like tooltips, popovers, dropdowns, menus and more. Since these types of elements float on top of the UI without disrupting the flow of content, challenges arise when positioning them.

Floating UI exposes primitives which enable a floating element to be positioned next to a given reference element while appearing in view for the user as best as possible. Features include overflow prevention (or collision awareness), placement flipping, and more.

Tiny: 600-byte core with highly modular architecture for tree-shaking
Low-level: Hyper-granular control over positioning behavior
Pure: Predictable, side-effect free behavior
Extensible: Powerful middleware system
Platform-agnostic: Runs on any JavaScript environment which provides measurement APIs, including the web and React Native

Installation

To use it on the web:

npm install @floating-ui/dom

yarn add @floating-ui/dom

Quick start

import {computePosition} from '@floating-ui/dom';

const referenceElement = document.querySelector('#button');
const floatingElement = document.querySelector('#tooltip');

function applyStyles({x = 0, y = 0, strategy = 'absolute'}) {
  Object.assign(floatingElement.style, {
    position: strategy,
    left: `${x}px`,
    top: `${y}px`,
  });
}

applyStyles();

computePosition(referenceElement, floatingElement, {
  placement: 'right',
}).then(applyStyles);

Visit the docs for detailed information.

React

React DOM
React Native (*experimental)

Components

Right now, Floating UI focuses on positioning floating elements, but a package that exposes higher-level primitives for building these elements more easily is in development.

Inspiration

Floating UI is an evolution of libraries in this space like Popper and Tether, developed by the co-author of the former and creator of Tippy.js. Much of the code is forked from Popper 2's codebase and adapted to the new API.

Contributing

This project a monorepo written in TypeScript using npm workspaces. The website is using Next.js SSG and Tailwind CSS for styling.

Clone the repo
Install dependencies in root directory with npm install
npm run dev in the root will launch the @floating-ui/dom development visual tests at http://localhost:1234/spec. You can fiddle around with each test file in packages/dom/test/visual/spec/. Reload the page to see your changes.

License

MIT

joshwooding / floating-ui