mozilla
Your Search Results

    Proximity Events

    This article is in need of a technical review.

    This is an experimental technology
    Because this technology's specification has not stabilized, check the compatibility table for the proper prefixes to use in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the spec changes.

    The proximity events are a handy way to know when a user is close to a device. These events make it possible to react to such a change, for example by shutting down the screen of a smartphone when the user is having a phone call with the device close to their ear.

    Note: Obviously, the API requires the device to have a proximity sensor, which are mostly available only on mobile devices. Devices without such a sensor may support those events but will never fire them.

    Proximity Events

    When the device proximity sensor detects a change between the device and an object, it notifies the browser of that change. When the browser gets such a notification, it fires a DeviceProximityEvent for any change, and a UserProximityEvent event in the case of a more rough change.

    This event can be captured at the window object level by using the addEventListener method (using the deviceproximity or userproximity event name) or by attaching an event handler to the window.ondeviceproximity or window.onuserproximity properties.

    Once captured, the event object gives access to different kinds of information:

    • The DeviceProximityEvent event provides an exact match for the distance between the device and the object through its value property. It also provides the closest and farthest distance the device is able to detect something through its min and max properties.
    • The UserProximityEvent event provides a rough approximation of the distance, expressed through a boolean. The UserProximityEvent.near property is true if the object is close or false if the object is far.

    Example

    window.addEventListener('userproximity', function(event) {
      if (event.near) {
        // let's power off the screen
        navigator.mozPower.screenEnabled = false;
      } else {
        // Otherwise, let's power on the screen
        navigator.mozPower.screenEnabled = true;
      }
    });

    Specifications

    Specification Status Comment
    Proximity Events
    The definition of 'Proximity Events' in that specification.
    Candidate Recommendation Initial specification

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    DeviceProximityEvent Not supported (Yes) Not supported Not supported Not supported
    UserProximityEvent Not supported (Yes) Not supported Not supported Not supported
    Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    DeviceProximityEvent Not supported Not supported 15.0 (15.0) Not supported Not supported Not supported
    UserProximityEvent Not supported Not supported (Yes) Not supported Not supported Not supported

    See also

    Document Tags and Contributors

    Contributors to this page: kscarfone, SpencerG, teoli, samdutton, Jeremie
    Last updated by: SpencerG,