Haptics

Haptics are on by default and are part of this library—patterns, WebHaptics, and helpers are bundled with web-haptics-toast, not a separate install. On supported devices, each toast triggers a short vibration so feedback feels closer to native apps. See also the <Toaster /> API for a concise prop list.

Quick usage

import { Toaster } from 'web-haptics-toast';
import 'web-haptics-toast/dist/styles.css';
 
export function App() {
  return <Toaster />;
}

haptics defaults to true, so you only need to pass props when you want to change behavior.

Manual haptics: buttons, forms, anywhere

You can use the library in two complementary ways:

1. Automatic (default) — With <Toaster />, each toast plays a haptic that matches its type (toast.success → success pattern, etc.).
2. Manual / selective — Turn off toast-driven haptics, then call triggerHaptic only where you want vibration (button onClick, onSubmit, keyboard shortcuts, game actions, etc.).

import { Toaster, toast, triggerHaptic } from 'web-haptics-toast';
import 'web-haptics-toast/dist/styles.css';
 
export function App() {
  return (
    <>
      {/* No vibration when these toasts appear */}
      <Toaster haptics={false} />
 
      <button
        type="button"
        onClick={() => {
          `triggerHaptic`('success');
          `toast`('Saved');
        }}
      >
        Save (manual haptic + toast)
      </button>
 
      <button
        type="button"
        onClick={() => `toast`('Silent banner', { haptics: false })}
      >
        Toast without haptic (per-toast)
      </button>
 
      <button
        type="button"
        onClick={() => {
          `triggerHaptic`('selection');
          void runSideEffect();
        }}
      >
        No toast — haptic only
      </button>
    </>
  );
}

On desktop, pass { debug: true } to triggerHaptic to hear the pattern while you build (independent of <Toaster hapticsDebug />, though you can enable both).

`triggerHaptic`('medium', { debug: true });

Props

haptics

Enable or disable automatic haptics when toasts from this <Toaster /> are shown. Does not remove your ability to call triggerHaptic elsewhere.

<Toaster haptics={false} />

hapticsDebug

When true, plays the pattern as audio on desktop for development and QA. On phones that vibrate, you still get real haptics; debug may add sound on top depending on the environment.

<Toaster haptics hapticsDebug />

hapticsShowSwitch

Shows a small built-in on-screen toggle (showSwitch on the internal engine) so people can turn feedback off without you building custom UI.

<Toaster haptics hapticsShowSwitch />

hapticPatternMap

Map each toast type to a named pattern. Names must match the presets shipped in this package: success, error, warning, light, medium, heavy, soft, rigid, selection, nudge, buzz. (That vocabulary matches common web vibration tooling so patterns are easy to remember.)

Defaults (when you don’t pass a map) include e.g. success → success, error → error, warning → warning, info / loading / default → light.

<Toaster
  haptics
  hapticPatternMap={{
    success: 'success',
    error: 'error',
    warning: 'warning',
    info: 'selection',
    default: 'light',
  }}
/>

Programmatic helpers

Exports for use outside the toast pipeline (or alongside <Toaster haptics={false} />):

• isHapticsSupported – Returns true on modern browsers and iOS (via the switch workaround).
• triggerHaptic(name, options?) – fire a built-in preset by name from any event handler. Options include debug?: boolean (sound on desktop) and intensity (see types). Uses a small internal singleton, separate from each <Toaster />’s engine.
• WebHaptics / defaultPatterns – own your instance and timing; both are exported from web-haptics-toast.

Compatibility

While official MDN docs  state that Safari doesn’t support the Vibration API, this library implements a sophisticated workaround for iOS Safari that provides tactile feedback comparable to native apps.

Tips

• Keep patterns subtle for frequent toasts (e.g. selection / light).
• Use stronger patterns for rare, important outcomes (success / error).
• Offer a user-facing way to disable haptics where your product has accessibility or preference settings.