OVERLAYBETA

Dialog

A native top-layer dialog primitive with controlled Signals, deterministic close reasons, focus restoration, localized controls and complete visual ownership.

Native dialogFocus safeSSR safe

GET STARTED

Import

Import the canonical standalone primitive and only the semantic sections used by the view.

import {
  NeuralDialog,
  NeuralDialogHeader,
  NeuralDialogBody,
  NeuralDialogFooter,
  NeuralDialogInitialFocus,
} from '@neural-ng/core/dialog';

@Component({ imports: [NeuralDialog, NeuralDialogHeader] })

Controlled state and policy

Bind open when application state owns visibility. This review cannot be dismissed by Escape or the backdrop.

Viewport-safe fluid width

fluid fills the safe viewport width while the native surface retains its maximum height and internal scrolling.

Full-screen workspace

full creates a borderless 100vw × 100dvh surface for focused editors, onboarding and immersive workflows. Content scroll remains owned by the native dialog.

Lifecycle and close intent

opened reports entry into the top layer. Every close includes its source and optional native return value.

Closed

Unstyled and typed class slots

Headless mode removes Dialog visual classes while preserving the native top layer, structural hooks, focus and close behavior.

Intentional boundaries

Dialog is a composable primitive. Confirmation workflows belong to NeuralConfirmDialog and NeuralConfirmationService.

Dragging, resizing and maximization are not implied by modal semantics and are excluded from the Beta contract.

Nested popups should use their own top-layer or appendTo="body" contract rather than escaping with arbitrary z-index values.

ACCESSIBILITY

A real dialog, not a simulated overlay

Native semantics, browser focus containment and deterministic application policy work as one contract.

Native semantics

The host renders a real <dialog>. Modal mode uses showModal(), enters the browser top layer, exposes aria-modal="true" and makes the remaining document inert.

Accessible name and description

Prefer ariaLabelledby pointing to a visible heading. Use ariaLabel only when no visible heading exists, and connect supporting copy through ariaDescribedby.

Focus lifecycle

neuralDialogInitialFocus targets the most useful first control after opening. Native modal focus remains contained and the exact opener regains focus after closing.

Keyboard

Tab / Shift+Tab

Navigate native focus order inside a modal.

Escape

Closes only when policy allows and reports escape.

Dismiss policy

When Escape or backdrop dismissal is disabled, always provide an obvious keyboard-operable action. closable="false" must never create a dead end.

SSR and hydration

The server emits a closed dialog. Browser-only top-layer, active-element and focus calls run after hydration; an initially true model opens safely when the native element exists.

API

Dialog contract

Every runtime declaration is canonical: NeuralDialog, NeuralDialogHeader, NeuralDialogBody, NeuralDialogFooter, and NeuralDialogInitialFocus. Previous Dialog* names remain only as deprecated aliases.

Inputs

Name	Type	Default	Purpose
open	ModelSignal<boolean>	false	Controlled visibility model.
modal	boolean	true	Uses showModal(); false uses show().
closable	boolean	true	Renders the localized close action.
closeOnEscape	boolean	true	Allows Escape dismissal.
dismissibleBackdrop	boolean	true	Allows pointer dismissal outside a modal.
fluid	boolean	false	Uses the viewport-safe fluid width.
full	boolean	false	Fills the complete dynamic viewport; takes precedence over fluid.
showFullScreenButton	boolean	false	Shows a full-screen toggle immediately before the close action.
ariaLabel	string \| null	null	Direct accessible name.
ariaLabelledby	string \| null	null	ID of the visible dialog heading.
ariaDescribedby	string \| null	null	ID of descriptive dialog content.
closeLabel	string \| null	locale	Close-button label override.
enterFullScreenLabel	string \| null	locale	Accessible enter-full-screen label override.
exitFullScreenLabel	string \| null	locale	Accessible exit-full-screen label override.
unstyled	boolean	false	Removes every Neural visual class.
dialogClass	string	''	Additive class on native dialog.
classes	NeuralDialogClasses	{}	Typed additive slot classes.

Outputs

openChangebooleanGenerated by the open model.

fullChangebooleanUser-triggered full-screen state change.

openedvoidNative dialog entered the top layer.

closedNeuralDialogCloseEvery completed close with exact reason.

Imperative methods

show()

Opens with modal/non-modal policy.

close(reason = 'api', returnValue = '', event?)

Closes and records intent plus native return value.

Semantic sections

neural-dialog-headerheaderClassSemantic header slot.

neural-dialog-bodybodyClassMain content slot.

neural-dialog-footerfooterClassAction-row slot.

neuralDialogInitialFocusdirectiveReceives focus after opening.

Typed class slots

root

Native dialog element.

header

Projected header section.

body

Projected body section.

footer

Projected footer section.

closeButton

Localized close button.

closeIcon

Neural Icons close glyph.

fullScreenButton

Optional full-screen toggle action.

fullScreenIcon

Dynamic maximize/minimize Neural Icon.

Public types

NeuralDialogCloseReason

'api' | 'escape' | 'backdrop' | 'close-button' | 'native'

NeuralDialogClose

{ reason, returnValue, nativeEvent? }

NeuralDialogClasses

Typed additive class-slot contract.

DESIGN TOKENS

Dialog tokens

Structural base → component tokens → active theme → consumer classes remains the stable cascade.

Surface and backdrop

--neural-dialog-color

Component foreground color.

--neural-dialog-background

Component background surface.

--neural-dialog-border

Component border shorthand.

--neural-dialog-radius

Component corner radius.

--neural-dialog-shadow

Component box shadow.

--neural-dialog-backdrop

Component backdrop color.

--neural-dialog-backdrop-filter

Component backdrop filter effect.

--neural-dialog-font-family

Component font family.

Layout and sections

--neural-dialog-width

Component inline size.

--neural-dialog-full-border

Full border shorthand.

--neural-dialog-full-radius

Full corner radius.

--neural-dialog-full-shadow

Full box shadow.

--neural-dialog-header-gap

Spacing between header items.

--neural-dialog-header-padding

Header internal spacing.

--neural-dialog-header-border

Header border shorthand.

--neural-dialog-body-padding

Body internal spacing.

--neural-dialog-body-color

Body foreground color.

--neural-dialog-footer-justify

Footer main-axis alignment.

--neural-dialog-footer-gap

Spacing between footer items.

--neural-dialog-footer-padding

Footer internal spacing.

--neural-dialog-footer-border

Footer border shorthand.

Close control and focus

--neural-dialog-close-inset

Close logical inset from its containing edge.

--neural-dialog-close-size

Close width and height.

--neural-dialog-close-color

Close foreground color.

--neural-dialog-close-color-hover

Hovered close foreground color.

--neural-dialog-close-background

Close background surface.

--neural-dialog-close-background-hover

Hovered close background surface.

--neural-dialog-close-border

Close border shorthand.

--neural-dialog-close-radius

Close corner radius.

--neural-dialog-close-icon-size

Close icon width and height.

--neural-dialog-focus-ring

Component keyboard focus ring.

--neural-dialog-focus-ring-offset

Component focus ring offset.

Motion

Reduced-motion preferences collapse transition duration automatically.

--neural-dialog-enter-distance

Component enter animation travel distance.

--neural-dialog-enter-scale

Component enter animation starting scale.

--neural-dialog-enter-duration

Component enter animation duration.

--neural-dialog-enter-easing

Component enter animation easing curve.

--neural-dialog-leave-duration

Component leave animation duration.

--neural-dialog-leave-easing

Component leave animation easing curve.

--neural-dialog-transition

Component CSS transition.

Primary

Surface

Dialog

Import

Controlled state and policy

Release review

Viewport-safe fluid width

Responsive workspace

Full-screen workspace

Agent workspace

The full viewport is yours

Lifecycle and close intent

Unstyled and typed class slots

Consumer-owned canvas

Intentional boundaries

A real dialog, not a simulated overlay

Native semantics

Accessible name and description

Focus lifecycle

Keyboard

Dismiss policy

SSR and hydration

Dialog contract

Inputs

Outputs

Imperative methods

Semantic sections

Typed class slots

Public types

Dialog tokens

Surface and backdrop

Layout and sections

Close control and focus

Motion

Import

Native modal composition

Controlled state and policy

Non-modal surface

Viewport-safe fluid width

Full-screen workspace

Lifecycle and close intent

Unstyled and typed class slots

Intentional boundaries

Native semantics

Accessible name and description

Focus lifecycle

Keyboard

Dismiss policy

SSR and hydration

Inputs

Outputs

Imperative methods

Semantic sections

Typed class slots

Public types

Surface and backdrop

Layout and sections

Close control and focus

Motion