Dialog

Guidelines
React API Reference
Blazor API Reference

Dialogs (modals) present important content or interactions that block user interaction with the rest of the page until the user addresses them. Used correctly, they help users focus on critical tasks, decisions, or acknowledgments.

Guidance

Aspect	Best Practice
Usage	Use dialogs for critical information or actions that must be acknowledged or completed before proceeding.
Content	Keep the body concise. Aim for 3 lines or fewer to avoid overwhelming users. Do not use asterisks (*) as they can imply hidden details.
Behavior	Dialogs block interaction with the underlying page until dismissed. They can be configured to close on outside click or require explicit user action.
Alignment	Left-align headers and body text for clarity and consistency.
Hierarchy	An overlay beneath the dialog obscures page content, signaling the dialog’s importance.
Examples	EULA agreements, required forms, or confirmation steps before proceeding.

Language and Formatting

Use sentence case for descriptive text, capitalizing only the first word and proper nouns. Apply appropriate punctuation for clarity:

End complete sentences with periods.
Use commas to separate items in lists, compound sentences, introductory phrases, dates, addresses, nonessential clauses, and multiple adjectives.
Spell out numbers one through nine in descriptive text and use numerals for 10 and above.

Examples:

Category	Example
Lists	“The options are red, blue, and green.”
Compound Sentences	“The button is blue, and the text is white.”
Introductory Phrases	“With a single click, the user can submit the form.”
Dates and Addresses	“The meeting is scheduled for Thursday, June 10, 2022, at 10 a.m.”
Nonessential Clauses	“The user, who is new to the app, may need assistance.”
Separate Adjectives	“The user-friendly, intuitive interface makes it easy to use.”
Pauses/Breaks	“The app is designed for people who are looking for an easy way to manage their finances, not for professional accountants.”
Numbers	“Use three fields,” vs. “Enter 15 items.”

Best Practices

Overlay Color: Use our background overlay color (#11111) to create a clear separation from the page content behind the dialog.
Dismissal: Provide clear dismissal options (e.g., an “X” close icon, “Accept” or “Decline” buttons) so users know how to proceed or exit.

Do’s and Don’ts

Do

Use modals for critical, pivotal information. * Keep modals concise and focused. * Align actions with the modal title and content.

Don't

Overuse modals for non-critical details. * Present a “wall of text” that overwhelms the user. * Use generic labels that don’t clarify the next step.

Additional Guidance

Psychological Impact:
- Task Immersion: The modal’s overlay focuses attention on the current task, reducing distractions.
- Urgency and Importance: The full-page overlay conveys that the information or action is important.
- Control: Users must address the modal before returning to their previous task, which can be helpful for focus but frustrating if overused.

Import

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogFooter,
  DialogTitle,
  DialogDescription,
  DialogClose,
} from '@strongtie/design-system/dialog';

Usage

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
      <DialogDescription>
        Make changes to your profile here. Click save when you're done.
      </DialogDescription>
    </DialogHeader>
    <div className="py-4">
      <p>Dialog content goes here.</p>
    </div>
    <DialogFooter>
      <Button type="submit">Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

`<Dialog>` Props

defaultOpen

boolean

default:"false"

If true, the dialog will be open by default.

open

boolean

If true, the dialog will be open.

onOpenChange

function

Callback function that is called when the open state changes.

When set to true, interaction with outside elements will be disabled and only dialog content will be visible to screen readers.

`<DialogTrigger>` Props

asChild

boolean

default:"false"

If true, the trigger will render as a child component.

`<DialogPortal>` Props

forceMount

boolean

Used to force mounting when more control is needed.

container

HTMLElement

default:"document.body"

The container element to render the dialog into.

`<DialogOverlay>` Props

asChild

boolean

default:"false"

If true, the overlay will render as a child component.

forceMount

boolean

Used to force mounting when more control is needed.

`<DialogContent>` Props

asChild

boolean

default:"false"

If true, the content will render as a child component.

forceMount

boolean

default:"false"

If true, the content will always be mounted in the DOM.

onOpenAutoFocus

function

Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault.

onCloseAutoFocus

function

Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.

onEscapeKeyDown

function

Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.

onPointerDownOutside

function

Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.

onInteractOutside

function

Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling event.preventDefault.

`<DialogClose>` Props

asChild

boolean

default:"false"

If true, the close button will render as a child component.

`<DialogTitle>` Props

asChild

boolean

default:"false"

If true, the title will render as a child component.

`<DialogDescription>` Props

asChild

boolean

default:"false"

If true, the description will render as a child component.

Styling Classes

The following CSS classes are applied by the Dialog components:

dialog-overlay – Modal backdrop overlay
dialog-content – Main dialog container
dialog-close – Close button element
dialog-header – Dialog header section
dialog-footer – Dialog footer section
dialog-title – Dialog title element
dialog-description – Dialog description element

For more examples, visit the Storybook.

@inject DialogService DialogService

await DialogService.OpenAsync(Title, ds => ChildContent, new DialogOptions
      {
          Width = Width,
          Left = Left,
          Top = Top,
          Bottom = Bottom,
          Height = Height,
          ShowTitle = ShowTitle,
          ShowClose = ShowClose,
          Resizable = Resizable,
          Draggable = Draggable,
          Description = Description,
          Style = Style,
          AutoFocusFirstElement = AutoFocusFirstElement,
          CloseDialogOnOverlayClick = CloseDialogOnOverlayClick,
          CloseDialogOnEsc = CloseDialogOnEsc,
          CssClass = CssClass,
          WrapperCssClass = WrapperCssClass,
          CloseTabIndex = CloseTabIndex,
          ContentCssClass = ContentCssClass,
          Resize = Resize,
          Drag = Drag
      });
  }

Parameters

ChildContent

RenderFragment

Gets or sets the child content.

Title

string

Gets or sets the title of the dialog.

ShowTitle

bool

default:"true"

Gets or sets a value indicating whether to show the title.

Description

string

Gets or sets the description of the dialog.

ShowClose

bool

default:"true"

Gets or sets a value indicating whether to show the close button.

Width

string

Gets or sets the width of the dialog.

Height

string

Gets or sets the height of the dialog.

Left

string

Gets or sets the left position of the dialog.

Top

string

Gets or sets the top position of the dialog.

Bottom

string

Gets or sets the bottom position of the dialog.

Resizable

bool

default:"false"

Gets or sets a value indicating whether the dialog is resizable.

Draggable

bool

default:"false"

Gets or sets a value indicating whether the dialog is draggable.

Style

string

Gets or sets the style of the dialog.

CssClass

string

Gets or sets the CSS class of the dialog.

WrapperCssClass

string

Gets or sets the wrapper CSS class of the dialog.

ContentCssClass

string

Gets or sets the content CSS class of the dialog.

AutoFocusFirstElement

bool

default:"true"

Gets or sets a value indicating whether to auto-focus the first element in the dialog.

CloseDialogOnOverlayClick

bool

default:"true"

Gets or sets a value indicating whether to close the dialog when the overlay is clicked.

CloseDialogOnEsc

bool

default:"true"

Gets or sets a value indicating whether to close the dialog when the escape key is pressed.

Resize

Action<Size>

Gets or sets the resize action of the dialog.

Drag

Action<Point>

Gets or sets the drag action of the dialog.

Styling Classes

The following CSS classes are applied by the Dialog components:

dialog-titlebar – Dialog title bar
dialog-title – Dialog title element
dialog-titlebar-close – Close button in title bar
dialog-content – Dialog content area
dialog-mask – Background overlay mask
dialog-header – Dialog header section
dialog-description – Dialog description element

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Language and Formatting

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<Dialog>` Props

`<DialogTrigger>` Props

`<DialogPortal>` Props

`<DialogOverlay>` Props

`<DialogContent>` Props

`<DialogClose>` Props

`<DialogTitle>` Props

`<DialogDescription>` Props

Styling Classes

Parameters

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Language and Formatting

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<Dialog> Props

​<DialogTrigger> Props

​<DialogPortal> Props

​<DialogOverlay> Props

​<DialogContent> Props

​<DialogClose> Props

​<DialogTitle> Props

​<DialogDescription> Props

​Styling Classes

​Parameters

​Styling Classes

Guidance

Language and Formatting

Best Practices

Do’s and Don’ts

Additional Guidance

`<Dialog>` Props

`<DialogTrigger>` Props

`<DialogPortal>` Props

`<DialogOverlay>` Props

`<DialogContent>` Props

`<DialogClose>` Props

`<DialogTitle>` Props

`<DialogDescription>` Props

Styling Classes

Parameters

Styling Classes