An example of canvas hit regions

Share RGraph:   To help my Google visibility (it can't get much worse!), if you like and use RGraph I'd appreciate it if you could link to me

Shows you an example of canvas hit regions and how you can use them to add interactivity to your canvas and/or charts.

Warning: The features described on this page are not implemented in all browsers yet!


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.

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:

Internet Explorer:

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.

    context.addHitRegion({'id': 'The First Button', 'cursor': 'pointer'});

    context.addHitRegion({'id': 'The Second Button', 'cursor': 'pointer'});

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

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({'id': '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 aren't currently implemented in any browser but there are various methods that you can employ for hit detection including:

Of these the latter two 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 the latter two - depending on how complex the shape being tested is. For example it's easy to test the boundaries of a simple square, but much more complicated if the shape you're testing involves curves (such as the Marker1 drawing API object).