Overlays and disclosure

Flyout

<forma-flyout>

Left/right edge modal surface built on native dialog semantics with reciprocal physics-derived motion.

Authoring tag
<forma-flyout>
Behavior owner
Native HTML
Canonical source
patterns/flyout.html

Purpose

A flyout is a full-height modal panel attached to the left or right edge of the viewport, for filters, navigation, record detail or a bounded task that relates to the page underneath. It is a native dialog with class="forma-flyout" and data-forma-side="left|right", opened with an invoker button (commandfor plus command="show-modal"). The browser owns the modal behavior: top layer, inert page, focus placement, Escape and focus return. Forma lays out a pinned header with a title and close button, a scrolling body, and a pinned action footer, respects safe-area insets, and slides the panel in from its edge with heavy perceived weight. Swipe-to-close, drag, resizing, bottom sheets and persistent non-modal drawers are application or Limen behavior.

Use when

  • Users refine a list with filters and want to return to the same list.
  • Users inspect or edit a record's detail without leaving the collection they came from.
  • Navigation or tools must be available on small screens as a temporary side panel.

Avoid when

  • A single decision or confirmation is needed: use Dialog.
  • The panel should stay open while the user works with the page: that is a non-modal drawer or Split pane, not a flyout.
  • The content is a small hint or menu anchored to a button: use Popover or Action menu.
  • The navigation should always be visible on wide screens: use Sidebar or Navigation shell.

Behavior to know

  • One component, two sides: data-forma-side="left" or "right".
  • Full dynamic-viewport height, min(28rem, 90vw) wide, so a strip of the page remains visible as context.
  • Header and footer stay in place while only the body scrolls, with contained overscroll.
  • Safe-area insets pad the header top and footer bottom.

Basic example

The smallest correct markup: the canonical pattern from patterns/flyout.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal flyout

Rendered from the canonical pattern file.

Live demo. 8 native actions work here and are verified by an outcome test.

Filters

Refine results

A left-edge modal surface for contextual controls or navigation.

Details

Record context

A right-edge modal surface for detail, inspection, or contextual work.

Status
Needs review
Owner
Application supplied
HTML · Minimal flyout Raw HTML for HTML · Minimal flyout
<forma-flyout class="forma-component-tag">
<button type="button" commandfor="left-flyout" command="show-modal">Open left flyout</button>
<dialog
  class="forma-flyout"
  id="left-flyout"
  data-forma-side="left"
  data-forma-motion-weight="heavy"
  aria-labelledby="left-flyout-title"
  aria-describedby="left-flyout-description">
  <div class="forma-flyout__surface">
    <header class="forma-flyout__header">
      <div>
        <p class="forma-component-kicker">Filters</p>
        <h2 id="left-flyout-title">Refine results</h2>
      </div>
      <button
        class="forma-flyout__close"
        type="button"
        commandfor="left-flyout"
        command="close"
        aria-label="Close left flyout">Close</button>
    </header>
    <div class="forma-flyout__body">
      <p id="left-flyout-description">A left-edge modal surface for contextual controls or navigation.</p>
      <label class="forma-checkbox" data-forma-motion-weight="standard">
        <input class="forma-checkbox__input" type="checkbox" name="open-only" value="yes">
        <span class="forma-checkbox__box" aria-hidden="true"></span>
        <span class="forma-checkbox__text">
          <span class="forma-checkbox__label">Open items only</span>
        </span>
      </label>
    </div>
    <footer class="forma-flyout__actions">
      <button type="button" commandfor="left-flyout" command="close">Apply</button>
    </footer>
  </div>
</dialog>

<button type="button" commandfor="right-flyout" command="show-modal">Open right flyout</button>
<dialog
  class="forma-flyout"
  id="right-flyout"
  data-forma-side="right"
  data-forma-motion-weight="heavy"
  aria-labelledby="right-flyout-title"
  aria-describedby="right-flyout-description">
  <div class="forma-flyout__surface">
    <header class="forma-flyout__header">
      <div>
        <p class="forma-component-kicker">Details</p>
        <h2 id="right-flyout-title">Record context</h2>
      </div>
      <button
        class="forma-flyout__close"
        type="button"
        commandfor="right-flyout"
        command="close"
        aria-label="Close right flyout">Close</button>
    </header>
    <div class="forma-flyout__body">
      <p id="right-flyout-description">A right-edge modal surface for detail, inspection, or contextual work.</p>
      <dl>
        <dt>Status</dt>
        <dd>Needs review</dd>
        <dt>Owner</dt>
        <dd>Application supplied</dd>
      </dl>
    </div>
    <footer class="forma-flyout__actions">
      <button type="button" commandfor="right-flyout" command="close">Done</button>
    </footer>
  </div>
</dialog>
</forma-flyout>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Filters with a long, scrolling body

A left flyout holding more filters than fit on screen. The body scrolls on its own while the header (title and close) and the footer (Clear and Show results) stay pinned. The form uses method="dialog" so either footer button closes the flyout and the application reads which one was used.

Live demo. 6 native actions work here and are verified by an outcome test.

Filter work items

Status
HTML · Filters with a long, scrolling body Raw HTML for HTML · Filters with a long, scrolling body
<forma-flyout class="forma-component-tag">
  <button type="button" commandfor="flyout-filters-with-pinned-actions" command="show-modal">Filters</button>
  <dialog class="forma-flyout" id="flyout-filters-with-pinned-actions" data-forma-side="left" aria-labelledby="flyout-filters-with-pinned-actions-title">
    <form class="forma-flyout__surface" method="dialog">
      <header class="forma-flyout__header">
        <h2 id="flyout-filters-with-pinned-actions-title">Filter work items</h2>
        <button class="forma-flyout__close" type="button" commandfor="flyout-filters-with-pinned-actions" command="close" aria-label="Close filters">Close</button>
      </header>
      <div class="forma-flyout__body forma-stack">
        <fieldset class="forma-stack" data-density="compact">
          <legend>Status</legend>
          <label class="forma-checkbox">
            <input class="forma-checkbox__input" type="checkbox" name="flyout-filters-status" value="open" checked>
            <span class="forma-checkbox__box" aria-hidden="true"></span>
            <span class="forma-checkbox__text"><span class="forma-checkbox__label">Open</span></span>
          </label>
          <label class="forma-checkbox">
            <input class="forma-checkbox__input" type="checkbox" name="flyout-filters-status" value="blocked">
            <span class="forma-checkbox__box" aria-hidden="true"></span>
            <span class="forma-checkbox__text"><span class="forma-checkbox__label">Blocked</span></span>
          </label>
          <label class="forma-checkbox">
            <input class="forma-checkbox__input" type="checkbox" name="flyout-filters-status" value="done">
            <span class="forma-checkbox__box" aria-hidden="true"></span>
            <span class="forma-checkbox__text"><span class="forma-checkbox__label">Done</span></span>
          </label>
        </fieldset>
        <div class="forma-field">
          <label class="forma-field__label" for="flyout-filters-with-pinned-actions-owner">Owner</label>
          <input id="flyout-filters-with-pinned-actions-owner" name="owner" type="text" autocomplete="off">
        </div>
        <div class="forma-field">
          <label class="forma-field__label" for="flyout-filters-with-pinned-actions-updated">Updated after</label>
          <input id="flyout-filters-with-pinned-actions-updated" name="updated-after" type="date">
        </div>
        <div class="forma-field">
          <label class="forma-field__label" for="flyout-filters-with-pinned-actions-text">Contains text</label>
          <textarea id="flyout-filters-with-pinned-actions-text" name="text" rows="4"></textarea>
        </div>
      </div>
      <footer class="forma-flyout__actions">
        <button type="submit" value="clear">Clear all</button>
        <button type="submit" value="apply">Show results</button>
      </footer>
    </form>
  </dialog>
</forma-flyout>

Click or tap the code once to select all of it, then copy.

Scenario

Quick view that closes on outside click

A right flyout for glancing at recent activity. closedby="any" lets a click on the visible strip of page (the backdrop) close it where supported, and the standard motion weight makes it feel lighter than the heavy default. It has no footer, so the body fills the remaining height.

Live demo. 2 native actions work here and are verified by an outcome test.

Last 24 hours

Recent activity

  • Dana moved “Invoice export” to Done.
  • Sam commented on “Rate limit alerts”.
  • Build 1842 finished with 2 warnings.
HTML · Quick view that closes on outside click Raw HTML for HTML · Quick view that closes on outside click
<forma-flyout class="forma-component-tag">
  <button type="button" commandfor="flyout-quick-view-light-dismiss" command="show-modal">Recent activity</button>
  <dialog class="forma-flyout" id="flyout-quick-view-light-dismiss" data-forma-side="right" data-forma-motion-weight="standard" closedby="any" aria-labelledby="flyout-quick-view-light-dismiss-title">
    <div class="forma-flyout__surface">
      <header class="forma-flyout__header">
        <div>
          <p class="forma-component-kicker">Last 24 hours</p>
          <h2 id="flyout-quick-view-light-dismiss-title">Recent activity</h2>
        </div>
        <button class="forma-flyout__close" type="button" commandfor="flyout-quick-view-light-dismiss" command="close" aria-label="Close recent activity">Close</button>
      </header>
      <div class="forma-flyout__body">
        <ul>
          <li>Dana moved “Invoice export” to Done.</li>
          <li>Sam commented on “Rate limit alerts”.</li>
          <li>Build 1842 finished with 2 warnings.</li>
        </ul>
      </div>
    </div>
  </dialog>
</forma-flyout>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Record detail on a phone

A right flyout with record details at phone width. It covers 90% of the width, leaving a strip of the page visible as context.

Live demo. 4 native actions work here and are verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • Width is min(28rem, 90vw): at 320px the panel is 288px wide and a 32px strip of the dimmed page stays visible on the opposite side.
  • Height is 100dvh, so the panel follows the dynamic viewport as mobile browser toolbars show and hide.
  • The header pads its top by env(safe-area-inset-top) and the footer its bottom by env(safe-area-inset-bottom), clearing notches and home indicators in either orientation.
  • Only the body scrolls; the Close button (44px square minimum) and footer actions stay reachable. Footer actions wrap onto new lines when labels are long.
  • There is no swipe-to-close; Close, Escape and the footer actions are the close paths.
HTML · Record detail on a phone Raw HTML for HTML · Record detail on a phone
<forma-flyout class="forma-component-tag">
  <button type="button" commandfor="flyout-mobile-record-detail" command="show-modal">View order 58213</button>
  <dialog class="forma-flyout" id="flyout-mobile-record-detail" data-forma-side="right" aria-labelledby="flyout-mobile-record-detail-title" aria-describedby="flyout-mobile-record-detail-summary">
    <div class="forma-flyout__surface">
      <header class="forma-flyout__header">
        <h2 id="flyout-mobile-record-detail-title">Order 58213</h2>
        <button class="forma-flyout__close" type="button" commandfor="flyout-mobile-record-detail" command="close" aria-label="Close order 58213">Close</button>
      </header>
      <div class="forma-flyout__body forma-stack">
        <p id="flyout-mobile-record-detail-summary">Shipped on 28 September. Delivery expected by 2 October.</p>
        <dl class="forma-key-value-list">
          <div><dt>Customer</dt><dd>Harbour Street Cafe</dd></div>
          <div><dt>Items</dt><dd>6</dd></div>
          <div><dt>Total</dt><dd>€418.20</dd></div>
          <div><dt>Carrier</dt><dd>Parcelnet, tracking 00340434161094042557</dd></div>
        </dl>
      </div>
      <footer class="forma-flyout__actions">
        <button type="button" commandfor="flyout-mobile-record-detail" command="close">Done</button>
      </footer>
    </div>
  </dialog>
</forma-flyout>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Live demo. 8 native actions work here and are verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
commandforinvoker and close buttonsid of the flyout dialog—Connects a button to the flyout.
commandinvoker and close buttonsshow-modal | close—Always open with show-modal; a non-modal show() is not a supported flyout state.
data-forma-sidedialogleft | right—Required. Which viewport edge the panel attaches to and enters from. Without it the panel is not attached to an edge (the browser centers it horizontally) but still slides in from the right.
aria-labelledbydialogid of the header title—Required. Names the flyout.
aria-describedbydialogid—Optional short summary announced on open.
aria-label.forma-flyout__closestring—Names the close button with its object ("Close filters") so several flyouts are distinguishable.
closedbydialogany | closerequest | nonecloserequestany adds light dismiss on backdrop click where supported.
methodform.forma-flyout__surfacedialog—Lets footer submit buttons close the flyout and report their value.
data-forma-motion-weightdialoglight | standard | heavyheavyPresentation-only perceived mass for the slide.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-flyoutBlock class—The panel dialog: fixed, full dynamic-viewport height, min(28rem, 90vw) wide, bordered, shadowed, with contained overscroll and the edge slide transition. Also styles the backdrop.
.forma-flyout__actionsElement class—Pinned footer: wrapping action row aligned to the inline end, with safe-area bottom padding and a top rule.
.forma-flyout__bodyElement class—The only scrolling region, with contained overscroll and 1rem padding.
.forma-flyout__closeElement class—Close button kept at least 44 by 44px and never shrunk by a long title.
.forma-flyout__headerElement class—Pinned top row: title block and close button, spaced apart, with safe-area top padding and a bottom rule.
.forma-flyout__surfaceElement class—Three-row grid (header, flexible body, footer) filling the panel. May be a div or a form method="dialog".
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass: heavy (default for flyouts), standard or light.
[data-forma-side]Attribute hook"left", "right"left attaches the panel to the inline-start edge and enters from the left (--forma-flyout-closed-x: -100%); right attaches to the inline-end edge and enters from the right. The attach edge is logical but the travel is physical, so in right-to-left pages the two do not match.
[open]Attribute hook—Native open state. [open] translates the panel to rest and dims and blurs the backdrop; it also selects spring entry timing.
--forma-flyout-closed-xCustom propertydefault 100%Horizontal offset of the panel while closed and at the start of entry. Set by data-forma-side (-100% left, 100% right).
Keyboard interaction
KeysResult
Enter / Space on the invokerOpens the flyout; focus moves to the first focusable element (normally Close) or an autofocus element.
Tab / Shift+TabCycles through controls inside the flyout; the page behind is inert.
EscapeCloses the flyout and returns focus to the invoker (native modal dialog).
Events
EventDescription
cancel / closeNative dialog events on Escape or light dismiss, and after closing. returnValue holds the submitting button's value when a method="dialog" form closed it.
commandNative event on the dialog when an invoker button targets it.

Form behavior

Controls inside a flyout belong to whatever form contains them. With form method="dialog" as the surface, submitting closes the flyout without a request and sets returnValue; the application reads the field values.

States

Flyout states
StateHow it is expressedPresentation
Closedno open attributeTranslated off its edge by --forma-flyout-closed-x and not displayed once the exit completes.
Open[open] via show-modalAt rest against its edge over a dimmed, blurred backdrop; the page is inert.
Left / rightdata-forma-sideChooses the attach edge and the direction of travel.
Body scrollingcontent taller than the body rowOnly the body scrolls; header and footer stay pinned.

Accessibility

Forma provides

  • Uses native modal dialog behavior for focus containment, inertness, Escape and focus return.
  • Keeps the close control at least 44 by 44px and pinned in the header, and footer actions pinned and wrapping.
  • Pads header and footer for safe-area insets and contains scroll inside the body.
  • Keeps a visible border in forced-colors mode; removes travel and backdrop blur under reduced motion.

Your application supplies

  • Name the flyout with a visible heading and aria-labelledby.
  • Give the close button an accessible name that includes what it closes.
  • Use data-forma-side consistently: the same kind of content should always come from the same edge.
  • For right-to-left pages, verify the side and travel direction; the travel is physical.
  • Implement any swipe, drag or resize behavior in Limen/application code, and never make it the only way to close.

Responsive behavior

  • Width is min(28rem, 90vw) at every size and height is 100dvh; there is no breakpoint.
  • The body is a minmax(0, 1fr) row that scrolls; header and footer keep their natural height.
  • Header title text wraps beside the close button; footer actions wrap onto new rows.
  • Bottom sheets, full-width phone flyouts and persistent side drawers are not provided.

Motion

  • Entry: the panel slides from its edge (--forma-flyout-closed-x) to rest over the heavy inertial duration with spring easing. The backdrop dims and blurs by perceptual interpolation, independent of mass.
  • Exit: where overlay retention is supported, the panel slides back over the same inertial duration and spring easing as entry without changing its viewport geometry. Otherwise native closing is immediate, avoiding retraction into a containing example or application element.
  • data-forma-motion-weight changes perceived mass; heavy is the default. The native open state is authoritative and focus moves immediately.
  • Under prefers-reduced-motion: reduce the edge translation is removed, the backdrop blur is dropped, and the state change is effectively instant.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only

Filters

Refine results

A left-edge modal surface for contextual controls or navigation.

Details

Record context

A right-edge modal surface for detail, inspection, or contextual work.

Status
Needs review
Owner
Application supplied
standardpresentation only

Filters

Refine results

A left-edge modal surface for contextual controls or navigation.

Details

Record context

A right-edge modal surface for detail, inspection, or contextual work.

Status
Needs review
Owner
Application supplied
heavypresentation only

Filters

Refine results

A left-edge modal surface for contextual controls or navigation.

Details

Record context

A right-edge modal surface for detail, inspection, or contextual work.

Status
Needs review
Owner
Application supplied

Usage guidance

Do

  • Use the left edge for navigation and filters and the right edge for detail and inspection, and keep that convention across the product.
  • Keep the primary action in the footer so it is always visible.

Avoid

  • Opening a flyout from another flyout.
  • Putting a multi-step workflow in a flyout; use a page.
  • Making the flyout full width on phones by overriding the width; the visible strip is context.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.