BwOverlay | bw-overlay

Overview

Overlays display content in a floating container with a backdrop. They can be configured to show as a modal, drawer, or bottom sheet. The container has no base styling; you should use bw-view to format the overlay's content.

Usage

Close Buttons

When using a bw-view with the overlay component, it will automatically add a close button for the overlay. If you wish to add more close buttons, or you are not using a bw-view, add data-overlay="close" as an attribute to the desired close button. If the close button needs to show a discard changes prompt for a specific form, set the data-discard-form attribute equal to the id of the form.

<bw-overlay>
  <bw-button slot="trigger">Open Modal</bw-button>
  <bw-view label="Example Modal">
    <bw-form id="closeButtonExampleForm">
      <bw-input></bw-input>
    </bw-form>
    <bw-button data-overlay="close" slot="footer">Cancel (No Discard)</bw-button>
    <bw-button data-overlay="close" data-discard-form="closeButtonExampleForm" slot="footer">Cancel (Discard)</bw-button>
  </bw-view>
</bw-overlay>

Drawers and Bottom Sheets

You can set the side attribute to left or right to present the overlay as drawer, or bottom for a bottom sheet.

<bw-overlay side="left">
  <bw-button slot="trigger">Open Drawer</bw-button>
  <bw-view label="Example Drawer">
    <p>Hello there</p>
  </bw-view>
</bw-overlay>
<bw-overlay side="bottom">
  <bw-button slot="trigger">Open Sheet</bw-button>
  <bw-view label="Example Bottom Sheet">
    <p>Hello there</p>
  </bw-view>
</bw-overlay>

Bottom sheets snap to 40% and 80% of the screen height. If you drag it near the bottom or swipe down, it will auto dismiss.

Modals

By default, overlay will appear centered in the middle of the screen. This is referred to as a modal

<bw-overlay>
  <bw-button slot="trigger">Open Modal</bw-button>
  <bw-view label="Example Modal">
    <p>Hello there</p>
  </bw-view>
</bw-overlay>

When being used as a modal, you can set the size attribute to change the dimensions of the overlay.

<bw-overlay id="overlaySizeEx" size="md">
  <bw-button slot="trigger">Open Modal</bw-button>
  <bw-view label="Example Modal">
    <bw-radio-group id="overlaySizeControl" value="md">
      <bw-radio-button value="xs">XS</bw-radio-button>
      <bw-radio-button value="sm">SM</bw-radio-button>
      <bw-radio-button value="md">MD</bw-radio-button>
      <bw-radio-button value="lg">LG</bw-radio-button>
      <bw-radio-button value="xl">XL</bw-radio-button>
    </bw-radio-group>
  </bw-view>
</bw-overlay>

<script>
  const radioGroup = document.querySelector('#overlaySizeControl')
  const overlay = document.querySelector('#overlaySizeEx')
  radioGroup.addEventListener('valueChange', ({detail}) => {
    overlay.size = detail
  })
</script>

Properties

Property	Attribute	Description	Type	Default
backdropDismiss	backdrop-dismiss	Backdrop will close the overlay on click when enabled	boolean	true
destroy	--	Execute a callback after the overlay has dismissed	() => void | Promise<void>	undefined
init	--	Execute a callback before the overlay starts presenting	() => void | Promise<void>	undefined
open	open	Opens and closes overaly	boolean	false
side	side	Side of the screen where the drawer will be displayed	"bottom" | "left" | "right"	undefined
size	size	Size of the overlay	"lg" | "md" | "sm" | "xl" | "xs"	"md"

Events

Event	Description	Type
overlayDismiss	Emits whenever the overlay has finished closing. Emits the role and optional data object passed to the dismiss() method.	CustomEvent<T>
overlayPresent	Emits whenever the overlay has opened. Does not emit any data	CustomEvent<any>

Methods

dismiss(role?: string, data?: any) => Promise<void>

Dismisses the modal

Parameters

Name	Type	Description
role	string	- The role of the modal
data	any	- The data of the modal

Returns

Type: Promise<void>

present() => Promise<void>

Presents the modal

Returns

Type: Promise<void>

Slots

Slot	Description
"trigger"	The trigger for the overlay

Shadow Parts

Part	Description
"dialog"	The dialog element of the modal
"inner-container"	The inner container of the dialog element

CSS Custom Properties

Name	Description
--background	The background color of the modal
--border	The border of the modal
--color	The color of the modal
--radius	The radius of the modal

Dependencies

Used by

• bw-select

Depends on

• bw-discard-form

Graph

---

© 2025 United Systems & Software - All Rights Reserved.