Dialog
DraftA modal dialog for presenting focused content, confirmation flows, and action panels with keyboard focus trapping, backdrop dismissal, and optional header/footer regions.
Preview
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>
Install
npm install @fbin-web/neighborhood-react
Import
import { NbhdDialog } from '@fbin-web/neighborhood-react';
Usage
import { useRef } from 'react';
import { NbhdDialog, NbhdButton, NbhdText } from '@fbin-web/neighborhood-react';
const App = () => {
const dialogRef = useRef(null);
return (
<>
<NbhdButton
id="open-dialog-button"
variant="primary"
onClick={() => dialogRef.current?.show()}>
Open dialog
</NbhdButton>
<NbhdDialog
ref={dialogRef}
label="Title for basic dialog "
surface="primary">
<NbhdText>
This is a dialog. It can contain any content, but it's up to you to provide it. You can
use the
</NbhdText>
<div slot="footer">
<NbhdButton variant="secondary">Cancel</NbhdButton>
<NbhdButton variant="primary">Confirm</NbhdButton>
</div>
</NbhdDialog>
</>
);
};
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
label | label | string | — | Accessible label displayed in the header when no label slot is provided. Prefer this over the native title attribute. |
hideHeader | hide-header | boolean | false | Hides the dialog header. |
open | open | boolean | false | Whether the dialog is open. |
persistent | persistent | boolean | false | Prevents the dialog from closing when clicking the backdrop or pressing Escape. |
width | width | number | — | Sets a custom width for the dialog panel in pixels. |
surface | surface | Surface | 'primary' | The visual surface token applied to the dialog panel. |
closeLabel | close-label | string | Close dialog | Accessible name of the close button. |
No properties match.
Events
| Name | Description | Event Detail |
|---|---|---|
nbhd-dialog-open | Emitted after the dialog opens and focus is moved into it. | — |
nbhd-dialog-close | Emitted after the dialog closes and focus is returned to the element that opened it. | — |
Slots
| Name | Description |
|---|---|
(default) | Main dialog body content. The default slot renders inside the body container. |
label | Optional header label content. When provided, it overrides the label property and is rendered inside the header slot. |
footer | Optional footer content. This is only rendered when the footer slot is present. |
CSS Parts
| Name | Description |
|---|---|
base | The outer dialog wrapper around the backdrop and panel. |
backdrop | The overlay backdrop behind the dialog panel. |
panel | The dialog panel itself, including the surface styling and content container. |
header | The dialog header container when the header is visible. |
label | The label slot container used for the dialog title area. |
title | The default rendered title element when the label property is used. |
body | The main body container that wraps the default slot content. |
body-slot | The default slot element for dialog body content. |
footer | The footer container when footer content is present. |
footer-slot | The slot element for dialog footer content. |
No css parts match.
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
| Property | Token | Value | 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-4 | 16px |
|
--nbhd-dialog-body-paddingInline | --nbhd-space-6 | 24px |
|
--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-2 | 8px |
|
--nbhd-dialog-footer-justifyContent | — | end |
|
--nbhd-dialog-footer-paddingBlock | --nbhd-space-0 --nbhd-space-5 | 0px 20px |
|
--nbhd-dialog-footer-paddingInline | --nbhd-space-6 | 24px |
|
--nbhd-dialog-header-display | — | block |
|
--nbhd-dialog-header-paddingBlock | --nbhd-space-5 --nbhd-space-0 | 20px 0px |
|
--nbhd-dialog-header-paddingInline | --nbhd-space-6 --nbhd-space-8 | 24px 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-md | 6px |
|
--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-1 | 1 |
|
--nbhd-dialog-position | — | fixed |
|
--nbhd-dialog-visibility | — | hidden |
|
--nbhd-dialog-zIndex | --nbhd-z-800 | 800 |
No dialog match.
Overlay
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-overlay-color | --nbhd-color-overlay | #000000 |
|
--nbhd-overlay-opacity | --nbhd-opacity-overlay-backdrop | 0.5 |
Dependencies
Child components <nbhd-dialog> renders internally. Import them too when you tree-shake.