An example of HTML5 canvas hit regions

Warning: The features described on this page are only implemented in Google Chrome Canary This demo shows them in use.

Introduction

Hit regions are possibly the most exciting of all the features introduced in the early 2012 canvas specification additions. They provide a way for you to define an area of your canvas (and add an id: property to it) and then in a click or mousemove event you can check the region property on the event object to see if it matches the hit regions id. No more working out whether the mouse coordinates are within a particular area - which can range from being a chore to being entirely inpractical. They can also be used as an easy way to make the cursor change when it's in a specific position. It will mean that significant amounts of click-detection code could be eliminated from libraries that use canvas which means faster, smaller downloads and more efficient and readable code. Also, it will mean that click detection becomes much easier for complex shapes.

Another way to achieve a similar effect would be to use Path objects. In this way you could retain your Path objects and then when a click or mousemove event occurs each Path object can be tested with its isPointInPath() function.

Update 28th July 2014:

As of this date the addHitRegion() and removeHitRegion() functions have been implemented in Google Chrome Canary and are functioning. There's an example of them in use here.

Browser support

At the time of writing (24th January 2013) there are no browsers that have implemented hit regions. You could achieve a similar effect with your own code - but it would be non-trivial.

Your browser:


Chrome:
Yes1
Firefox:
No
Internet Explorer:
No
Safari:
No
Opera:
No
1 As of 28th July 2014 the addHitRegion() and removeHitRegion() functions appear to have been implemented in Google Chrome Canary.

An example

To add hit regions to your canvas you can use the addHitRegion() function as described below. This is a simple example of adding two hit regions to your canvas that might be used to act as buttons.

<script>
    context.beginPath();
    context.rect(10,10,100,100);
    context.fill();
    context.addHitRegion({'id': 'The First Button', 'cursor': 'pointer'});

    context.beginPath();
    context.rect(120,10,100,100);
    context.fill();
    context.addHitRegion({'id': 'The Second Button', 'cursor': 'pointer'});

    canvas.onclick = function (event)
    {
        if (event.region) {
            alert('You clicked ' + event.region);
        }
    }
<script>

The addHitRegion function

context.addHitRegion({'id': 'button1', 'cursor': 'pointer'});

The addHitRegion() function can be used to add a hit region to your canvas. It takes an object as an argument which can contain the following properties:

The removeHitRegion function

context.removeHitRegion('button1');

This removes a hit region that has previously added to the canvas. The id is used to identify the hit region. This function clears the hit region and also any child hit regions.

Resizing a canvas (with the HTML width/height attributes) clears all of the hit regions.

How can I use them now?

Hit regions are only implemented in Chrome Canary as of 28th July 2014 but there are various methods that you can employ for hit detection including:

Of these the latter three are the best choice. The former should probably be avoided - but if you can control the end user environment it could potentially save you a lot of time and code. RGraph uses a mixture of replaying paths and geometric calculations - depending on how complex the shape being tested is. For example it's easy to test the boundaries of a simple square, but it would be impractical to use geometric calculations if the shape you're testing involves curves (such as the Marker1 drawing API object).