Overlays

ClickAwayListener

Headless utility that calls a function when the user clicks or taps outside a subtree.

import { ClickAwayListener } from '@lostgradient/cinder/click-away-listener';
overlayutility
01

Overview

Headless utility that calls a function when the user clicks or taps outside a subtree.

Usage

svelte 
<script lang="ts">
  import Button from '@lostgradient/cinder/button';
  import ClickAwayListener from '@lostgradient/cinder/click-away-listener';

  let open = $state(false);
</script>

<Button onclick={() => (open = true)}>Open inline editor</Button>

{#if open}
  <ClickAwayListener
    onClickAway={() => (open = false)}
    style="
      display: inline-flex;
      flex-direction: column;
      gap: var(--cinder-space-3);
      margin-block-start: var(--cinder-space-4);
      padding: var(--cinder-space-4);
      border: 1px solid var(--cinder-border);
      border-radius: var(--cinder-radius-lg);
      background: var(--cinder-surface-raised);
    "
  >
    <p style="margin: 0;">Click outside this box to dismiss it.</p>
    <Button variant="secondary" onclick={() => (open = false)}>Close</Button>
  </ClickAwayListener>
{/if}

Guidance

Use When

  • Building a custom inline-edit field, custom dropdown, or any overlay that should close on outside interaction.

Avoid When

  • Using Popover, Dropdown, or Modal — those handle click-away internally.
Live preview
02

When to use

Use when
  • Building a custom inline-edit field, custom dropdown, or any overlay that should close on outside interaction.
Avoid when
  • Using Popover, Dropdown, or Modal — those handle click-away internally.
03

Examples

Basic click-away listener

Calls a function when the user presses a pointer outside the wrapped subtree.

04

Props

Props for click-away-listener
NameTypeDefaultDescription
onClickAway required (event: PointerEvent | MouseEvent | TouchEvent) => void Called with the triggering PointerEvent (or MouseEvent/TouchEvent on browsers that do not support the Pointer Events API) when the user presses a pointer device outside the root element.
enabled boolean true When false the document listener is detached and onClickAway is never called. Defaults to true.
children required snippet Content rendered inside the root element. Required.