Overlays

One does not simply click outside a menu. Set up overlays once, and see why the first outside click only closes them.

A select, a menu, a dialog and a modal popover shut the rest of the page while open. An outside click only closes them, the page doesn't scroll, and screen readers see only the open panel.

Setup

Wrap the app in ConfigProvider once, with :scroll-body="false":

<script setup lang="ts">
import { ConfigProvider } from 'reka-ui'
</script>

<template>
  <ConfigProvider :scroll-body="false">
    <RouterView />
  </ConfigProvider>
</template>

While an overlay locks scrolling, Kappa UI keeps the scrollbar's space on <html>, so neither the page nor a fixed header moves. Skip the setup, and Reka UI also pads <body> for the missing scrollbar: the page shifts sideways by the scrollbar's width whenever an overlay opens. Overlays from other libraries that pad <body> need that turned off too.

What the scrollbar does to the page
Without the setup
Menu closed
Menu open

The page jumps left by the scrollbar’s width.

With :scroll-body="false"
Menu closed
Menu open

Nothing moves.

  • The content’s edge with the menu closed
  • The scrollbar, hidden while the menu is open
  • Where the button was
  • Padding the overlay adds to <body>

Testing on a Mac or a phone? You won't see the shift there, since their scrollbars float over the page by default. Your Windows users will.

The first outside click

Open the select or the menu below, then press the button in the corner. The first press only closes the overlay.

Overlay scrim

While a select, a menu or a modal popover is open, an invisible scrim covers the window under it. The first outside click lands on the scrim, closes the overlay and goes no further, even over elements that would otherwise catch it, such as a button in a floating toolbar. The release can't land on the element underneath either. The next click works as usual.

Non-modal overlays, such as a popover without modal or a menu with :modal="false", have no scrim. An outside click closes them and reaches whatever it lands on.

Rendering into a container

Overlays render at the end of <body>. Need them somewhere else, such as inside an element shown with the Fullscreen API, where nothing outside it is visible? Provide the container to the components inside it:

<script setup lang="ts">
import { provideOverlayPortalTarget } from '@kappa-ui/core/overlay'

const container = ref<HTMLElement>()
provideOverlayPortalTarget(container)
</script>

<template>
  <div ref="container">
    <!-- selects, menus and popovers in here render into the container -->
  </div>
</template>

Next