HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
DialogView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA modal window built on the native <dialog> element.StableSince 0.1.0OverlaysUsageimport'@fusion.dev/helix/dialog'import'@fusion.dev/helix-headless/dialog'Preview
API ReferenceRoothelix-dialogA modal window built on the native <dialog> element.
PropTypeDescriptionalertbooleanDefaultfalseMakes the dialog an alert dialog, for a message that interrupts to ask for
an answer, such as a confirmation before something is deleted.closedBy"any"|"closerequest"|"none"Which close requests the browser handles on its own.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.dismissiblebooleanDefaultfalseDraws a control that closes the dialog, in the corner where the title is.dismissLabelstringDefault"Close"The close control's accessible name. Translate it with the rest of your
interface.fallbackLabelstringDefault"Dialog"The dialog's name where nothing names it: no label, no heading in the
header slot, and no aria-labelledby on the host.labelstringDefault""Accessible name for the dialog. When it is empty, the heading in the
header slot names the dialog.openbooleanWhether the element is open.persistentbooleanDefaultfalseStops Escape and a press on the backdrop from closing the dialog.returnValuestringWhat the dialog closed with, the way <dialog> reports it. A
command="--close" button closes it with its value, as
command="close" closes a native <dialog>.size"sm"|"md"|"lg"|"full"How wide the panel is allowed to be.textAlign"center"|"start"Which way the panel's contents read.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The dialog's content.dismiss-iconReplaces the glyph inside the close control.footerThe dialog's actions.headerThe title, and anything beside it.iconAn icon above the title, for a warning dialog.
EventTypeDescriptioncloseEventSent from the host after the dialog closes, because the native close event does not leave the shadow root.helix-before-closeHelixBeforeCloseEventFired before it closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before it opens, and cancelable.toggleToggleEventSent when the dialog opens or closes, with newState and oldState.
MethodTypeDescriptionclose(returnValue: string) => voidRequests that the dialog close. A helix-before-close listener can cancel
the request.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the dialog, moves focus into it, and makes the rest of the page inert.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionbodyThe slot the content is in. It draws no box until you give it one.dismissThe close control, drawn when the dialog is dismissible.dismiss-markThe glyph on the close control, where none is slotted.footerThe slot the actions are in. It draws no box until you give it one.headerThe slot the title is in. It draws no box until you give it one.surfaceThe panel, which is the native dialog element.
CSS PropertyDescription--dialog-background-colorThe panel's fill. Follows --helix-color-surface-overlay.--dialog-border-colorColor of the panel's edge.--dialog-border-widthWidth of the panel's edge. Follows --helix-border-floating, which is 0, so the panel stands out by its shadow unless your theme sets a border.--dialog-colorColor of the words in the panel. Follows --helix-color-foreground.--dialog-icon-sizeHow big the mark above the title is.--dialog-inline-sizeWidth of the panel.--dialog-paddingPadding inside the panel.--dialog-radiusThe panel's corner radius. Follows --helix-radii-sm.--dialog-riseHow far the panel rises as it opens. Follows --helix-space-lg.--dialog-scrimThe tint over the page behind the dialog. Set it on the host, because a var() written inside ::backdrop cannot read a token.--dialog-shadowShadow under the panel. Follows --helix-shadow-floating. A floating surface can sit over any content, so it has a shadow by default.
Custom stateDescriptionenteringFrom the moment the dialog opens until its entrance has finished.exitingFrom the moment the dialog closes until its exit has finished.openWhile the dialog is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-dialogA modal window built on the native <dialog> element.
PropTypeDescriptionalertbooleanDefaultfalseMakes the dialog an alert dialog, for a message that interrupts to ask for
an answer, such as a confirmation before something is deleted.closedBy"any"|"closerequest"|"none"Which close requests the browser handles on its own.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.dismissiblebooleanDefaultfalseDraws a control that closes the dialog, in the corner where the title is.dismissLabelstringDefault"Close"The close control's accessible name. Translate it with the rest of your
interface.fallbackLabelstringDefault"Dialog"The dialog's name where nothing names it: no label, no heading in the
header slot, and no aria-labelledby on the host.labelstringDefault""Accessible name for the dialog. When it is empty, the heading in the
header slot names the dialog.openbooleanWhether the element is open.persistentbooleanDefaultfalseStops Escape and a press on the backdrop from closing the dialog.returnValuestringWhat the dialog closed with, the way <dialog> reports it. A
command="--close" button closes it with its value, as
command="close" closes a native <dialog>.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The dialog's content.dismiss-iconReplaces the glyph inside the close control.footerThe dialog's actions.headerThe title, and anything beside it.iconAn icon above the title, for a warning dialog.
EventTypeDescriptioncloseEventSent from the host after the dialog closes, because the native close event does not leave the shadow root.helix-before-closeHelixBeforeCloseEventFired before it closes, and cancelable.helix-before-openHelixBeforeOpenEventFired before it opens, and cancelable.toggleToggleEventSent when the dialog opens or closes, with newState and oldState.
MethodTypeDescriptionclose(returnValue: string) => voidRequests that the dialog close. A helix-before-close listener can cancel
the request.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the dialog, moves focus into it, and makes the rest of the page inert.toggleOpen() => booleanRequests the opposite of the current state.
PartDescriptionbodyThe slot the content is in. It draws no box until you give it one.dismissThe close control, drawn when the dialog is dismissible.dismiss-markThe glyph on the close control, where none is slotted.footerThe slot the actions are in. It draws no box until you give it one.headerThe slot the title is in. It draws no box until you give it one.surfaceThe panel, which is the native dialog element.
Custom stateDescriptionenteringFrom the moment the dialog opens until its entrance has finished.exitingFrom the moment the dialog closes until its exit has finished.openWhile the dialog is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAlertAn alert dialog with a close control, described by the sentence under its title.CenteredA dialog with centered content, for a short confirmation.EventsA helix-before-close listener cancels the first close and allows the second.FullA dialog that fills the viewport, for content that needs the whole screen.LargeA wider dialog, for a form that does not fit the default width.Light DismissA dialog that closes on a press outside it, handled by the browser with closedby set to any.PersistentA dialog that Escape and a press outside do not close, for a required choice.PreviewA dialog opened by a button, with actions in its footer.PreviewA dialog opened by a button, with actions in its footer.SmallA narrow dialog, for a question with two answers.