Skip to main content
Neighborhood Design System v5.1.0

Dialog

Draft

A modal dialog for presenting focused content, confirmation flows, and action panels with keyboard focus trapping, backdrop dismissal, and optional header/footer regions.

Draft. This component is in draft. Its API may change before it is marked Ready. What this means

Preview

Open in Storybook (opens in new tab)

Code

Install
npm install @fbin-web/neighborhood-core
Import
import { NbhdDialog } from '@fbin-web/neighborhood-core';
Usage
<nbhd-button
  id="open-dialog-button"
  variant="primary">
  Open dialog
</nbhd-button>

<nbhd-dialog
  label="Title for basic dialog "
  surface="primary">
  <nbhd-text>
    This is a dialog. It can contain any content, but it's up to you to provide it. You can use the
  </nbhd-text>
  <div slot="footer">
    <nbhd-button variant="secondary"> Cancel </nbhd-button>
    <nbhd-button variant="primary"> Confirm </nbhd-button>
  </div>
</nbhd-dialog>

<script>
  // Example script to show the dialog programmatically
  document.querySelector('#open-dialog-button').addEventListener('click', () => {
    document.querySelector('nbhd-dialog').show();
  });
</script>

Properties

PropertyAttributeTypeDefaultDescription
labellabelstring—Accessible label displayed in the header when no label slot is provided. Prefer this over the native title attribute.
hideHeaderhide-headerbooleanfalseHides the dialog header.
openopenbooleanfalseWhether the dialog is open.
persistentpersistentbooleanfalsePrevents the dialog from closing when clicking the backdrop or pressing Escape.
widthwidthnumber—Sets a custom width for the dialog panel in pixels.
surfacesurfaceSurface'primary'The visual surface token applied to the dialog panel.
closeLabelclose-labelstringClose dialogAccessible name of the close button.

Events

NameDescriptionEvent Detail
nbhd-dialog-openEmitted after the dialog opens and focus is moved into it.—
nbhd-dialog-closeEmitted after the dialog closes and focus is returned to the element that opened it.—

Slots

NameDescription
(default)Main dialog body content. The default slot renders inside the body container.
labelOptional header label content. When provided, it overrides the label property and is rendered inside the header slot.
footerOptional footer content. This is only rendered when the footer slot is present.

CSS Parts

NameDescription
baseThe outer dialog wrapper around the backdrop and panel.
backdropThe overlay backdrop behind the dialog panel.
panelThe dialog panel itself, including the surface styling and content container.
headerThe dialog header container when the header is visible.
labelThe label slot container used for the dialog title area.
titleThe default rendered title element when the label property is used.
bodyThe main body container that wraps the default slot content.
body-slotThe default slot element for dialog body content.
footerThe footer container when footer content is present.
footer-slotThe slot element for dialog footer content.
nbhd-dialog::part(base) {
  /* your styles */
}

CSS Properties

Set these on nbhd-dialog or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.

Dialog

PropertyTokenValue Copy
--nbhd-dialog-alignItems—center
--nbhd-dialog-backdrop-background—rgb(from var(--nbhd-overlay-color) r g b / var(--nbhd-overlay-opacity))
--nbhd-dialog-backdrop-inset—0
--nbhd-dialog-backdrop-opacity—0
--nbhd-dialog-backdrop-position—fixed
--nbhd-dialog-backdrop-visibility—hidden
--nbhd-dialog-body-overflowBlock—auto
--nbhd-dialog-body-paddingBlock--nbhd-space-416px
--nbhd-dialog-body-paddingInline--nbhd-space-624px
--nbhd-dialog-close-insetBlockStart—8px
--nbhd-dialog-close-insetInlineEnd—8px
--nbhd-dialog-close-position—absolute
--nbhd-dialog-display—none
--nbhd-dialog-footer-display—flex
--nbhd-dialog-footer-gap--nbhd-space-28px
--nbhd-dialog-footer-justifyContent—end
--nbhd-dialog-footer-paddingBlock--nbhd-space-0 --nbhd-space-50px 20px
--nbhd-dialog-footer-paddingInline--nbhd-space-624px
--nbhd-dialog-header-display—block
--nbhd-dialog-header-paddingBlock--nbhd-space-5 --nbhd-space-020px 0px
--nbhd-dialog-header-paddingInline--nbhd-space-6 --nbhd-space-824px 32px
--nbhd-dialog-header-position—relative
--nbhd-dialog-inset—0
--nbhd-dialog-justifyContent—center
--nbhd-dialog-opacity—0
--nbhd-dialog-open-opacity—1
--nbhd-dialog-open-visibility—visible
--nbhd-dialog-panel-borderRadius--nbhd-border-radius-md6px
--nbhd-dialog-panel-boxShadow--nbhd-shadow-md-6px 3px 25px 8px rgb(from #000000 r g b / 0.15)
--nbhd-dialog-panel-display—flex
--nbhd-dialog-panel-flexDirection—column
--nbhd-dialog-panel-inlineSize—33rem
--nbhd-dialog-panel-maxBlockSize—90dvh
--nbhd-dialog-panel-opacity—0
--nbhd-dialog-panel-visibility—hidden
--nbhd-dialog-panel-zIndex--nbhd-z-11
--nbhd-dialog-position—fixed
--nbhd-dialog-visibility—hidden
--nbhd-dialog-zIndex--nbhd-z-800800

Overlay

PropertyTokenValue Copy
--nbhd-overlay-color--nbhd-color-overlay#000000
--nbhd-overlay-opacity--nbhd-opacity-overlay-backdrop0.5

Dependencies

Child components <nbhd-dialog> renders internally. Import them too when you tree-shake.

Esc
↑ ↓ to move↵ to open