🌜
🌞
pressure

pressure

v2.2.0

Pressure is a lightweight JavaScript library for both Force Touch and 3D Touch through a single API.

npm install pressure

README

Pressure.js

Join the chat at https://gitter.im/yamartino/pressure npm https://www.npmjs.com/package/pressure npm https://www.npmjs.com/package/pressure

Pressure Example

Pressure is a JavaScript library for handling both Force Touch and 3D Touch on the web, bundled under one library with a simple API that makes working with them painless.

Head over to the documentation for installation instructions, supported devices, and more details on pressure.js.

Install

Download pressure.min.js or pressure.js files from GitHub or install with npm or bower

npm

npm install pressure --save

bower

bower install pressure --save

Setup

Use pressure in the global space:

Pressure.set('#id-name', {
  change: function(force){
    this.innerHTML = force;
  }
});

OR use it with browserify or CommonJS like setups:

var Pressure = require('pressure');

Pressure.set('#id-name', {
  change: function(force){
    this.innerHTML = force;
  }
});

Usage

NOTE: the "this" keyword in each of the callback methods will be the element itself that has force applied to it

Pressure.set('#element', {
  start: function(event){
    // this is called on force start
  },
  end: function(){
    // this is called on force end
  },
  startDeepPress: function(event){
    // this is called on "force click" / "deep press", aka once the force is greater than 0.5
  },
  endDeepPress: function(){
    // this is called when the "force click" / "deep press" end
  },
  change: function(force, event){
    // this is called every time there is a change in pressure
    // force will always be a value from 0 to 1 on mobile and desktop
  },
  unsupported: function(){
    // NOTE: this is only called if the polyfill option is disabled!
    // this is called once there is a touch on the element and the device or browser does not support Force or 3D touch
  }
});

jQuery Usage

NOTE: the "this" keyword in each of the callback methods will be the element itself that has force applied to it

$('#element').pressure({
  start: function(event){
    // this is called on force start
  },
  end: function(){
    // this is called on force end
  },
  startDeepPress: function(event){
    // this is called on "force click" / "deep press", aka once the force is greater than 0.5
  },
  endDeepPress: function(){
    // this is called when the "force click" / "deep press" end
  },
  change: function(force, event){
    // this is called every time there is a change in pressure
    // force will always be a value from 0 to 1 on mobile and desktop
  },
  unsupported: function(){
    // NOTE: this is only called if the polyfill option is disabled!
    // this is called once there is a touch on the element and the device or browser does not support Force or 3D touch
  }
});

Options

With Pressure, the third paramater is an optional object of options that can be passed in.

Polyfill Support

Using the "polyfill" keyword, you can disable polyfill support for the element. The polyfill is enabled by default and is useful if the device or browser does not support pressure, it will fall back to using time. For example instead of force from 0 to 1, it counts up from 0 to 1 over the course of one second, as long as you are holding the element. Try some of the examples on the main page on a devices that does not support pressure and see for yourself how it works.

Pressure.set('#example', {
  change: function(force, event){
    this.innerHTML = force;
  },
  unsupported: function(){
    alert("Oh no, this device does not support pressure.");
  }
}, {polyfill: false});

Polyfill Speed Up

If you are using the polyfill (on by default), you can see the "polyfillSpeedUp" speed to determine how fast the polyfill takes to go from 0 to 1. The value is an integer in milliseconds and the default is 1000 (1 second).

Pressure.set('#example', {
  change: function(force, event){
    this.innerHTML = force;
  }
}, {polyfillSpeedUp: 5000});
// takes 5 seconds to go from a force value of 0 to 1
// only on devices that do not support pressure

Polyfill Speed Down

If you are using the polyfill (on by default), you can see the "polyfillSpeedDown" speed to determine how fast the polyfill takes to go from 1 to 0 when you let go. The value is an integer in milliseconds and the default is 0 (aka off).

Pressure.set('#example', {
  change: function(force, event){
    this.innerHTML = force;
  }
}, {polyfillSpeedDown: 2000});
// takes 2 seconds to go from a force value of 1 to 0
// only on devices that do not support pressure

Only run on Force Touch trackpads (mouse)

Set the option only to the type you want it to run on 'mouse', 'touch', or 'pointer'. The names are the types of events that pressure will respond to.

Pressure.set('#example',{
  change: function(force, event){
    console.log(force);
  },
}, {only: 'mouse'});

Only run on 3D Touch (touch)

Pressure.set('#example',{
  change: function(force, event){
    console.log(force);
  },
}, {only: 'touch'});

Only run on Pointer Supported Devices (pointer)

Pressure.set('#example',{
  change: function(force, event){
    console.log(force);
  },
}, {only: 'pointer'});

Change the preventSelect option

The preventDefault option in "true" by default and it prevents the default actions that happen on 3D "peel and pop" actions and the Force "define word" actions as well as other defaults. To allow the defaults to run set preventDefault to "false"

Pressure.set('#example',{
  change: function(force, event){
    console.log(force);
  },
}, {preventSelect: false});

Helpers

Config

You can use Pressure.config() to set default configurations for site wide setup. All of the configurations are the same as the options listed above.

Heads Up: If you have a config set, you can always overide the config on individual Pressure elements by passing in any of the options listed above to a specific Pressure block.

When using the jQuery Pressure library, use $.pressureConfig() rather than Pressure.map()

// These are the default configs set by Pressure
Pressure.config({
  polyfill: true,
  polyfillSpeedUp: 1000,
  polyfillSpeedDown: 0,
  preventDefault: true,
  only: null
});

Map

You can use Pressure.map() to map a value from one range of values to another. It takes 5 params: Pressure.map(inputValue, inputValueMin, inputValueMax, mapToMin, mapToMax); Here is a good write up on how this works in the Processing framework: Map Function.

When using the jQuery Pressure library, use $.pressureMap() rather than Pressure.map()

Pressure.set('#element', {
  change: function(force, event){
    // this takes the force, given that the force can range from 0 to 1, and maps that force value on a 100 to 200 range
    this.style.width = Pressure.map(force, 0, 1, 100, 200);
  }
});

Release Notes

2.2.0
By Stuart Yamartino • Published on September 30, 2020

Fixes #81 and #85 MacOS Safari Bug

2.1.2
By Stuart Yamartino • Published on November 29, 2017

This fixes issue #67 where some android devices have incorrect pointer pressure values.

2.1.1
By Stuart Yamartino • Published on March 29, 2017

Fixes issue: #64 Does some error checking around making sure Touch objects have force params before using them.

Thanks to @davidshimjs for making this release possible. 👍 ⚡️

2.1.0
By Stuart Yamartino • Published on February 26, 2017

This release has a few great improvements. 😄

Features

  1. Support for Pointer Events! #60 That means that any browser that supports Pointer Events and any device that gives a pressure reading should now work on pressure. Things like Microsoft Surfaces and Wacom Tablets will now work with pressure. 🎉

This also means that pressure is now more future proofed now that more browsers are adding support for pointer events! Can I Use Pointer Events

  1. Support for polyfillSpeedDown #56 Now you can set a speed in which you want the polyfill to "decrease" once the mouse or touch is released. By default this value is set to 0 so when you release your finger it snaps back to 0.

Changes

  1. The only setting now accepts touch, mouse, or pointer to specify if you want pressure to only respond to specific events.

  2. The polyfillSpeedsetting has been changed to polyfillSpeedUp because the polyfillSpeedDown was added to this release.

2.0.3
By Stuart Yamartino • Published on November 4, 2016

The jQuery package was updated to return void from the factory. This is because pressure is attached to $ so no return is needed.

2.0.2
By Stuart Yamartino • Published on November 3, 2016

This update adds the UMD gulp wrapper. This improves the way that pressure loads itself for RequireJS, CommonJS, or the browser Window. This improvement helps when using pressure with something like Webpack. See this pull request for more information: https://github.com/stuyam/pressure/pull/52

2.0.1
By Stuart Yamartino • Published on October 24, 2016

See issue #50 for more information on this bug fix. The gist of it was that the polyfill and 3d touch could conflict when you touched very very lightly. Now even if the polyfill runs but then force is detected, the force will cancel the polyfill and take over.

2.0.0
By Stuart Yamartino • Published on October 19, 2016

50 Commits. 80% of the file size of Pressure 1. More flexible than Pressure 1.

Biggest Additions to v2.0.0

  • Support for iOS 10.
  • Polyfill is now enabled by default.
  • You can set the polfillSpeed to tell pressure how fast you want it to run for 0 to 1.
  • Support for Pressure is now tested on every single press of an element rather than once per page. This means you could switch between something like a mouse (that does NOT support force touch) and a trackpad (that does support force touch) and Pressure can handle it without having to refresh the page.

Lot's of hard work in this release so check it out and let me know me know what you think! 💥 🎉

1.0.1
By Stuart Yamartino • Published on March 19, 2016
  • This release fixes a bug that was running pressure in an environment that has no window or document such as node.
1.0.0
By Stuart Yamartino • Published on March 13, 2016
  • The biggest addition to v1.0.0 is the polyfill support. Now you can optionally give "support" to older browsers and devices that do not support force or 3d touch. It uses time to fake a pressure value, the longer you press, the higher the "force" is returned. It takes one second to go from 0 to 1 and can do a good job of faking pressure if that if what you are looking for. The Instagram iOS app for example uses the "peek and pop" on iOS. If you have 3D touch support, then you can press hard on an Instagram photo to display it. Else if you do not have 3D touch support, you can simply long hold on an image and it will open it just like the 3D touch version. The same idea applies with the optional pressure.js polyfill support.
  • Now you can set global configurations for pressure so you do not have to set them on each element if you are using options that will be used throughout your site.
  • Fixed a bug that did not allow the value of 1 to be reached on force touch trackpads. Now every type of support will have a force value returned that goes from 0 to 1. Before force touch only got up to around 0.9997 or so.
  • Other various bugs, improvements, and happinest went into making this build!

-Also this build starts the 1.0.0 track of pressure :tada: This will make it easier to make smaller more incremental improvements to pressure.

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
2,834
Community Interest
2,918
Number of Forks
106

Maintenance

Commits
10/219/2201
Last Commit
Open Issues
12
Closed Issues
55
Open Pull Requests
6
Closed Pull Requests
3

Versions

Versions Released
10/219/2201
Latest Version Released
Sep 30, 2020
Current Tags
latest2.2.0

Contributors

stuyam
stuyam
Commits: 238
davidshimjs
davidshimjs
Commits: 7
marcusmolchany
marcusmolchany
Commits: 1
gitter-badger
gitter-badger
Commits: 1
zetlen
zetlen
Commits: 1