What Input

5.2.12 · active · verified Sun Apr 19

what-input is a client-side JavaScript utility designed to accurately track the user's current input method, distinguishing between mouse, keyboard, and touch interactions. It operates by listening for specific DOM events (mousedown, keydown, touchstart) and dynamically applies `data-whatinput` and `data-whatintent` attributes to the `window` object, making the current input state accessible via CSS or a simple JavaScript API. Currently at version 5.2.12, the package maintains an active release cadence, primarily focusing on bug fixes, TypeScript definition enhancements, and minor feature additions. A key feature is its default use of session storage to persist input/intent across page navigations, improving user experience by maintaining context. It also smartly manages form interactions, preserving the `data-whatintent` as `mouse` even when a user types into form fields, preventing unnecessary input state changes.

Common errors

```
whatInput is not defined
```
cause The `what-input` script or module was not loaded or initialized before being accessed, or it was imported as a global side-effect (`import 'what-input';`) without assigning the `whatInput` API to a variable.

fix Ensure `what-input` is correctly imported and that the `whatInput` default export is assigned: `import whatInput from 'what-input';`. If using a script tag, ensure it is loaded before your consuming script.
```
Keyboard focus outlines are missing on my site.
```
cause This typically occurs when the provided CSS `[data-whatintent='mouse'] *:focus { outline: none; }` is applied without also implementing custom, visible focus styles for keyboard users, thus removing the browser's default outlines.

fix Provide alternative `:focus` styles that clearly indicate the active element for keyboard users. Refer to WCAG 2.0 2.4.7 for guidelines on visible focus. Only remove default outlines if an accessible alternative is in place.
```
Input method is incorrect after navigating to a new page.
```
cause `what-input` persists the input method and intent across pages using `sessionStorage` by default. This might cause the 'previous' input type to show up before a new interaction on the loaded page.

fix If this persistence behavior is undesired, disable it by adding the `data-whatpersist="false"` attribute to your `<html>` or `<body>` tag. Alternatively, call `whatInput.clearStorage()` programmatically when you need to explicitly reset the stored state.

Warnings

breaking The transition to `what-input` v5 introduced changes framed as 'more information and less opinion'. While not explicitly detailing API breaks in the README, this implies potential shifts in default behaviors, new primary data attributes (`data-whatinput`, `data-whatintent`), and potentially how certain inputs are categorized compared to previous major versions. Developers upgrading from v4 or earlier should thoroughly review the official changelog for specific impacts.
Fix: Consult the `what-input` v5 changelog and documentation. Update CSS selectors and JavaScript API calls if prior versions' behaviors or attributes were relied upon.
gotcha Applying `outline: none` to elements for mouse users without providing alternative, visible focus styles for keyboard navigation creates significant accessibility barriers. `what-input` provides a CSS selector (`[data-whatintent='mouse'] *:focus { outline: none; }`) to assist with this, but developers are solely responsible for ensuring other accessible focus indicators are present for keyboard users.
Fix: Always provide clear, visible `:focus` styles for keyboard users. Refer to WCAG 2.0 Guideline 2.4.7 ('Focus Visible') for best practices. Only remove default outlines if an accessible alternative is in place.
gotcha `what-input` uses `sessionStorage` by default to persist the detected input method and intent across page loads. This can be an unexpected behavior for developers anticipating a fresh input state on each page, potentially leading to inconsistencies if not explicitly managed.
Fix: To disable persistence, add the `data-whatpersist="false"` attribute to your `<html>` or `<body>` tag. Alternatively, call `whatInput.clearStorage()` programmatically when you need to reset the stored state.
gotcha Prior to version 5.2.12, the initial value of `shouldPersist` was not correctly aligned with `DOMContentLoaded`, potentially leading to `sessionStorage` being set before the DOM was fully ready. This could cause minor timing issues or unnecessary storage writes in specific edge cases.
Fix: Upgrade to `what-input` v5.2.12 or later to ensure that persistence logic correctly respects DOM readiness and avoids premature `sessionStorage` interactions.

Install

npm install what-input npm
yarn add what-input yarn
pnpm add what-input pnpm

Imports

what-input-global
```
import 'what-input';
```
Imports `what-input` for its global side-effects, enabling data attributes on the `window` object without needing to interact with its API directly. This is common for CSS-only usage.
whatInput
wrong:
```
const whatInput = require('what-input'); // CommonJS in ESM context, or before v5
```
correct:
```
import whatInput from 'what-input';
```
Imports the default export, which provides the `whatInput` API object for programmatic interaction (e.g., `whatInput.ask()`). This is the standard way to use the API in modern JavaScript environments.
whatInput
wrong:
```
import whatInput from 'what-input'; // In CommonJS-only environments (older Node.js)
```
correct:
```
const whatInput = require('what-input');
```
CommonJS `require` syntax for Node.js environments or older bundlers. The `whatInput` API object is assigned directly to the variable.

Quickstart

This quickstart demonstrates how to import `what-input`, query the current input method and intent using its API, and observe how it updates data attributes on the `window` and body. It also highlights how to set up basic logging and interaction, alongside a note on persistence.

import whatInput from 'what-input';

// Ensure the DOM is fully loaded before trying to access or manipulate elements
document.addEventListener('DOMContentLoaded', () => {
  console.log('what-input module loaded.');

  // Function to update input display and log current state
  const logInputState = () => {
    const currentInput = whatInput.ask();
    const currentIntent = whatInput.ask('intent');
    console.log(`Current Input: ${currentInput}, Current Intent: ${currentIntent}`);

    // Update a display element or body attribute for visual feedback
    const inputDisplay = document.getElementById('input-display');
    if (inputDisplay) {
      inputDisplay.textContent = `Input: ${currentInput}, Intent: ${currentIntent}`;
    }
    document.body.setAttribute('data-current-input', currentInput);
    document.body.setAttribute('data-current-intent', currentIntent);
  };

  // Initial log of input state
  logInputState();

  // Add listeners to trigger state updates (what-input does this internally, but for demonstration)
  document.addEventListener('mousedown', logInputState);
  document.addEventListener('keydown', logInputState);
  document.addEventListener('touchstart', logInputState);

  // Example of how to add an element for demonstration
  const displayDiv = document.createElement('div');
  displayDiv.id = 'input-display';
  displayDiv.style.marginTop = '20px';
  displayDiv.style.padding = '10px';
  displayDiv.style.border = '1px solid #ccc';
  document.body.appendChild(displayDiv);

  // Example of checking persistence status
  const persistStatus = document.documentElement.dataset.whatpersist || 'default (enabled via sessionStorage)';
  console.log(`Persistence status (data-whatpersist attribute on html/body): ${persistStatus}`);

  // To disable persistence on a page, add this to your html/body tag:
  // <html data-whatpersist="false">...
  // Or programmatically:
  // whatInput.clearStorage(); // Clears existing stored state
});

view raw JSON →