Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

A basic dialog

Use a dialog for one contained task, such as editing a record or checking its details, before the user carries on.

Open a dialog
The close disc and the footer buttons dismiss the modal. Escape closes it unless close-on-escape is false, and the backdrop leaves it open unless static-backdrop is false.
Show code
<app-button data-bs-toggle="modal" data-bs-target="#scEditModal">Edit project</app-button>
<app-modal id="scEditModal" title="Edit project" header-icon="edit">
    <p>Modal body: a form, details, or a short task.</p>
    <app-modal-footer>
        <app-button variant="Soft" data-bs-dismiss="modal">Cancel</app-button>
        <app-button data-bs-dismiss="modal">Save</app-button>
    </app-modal-footer>
</app-modal>
A field at the foot
The body scrolls past the card's height. Focusing the last field scrolls the body, and the card does not move.
Show code
<app-modal id="editContact" title="Edit contact" header-icon="edit">
    <app-input label="Name" name="name" />
    …
    <app-input label="Email" name="email" type="email" data-autofocus />
    <app-modal-footer>…</app-modal-footer>
</app-modal>
A dialog that loads its content
remote-url fetches the card each time the dialog opens, and the children show while it loads. A trigger's data-wui-url overrides the URL, so one dialog serves every row of a table. remote-cache="true" keeps the loaded card for the next open.
Show code
<app-button data-bs-toggle="modal" data-bs-target="#leave" data-wui-url="/Leave?handler=Form&amp;id=7">Edit</app-button>
<app-modal id="leave" title="Request leave" remote-url="/Leave?handler=Form">
    <p>Loading the form…</p>
</app-modal>

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.

Danger and forced choice
Left: eyebrow + tone="danger". Right: tone="success", dismissible="false" + static-backdrop + close-on-escape="false". No close disc, and neither Escape nor the backdrop dismisses it.
Show code
<app-modal id="del" eyebrow="Danger zone" title="Delete project" header-icon="trash-2" tone="Danger">…</app-modal>
<app-modal id="terms" eyebrow="Action required" title="Accept the terms" tone="Success" dismissible="false" static-backdrop="true" close-on-escape="false">…</app-modal>

Actions beside the title

Use header actions for stepping through records, such as Previous and Next, without closing the dialog.

Step through records
The actions stay in the header; the body holds the record.
Show code
<app-modal id="scHeaderActionsModal" title="Leave request" header-icon="calendar" size="AppModalSize.Lg">
    <app-modal-header-actions>
        <div class="d-flex gap-2">
            <app-button variant="Ghost" size="WideSize.Sm">Previous</app-button>
            <app-button variant="Ghost" size="WideSize.Sm">Next</app-button>
        </div>
    </app-modal-header-actions>
    <p class="mb-0">Annual leave, 3 days, 4 to 6 November 2026.</p>
</app-modal>

Sizes

The default md suits most tasks, so use a larger preset or fullscreen only for a dense form or a long document.

Presets and fullscreen
Same primitive, same trigger mechanism. Only the width changes. A number is an exact max-width in px.
Show code
<app-modal id="lg" title="Large dialog" size="AppModalSize.Lg">…</app-modal>
<app-modal id="custom" title="Custom width" size-px="960">…</app-modal>
<app-modal id="full" title="Fullscreen dialog" size="AppModalSize.Fullscreen">…</app-modal>

Placement

Centre the dialog by default, and pin it to the top when the trigger is high on the page.

Top-aligned dialog
placement="top" pins the card near the top, useful when the trigger is high on the page or the dialog is short.
Show code
<app-modal id="note" title="Quick note" placement="Top">…</app-modal>

Title font

Draw the title in the display typeface instead of the default sans face.

Serif title
titleFont="serif" draws the title in the display typeface at the 3xl size. The default is "sans".
Show code
<app-modal id="scTitleFontModal" title="Edit project" title-font="Serif">…</app-modal>

A back button

Add a back arrow when a dialog is one step of a short flow with a real previous screen.

Back to request types
Open the dialog, pick a request type, then use Back on the second step to return to the list.
Show code
<app-button variant="Outline" data-bs-toggle="modal" data-bs-target="#scBackTypes">Request something</app-button>
<app-modal id="scBackTypes" title="Request type" header-icon="calendar">
    <div class="d-flex flex-column gap-2">
        <app-button variant="Outline" block="true" data-bs-toggle="modal" data-bs-target="#scBackLeave">Leave</app-button>
        <app-button variant="Outline" block="true" data-bs-toggle="modal" data-bs-target="#scBackLeave">Expense claim</app-button>
    </div>
</app-modal>
<app-modal id="scBackLeave" title="Request leave" header-icon="calendar">
    <p class="mb-0">Pick the dates for your leave.</p>
    <app-modal-footer>
        <app-button variant="Soft" data-bs-toggle="modal" data-bs-target="#scBackTypes">Back to request types</app-button>
    </app-modal-footer>
</app-modal>

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.

Open from any trigger
Any element with data-wui-modal="url" loads the fragment into one shared dialog (data-wui-size and data-wui-title are optional). Try sending with the last day before the first: the form comes back with its errors and the dialog stays open. A valid request closes it and shows a toast.
Show code
<app-button data-wui-modal="/Leave?handler=Form" data-wui-title="Request leave">Request leave</app-button>

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 only
subtitle only
header-icon only
title only, with no eyebrow, subtitle or icon
eyebrow, subtitle and header-icon together

hideHeader 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 shows
dismissible="false": no close button
static-backdrop (default): an outside click leaves it open
static-backdrop="false": an outside click closes it
close-on-escape="false": Escape does not close it
dismissible="false" with static-backdrop and close-on-escape="false": forced choice

headerActions: 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 footer

className

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

Do

A clear trigger opens a single-purpose dialog; open and onClose stay controlled so the close control always works.

Avoid

A modal with no onClose traps the user: the backdrop and Escape have nothing to call.

One primary action in the footer

Do

A footer that pairs a secondary Cancel with one primary confirm: the eye knows the main action.

Avoid

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.

(none) edit trash-2 check-circle info-circle alert-triangle
neutral danger success warning
sm md lg xl fullscreen
(none) 480 720
center top
sans serif
React, generated from the controls
<AppModal
  open={open}
  title="Playground modal"
  onBack={onBack}
  onClose={onClose}
  footer={<>…</>}
>
  …
</AppModal>
Razor, the same props
<app-modal id="pgModal" title="Playground modal">…</app-modal>

25 props. The 3 most used come first.

Used on most screens 3 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

One trigger, one dialog

Do

A clear trigger opens a single-purpose dialog; open and onClose stay controlled so the close control always works.

Avoid

A modal with no onClose traps the user: the backdrop and Escape have nothing to call.

One primary action in the footer

Do

A footer that pairs a secondary Cancel with one primary confirm: the eye knows the main action.

Avoid

Three competing primaries in the footer leave the user unsure which one commits.