A lightweight, flexible React component for positioning floating elements (tooltips, dropdowns, popovers) with built-in portal support and arrow positioning. Specifically implemented to solve the Headless UI portal issue where dropdowns and popovers need to be rendered in specific containers rather than the default document.body.
- 🌐 Portal Support: Render Headless UI floating elements in any DOM container by determining container portal
- ♿ Accessible: You have Accessibility of Headless UI un hurt
- 📦 Lightweight: Uses Floating UI that Headless UI uses internally
npm install react-uni-popper
# or
yarn add react-uni-popper
# or
pnpm add react-uni-popperimport React, { useRef, useState } from 'react';
import ReactUniPopper from 'react-uni-popper';
function TooltipExample() {
const [isOpen, setIsOpen] = useState(false);
const buttonRef = useRef<HTMLButtonElement>(null);
return (
<div>
<button
ref={buttonRef}
onMouseEnter={() => setIsOpen(true)}
onMouseLeave={() => setIsOpen(false)}
>
Hover me
</button>
{isOpen && (
<ReactUniPopper
reference={buttonRef.current}
placement="top"
offset={8}
arrow
arrowSize={8}
>
<div className="bg-gray-900 text-white px-3 py-2 rounded text-sm">
This is a tooltip!
</div>
</ReactUniPopper>
)}
</div>
);
}| Prop | Type | Default | Description |
|---|---|---|---|
reference |
HTMLElement | null |
required | The reference element to position relative to |
children |
ReactNode | RenderFunction |
required | Content to render or render function |
placement |
PositionType |
'bottom' |
Preferred placement direction |
offset |
number |
4 |
Distance between reference and floating element |
arrow |
boolean |
false |
Whether to show positioning arrow |
arrowSize |
number |
8 |
Size of the arrow in pixels |
portalContainer |
HTMLElement |
document.body |
Container to render the portal in |
zIndex |
number |
undefined |
CSS z-index value |
type PositionType =
| 'top'
| 'right'
| 'bottom'
| 'left'
| 'top-start'
| 'top-end'
| 'right-start'
| 'right-end'
| 'bottom-start'
| 'bottom-end'
| 'left-start'
| 'left-end';The children prop can be a render function that receives positioning data:
<ReactUniPopper reference={ref} arrow>
{({ placement, arrowStyles, floatingStyles, arrowRef }) => (
<div style={floatingStyles} className="tooltip">
Content here
{arrow && <div ref={arrowRef} style={arrowStyles} className="arrow" />}
</div>
)}
</ReactUniPopper>This package is specifically designed to solve portal issues with Headless UI components. Here are examples of how to integrate it with various Headless UI components:
import React, { useMemo, useRef, useState } from 'react';
import {
Listbox,
ListboxButton,
ListboxOption,
ListboxOptions,
ListboxProps,
} from '@headlessui/react';
import ReactUniPopper from 'react-uni-popper';
interface SelectOption {
name: string;
value: string | number;
className?: string;
disabled?: boolean;
}
interface SelectProps extends Omit<ListboxProps<any>, 'children'> {
options: SelectOption[];
renderOption?: (option: SelectOption) => React.ReactNode;
popperClassName?: string;
portalContainer?: HTMLElement;
}
function Select({
options,
className,
value,
renderOption,
popperClassName,
portalContainer = document.body,
...props
}: SelectProps) {
const selectedValue = !value ? options[0].value : value;
const selectedOption = options.find(
(option) => option.value === selectedValue,
);
const buttonRef = useRef<HTMLButtonElement>(null);
return (
<Listbox value={selectedValue} onChange={props.onChange}>
{({ open }) => (
<>
<ListboxButton
ref={buttonRef}
className={`flex h-9 min-h-9 w-full items-center justify-between text-nowrap rounded-lg border border-gray-300 bg-white px-4 text-sm text-gray-700 ${className || ''}`}
>
{selectedOption?.name}
<svg
className="w-4 h-4"
fill="none"
stroke="currentColor"
viewBox="0 0 24 24"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={2}
d="M19 9l-7 7-7-7"
/>
</svg>
</ListboxButton>
{open && (
<ReactUniPopper
reference={buttonRef.current}
portalContainer={portalContainer}
zIndex={1300}
placement="bottom-start"
offset={4}
>
<ListboxOptions
style={{
width: buttonRef.current?.offsetWidth,
}}
className={`max-h-60 overflow-auto rounded-lg border bg-white shadow-lg ${popperClassName || ''}`}
>
{options.map((option) => (
<ListboxOption
key={option.value}
className={`cursor-pointer text-nowrap px-4 py-2 text-sm font-medium text-gray-700 data-[focus]:bg-blue-100 ${option.className || ''}`}
disabled={option.disabled}
value={option.value}
>
{renderOption ? (
renderOption(option)
) : (
<span>{option.name}</span>
)}
</ListboxOption>
))}
</ListboxOptions>
</ReactUniPopper>
)}
</>
)}
</Listbox>
);
}
export default Select;import React, { useRef, useState } from 'react';
import {
Combobox,
ComboboxButton,
ComboboxInput,
ComboboxOption,
ComboboxOptions,
ComboboxProps,
} from '@headlessui/react';
import ReactUniPopper from 'react-uni-popper';
interface ComboboxOption {
name: string;
value: string | number;
className?: string;
disabled?: boolean;
}
interface CustomComboboxProps extends Omit<ComboboxProps<any>, 'children'> {
options: ComboboxOption[];
renderOption?: (option: ComboboxOption) => React.ReactNode;
popperClassName?: string;
portalContainer?: HTMLElement;
}
function CustomCombobox({
options,
className,
value,
onChange,
renderOption,
popperClassName,
portalContainer = document.body,
...props
}: CustomComboboxProps) {
const [query, setQuery] = useState('');
const buttonRef = useRef<HTMLDivElement>(null);
const filteredOptions =
query === ''
? options
: options.filter((option) =>
option.name.toLowerCase().includes(query.toLowerCase()),
);
return (
<Combobox value={value} onChange={onChange}>
{({ open }) => (
<>
<div ref={buttonRef} className="relative">
<ComboboxInput
className={`w-full rounded-lg border border-gray-300 bg-white px-4 py-2 text-sm text-gray-700 ${className || ''}`}
onChange={(event) => setQuery(event.target.value)}
displayValue={(option: ComboboxOption) => option?.name}
/>
<ComboboxButton className="absolute inset-y-0 right-0 flex items-center pr-2">
<svg
className="w-4 h-4"
fill="none"
stroke="currentColor"
viewBox="0 0 24 24"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={2}
d="M19 9l-7 7-7-7"
/>
</svg>
</ComboboxButton>
</div>
{open && (
<ReactUniPopper
reference={buttonRef.current}
portalContainer={portalContainer}
zIndex={1300}
placement="bottom-start"
offset={4}
>
<ComboboxOptions
className={`max-h-60 overflow-auto rounded-lg border bg-white shadow-lg ${popperClassName || ''}`}
>
{filteredOptions.map((option) => (
<ComboboxOption
key={option.value}
className={`cursor-pointer px-4 py-2 text-sm font-medium text-gray-700 data-[focus]:bg-blue-100 ${option.className || ''}`}
disabled={option.disabled}
value={option}
>
{renderOption ? (
renderOption(option)
) : (
<span>{option.name}</span>
)}
</ComboboxOption>
))}
</ComboboxOptions>
</ReactUniPopper>
)}
</>
)}
</Combobox>
);
}
export default CustomCombobox;import React, { useRef, useState } from 'react';
import {
Menu,
MenuButton,
MenuItem,
MenuItems,
MenuProps,
} from '@headlessui/react';
import ReactUniPopper from 'react-uni-popper';
interface MenuOption {
name: string;
value: string | number;
onClick?: () => void;
className?: string;
disabled?: boolean;
}
interface CustomDropdownProps extends Omit<MenuProps<any>, 'children'> {
options: MenuOption[];
renderOption?: (option: MenuOption) => React.ReactNode;
popperClassName?: string;
portalContainer?: HTMLElement;
buttonContent?: React.ReactNode;
}
function CustomDropdown({
options,
renderOption,
popperClassName,
portalContainer = document.body,
buttonContent = 'Open Menu',
...props
}: CustomDropdownProps) {
const buttonRef = useRef<HTMLButtonElement>(null);
return (
<Menu>
{({ open }) => (
<>
<MenuButton
ref={buttonRef}
className="flex h-9 min-h-9 items-center justify-between rounded-lg border border-gray-300 bg-white px-4 text-sm text-gray-700"
>
{buttonContent}
<svg
className="w-4 h-4"
fill="none"
stroke="currentColor"
viewBox="0 0 24 24"
>
<path
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={2}
d="M19 9l-7 7-7-7"
/>
</svg>
</MenuButton>
{open && (
<ReactUniPopper
reference={buttonRef.current}
portalContainer={portalContainer}
zIndex={1300}
placement="bottom-start"
offset={4}
>
<MenuItems
className={`min-w-48 rounded-lg border bg-white shadow-lg p-2 ${popperClassName || ''}`}
>
{options.map((option) => (
<MenuItem
key={option.value}
disabled={option.disabled}
className={`cursor-pointer rounded px-3 py-2 text-sm font-medium text-gray-700 data-[focus]:bg-blue-100 ${option.className || ''}`}
onClick={option.onClick}
>
{renderOption ? (
renderOption(option)
) : (
<span>{option.name}</span>
)}
</MenuItem>
))}
</MenuItems>
</ReactUniPopper>
)}
</>
)}
</Menu>
);
}
export default CustomDropdown;The component renders with a headless-popper class for custom styling:
.headless-popper {
/* Your custom styles */
}
.headless-popper .arrow {
/* Arrow styles */
position: absolute;
width: 8px;
height: 8px;
background: inherit;
transform: rotate(45deg);
}- React 16.8+ (hooks support required)
- Modern browsers with ES6+ support
- IE11+ with polyfills
MIT
Contributions are welcome! Please feel free to submit a Pull Request.