Nullifying Precipitation Machine

    @wessberg/pointer-events
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.9 • Public • Published
    Logo

    A Level 2 spec-compliant Pointer Events polyfill with first-class Shadow DOM support

    Downloads per month NPM version Dependencies Contributors code style: prettier License: MIT Support on Patreon

    Description

    This polyfill brings Level 2 Pointer Events to all browsers! The Pointer Events specification provides a unified model for handling input from a pointer such as a mouse, a touch, and a pen.

    Gone are the complexities of handling both MouseEvents and TouchEvents and juggling the differences between them. The primary design goals of this polyfill are to be as spec-compliant as possible, and to support modern web technologies such as Shadow DOM.

    Features

    • Spec-compliant
    • Shadow DOM support
    • Performant
    • Feature-complete

    Table of Contents

    Install

    NPM

    $ npm install @wessberg/pointer-events
    

    Yarn

    $ yarn add @wessberg/pointer-events
    

    Usage

    To use the Polyfill, simply import it:

    import "@wessberg/pointer-events";

    However, it is strongly suggested that you only include the polyfill for browsers that doesn't already support Pointer Events. One way to do so is with an async import:

    if (!("PointerEvent" in window)) {
    	await import("@wessberg/pointer-events");
    }

    Alternatively, you can use Polyfill.app which uses this polyfill and takes care of only loading the polyfill if needed as well as adding the language features that the polyfill depends on (See dependencies).

    touch-action support

    This polyfill supports the following Pointer Events (Level 2) touch-action values, as well as those defined in the latest Draft Community Report:

    • none
    • pan-x
    • pan-y
    • pan-left
    • pan-right
    • pan-up
    • pan-down
    • auto
    • manipulation (will be treated the same ast auto)

    Upon pointer contact, the polyfill will walk up the DOM tree from the target element and look for elements that has either:

    • A style attribute including a touch-action property.
    • An element with a touch-action attribute.
    • Or, an element with a CSSStyleDeclaration with a touchAction property.

    This means that either of the following approaches will work:

    <!-- Works just fine when given in the 'style' attribute -->
    <div style="touch-action: pan-y"></div>
    <!-- Works just fine when given as an attribute of the name 'touch-action' -->
    <div touch-action="pan-y"></div>
    // Works jut fine when given as a style property
    element.style.touchAction = "pan-y";

    See this section for information about why touch-action values provided in stylesheets won't be discovered by the polyfill.

    Dependencies & Browser support

    This polyfill is distributed in ES3-compatible syntax, but is using some modern APIs and language features which must be available:

    • EventTarget
    • Set
    • Map
    • Object.defineProperty
    • Object.defineProperties
    • Array.from
    • Array.prototype.some
    • Array.prototype.every
    • String.prototype.includes
    • Constructable Events
    • EventTarget.prototype.addEventListener
    • EventTarget.prototype.removeEventListener
    • EventTarget.prototype.dispatchEvent
    • Document.prototype.elementFromPoint
    • window.getComputedStyle
    • ShadowRoot.prototype.elementFromPoint*

    *: This is only relevant if you're using Shadow DOM (in which case a Shadow DOM polyfill will most likely polyfill the prototype method).

    For by far the most browsers, these features will already be natively available. Generally, I would highly recommend using something like Polyfill.app which takes care of this stuff automatically.

    Contributing

    Do you want to contribute? Awesome! Please follow these recommendations.

    Maintainers

    Frederik Wessberg
    Frederik Wessberg
    @FredWessberg
    Lead Developer

    Backers

    Patreon

    Become a backer and get your name, avatar, and Twitter handle listed here.

    Backers on Patreon

    FAQ

    There are several polyfills for Pointer events already. Why another one?

    Yes, there are several, including PEP and Points. This polyfill was made because neither were built with Shadow DOM (v1) support in mind. For example, Points assumes a single document-level root and relies on document.elementFromPoint which will never reach within Shadow roots. And, PEP relies on /deep/ selectors, something that has been removed from the platform. I found that none of the existing polyfills I attempted "just worked" and decided to try it out for myself. There may well be parts of this polyfill that is less aligned with the spec than other polyfills, and such issues will be ironed out over time.

    Are there any known quirks?

    For now, just one: The touch-action CSS property needs to be provided from either inline styles or an attribute of the same name. This is because polyfilling CSS is hard and really bad for performance.

    License

    MIT © Frederik Wessberg (@FredWessberg) (Website)

    Install

    npm i @wessberg/pointer-events

    DownloadsWeekly Downloads

    564

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    252 kB

    Total Files

    7

    Last publish

    Collaborators

    • wessberg