Popover - Skeleton

Floating UI React

Floating UI →

Floating UI React →

Floating UI provides primitives for creating tooltips, popovers, dropdown menus, hover cards, modal dialogs, select menus, comboboxes, and more. Instead of providing pre-built components, this guide will introduce the fundamentals of Floating UI React. This provides an open-ended solution for creating your own popover features and components for any form factor - while pairing with Skeleton’s design system and components.

Learn the Basics

If this is your first time using Floating UI, start here:

Floating UI Tutorial - covers the basics of using native Javascript.
Floating UI React Tutorial - covers the basics of using the React wrapper.

Imports

Floating UI React exposes all required Floating UI middleware, types, etc.

import { useFloating } from '@floating-ui/react';

Making Elements Float

You’ll need a dedicated CSS class to apply common styles to all floating elements. Apply the following in your global stylesheet. We’ll use the following class convention for all Skeleton examples.

.floating {
  width: max-content;
  position: absolute;
  top: 0;
  left: 0;
}

Z-Index Stacking

Please be aware that Floating UI does not take an opinionated stance on z-index stacking. This means that if a floating element is occluded by another element in the z-axis, you must handle this directly.

Middleware

Make sure you’re familiar all available Floating UI Middleware, which provides modules for customizing the look and feel of popovers.

Examples

Floating UI React provides an extensive set of headless React examples. We’ll use these as the foundation for at the following set of examples that fully integrate Skeleton. See the official Floating UI React documentation for a complete API Reference.

Triggers an anchored popover when you click the trigger element.

// Based On: https://floating-ui.com/docs/popover

import React, { useRef, useState } from 'react';
import {
	useFloating,
	autoUpdate,
	offset,
	flip,
	shift,
	arrow,
	useClick,
	useDismiss,
	useRole,
	useInteractions,
	FloatingFocusManager,
	FloatingArrow
} from '@floating-ui/react';
import { X as IconX } from 'lucide-react';

export const Page: React.FC = () => {
	const [isOpen, setIsOpen] = useState(false);

	const arrowRef = useRef(null);
	const { refs, floatingStyles, context } = useFloating({
		open: isOpen,
		onOpenChange: setIsOpen,
		middleware: [
			offset(10),
			flip(),
			shift(),
			arrow({
				element: arrowRef
			})
		],
		placement: 'top',
		whileElementsMounted: autoUpdate
	});

	const click = useClick(context);
	const dismiss = useDismiss(context);
	const role = useRole(context);

	const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss, role]);

	return (
		<>
			{/* Trigger */}
			<button ref={refs.setReference} {...getReferenceProps()} className="btn preset-tonal">
				Click Me
			</button>
			{isOpen && (
				<FloatingFocusManager context={context} modal={false}>
					{/* Popover */}
					{/* Note the use of the `.floating` class here */}
					<div
						ref={refs.setFloating}
						style={floatingStyles}
						className="floating card bg-surface-200-800 p-4 max-w-[320px]"
						{...getFloatingProps()}
					>
						<div className="space-y-4">
							<header className="flex justify-between">
								<p className="font-bold type-scale-5">Popover Example</p>
								<button className="btn-icon hover:preset-tonal" onClick={() => setIsOpen(false)}>
									<IconX />
								</button>
							</header>
							<article>
								<p className="opacity-60">
									This will display a basic popover with a header and body. This also includes a title, description, and close button.
								</p>
							</article>
						</div>
						{/* Arrow */}
						<FloatingArrow ref={arrowRef} context={context} className="fill-surface-200-800" />
					</div>
				</FloatingFocusManager>
			)}
		</>
	);
};

Triggers an anchored popover when you hover the trigger element.

// Based On: https://floating-ui.com/docs/tooltip

import React, { useState } from 'react';
import { useFloating, autoUpdate, offset, flip, shift, useHover, useFocus, useDismiss, useRole, useInteractions } from '@floating-ui/react';

export const Page: React.FC = () => {
	const [isOpen, setIsOpen] = useState(false);

	const { refs, floatingStyles, context } = useFloating({
		open: isOpen,
		onOpenChange: setIsOpen,
		middleware: [offset(10), flip(), shift()],
		placement: 'top',
		whileElementsMounted: autoUpdate
	});

	const hover = useHover(context, { move: false });
	const focus = useFocus(context);
	const dismiss = useDismiss(context);
	const role = useRole(context, { role: 'tooltip' });

	const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);

	return (
		<>
			{/* Trigger */}
			<button ref={refs.setReference} {...getReferenceProps()} className="underline">
				Hover Me
			</button>
			{/* Tooltip */}
			{isOpen && (
				<div ref={refs.setFloating} style={floatingStyles} className="floating card preset-filled p-4" {...getFloatingProps()}>
					This is a tooltip.
				</div>
			)}
		</>
	);
};

Combobox

Triggers an anchored popover list on search. Includes autocomplete with automatic selection.

// Based On: https://codesandbox.io/p/sandbox/fragrant-water-bsuirj?file=%2Fsrc%2FApp.tsx%3A1%2C1-168%2C2

import { forwardRef, useRef, useState } from 'react';
import {
	autoUpdate,
	size,
	offset,
	flip,
	useId,
	useDismiss,
	useFloating,
	useInteractions,
	useListNavigation,
	useRole,
	FloatingFocusManager,
	FloatingPortal
} from '@floating-ui/react';

// prettier-ignore
const data = [
	"Alfalfa Sprouts", "Apple", "Apricot", "Artichoke", "Asian Pear", "Asparagus", "Atemoya", "Avocado", "Bamboo Shoots", "Banana", "Bean Sprouts", "Beans", "Beets", "Belgian Endive", "Bell Peppers", "Bitter Melon", "Blackberries", "Blueberries", "Bok Choy", "Boniato", "Boysenberries", "Broccoflower", "Broccoli", "Brussels Sprouts", "Cabbage", "Cactus Pear", "Cantaloupe", "Carambola", "Carrots", "Casaba Melon", "Cauliflower", "Celery", "Chayote", "Cherimoya", "Cherries", "Coconuts", "Collard Greens", "Corn", "Cranberries", "Cucumber", "Dates", "Dried Plums", "Eggplant", "Endive", "Escarole", "Feijoa", "Fennel", "Figs", "Garlic", "Gooseberries", "Grapefruit", "Grapes", "Green Beans", "Green Onions", "Greens", "Guava", "Hominy", "Honeydew Melon", "Horned Melon", "Iceberg Lettuce", "Jerusalem Artichoke", "Jicama", "Kale", "Kiwifruit", "Kohlrabi", "Kumquat", "Leeks", "Lemons", "Lettuce", "Lima Beans", "Limes", "Longan", "Loquat", "Lychee", "Madarins", "Malanga", "Mandarin Oranges", "Mangos", "Mulberries", "Mushrooms", "Napa", "Nectarines", "Okra", "Onion", "Oranges", "Papayas", "Parsnip", "Passion Fruit", "Peaches", "Pears", "Peas", "Peppers", "Persimmons", "Pineapple", "Plantains", "Plums", "Pomegranate", "Potatoes", "Prickly Pear", "Prunes", "Pummelo", "Pumpkin", "Quince", "Radicchio", "Radishes", "Raisins", "Raspberries", "Red Cabbage", "Rhubarb", "Romaine Lettuce", "Rutabaga", "Shallots", "Snow Peas", "Spinach", "Sprouts", "Squash", "Strawberries", "String Beans", "Sweet Potato", "Tangelo", "Tangerines", "Tomatillo", "Tomato", "Turnip", "Ugli Fruit", "Water Chestnuts", "Watercress", "Watermelon", "Waxed Beans", "Yams", "Yellow Squash", "Yuca/Cassava", "Zucchini Squash"
];

interface ItemProps {
	children: React.ReactNode;
	active: boolean;
}

/** Component: Option */
const Item = forwardRef<HTMLDivElement, ItemProps & React.HTMLProps<HTMLDivElement>>(function Item({ children, active, ...rest }, ref) {
	const id = useId();
	return (
		<div
			ref={ref}
			role="option"
			id={id}
			aria-selected={active}
			{...rest}
			style={{ ...rest.style }}
			className="btn justify-start w-full hover:preset-tonal cursor-pointer"
		>
			{children}
		</div>
	);
});

/** Component: Autocomplete */
function AutoComplete() {
	const [open, setOpen] = useState(false);
	const [inputValue, setInputValue] = useState('');
	const [activeIndex, setActiveIndex] = useState<number | null>(null);

	const listRef = useRef<Array<HTMLElement | null>>([]);

	const { refs, floatingStyles, context } = useFloating<HTMLInputElement>({
		whileElementsMounted: autoUpdate,
		open,
		onOpenChange: setOpen,
		middleware: [
			offset(10),
			flip({ padding: 10 }),
			size({
				apply({ rects, availableHeight, elements }) {
					Object.assign(elements.floating.style, {
						width: `${rects.reference.width}px`,
						maxHeight: `${availableHeight}px`
					});
				},
				padding: 10
			})
		]
	});

	const role = useRole(context, { role: 'listbox' });
	const dismiss = useDismiss(context);
	const listNav = useListNavigation(context, {
		listRef,
		activeIndex,
		onNavigate: setActiveIndex,
		virtual: true,
		loop: true
	});

	const { getReferenceProps, getFloatingProps, getItemProps } = useInteractions([role, dismiss, listNav]);

	function onChange(event: React.ChangeEvent<HTMLInputElement>) {
		const value = event.target.value;
		setInputValue(value);

		if (value) {
			setOpen(true);
			setActiveIndex(0);
		} else {
			setOpen(false);
		}
	}

	const items = data.filter((item) => item.toLowerCase().startsWith(inputValue.toLowerCase()));

	return (
		<>
			<input
				{...getReferenceProps({
					ref: refs.setReference,
					onChange,
					value: inputValue,
					placeholder: 'Enter fruit',
					'aria-autocomplete': 'list',
					onKeyDown(event) {
						if (event.key === 'Enter' && activeIndex != null && items[activeIndex]) {
							setInputValue(items[activeIndex]);
							setActiveIndex(null);
							setOpen(false);
						}
					}
				})}
				className="input max-w-[300px]"
			/>
			<FloatingPortal>
				{open && (
					<FloatingFocusManager context={context} initialFocus={-1} visuallyHiddenDismiss>
						<div
							{...getFloatingProps({
								ref: refs.setFloating,
								style: { ...floatingStyles }
							})}
							className="card p-2 preset-outlined-surface-200-800 bg-surface-50-950 space-y-1 overflow-y-auto"
						>
							{items.length === 0 && <p className="opacity-60">No Results Found.</p>}
							{items.map((item, index) => (
								<Item
									key={item}
									{...getItemProps({
										key: item,
										ref(node) {
											listRef.current[index] = node;
										},
										onClick() {
											setInputValue(item);
											setOpen(false);
											refs.domReference.current?.focus();
										}
									})}
									active={activeIndex === index}
								>
									{item}
								</Item>
							))}
						</div>
					</FloatingFocusManager>
				)}
			</FloatingPortal>
		</>
	);
}

// Page Interface
export const Page: React.FC = () => {
	return <AutoComplete />;
};

Generates any form of modal or dialog that require a user’s immediate attention.

// Based On: https://floating-ui.com/docs/dialog

import React, { useState } from 'react';
import {
	useFloating,
	useClick,
	useDismiss,
	useRole,
	useInteractions,
	useId,
	FloatingOverlay,
	FloatingFocusManager,
	useTransitionStyles
} from '@floating-ui/react';

export const Page: React.FC = () => {
	const [isOpen, setIsOpen] = useState(false);

	const { refs, context } = useFloating({
		open: isOpen,
		onOpenChange: setIsOpen
	});

	// https://floating-ui.com/docs/useTransition#usetransitionstatus
	const { isMounted, styles } = useTransitionStyles(context, {
		duration: 200,
		initial: {
			opacity: 0,
			transform: 'translateY(50px)'
		}
	});

	const click = useClick(context);
	const dismiss = useDismiss(context, {
		outsidePressEvent: 'mousedown'
	});
	const role = useRole(context);

	const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss, role]);

	const labelId = useId();
	const descriptionId = useId();

	return (
		<>
			{/* Trigger */}
			<button ref={refs.setReference} {...getReferenceProps()} className="btn preset-tonal">
				Open Modal
			</button>
			{isMounted && (
				// Backdrop
				<FloatingOverlay
					lockScroll
					className="fixed top-0 left-0 right-0 bottom-0 z-[998] bg-surface-50/75 dark:bg-surface-950/75 backdrop-blur-sm flex justify-center items-center p-4"
				>
					<FloatingFocusManager context={context}>
						{/* Modal */}
						<div
							ref={refs.setFloating}
							aria-labelledby={labelId}
							aria-describedby={descriptionId}
							{...getFloatingProps()}
							className="card bg-surface-100-900 p-4 space-y-4 shadow-xl max-w-screen-sm"
							style={{
								...styles // Transition styles
							}}
						>
							<header className="flex justify-between">
								<h2 className="h2">Modal Example</h2>
							</header>
							<article>
								<p className="opacity-60">
									Lorem ipsum dolor sit amet consectetur adipisicing elit. Nam, ab adipisci. Libero cumque sunt quis error veritatis amet,
									expedita voluptatem. Quos repudiandae consequuntur voluptatem et dicta quas, reprehenderit velit excepturi?
								</p>
							</article>
							<footer className="flex justify-end gap-4">
								<button type="button" className="btn preset-tonal" onClick={() => setIsOpen(false)}>
									Cancel
								</button>
								<button type="button" className="btn preset-filled" onClick={() => setIsOpen(false)}>
									Confirm
								</button>
							</footer>
						</div>
					</FloatingFocusManager>
				</FloatingOverlay>
			)}
		</>
	);
};

Additional Tips

Reusable Components

See tips for convert the primitive examples above into reusable components in your local project.

Accessibility

When implementing popovers, make sure to account for accessibility and keyboard interactions. Floating UI React provides a number of hooks and components to help facilitate all requirements.

ARIA APG Patterns →

Native Browser APIs

Skeleton will always favor native browser APIs over third-party libraries such as Floating UI Svelte. The following is a list of current and upcoming incoming APIs we will aim to support in the future, but are not quite standardized cross-browser yet.