OverlaysReact
A small popup anchored to a button that asks the person to confirm an action before it runs.
Rendered by React 19.3.1
Loading React…Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<Popconfirm.Root>
<Popconfirm.Trigger />
<Popconfirm.Portal>
<Popconfirm.Positioner>
<Popconfirm.Popup>
<Popconfirm.Arrow />
<Popconfirm.Title />
<Popconfirm.Description />
<Popconfirm.Cancel />
<Popconfirm.Confirm />
</Popconfirm.Popup>
</Popconfirm.Positioner>
</Popconfirm.Portal>
</Popconfirm.Root>Examples
Async
onConfirm returns a promise: Confirm shows data-pending until it settles, and Cancel and Escape still close the popup.
API reference
35 props across 10 parts, in React syntax. className, style, render are listed once, under Shared props.
ArrowPopconfirm.Arrow
Displays an element positioned against the popconfirm anchor. Renders a <div>.
| Data attribute | Description |
|---|---|
data-open | Present when the popup is open. |
data-closed | Present when the popup is closed. |
data-side | Indicates which side the popup is positioned relative to the trigger. |
data-align | Indicates how the popup is aligned relative to specified side. |
data-uncentered | Present when the popconfirm arrow is uncentered. |
CancelPopconfirm.Cancel
A button that closes the popconfirm without confirming. It is focused when the popup opens, and stays usable while a confirm is pending. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
disabledWhether the button ignores presses. | boolean | — |
| Data attribute | Description |
|---|---|
data-disabled | Present when the button is disabled. |
data-pending | Present while the promise returned by onConfirm has not settled. |
ConfirmPopconfirm.Confirm
A button that calls the root's onConfirm and closes the popconfirm. While the promise onConfirm returned is pending, presses are ignored and it has aria-disabled. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
disabledWhether the button ignores presses. | boolean | — |
| Data attribute | Description |
|---|---|
data-disabled | Present when the button is disabled. |
data-pending | Present while the promise returned by onConfirm has not settled. |
DescriptionPopconfirm.Description
A paragraph that describes what the confirmed action does. Renders a <p>.
PopupPopconfirm.Popup
A container for the popconfirm contents, rendered as an alertdialog. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
initialFocusDetermines the element to focus when the popconfirm is opened. | boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) | — |
finalFocusDetermines the element to focus when the popconfirm is closed. | boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | — |
| Data attribute | Description |
|---|---|
data-open | Present when the popup is open. |
data-closed | Present when the popup is closed. |
data-starting-style | Present when the popup begins animating in. |
data-ending-style | Present when the popup is animating out. |
data-side | Indicates which side the popup is positioned relative to the trigger. |
data-align | Indicates how the popup is aligned relative to specified side. |
data-instant | Present if animations should be instant. |
data-pending | Present while the promise returned by onConfirm has not settled. |
| CSS variable | Description |
|---|---|
--popup-width | The width of the popup. |
--popup-height | The height of the popup. |
PortalPopconfirm.Portal
A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
keepMountedWhether to keep the portal mounted in the DOM while the popup is hidden. | boolean | false |
containerA parent element to render the portal element into. | HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | — |
PositionerPopconfirm.Positioner
Positions the popconfirm against the trigger. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
anchorAn element to position the popup against. | Element | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null | — |
positionMethodDetermines which CSS position property to use. | "absolute" | "fixed" | 'absolute' |
sideWhich side of the anchor element to align the popup against. | Side | 'bottom' |
sideOffsetDistance between the anchor and the popup in pixels. | number | OffsetFunction | 0 |
alignHow to align the popup relative to the specified side. | Align | 'center' |
alignOffsetAdditional offset along the alignment axis in pixels. | number | OffsetFunction | 0 |
collisionBoundaryAn element or a rectangle that delimits the area that the popup is confined to. | Boundary | 'clipping-ancestors' |
collisionPaddingAdditional space to maintain from the edge of the collision boundary. | Padding | 5 |
stickyWhether to maintain the popup in the viewport after | boolean | false |
arrowPaddingMinimum distance to maintain between the arrow and the edges of the popup. | number | 5 |
disableAnchorTrackingWhether to disable the popup from tracking any layout shift of its positioning anchor. | boolean | false |
collisionAvoidanceDetermines how to handle collisions when positioning the popup. | CollisionAvoidance | — |
| Data attribute | Description |
|---|---|
data-open | Present when the popup is open. |
data-closed | Present when the popup is closed. |
data-anchor-hidden | Present when the anchor is hidden. |
data-side | Indicates which side the popup is positioned relative to the trigger. |
data-align | Indicates how the popup is aligned relative to specified side. |
| CSS variable | Description |
|---|---|
--available-width | The available width between the trigger and the edge of the viewport. |
--available-height | The available height between the trigger and the edge of the viewport. |
--anchor-width | The anchor's width. |
--anchor-height | The anchor's height. |
--transform-origin | The coordinates that this element is anchored to. Used for animations and transitions. |
--positioner-width | The width of the popconfirm's positioner.
It is important to set width to this value when using CSS to animate size changes. |
--positioner-height | The height of the popconfirm's positioner.
It is important to set height to this value when using CSS to animate size changes. |
RootPopconfirm.Root
Groups all parts of the popconfirm. Doesn’t render its own element.
| Prop | Type | Default |
|---|---|---|
defaultOpenWhether the popconfirm is initially open. | boolean | false |
openWhether the popconfirm is currently open. | boolean | — |
onOpenChangeEvent handler called when the popconfirm is opened or closed. | ((open: boolean, eventDetails: PopconfirmRootChangeEventDetails) => void) | — |
onOpenChangeCompleteEvent handler called after any animations complete when the popconfirm is opened or closed. | ((open: boolean) => void) | — |
onConfirmCalled when Confirm is pressed. | ((details: PopconfirmRoot.ConfirmDetails<Payload>) => unknown) | — |
actionsRefA ref to imperative actions. | React.RefObject<PopconfirmRootActions | null> | — |
modalDetermines if the popconfirm enters a modal state when open. | boolean | "trap-focus" | 'trap-focus' |
triggerIdID of the trigger that the popconfirm is associated with. | string | null | — |
defaultTriggerIdID of the trigger that the popconfirm is associated with. | string | null | — |
handleA handle to associate the popconfirm with a trigger. | PopconfirmHandle<Payload> | — |
childrenThe content of the popconfirm. | React.ReactNode | PayloadChildRenderFunction<Payload> | — |
TitlePopconfirm.Title
A heading that labels the popconfirm. Renders a <h2>.
TriggerPopconfirm.Trigger
A button that opens the popconfirm when pressed. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
handleA handle to associate the trigger with a popconfirm. | PopconfirmHandle<Payload> | — |
payloadA payload to pass to the popconfirm when it is opened. | Payload | — |
idID of the trigger. | string | — |
| Data attribute | Description |
|---|---|
data-popup-open | Present when the corresponding popconfirm is open. |
data-pressed | Present when the trigger is pressed. |
data-disabled | Present when the trigger is disabled. |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| EnterSpace | Open or close the popconfirm; press Cancel or Confirm when focused | Trigger, buttons |
| TabShiftTab | Move between Cancel and Confirm; focus stays inside and wraps | Popup |
| Escape | Closes the popconfirm and returns focus to the Trigger, also while pending | Popup |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Trigger | aria-haspopup="dialog", aria-expanded, aria-controls | a screen reader says the button opens a dialog and whether it is open |
| Popup | role="alertdialog", tabindex="-1" | the popup is announced as an alert that needs an answer |
| Popup | aria-labelledby to Title, aria-describedby to Description | the question and its consequence are read when it opens |
| Confirm | aria-disabled="true" and data-pending while pending | the button keeps focus while it waits, which the native disabled would drop |
Focus order
- Opening moves focus to
Cancel, or to the Popup when there is noCancel, or toinitialFocus. TabandShift+Tabstay inside the popup and wrap at either end.Cancelcomes first, thenConfirm.- Closing returns focus to the Trigger that opened it, or to
finalFocus.