How to Use

Backdrop

Backdrop renders a semi-transparent overlay behind modals, drawers, or any foreground element. It blocks interaction with content behind it and calls onClose when clicked or when Escape is pressed. Always pair Backdrop with isOpen/onClose state management. The backdrop uses the --oks-color-overlay CSS variable for its background color — customize this for light/dark mode adaptation.

import {Backdrop} from "oks-ui"

Backdrop with Modal

The typical pattern: toggle isOpen state with a button, render Backdrop and a modal panel conditionally when isOpen is true. Backdrop must have a higher z-index than the page content but lower than the foreground panel. Clicking the backdrop calls onClose — ideal for dismissible overlays. The modal panel sits above the backdrop with z-50.

function ModalWithBackdrop() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="space-y-4">
      <Button onClick={() => setIsOpen(true)} color="primary">
        Open Modal
      </Button>
      {isOpen && (
        <>
          <Backdrop isOpen={isOpen} onClose={() => setIsOpen(false)} />
          <div className="fixed inset-0 z-50 flex items-center justify-center">
            <div
              className="mx-4 w-full max-w-sm rounded-xl border p-6 shadow-2xl"
              style={{
                backgroundColor: "var(--color-surface)",
                borderColor: "var(--color-border)",
              }}
            >
              <h2 className="text-lg font-semibold">Modal Title</h2>
              <p className="mt-2 text-sm">Content here.</p>
              <div className="mt-4 flex justify-end gap-3">
                <Button variant="soft" onClick={() => setIsOpen(false)}>
                  Cancel
                </Button>
              </div>
            </div>
          </div>
        </>
      )}
    </div>
  );
}

Accessibility

Backdrop manages focus trapping — when active, keyboard focus is confined to the foreground element. The backdrop element has aria-hidden="true" since it is decorative. Escape key triggers onClose. For proper accessibility, ensure the modal/drawer over the backdrop receives focus on open and manages focus within its content. The backdrop's role is presentation-only — it should not receive focus itself.

Props Reference

All available props for Backdrop. See the full API reference page for interactive playground examples.

Prop	Type	Default	Description
isOpen	boolean	`—`	Controls visibility (required).
onClose	() => void	`—`	Called when backdrop is dismissed (required).
closeOnOutsideClick	boolean	`true`	Close when clicking outside content.
closeOnEscape	boolean	`true`	Close on Escape key press.
lockScroll	boolean	`true`	Lock body scroll when open.
blur	boolean \| 'sm' \| 'md' \| 'lg' \| number	`false`	Backdrop blur intensity.
animationType	"fade" \| "zoom" \| "slideUp" \| "slideDown" \| "slideLeft" \| "slideRight"	`"fade"`	Animation style.
zIndex	number	`—`	Custom z-index.
portal	boolean	`true`	Render in a portal.

Best Practices

◆Always pair Backdrop with isOpen/onClose state management — they are required props
◆Backdrop uses z-index layering — ensure your modal/drawer has a z-index above the backdrop (typically z-50 vs z-40)
◆Clicking the backdrop calls onClose by default — ideal for dismissible overlays but can be confusing for forms; consider disabling backdrop dismiss for modal forms
◆To make a non-dismissible modal, simply do not render the Backdrop component (though this is not recommended for UX)
◆The backdrop color is controlled by --oks-color-overlay CSS variable — customize for light/dark themes

View full API reference for Backdrop →