Working with groups

You can group any number of regular canvas objects — rectangles, circles, images, paths — into groups. Groups are simply sets of objects rendered together. From the user point of view, groups are represented as one object. User can move them, resize, rotate, and so on. Groups created programmatically can even be "grouped" together by a user, using regular object selection.

Here's an example of creating 2 different fabric groups. First group is a set of 2 objects — red rectangle and green circle. Second group is a set of 3 objects — red circle, green circle, and blue circle.

Notice how groups are added to canvas the same way as other objects — via canvas.add:

var rect = new fabric.Rect({ width: 100, height: 100, fill: 'red' });
var circle = new fabric.Circle({ radius: 100, fill: 'green' });
var group1 = new fabric.Group([ circle, rect ], { left: 100, top: 100 });
canvas.add(group1);

var circle1 = new fabric.Circle({ radius: 100, fill: 'red' });
var circle2 = new fabric.Circle({ radius: 75, fill: 'green' });
var circle3 = new fabric.Circle({ radius: 50, fill: 'blue' });

var group2 = new fabric.Group([ circle1, circle2, circle3 ], { left: 200, top: 200 });
canvas.add(group2);

The objects in the above example are all positioned relative to the center of the group. If you don't want this to happen, you need to specify their left/top coordinates. In that case, objects will be grouped together according to those coordinates.

For example, we can create a group of 3 images, positioned side-by-side, with offset to the bottom-right corner:

fabric.Image.fromURL('http://localhost:4000/assets/pug.jpg', function(img) {
  var img1 = img.scale(0.1).set({ left: 100, top: 100 });
  
  fabric.Image.fromURL('http://localhost:4000/assets/pug.jpg', function(img) {
    var img2 = img.scale(0.1).set({ left: 175, top: 175 });
    
    fabric.Image.fromURL('http://localhost:4000/assets/pug.jpg', function(img) {
      var img3 = img.scale(0.1).set({ left: 250, top: 250 });
      
      canvas.add(new fabric.Group([ img1, img2, img3], { left: 200, top: 200 }))
    });
  });
});

Similar to other objects, groups can be serialized (into fabric's JSON representation) and populated from JSON (that same fabric's JSON representation).

Some of the most notable group methods are:

getObjects — returns an array of objects in a group
size — represents a number of objects in a group
contains — returns true if an object is contained within a group
item — returns object at a specified index in a group
forEachObject — invokes callback for each object in a group
add — adds object to a group
remove — removes object from a group

You can add/remove objects from group in 2 ways — with update of group dimensions/position and without.

// to add rectangle at the center of a group (left=0, top=0)
group.add(new fabric.Rect({ 
  width: 20, 
  height: 20, 
  fill: 'yellow'
}));

// to add rectangle 100 px off the center of the group
group.add(new fabric.Rect({ 
  width: 20, 
  height: 20, 
  fill: 'yellow', 
  left: 100, 
  top: 100
}));

// to add rectangle at the center of a group AND update group's dimensions
group.addWithUpdate(new fabric.Rect({ 
  width: 20, 
  height: 20, 
  fill: 'yellow', 
  left: group.get('left'), 
  top: group.get('top')
}));

// to add rectangle at 100 px off the center of a group AND update group's dimensions
group.addWithUpdate(new fabric.Rect({
  width: 20,
  height: 20,
  fill: 'yellow',
  left: group.get('left') + 100,
  top: group.get('top') + 100
}));

Here's an example of creating a group with 2 objects already existing on canvas:

// create group with copies of existing (2) objects
var group = new fabric.Group([
  canvas.item(0).clone(),
  canvas.item(1).clone()
]);

// remove all objects and re-render
canvas.clear().renderAll();

// add group onto canvas
canvas.add(group);