# @solid-primitives/interaction
[](https://turborepo.org/)
[](https://bundlephobia.com/package/@solid-primitives/interaction)
[](https://www.npmjs.com/package/@solid-primitives/interaction)
[](https://github.com/solidjs-community/solid-primitives#contribution-process)
[](https://vitest.dev)
Primitives for detecting and hiding interactions that originate **outside** a given element, and for hiding off-screen content from assistive technologies. Useful for building accessible dismissible UI components such as dropdowns, popovers, dialogs, and tooltips.
## Installation
```bash
npm install @solid-primitives/interaction
# or
yarn add @solid-primitives/interaction
# or
pnpm add @solid-primitives/interaction
```
## `makeInteractOutside`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, onCleanup } from "solid-js";
import { makeInteractOutside } from "@solid-primitives/interaction";
function Demo() {
const [status, setStatus] = createSignal("Not listening");
let box!: HTMLDivElement;
let cleanup: (() => void) | undefined;
onCleanup(() => cleanup?.());
const attach = () => {
cleanup?.(); // the returned function removes the listeners
cleanup = makeInteractOutside(box, {
onPointerDownOutside: () => setStatus("Pointer down outside"),
onFocusOutside: () => setStatus("Focus moved outside"),
});
setStatus("Listening — click or tab outside the box");
};
return (
<>
{status()}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
function makeInteractOutside(
el: T,
options: MakeInteractOutsideOptions,
): () => void;
```
A non-reactive, pure-ref primitive. Attaches outside-interaction listeners to `el` immediately and returns a cleanup function. Use this when you already have a stable element reference and don't need reactive re-attachment.
```ts
import { makeInteractOutside } from "@solid-primitives/interaction";
const cleanup = makeInteractOutside(el, {
onInteractOutside: () => close(),
});
// later, to remove listeners:
cleanup();
```
## `interactOutside`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, Show } from "solid-js";
import { interactOutside } from "@solid-primitives/interaction";
function Demo() {
const [open, setOpen] = createSignal(false);
let trigger!: HTMLButtonElement;
return (
<>
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
function interactOutside(options: MakeInteractOutsideOptions): (el: Element) => void;
```
A ref factory for `makeInteractOutside`. The most concise way to build dismissable UI — pass the result directly to a JSX `ref` prop and the element will close itself when the user interacts outside it. Cleanup is registered via `onCleanup` in the component's reactive scope, so listeners are removed automatically when the component disposes — no signal ref needed.
```tsx
import { createSignal, Show } from "solid-js";
import { interactOutside } from "@solid-primitives/interaction";
function Popover() {
const [open, setOpen] = createSignal(false);
return (
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
function createInteractOutside(
options: CreateInteractOutsideOptions,
ref: Accessor,
): void;
```
Reactive wrapper around `makeInteractOutside`. Sets up document-level event listeners that fire whenever the user interacts outside the element returned by `ref`. Re-attaches automatically when `ref` or `options.disabled` changes. Cleans up with the reactive owner.
### Options
| Option | Type | Description |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `disabled` | `MaybeAccessor` | Disables all listeners when `true`. Reactive — can be an accessor. |
| `shouldExcludeElement` | `(element: Element) => boolean` | Return `true` to suppress handlers for a specific element. |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | Fired when a `pointerdown` event occurs outside `ref`. Call `event.preventDefault()` to stop `onInteractOutside` from firing. |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | Fired when focus moves outside `ref`. Call `event.preventDefault()` to stop `onInteractOutside` from firing. |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | Fired for any outside interaction — both pointer and focus. Always fires after the specific handler unless that handler called `preventDefault`. |
### Event types
All handlers receive a `CustomEvent` that wraps the original DOM event.
```ts
type EventDetails = {
originalEvent: T; // the original PointerEvent or FocusEvent
isContextMenu: boolean; // true for right-click / Ctrl+click on Mac
};
type PointerDownOutsideEvent = CustomEvent>;
type FocusOutsideEvent = CustomEvent>;
type InteractOutsideEvent = PointerDownOutsideEvent | FocusOutsideEvent;
```
## Usage
### Dismiss a popover on outside interaction
```tsx
import { createSignal, Show } from "solid-js";
import { createInteractOutside } from "@solid-primitives/interaction";
function Popover() {
const [ref, setRef] = createSignal();
const [open, setOpen] = createSignal(false);
createInteractOutside({ onInteractOutside: () => setOpen(false) }, ref);
return (
Popover content
);
}
```
### Using individual focus and pointer handlers
```tsx
import { createSignal } from "solid-js";
import { createInteractOutside } from "@solid-primitives/interaction";
function Tooltip() {
const [ref, setRef] = createSignal();
createInteractOutside(
{
onPointerDownOutside(e) {
console.log("Clicked outside", e.detail.originalEvent);
},
onFocusOutside(e) {
// Prevent onInteractOutside from also firing
e.preventDefault();
console.log("Focus moved outside");
},
onInteractOutside() {
console.log("Any outside interaction");
},
},
ref,
);
return
;
}
```
### Excluding specific elements
```tsx
import { createSignal } from "solid-js";
import { createInteractOutside } from "@solid-primitives/interaction";
function Dropdown() {
const [ref, setRef] = createSignal();
const [triggerRef, setTriggerRef] = createSignal();
createInteractOutside(
{
// Prevent the trigger button from closing the dropdown when clicked
shouldExcludeElement: el => el === triggerRef() || !!triggerRef()?.contains(el),
onInteractOutside: () => {
/* close */
},
},
ref,
);
return (
<>
Dropdown content
>
);
}
```
### Using the ref factory
`interactOutside` is the most concise option when you don't need a signal ref:
```tsx
import { createSignal, Show } from "solid-js";
import { interactOutside } from "@solid-primitives/interaction";
function Menu() {
const [open, setOpen] = createSignal(false);
return (
setOpen(false) })}>
Item 1
);
}
```
### Using the base primitive imperatively
`makeInteractOutside` is the right choice outside of JSX — custom directives, imperative setups, or tests:
```ts
import { makeInteractOutside } from "@solid-primitives/interaction";
const cleanup = makeInteractOutside(el, {
onInteractOutside: () => close(),
});
// later:
cleanup();
```
---
## `ariaHideOutside`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, onCleanup } from "solid-js";
import { ariaHideOutside } from "@solid-primitives/interaction";
function Demo() {
const [hiding, setHiding] = createSignal(false);
let root!: HTMLDivElement;
let dialog!: HTMLDivElement;
let cleanup: (() => void) | undefined;
onCleanup(() => cleanup?.());
const toggle = () => {
cleanup = cleanup ? void cleanup() : ariaHideOutside([dialog], root);
setHiding(!!cleanup);
};
return (
<>
Background paragraph
Dialog (stays visible)
Another background paragraph
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
function ariaHideOutside(
targets: Element[],
root?: HTMLElement,
alwaysVisibleSelector?: string,
): () => void;
```
A non-reactive, imperative primitive. Walks the DOM from `root` (defaults to `document.body`) and sets `aria-hidden="true"` on every element that is not an ancestor of, or contained within, one of `targets`. A `MutationObserver` watches for newly added nodes and hides them automatically. Returns a cleanup function that removes all `aria-hidden` attributes added by this call.
Ref-counted — nested calls cooperate correctly so that tearing down an inner layer does not accidentally reveal content that an outer layer is still hiding.
```ts
import { ariaHideOutside } from "@solid-primitives/interaction";
const cleanup = ariaHideOutside([dialogEl]);
// when the dialog closes:
cleanup();
```
Pass `alwaysVisibleSelector` to exempt elements matched by a CSS selector from being hidden regardless of their position in the tree (useful for live-region announcers or top-layer elements):
```ts
const cleanup = ariaHideOutside([dialogEl], document.body, "[aria-live]");
```
## `createHideOutside`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createHideOutside } from "@solid-primitives/interaction";
function Demo() {
const [open, setOpen] = createSignal(false);
const [root, setRoot] = createSignal();
const [dialog, setDialog] = createSignal();
createHideOutside({
targets: () => (dialog() ? [dialog()!] : []),
root,
disabled: () => !open(),
inert: true,
});
return (
<>
Background content (hidden + inert while open)
Dialog content
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
function createHideOutside(options: CreateHideOutsideOptions): void;
```
Reactive wrapper around `ariaHideOutside`. Re-runs whenever `targets`, `root`, or `disabled` changes and cleans up the previous hide pass automatically. Integrates with the reactive owner so everything is torn down when the component or scope disposes.
### Options
| Option | Type | Description |
| ----------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `targets` | `MaybeAccessor` | The elements that should remain visible (and their ancestors / descendants). Reactive — can be an accessor. |
| `root` | `MaybeAccessor` | Subtree to walk. Defaults to `document.body`. Reactive — can be an accessor. |
| `disabled` | `MaybeAccessor` | Skips hiding entirely when `true`. Reactive — can be an accessor. |
| `alwaysVisibleSelector` | `string` | CSS selector for elements that must never be hidden (e.g. `"[aria-live]"` for live-region announcers). Static. |
```tsx
import { createSignal, Show } from "solid-js";
import { createHideOutside } from "@solid-primitives/interaction";
function Dialog(props: { open: boolean }) {
const [ref, setRef] = createSignal();
createHideOutside({
targets: () => (ref() ? [ref()!] : []),
disabled: () => !props.open,
});
return (
Dialog content
);
}
```
### Combining with `createInteractOutside`
A fully accessible dismissible dialog uses both primitives together — `createHideOutside` removes the background from the accessibility tree while `createInteractOutside` closes the dialog on outside pointer or focus events:
```tsx
import { createSignal, Show } from "solid-js";
import { createHideOutside, createInteractOutside } from "@solid-primitives/interaction";
function Modal(props: { open: boolean; onClose: () => void }) {
const [ref, setRef] = createSignal();
createHideOutside({
targets: () => (ref() ? [ref()!] : []),
disabled: () => !props.open,
});
createInteractOutside(
{
disabled: () => !props.open,
onInteractOutside: props.onClose,
},
ref,
);
return (
Modal content
);
}
```
## Changelog
See [CHANGELOG.md](./CHANGELOG.md)
## Credits
Based on primitives from [Kobalte](https://kobalte.dev), adapted for Solid 2.0 and the Solid Primitives ecosystem:
- [`createInteractOutside`](https://github.com/kobaltedev/kobalte/blob/main/packages/core/src/primitives/create-interact-outside/create-interact-outside.ts) — Kobalte, MIT, Copyright (c) 2022 Kobalte contributors
- [`createHideOutside`](https://github.com/kobaltedev/kobalte/blob/main/packages/core/src/primitives/create-hide-outside/create-hide-outside.ts) — Kobalte, MIT, Copyright (c) 2022 Kobalte contributors
Kobalte's implementation draws from:
- [Radix UI Primitives](https://github.com/radix-ui/primitives) — MIT, Copyright (c) 2022 WorkOS
- [Zag by Chakra UI](https://github.com/chakra-ui/zag) — MIT, Copyright (c) 2021 Chakra UI