Pressure.js current v1.0.1

Pressure is a JavaScript library that makes dealing with Apple's Force Touch and 3D Touch simple. Force Touch for new Macs and 3D Touch for the new iPhone 6s and 6s Plus, all bundled under one roof with a simple API that makes working with them painless.

Pressure gives you a handle on browsers that do and don't support Force or 3D touch so you can have sensible fallbacks for users that don't support it.

Pressure Browser Test (click me)
Download on GitHub

Tweet at me @StuYam with the project you are working on that uses pressure.js and I will add you here to the expo! :)


Examples

Henry Blyth Valentines


Pressure.js Scale

This is still a work in progress, the "zero" doesn't work, but it is a cool example of what can be done with 3D Touch on the new iPhone 6s




Press

Current Browser/Device Support

  • Device: iPhone 6s / 6s Plus
  • Device: MacBook 2015 / MacBook Pro 2015
  • Device: Magic Trackpad 2
  • future devices and browser that support pressure will be added when they come out

If you are not using one of the devices / browsers listed above, here is a gif to show it in action.


Examples

Note: This page is using the "polyfill" option on most of the Pressure elements to give support for browsers that do not support Force or 3D touch. The "polyfill" option is disabled by default but can be useful in lots of situations where time is an ok replacement for force. For Example: The Instagram app uses 3D touch to allow users to quick look images, however if you do not have 3D touchs support, you can simply hold down on the image for a second and it will do the same thing.
1. Pressure Change

The best part about Pressure is that is uses a single API that works on both Force Touch and 3D Touch. (note: Apple currently only has support for desktop and mobile safari, but luckily with pressure you can test for that)

Targets All

0

Targets ONLY Force Touch (desktop)

0

Targets ONLY 3D Touch (mobile)

0
2. Unblur Photo

The harder you press on the image the less blurry it will become.

(try pressing with variable amounts of pressure)

3. Text Size

The harder you press on the text, the bigger it gets. This could be useful for accessibility on online articles.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
4. Rotating Square

The harder you press on the button, the farther the image will spin.

(try pressing with variable amounts of pressure)



5. "Deep" or Force Press

Press hard on the button, a "Deep" or Force press will occur and launch a bootstrap popover.

1. Installation

Pressure is really simple to install, you can use npm or bower, or head over to the github and download the repo itself. All you need is the pressure.min.js or the pressure.js file.

bower
bower install pressure --save
npm
npm install pressure --save
2. Setup

You can use pressure with browserify, debowerify, or anything that uses CommonJS to include packages. Pressure can be used normally if no module object exists.

// Regular
Pressure.set('#test', {
  change: function(force, event){
    console.log(force);
  }
});
// Browserify, Debowerify, CommonJS
var Pressure = require('pressure');

Pressure.set('#test', {
  change: function(force, event){
    console.log(force);
  }
});
// RequireJS
requirejs(['pressure'], function( Pressure ) {

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

});
3. Usage

Pressure has a really simple method signature. The first argument is the element(s) you are targeting and the second argument is an object with optional callback functions. This lists all the element types that can be passed into Pressure, anything from a string selector, to a DOM node object.

Click Me
// target all links
Pressure.set('a', {});

// pass in jQuery elements
var elements = $('.dogs');
Pressure.set(elements, {});

// pass in element list or single element
var elements2 = document.querySelectorAll('.cats');
Pressure.set(elements2, {});
var elements3 = document.getElementById('cat');
Pressure.set(elements3, {});

// element with the 'stuart' ID being selected and calling the 'change' callback
Pressure.set('#stuart', {
  change: function(force, event){
    // the force value is passed back as well as the full event
    this.innerHTML = force;
  }
});

This example uses all of the optional methods available to you in the callback object.

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
  },
  unsupported: function(){
    // this is called once there is a touch on the element and the device or browser does not support Force or 3D touch
  }
});
4. jQuery Usage

Use the jquery.pressure.min.js file if you are using jQuery in your project. Using the Pressure jQuery library makes it simple to attach pressure events to jQuery elements.

$('a').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
  },
  unsupported: function(){
    // this is called once there is a touch on the element and the device or browser does not support Force or 3D touch
  }
});
5. Options

Polyfill Support

With Pressure, the third paramater is an optional object of options that can be passed in. Using the "polyfill" keyword, you can enable polyfill support for the element. What this means is that if the device or browser does not support force or 3D touch, 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 force or 3D touch and see for yourself how it works.

Click on me on any device :)
Pressure.set('#polyfill-example', {
  change: function(force, event){
    this.innerHTML = force;
  }
}, {polyfill: true});

Device Detection

With Pressure, the third paramater is an optional object of options that can be passed in. The first option is device targeting. Using the "only" keyword, you can define if you want pressure to run on ONLY Mac or ONLY iPhone.

Click Me On an iPhone 6s
Pressure.set('#element-3d', {
  change: function(force, event){
    this.innerHTML = force + 'on an iphone';
  }
}, {only: '3d'});
Click Me On a Mac with Force Touch
Pressure.set('#element-force', {
  change: function(force, event){
    this.innerHTML = force + 'on a Mac';
  }
}, {only: 'force'});

Prevent Default

Both Mac and iPhones have system wide features that they default to when force clicking on something (ex. defining a word on Mac or "peeking and popping" an image on iOS). Pressure prevents those actions from happening, however if you still want those actions to be possible on "Pressure" elements, you can pass in "preventDefault" as an option.

Pressure sets user-select: none; css property on all of the elements it is attached to. It does this to keep text from being selected while force touching. However, sometimes you may want this turned off. The "preventDefault" option also handles removing that"
Push the image hard on an iPhone6s to "peek and pop" it
Pressure.set('#element-3d-prevent', {
  start: function(event){
    console.log('cool it started');
  }
}, {only: '3d', preventDefault: false});
Force touch one of these words on a Force Touch trackpad to define it.
Pressure.set('#element-force-prevent', {
  start: function(event){
    console.log('cool it started');
  }
}, {only: 'force', preventDefault: false});
6. Helpers

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: false,
  preventDefault: true,
  only: null
});

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);
  }
});