Dialog

Overview

Dialog is a window overlaid on the primary window, portaled to document.body so it escapes ancestor clipping and stacking contexts. It can be controlled (@bind-Open) or uncontrolled (DefaultOpen). When Modal (the default), opening it traps focus inside the popup and locks page scroll; closing it returns focus to the trigger.

Anatomy

@using Navius.Primitives.Components.Dialog

<NaviusDialog>
    <NaviusDialogTrigger />
    <NaviusDialogPortal>
        <NaviusDialogBackdrop />
        <NaviusDialogPopup>
            <NaviusDialogTitle />
            <NaviusDialogDescription />
            <NaviusDialogClose />
        </NaviusDialogPopup>
    </NaviusDialogPortal>
</NaviusDialog>

Root

Owns the open state and cascades a DialogContext to the parts. Renders no DOM of its own.

Prop	Type	Default	Description
`Open`	`bool`	`false`	Controlled open state. Pair with `OpenChanged` (`@bind-Open`).
`OpenChanged`	`EventCallback<bool>`	-	Fires when the controlled `Open` value should change.
`DefaultOpen`	`bool`	`false`	Initial open state when used uncontrolled.
`Modal`	`bool`	`true`	When `false`, does not trap focus, does not lock scroll, and leaves outside content interactive.
`ChildContent`	`RenderFragment?`	-	The dialog’s parts.

Trigger

The button that opens the dialog. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Trigger label content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Portal

Optional wrapper that hoists the Backdrop and Popup to document.body (or a Container). Renders no DOM of its own.

Prop	Type	Default	Description
`Container`	`string?`	-	CSS selector for the mount target. `null` uses `document.body`.
`ForceMount`	`bool`	`false`	Keeps Backdrop and Popup mounted while closed, driving exit transitions off `data-closed` instead of unmounting.
`ChildContent`	`RenderFragment?`	-	The Backdrop and Popup.

Backdrop

The dimmed backdrop behind the popup. Portaled to document.body; renders a div.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the backdrop mounted while closed, for exit animations.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

The panel that contains the dialog content. Self-portaled to document.body; renders a div with role="dialog".

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`OnOpenAutoFocus`	`EventCallback<NaviusOpenAutoFocusEventArgs>`	-	Fires when focus moves into the popup on open; cancelable.
`OnCloseAutoFocus`	`EventCallback<NaviusCloseAutoFocusEventArgs>`	-	Fires when focus returns to the trigger on close; cancelable.
`OnEscapeKeyDown`	`EventCallback<NaviusEscapeKeyDownEventArgs>`	-	Fires on `Escape`; cancelable.
`OnPointerDownOutside`	`EventCallback<NaviusPointerDownOutsideEventArgs>`	-	Fires on pointer-down outside the popup; cancelable.
`OnInteractOutside`	`EventCallback<NaviusInteractOutsideEventArgs>`	-	Fires on any outside interaction; cancelable.
`ChildContent`	`RenderFragment?`	-	The dialog’s content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Title

An accessible title announced when the dialog opens. aria-labelledby on the Popup points here. Renders an h2.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Title content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `h2`.

Description

An optional accessible description for the dialog. aria-describedby on the Popup points here. Renders a p.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Description content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `p`.

Close

A button that closes the dialog. Lives inside the content. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Close button content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Data attributes

Part	Attribute	Description
Trigger	`data-popup-open`	Present while the dialog is open.
Backdrop	`data-open`	Present while open.
Backdrop	`data-closed`	Present while closing (through the exit transition).
Backdrop	`data-starting-style`	Present at the start of the open transition.
Backdrop	`data-ending-style`	Present at the start of the close transition.
Popup	`data-open`	Present while open.
Popup	`data-closed`	Present while closing (through the exit transition).
Popup	`data-starting-style`	Present at the start of the open transition.
Popup	`data-ending-style`	Present at the start of the close transition.

Keyboard interactions

Key	Behavior
`Space`	Opens or closes the dialog when focus is on the trigger.
`Enter`	Opens or closes the dialog when focus is on the trigger.
`Tab`	Moves focus to the next focusable element inside the content. Focus is trapped when modal.
`Shift + Tab`	Moves focus to the previous focusable element inside the content.
`Escape`	Closes the dialog and returns focus to the trigger.

ARIA mechanism

The Trigger wires aria-haspopup="dialog", aria-expanded, and aria-controls pointing at the Popup’s id. The Popup renders role="dialog" and sets aria-modal="true" when Modal. aria-labelledby and aria-describedby on the Popup are wired only when a Title or Description part is mounted, so no dangling IDREF is emitted when they’re absent. On open, focus moves into the Popup; on close, it’s restored to the Trigger. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.