HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
PopoverView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA panel that opens next to its trigger and holds any content.StableSince 0.1.0OverlaysUsageimport'@fusion.dev/helix/popover'import'@fusion.dev/helix-headless/popover'Preview
API ReferenceRoothelix-popoverA panel that opens next to its trigger and holds any content.
PropTypeDescriptionanchorElement|stringDefault""The element the panel opens against, where that is not the trigger: its
id in the same document or shadow root, or the element itself. Left
empty, the panel opens against the trigger, or against the button whose
command opened it.arrowbooleanDefaultfalseDraws a point on the panel's edge facing the trigger.containerPaddingnumberHow close to the window's edges the panel may come, in pixels, when it
slides, shrinks or moves to the other side to fit. Left unset, it slides
and shrinks to 8 pixels from an edge and moves to the other side only
once it would cross one.crossOffsetnumberDefault0How far to slide the panel along the side it is on, in pixels: to the
right on the top or the bottom, and down on the left or the right.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.fallbackLabelstringDefault"Popover"The panel's name where nothing else names it: no label, no heading in
the panel, and no aria-labelledby on the host.flipbooleanDefaulttrueWhether the panel moves to the other side of the trigger when its own
side has no room. On by default. Write flip="false" to keep it on its
side, where it shrinks to fit, as React Aria's shouldFlip turns off.labelstringDefault""The panel's name, read by screen readers. Left empty, the first heading in
the panel names it, and then fallback-label.modalbooleanDefaultfalseKeeps Tab inside the panel while it is open, marks the panel
aria-modal, and hides the rest of the page from screen readers. A press
outside and Escape still close it.offsetnumberDefault4Space between the trigger and the panel, in pixels.openbooleanWhether the element is open.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"bottom-start"Preferred side.separation"plain"How the panel is set apart from the content under it.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The contents of the panel.triggerThe element that opens the panel.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventFired before it closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before it opens, and cancelable.toggleToggleEventFired after the panel opens or closes, with newState and oldState.
MethodTypeDescriptionhide() => voidCloses the panel and puts focus back on the trigger.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the panel.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionarrowThe point on the panel's edge facing the trigger, drawn with arrow.arrow-bottomAdded to arrow while the panel is below its trigger, with the point on the panel's top edge.arrow-leftAdded to arrow while the panel is left of its trigger, with the point on the panel's right edge.arrow-rightAdded to arrow while the panel is right of its trigger, with the point on the panel's left edge.arrow-topAdded to arrow while the panel is above its trigger, with the point on the panel's bottom edge.contentThe scrolling region inside the panel.surfaceThe panel.
CSS PropertyDescription--floating-anchor-inline-sizeThe trigger's width, written on the panel while it is open, as in min-inline-size: var(--floating-anchor-inline-size). Read it; a value set here is written over.--floating-available-block-sizeThe room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.--popover-arrow-sizeSize of the point drawn with arrow. Tooltip's point is the same size.--popover-border-colorColor of the panel's edge.--popover-border-widthWidth of the panel's edge. Defaults to --helix-border-floating, which is 0, so the panel stands out by its shadow unless your theme sets a width.--popover-inline-sizeWidth of the panel.--popover-max-block-sizeMaximum height of the panel before it scrolls.--popover-paddingSpace between the panel's edge and its contents.--popover-shadowShadow under the panel. Defaults to --helix-shadow-floating, because the panel can sit over any content.
Custom stateDescriptionaligned-endWhile the panel is aligned to the end of the side it sits on.aligned-startWhile the panel is aligned to the start of the side it sits on.enteringFrom the moment the panel shows until its entrance has finished.exitingFrom the moment the panel hides until its exit has finished.openWhile the popover is open.placed-bottomWhile the panel sits below its trigger.placed-leftWhile the panel sits to the left of its trigger.placed-rightWhile the panel sits to the right of its trigger.placed-topWhile the panel sits above its trigger.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-popoverA panel that opens next to its trigger and holds any content.
PropTypeDescriptionanchorElement|stringDefault""The element the panel opens against, where that is not the trigger: its
id in the same document or shadow root, or the element itself. Left
empty, the panel opens against the trigger, or against the button whose
command opened it.arrowbooleanDefaultfalseDraws a point on the panel's edge facing the trigger.containerPaddingnumberHow close to the window's edges the panel may come, in pixels, when it
slides, shrinks or moves to the other side to fit. Left unset, it slides
and shrinks to 8 pixels from an edge and moves to the other side only
once it would cross one.crossOffsetnumberDefault0How far to slide the panel along the side it is on, in pixels: to the
right on the top or the bottom, and down on the left or the right.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.fallbackLabelstringDefault"Popover"The panel's name where nothing else names it: no label, no heading in
the panel, and no aria-labelledby on the host.flipbooleanDefaulttrueWhether the panel moves to the other side of the trigger when its own
side has no room. On by default. Write flip="false" to keep it on its
side, where it shrinks to fit, as React Aria's shouldFlip turns off.labelstringDefault""The panel's name, read by screen readers. Left empty, the first heading in
the panel names it, and then fallback-label.modalbooleanDefaultfalseKeeps Tab inside the panel while it is open, marks the panel
aria-modal, and hides the rest of the page from screen readers. A press
outside and Escape still close it.offsetnumberDefault4Space between the trigger and the panel, in pixels.openbooleanWhether the element is open.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"bottom-start"Preferred side.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The contents of the panel.triggerThe element that opens the panel.
EventTypeDescriptionhelix-before-closeHelixBeforeCloseEventFired before it closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before it opens, and cancelable.toggleToggleEventFired after the panel opens or closes, with newState and oldState.
MethodTypeDescriptionhide() => voidCloses the panel and puts focus back on the trigger.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the panel.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionarrowThe point on the panel's edge facing the trigger, drawn with arrow.arrow-bottomAdded to arrow while the panel is below its trigger, with the point on the panel's top edge.arrow-leftAdded to arrow while the panel is left of its trigger, with the point on the panel's right edge.arrow-rightAdded to arrow while the panel is right of its trigger, with the point on the panel's left edge.arrow-topAdded to arrow while the panel is above its trigger, with the point on the panel's bottom edge.contentThe scrolling region inside the panel.surfaceThe panel.
CSS PropertyDescription--floating-anchor-inline-sizeThe trigger's width, written on the panel while it is open, as in min-inline-size: var(--floating-anchor-inline-size). Read it; a value set here is written over.--floating-available-block-sizeThe room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
Custom stateDescriptionaligned-endWhile the panel is aligned to the end of the side it sits on.aligned-startWhile the panel is aligned to the start of the side it sits on.enteringFrom the moment the panel shows until its entrance has finished.exitingFrom the moment the panel hides until its exit has finished.openWhile the popover is open.placed-bottomWhile the panel sits below its trigger.placed-leftWhile the panel sits to the left of its trigger.placed-rightWhile the panel sits to the right of its trigger.placed-topWhile the panel sits above its trigger.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCommandedA popover opened by a button through the command attributes.Default OpenA panel that is open when the page loads and stays closed once you dismiss it.EventsA panel anchored to its trigger, which sends events before it opens or closes and after.OffsetA popover set further from its trigger, to clear the trigger's focus ring.PlainA popover with no arrow and no fill, for content that brings its own.PreviewA panel anchored to what opened it.PreviewA panel anchored to what opened it.