Skip to main content

HTML5 Canvas Shape Caching Performance Tip

If you have a complex shape with many drawing operations, or if you're applying filters, you can improve performance by caching the shape. When you cache a shape, Konva will draw it onto an internal canvas buffer. After that, instead of redrawing the shape every time, Konva will simply use the cached version.

This is particularly useful for:

  1. Complex shapes with many drawing operations
  2. Shapes with filters
  3. Shapes that don't change often but need to be redrawn frequently

To cache a shape, simply call the cache() method. You can clear the cache with clearCache().

How caching works?​

When you call the cache() method on a shape, Konva:

  1. Creates an internal canvas buffer
  2. Draws the shape onto this buffer
  3. Stores this buffer for future use

After caching, instead of redrawing the shape every time it needs to be displayed, Konva simply uses the cached version from the buffer. This is much faster than redrawing the shape repeatedly.

Guidelines​

  1. Don't cache simple shapes without filters. It may be faster to render it dirrectly, then from cached version.
  2. Every cached node creates several canvas buffers. So don't overuse it, as it will consume a lot of memory.
  3. It is better to cache groups of shapes, then to cache each shape individually.
  4. Remember to always measure performance with and without caching to see the actual difference.

Below is a demo showing the performance difference between cached and non-cached complex shapes:

Instructions:

  • Click anywhere on the stage to add 1000 more circles
  • Toggle the checkbox to enable/disable caching
  • Watch the FPS counter to see the performance difference
  • The group of circles rotates continuously
import Konva from 'konva';

const stage = new Konva.Stage({
  container: 'container',
  width: window.innerWidth,
  height: window.innerHeight,
});

const layer = new Konva.Layer();
stage.add(layer);

// Create a group of circles
const group = new Konva.Group({
  x: stage.width() / 2,
  y: stage.height() / 2,
});
layer.add(group);

// Add initial circles
const addCircles = (count) => {
  const radius = 300;
  for (let i = 0; i < count; i++) {
    const angle = Math.random() * Math.PI * 2;
    const distance = Math.random() * radius;
    const x = Math.cos(angle) * distance;
    const y = Math.sin(angle) * distance;

    const circle = new Konva.Circle({
      x,
      y,
      radius: 5 + Math.random() * 10,
      fill: Konva.Util.getRandomColor(),
      shadowColor: 'black',
      shadowBlur: 10,
      shadowOpacity: 0.5,
      shadowOffset: { x: 2, y: 2 },
      listening: false,
    });

    group.add(circle);
  }
};

// Add initial circles
addCircles(5000);

// Add FPS counter
const fpsText = new Konva.Text({
  x: 10,
  y: 10,
  text: 'FPS: 0',
  fontSize: 16,
  fill: 'white',
  shadowColor: 'black',
  shadowBlur: 5,
  shadowOffset: { x: 1, y: 1 }
});
layer.add(fpsText);

// Add circle count text
const countText = new Konva.Text({
  x: 10,
  y: 40,
  text: 'Circles: 1000',
  fontSize: 16,
  fill: 'white',
  shadowColor: 'black',
  shadowBlur: 5,
  shadowOffset: { x: 1, y: 1 }
});
layer.add(countText);

// Create animation
const anim = new Konva.Animation((frame) => {
  group.rotation(frame.time * 0.05);
  
  // Update FPS counter
  fpsText.text('FPS: ' + frame.frameRate.toFixed(1));
}, layer);

// Add click handler to add more circles
stage.on('click', () => {
  addCircles(1000);
  countText.text('Circles: ' + group.children.length);
});

// Add DOM checkbox
const container = stage.container();
const checkbox = document.createElement('input');
checkbox.type = 'checkbox';
checkbox.id = 'cache-toggle';
checkbox.style.position = 'absolute';
checkbox.style.top = '70px';
checkbox.style.left = '10px';
checkbox.style.zIndex = '100';
container.appendChild(checkbox);

const label = document.createElement('label');
label.htmlFor = 'cache-toggle';
label.textContent = 'Enable Caching';
label.style.position = 'absolute';
label.style.top = '70px';
label.style.left = '30px';
label.style.color = 'white';
label.style.textShadow = '0 0 5px black';
label.style.zIndex = '100';
container.appendChild(label);

// Toggle caching
checkbox.addEventListener('change', () => {
  if (checkbox.checked) {
    group.cache();
  } else {
    group.clearCache();
  }
});

anim.start();
Open on CodeSandboxOpen Sandbox