@lattice-ui/popper early positioning foundation
What It Is For
Use popper when you need low-level anchored positioning without adopting a higher-level overlay component.
It provides the geometry engine used by packages like Select, Popover, and Tooltip.
TSX Example Preview
Preview the first lines below, or expand to inspect the full source file.
import { computePopper } from "@lattice-ui/popper";
export function PopperExample() {
const result = computePopper({
anchorPosition: new Vector2(180, 60),
anchorSize: new Vector2(160, 40),
...import { computePopper } from "@lattice-ui/popper";
export function PopperExample() {
const result = computePopper({
anchorPosition: new Vector2(180, 60),
anchorSize: new Vector2(160, 40),
contentSize: new Vector2(220, 120),
viewportRect: new Rect(0, 0, 800, 600),
placement: "bottom",
offset: new Vector2(0, 8),
padding: 12,
});
return (
<frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 220)}>
<frame
BackgroundColor3={Color3.fromRGB(53, 104, 196)}
BorderSizePixel={0}
Position={UDim2.fromOffset(180, 60)}
Size={UDim2.fromOffset(160, 40)}
>
<uicorner CornerRadius={new UDim(0, 8)} />
</frame>
<frame
BackgroundColor3={Color3.fromRGB(34, 41, 54)}
BorderSizePixel={0}
Position={result.position}
Size={UDim2.fromOffset(220, 120)}
>
<uicorner CornerRadius={new UDim(0, 10)} />
</frame>
<textlabel
BackgroundTransparency={1}
Position={UDim2.fromOffset(0, 0)}
Size={UDim2.fromOffset(400, 42)}
Text={`Resolved placement: ${result.placement} | x=${result.position.X.Offset} y=${result.position.Y.Offset}`}
TextColor3={Color3.fromRGB(236, 240, 248)}
TextSize={14}
TextWrapped={true}
TextXAlignment={Enum.TextXAlignment.Left}
TextYAlignment={Enum.TextYAlignment.Top}
/>
</frame>
);
}Install
Global CLI command: lattice add popper
Monorepo local script
Use your package manager wrapper when running the local lattice command.
pnpm lattice add popperPublic Exports
-
computePopper -
usePopper
State Model
- There is no shared React context;
usePopperderives position directly fromanchorRef,contentRef, and geometric inputs. placement,offset, andpaddingare the core variables that influence the computed result.- The returned model is just
position,anchorPoint, and the resolved placement plus anupdate()function.
Key API
usePopper
Use anchorRef, contentRef, placement, offset, padding, and enabled for live anchored positioning in a component tree.
computePopper
Use the pure compute helper when you need the same geometry logic outside a hook-driven surface.
PopperPlacement
Current placement options are top, bottom, left, and right.
Composition Patterns
Custom anchored overlays
Pair usePopper with Portal or your own mount strategy when you want positioning but not the rest of a compound overlay package.
Measured content surfaces
Use the update() function when geometry needs to be recomputed after layout or content changes.
Cautions / Limits
- Popper solves positioning only; it does not manage dismissal, focus, portals, or presence.
- If anchored content animates, keep motion on an isolated wrapper so placement measurement remains authoritative.
- The public placement model is intentionally small, so build more complex policies above it rather than expecting full menu-like behavior from the package alone.