Getting started

BEFORE YOU START

Choose a binding

sparsh separates its interaction engine from its platform adapters and framework bindings. Use the binding that matches your app; the React, Vue, Angular, SolidJS, and Svelte bindings install the browser DOM adapter for you.

A small naming note: sparsh means “touch” in Sanskrit.

Install the package that matches your app. The React, Vue, Angular, SolidJS, and Svelte bindings bring in @sparshlabs/dom automatically; install it directly only for vanilla JS or a custom host.

npm install @sparshlabs/dom

See DOM / vanilla API for the direct createGuard usage.

01 · REACT

Wrap the part of the app you want to protect

Add one provider near the root of the interactive surface. It observes activations in that subtree, so most controls do not need a sparsh-specific prop or wrapper.

npm install @sparshlabs/react

import { ActivationGuardProvider } from '@sparshlabs/react'

export function App() {
  return (
    <ActivationGuardProvider mode="enforce">
      <YourApp />
    </ActivationGuardProvider>
  )
}

The provider is a client component and attaches its DOM listeners in an effect. In React Server Component apps, place it in a client boundary. See the React API reference for hooks, callbacks, and provider options.

02 · VUE

Use the provider as a layout boundary

The Vue provider makes its guard available to descendants through Vue’s provide/inject mechanism. It attaches after mount and removes its listeners when unmounted.

npm install @sparshlabs/vue

<script setup lang="ts">
import { ActivationGuardProvider } from '@sparshlabs/vue'
</script>

<template>
  <ActivationGuardProvider mode="enforce">
    <YourApp />
  </ActivationGuardProvider>
</template>

See the Vue API reference for Composition API patterns and props.

03 · ANGULAR

Put the directive on the element you want to protect

The sparshGuard directive guards the element it’s placed on and everything inside it, without adding a wrapper. It attaches after the first render, never runs during server-side rendering, and removes its listeners when the element is destroyed. To guard the whole document instead, add provideActivationGuard() to your application config.

npm install @sparshlabs/angular

import { Component } from '@angular/core'
import { ActivationGuardDirective } from '@sparshlabs/angular'

@Component({
  selector: 'app-root',
  imports: [ActivationGuardDirective],
  template: `
    <main sparshGuard mode="enforce">
      <app-shell />
    </main>
  `,
})
export class AppComponent {}

See the Angular API reference for the provider, the element-feedback directive, and inputs.

04 · SOLIDJS

Wrap the part of the app you want to protect

The SolidJS provider shares its guard with descendants through Solid context. It attaches in an effect after the first render, never runs during server-side rendering, and removes its listeners when it is disposed, so it works unchanged in SolidStart.

npm install @sparshlabs/solidjs

import { ActivationGuardProvider } from '@sparshlabs/solidjs'

export function App() {
  return (
    <ActivationGuardProvider mode="enforce">
      <YourApp />
    </ActivationGuardProvider>
  )
}

See the SolidJS API reference for the element-feedback hook and props.

05 · SVELTE

Wrap the part of the app you want to protect

The Svelte provider shares its guard with descendants through Svelte context. It attaches in an effect after the first render, never runs during server-side rendering, and removes its listeners when it is destroyed, so it works unchanged in SvelteKit. It requires Svelte 5.

npm install @sparshlabs/svelte

<script lang="ts">
  import { ActivationGuardProvider } from '@sparshlabs/svelte'
  import YourApp from './YourApp.svelte'
</script>

<ActivationGuardProvider mode="enforce">
  <YourApp />
</ActivationGuardProvider>

See the Svelte API reference for the element-feedback hook and props.

06 · OBSERVE THE RESULT

Make a block understandable

Enforce mode is the default. A suspicious activation can be stopped, and onDecision tells you whether a decision was allowed or enforced. Render a status message or record the policy and input kind for diagnostics; avoid logging sensitive user content.

import type { Decision } from '@sparshlabs/react'

function recordDecision(decision: Decision) {
  if (decision.enforced) {
    analytics.track('activation_blocked', {
      policy: decision.policy,
      kind: decision.event.kind,
    })
  }
}

Use report mode when tuning a policy: it still reports suspicious decisions, but lets the activation through. decision.allowed is the policy verdict; decision.enforced tells you whether sparsh actually blocked the interaction.

NEXT STEPS

Understand the signals before tuning them

• Core concepts explains modes, policies, accessibility behavior, and known limits.
• DOM / vanilla API covers low-level integration and cleanup.
• The playground lets you try the guard against moving interfaces.