Dialog
A native top-layer dialog primitive with controlled Signals, deterministic close reasons, focus restoration, localized controls and complete visual ownership.
GET STARTED
Import
Import the canonical standalone primitive and only the semantic sections used by the view.
Native modal composition
The browser top layer supplies modal containment. Initial focus moves to the input and returns to the opener after every close.
Controlled state and policy
Bind open when application state owns visibility. This review cannot be dismissed by Escape or the backdrop.
Non-modal surface
Set modal="false" to use native show(). The page remains interactive and no modal backdrop is created.
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.
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.
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
Navigate native focus order inside a modal.
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.
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
rootNative dialog element.
headerProjected header section.
bodyProjected body section.
footerProjected footer section.
closeButtonLocalized close button.
closeIconNeural Icons close glyph.
fullScreenButtonOptional full-screen toggle action.
fullScreenIconDynamic maximize/minimize Neural Icon.
Public types
NeuralDialogCloseReason'api' | 'escape' | 'backdrop' | 'close-button' | 'native'
NeuralDialogClose{ reason, returnValue, nativeEvent? }
NeuralDialogClassesTyped additive class-slot contract.
Dialog tokens
Structural base → component tokens → active theme → consumer classes remains the stable cascade.
Surface and backdrop
--neural-dialog-colorComponent foreground color.
--neural-dialog-backgroundComponent background surface.
--neural-dialog-borderComponent border shorthand.
--neural-dialog-radiusComponent corner radius.
--neural-dialog-shadowComponent box shadow.
--neural-dialog-backdropComponent backdrop color.
--neural-dialog-backdrop-filterComponent backdrop filter effect.
--neural-dialog-font-familyComponent font family.
Layout and sections
--neural-dialog-widthComponent inline size.
--neural-dialog-full-borderFull border shorthand.
--neural-dialog-full-radiusFull corner radius.
--neural-dialog-full-shadowFull box shadow.
--neural-dialog-header-gapSpacing between header items.
--neural-dialog-header-paddingHeader internal spacing.
--neural-dialog-header-borderHeader border shorthand.
--neural-dialog-body-paddingBody internal spacing.
--neural-dialog-body-colorBody foreground color.
--neural-dialog-footer-justifyFooter main-axis alignment.
--neural-dialog-footer-gapSpacing between footer items.
--neural-dialog-footer-paddingFooter internal spacing.
--neural-dialog-footer-borderFooter border shorthand.
Close control and focus
--neural-dialog-close-insetClose logical inset from its containing edge.
--neural-dialog-close-sizeClose width and height.
--neural-dialog-close-colorClose foreground color.
--neural-dialog-close-color-hoverHovered close foreground color.
--neural-dialog-close-backgroundClose background surface.
--neural-dialog-close-background-hoverHovered close background surface.
--neural-dialog-close-borderClose border shorthand.
--neural-dialog-close-radiusClose corner radius.
--neural-dialog-close-icon-sizeClose icon width and height.
--neural-dialog-focus-ringComponent keyboard focus ring.
--neural-dialog-focus-ring-offsetComponent focus ring offset.
Motion
Reduced-motion preferences collapse transition duration automatically.
--neural-dialog-enter-distanceComponent enter animation travel distance.
--neural-dialog-enter-scaleComponent enter animation starting scale.
--neural-dialog-enter-durationComponent enter animation duration.
--neural-dialog-enter-easingComponent enter animation easing curve.
--neural-dialog-leave-durationComponent leave animation duration.
--neural-dialog-leave-easingComponent leave animation easing curve.
--neural-dialog-transitionComponent CSS transition.