• Version 14.5.2
  • Published
  • 435 kB
  • No dependencies
  • MIT license


npm i @testing-library/user-event
yarn add @testing-library/user-event
pnpm add @testing-library/user-event


Fire events the same way the user does



variable userEvent

const userEvent: {
readonly setup: typeof setupMain;
readonly clear: typeof directApi.clear;
readonly click: typeof directApi.click;
readonly copy: typeof directApi.copy;
readonly cut: typeof directApi.cut;
readonly dblClick: typeof directApi.dblClick;
readonly deselectOptions: typeof directApi.deselectOptions;
readonly hover: typeof directApi.hover;
readonly keyboard: typeof directApi.keyboard;
readonly pointer: typeof directApi.pointer;
readonly paste: typeof directApi.paste;
readonly selectOptions: typeof directApi.selectOptions;
readonly tripleClick: typeof directApi.tripleClick;
readonly type: typeof directApi.type;
readonly unhover: typeof directApi.unhover;
readonly upload: typeof directApi.upload;
readonly tab: typeof directApi.tab;


    interface keyboardKey

    interface keyboardKey {}

      property altGr

      altGr?: boolean;
      • Does the character in key require/imply AltRight to be pressed?

      property code

      code?: string;
      • Physical location on a keyboard

      property key

      key?: string;
      • Character or functional key descriptor

      property location

      location?: DOM_KEY_LOCATION;
      • Location on the keyboard for keys with multiple representation

      property shift

      shift?: boolean;
      • Does the character in key require/imply a shiftKey to be pressed?

      interface Options

      interface Options {}

        property advanceTimers

        advanceTimers?: ((delay: number) => Promise<void>) | ((delay: number) => void);
        • A function to be called internally to advance your fake timers (if applicable)

          Example 1


        property applyAccept

        applyAccept?: boolean;
        • When using userEvent.upload, automatically discard files that don't match an accept property if it exists.


        property autoModify

        autoModify?: boolean;
        • We intend to automatically apply modifier keys for printable characters in the future. I.e. A implying {Shift>}a{/Shift} if caps lock is not active.

          This options allows you to opt out of this change in foresight. The feature therefore will not constitute a breaking change.


        property delay

        delay?: number | null;
        • Between some subsequent inputs like typing a series of characters the code execution is delayed per setTimeout for (at least) delay seconds. This moves the next changes at least to next macro task and allows other (asynchronous) code to run between events.

          null prevents setTimeout from being called.


        property document

        document?: Document;
        • The document.

          This defaults to the owner document of an element if an API is called directly with an element and without setup. Otherwise it falls back to the global document.


        property keyboardMap

        keyboardMap?: keyboardKey[];
        • An array of keyboard keys the keyboard device consists of.

          This allows to plug in different layouts / localizations.

          Defaults to a "standard" US-104-QWERTY keyboard.

        property pointerEventsCheck

        pointerEventsCheck?: PointerEventsCheckLevel | number;
        • The pointer API includes a check if an element has or inherits pointer-events: none. This check is known to be expensive and very expensive when checking deeply nested nodes. This option determines how often the pointer related APIs perform the check.

          This is a binary flag option. You can combine multiple Levels.


        property pointerMap

        pointerMap?: pointerKey[];
        • An array of available pointer keys.

          This allows to plug in different pointer devices.

        property skipAutoClose

        skipAutoClose?: boolean;
        • userEvent.type automatically releases any keys still pressed at the end of the call. This option allows to opt out of this feature.


        property skipClick

        skipClick?: boolean;
        • userEvent.type implies a click at the end of the element content/value. This option allows to opt out of this feature.


        property skipHover

        skipHover?: boolean;
        • userEvent.click implies moving the cursor to the target element first. This options allows to opt out of this feature.


        property writeToClipboard

        writeToClipboard?: boolean;
        • Write selected data to Clipboard API when a cut or copy is triggered.

          The Clipboard API is usually not available to test code. Our setup replaces the navigator.clipboard property with a stub.

          Defaults to false when calling the APIs directly. Defaults to true when calling the APIs per setup.

        interface pointerKey

        interface pointerKey {}

          property button

          button?: MouseButton;
          • Type of button

          property name

          name: string;
          • Name of the pointer key

          property pointerType

          pointerType: 'mouse' | 'pen' | 'touch';
          • Type of the pointer device


          enum PointerEventsCheckLevel

          enum PointerEventsCheckLevel {
          EachTrigger = 4,
          EachApiCall = 2,
          EachTarget = 1,
          Never = 0,

            member EachApiCall

            EachApiCall = 2
            • Check each target once per call to pointer (related) API

            member EachTarget

            EachTarget = 1
            • Check each event target once

            member EachTrigger

            EachTrigger = 4
            • Check pointer events on every user interaction that triggers a bunch of events. E.g. once for releasing a mouse button even though this triggers pointerup, mouseup, click, etc...

            member Never

            Never = 0
            • No pointer events check

            Type Aliases

            type UserEvent

            type UserEvent = {
            readonly setup: (...args: Parameters<typeof setupSub>) => UserEvent;
            } & {
            readonly [k in keyof UserEventApi]: (
            ...args: Parameters<UserEventApi[k]>
            ) => ReturnType<UserEventApi[k]>;

              Package Files (6)

              Dependencies (0)

              No dependencies.

              Dev Dependencies (30)

              Peer Dependencies (1)


              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@testing-library/user-event.

              • Markdown
              • HTML
                <a href="https://www.jsdocs.io/package/@testing-library/user-event"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>