On this page
@addTagHelper *, Webority.Ui.RazorA basic dialog
Use a dialog for one contained task, such as editing a record or checking its details, before the user carries on.
Tone and forced choice
Tone signals intent in the header, and a forced choice removes Escape and the backdrop so only an explicit action closes it.
Actions beside the title
Use header actions for stepping through records, such as Previous and Next, without closing the dialog.
Sizes
The default md suits most tasks, so use a larger preset or fullscreen only for a dense form or a long document.
Placement
Centre the dialog by default, and pin it to the top when the trigger is high on the page.
Title font
Draw the title in the display typeface instead of the default sans face.
A back button
Add a back arrow when a dialog is one step of a short flow with a real previous screen.
Load from server
A dialog whose content comes from the server: a page handler answers with an HTML fragment rooted in <app-modal-content>, and the form inside submits by fetch. The server answers success, the same form again with its errors (a 200 marked Wui-Result: invalid), or an error, and the dialog follows. Fragments never carry script; page behaviour stays in the page.
Every option
Every value of every prop, one cell each.
open and onClose
id: the dialog a trigger opens (React: open)data-bs-dismiss="modal": closes it (React: onClose)tone: all four
tone="neutral" (default)tone="danger"tone="success"tone="warning"size: every preset, plus a custom width
size="sm"size="md" (default)size="lg"size="xl"size="fullscreen"size="720"placement
placement="center" (default)placement="top"header: eyebrow, subtitle, headerIcon and title
eyebrow onlysubtitle onlyheader-icon onlytitle only, with no eyebrow, subtitle or iconeyebrow, subtitle and header-icon togetherhideHeader and ariaLabel
hide-header="true": no header row at all (React: hideHeader)aria-label: the accessible name when the title is not plain text (React: ariaLabel)dismiss control: dismissible, staticBackdrop, closeOnEscape
dismissible (default): the close button showsdismissible="false": no close buttonstatic-backdrop (default): an outside click leaves it openstatic-backdrop="false": an outside click closes itclose-on-escape="false": Escape does not close itdismissible="false" with static-backdrop and close-on-escape="false": forced choiceheaderActions: beside the title
<app-modal-header-actions>: Previous and Next beside the title (React: headerActions)footer and children
no app-modal-footer: footer omitted (React: no footer prop)(content): long body, the card scrolls and header and footer stay pinned (React: children)footer long content: several actions wrap within the pinned footerclassName
class: extra classes on the modal shell (text-start here)confirmDiscard and dirty
confirm-discard="Discard your changes?": asks before closing while a field is dirty (React: dirty)back arrow: onBack and backLabel
back-url: loads the URL into this dialog (React: onBack)back-label: names the back arrow (React: backLabel)closeLabel
close-label="Dismiss": the close button's accessible name (React: closeLabel)remote loading (Razor only)
remote-url: the card loads each time it opens (React: keep data in app state)remote-cache="true": keeps the loaded card for the next open (React: keep data in app state)Guidance
What to do, and what to avoid.
Use it when
- A short, self-contained task: edit a record, view details, complete a small form.
- You need to interrupt the flow to get one thing done before continuing.
Reach for something else when
- It's a yes/no confirmation before a destructive action. → AppConfirmDialog
- It's a slide-in navigation or filter panel on mobile. → AppDrawer
- The content is a full workflow with many steps and forms. → a dedicated page
- It's a transient success/error message. → a toast
One trigger, one dialog
A clear trigger opens a single-purpose dialog; open and onClose stay controlled so the close control always works.
A modal with no onClose traps the user: the backdrop and Escape have nothing to call.
One primary action in the footer
A footer that pairs a secondary Cancel with one primary confirm: the eye knows the main action.
Three competing primaries in the footer leave the user unsure which one commits.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
25 props. The 3 most used come first.
Used on most screens 3 props
| Prop | Type | Default | Description |
|---|---|---|---|
| titledefault - | string | - | Header title. |
| subtitledefault - | string | - | Secondary line under the title. |
| tonedefault neutral | Neutral | Danger | Success | Warning | neutral | Tints the header icon and eyebrow to signal intent, such as a destructive or a success dialog. |
Less common 22 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault - | string | - | The modal id a trigger points at with data-bs-target. |
| sizedefault md | Sm | Md | Lg | Xl | Fullscreen | number | md | The card width: a preset, fullscreen for the whole viewport with header and footer pinned, or a number for an exact max width in pixels. |
| size-pxdefault - | number | - | The card width in pixels, instead of a preset. |
| placementdefault center | Center | Top | center | Vertical placement of the card: centred, or pinned near the top of the viewport. |
| titleFontdefault sans | Sans | Serif | sans | Face of the title. Serif draws it in the display typeface at the 3xl size, weight 500. |
| (content)default - | markup | - | The modal body. A trailing <app-modal-footer> is lifted out as a pinned sticky footer. |
| <app-modal-header-actions>default - | markup | - | Buttons drawn beside the title, before the close button. Not drawn while hide-header is set. |
| header-icondefault - | string | - | A library icon name drawn in the header. |
| eyebrowdefault - | string | - | A small kicker label above the title for a section, step, or category marker. |
| dismissibledefault true | bool | true | Shows the close button in the header. For a forced-choice dialog, pair false with staticBackdrop and closeOnEscape false. |
| hide-headerdefault false | bool | false | Hides the header, leaving the body and footer. |
| classdefault - | string | - | Extra classes merged onto the modal shell. |
| static-backdropdefault true | bool | true | Covers outside clicks only: by default an outside click leaves the pop-up open. false lets an outside click close it. |
| close-on-escapedefault true | bool | true | Escape closes the modal through onClose, asking first when confirmDiscard applies. Set false for a dialog that must not close from the keyboard. |
| back-urldefault - | string | - | The URL the back arrow before the title loads into this dialog; unset draws no back arrow. |
| back-labeldefault Back | string | Back | The accessible name of the back arrow shown when onBack is set. |
| close-labeldefault Close | string | Close | The close button's accessible name, for other languages. |
| confirm-discarddefault - | string | - | Asks before closing while dirty, with this text and Discard and Keep editing in the footer. |
| remote-urldefault - | string | - | Fragment URL loaded each time the dialog opens; the children become the loading placeholder. A trigger's data-wui-url overrides it. Razor only. |
| remote-cachedefault false | bool | false | Keep the loaded card after closing, so reopening from the same URL shows it without a request. |
| aria-labeldefault - | string | - | The accessible name when the title is not plain text, or when the header is hidden. |
| title-fontdefault sans | Sans | Serif | sans | Face of the title. serif draws it in the display typeface at the 3xl size, weight 500. |
Screen reader
3 notes- Focus opens on the first control. Tab moves through the dialog and then to the browser's bar, without wrapping.
- The dialog is named by a plain-text title or by ariaLabel; a headerless dialog with neither warns in development.
- An outside click leaves it open by default (staticBackdrop); Escape closes it unless closeOnEscape is false.
Do and avoid
2 pairsOne trigger, one dialog
A clear trigger opens a single-purpose dialog; open and onClose stay controlled so the close control always works.
A modal with no onClose traps the user: the backdrop and Escape have nothing to call.
One primary action in the footer
A footer that pairs a secondary Cancel with one primary confirm: the eye knows the main action.
Three competing primaries in the footer leave the user unsure which one commits.