~/ilker-balcilar
~/ilker-balcilar
ilker-balcilar/projects/tailwind-hitslop· Open Source Library

Open Source Library

tailwind-hitslop

A Tailwind CSS plugin that invisibly expands an element's touch area while its visual size stays the same — the web equivalent of React Native's hitSlop. Works on both v4 (pure-CSS @import) and v3 (config plugin) from one package, zero config, tested against the real Tailwind compiler.

Tailwind CSSCSSTypeScriptVitestBunReactViteGitHub ActionsVercelnpm

livesource

Overview

Small visual targets — 16px icons, dense toolbars, close buttons — are miserable to tap. Making them visually bigger is not always an option. React Native solves this with the hitSlop prop; the web never had a first-class equivalent.

tailwind-hitslop brings that concept to Tailwind CSS — both v4 and v3 — as a set of utilities that expand the interactive area of an element without touching its layout:

<button class="pointer-coarse:hit-slop-2">
  <x-icon class="size-4" />
</button>

How It Works

Each utility renders an absolutely-positioned ::before pseudo-element with negative offsets driven by per-side private custom properties. Because every directional utility sets only its own variable and repeats an identical pseudo-element block, utilities stack and merge cleanly in the cascade:

<button class="hit-slop-x-1 hit-slop-y-3">4px horizontal, 12px vertical</button>

On Tailwind v4 the whole thing is a single hand-written CSS file built on the CSS-first primitives — @utility, --value() and --spacing() — pulled in with one @import "tailwind-hitslop" and no JavaScript at all. On v3 the same package exposes a classic config plugin you register with require("tailwind-hitslop"), generating the identical utilities. The export map resolves the right entry per import style, so a single package name covers both majors with no configuration either way. Values resolve from the spacing scale (hit-slop-2), arbitrary lengths (hit-slop-[10px]) and an opt-in --hit-slop-* theme namespace.

Key Features

  • Directional control — hit-slop-t/r/b/l/x/y-* mirror core's inset family and stack freely
  • ::after fallback family — a full mirror for elements whose ::before is already taken by icons, rings or gradients
  • hit-slop-debug — visualizes the expanded hit areas with a radius-faithful overlay
  • Variant composition — works with every core variant (pointer-coarse:, hover:, md:) since the output is just standard utilities on both v4 and v3

Honest Documentation as a Feature

The README documents the failure modes most utility libraries hide: ancestor overflow: hidden silently clipping the expanded area, overlapping slops in dense layouts, and — most importantly — the fact that invisible hit areas do not make WCAG 2.5.8 target-size audits pass. Users who need audit compliance are pointed at min-h-11 min-w-11 instead, and the two approaches combine.

Testing Against the Real Compiler

Instead of asserting on hand-written expectations, the test suite compiles candidate classes through the actual Tailwind v4 compiler using @tailwindcss/node and asserts on the emitted CSS — value resolution, declaration dropping, variant wrapping, theme-token generation and the coexistence of both pseudo-element families.

Links

highlights

  • One package, two Tailwind majors — a pure-CSS @import on v4 and a config plugin on v3, resolved automatically by the export map with identical utilities on both
  • Compile-tested against the real Tailwind compiler via @tailwindcss/node — asserts on emitted CSS, not hand-written expectations
  • Published to npm with GitHub Actions provenance and an interactive demo site