Grid(​[properties])

Basic Use #

The grid automatically positions each object based on the grids flow. This means you do not need to set the x/y position of any of the objects and can let the grid handle that for you. This makes it extremely easy to set up UI elements such as menus without having to hand place each one.

let { Text, Grid } = kontra

let textOptions = {
  color: 'white',
  font: '20px Arial, sans-serif'
};

let start = Text({
  text: 'Start',
  ...textOptions
});

let options = Text({
  text: 'Options',
  ...textOptions
});

let quit = Text({
  text: 'Quit',
  ...textOptions
});

let menu = Grid({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // add 15 pixels of space between each row
  rowGap: 15,

  // center the children
  justify: 'center',

  children: [start, options, quit]
});

menu.render();

import { Text, Grid } from 'path/to/kontra.mjs'

let textOptions = {
  color: 'white',
  font: '20px Arial, sans-serif'
};

let start = Text({
  text: 'Start',
  ...textOptions
});

let options = Text({
  text: 'Options',
  ...textOptions
});

let quit = Text({
  text: 'Quit',
  ...textOptions
});

let menu = Grid({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // add 15 pixels of space between each row
  rowGap: 15,

  // center the children
  justify: 'center',

  children: [start, options, quit]
});

menu.render();

import { Text, Grid } from 'kontra';

let textOptions = {
  color: 'white',
  font: '20px Arial, sans-serif'
};

let start = Text({
  text: 'Start',
  ...textOptions
});

let options = Text({
  text: 'Options',
  ...textOptions
});

let quit = Text({
  text: 'Quit',
  ...textOptions
});

let menu = Grid({
  x: 300,
  y: 100,
  anchor: {x: 0.5, y: 0.5},

  // add 15 pixels of space between each row
  rowGap: 15,

  // center the children
  justify: 'center',

  children: [start, options, quit]
});

menu.render();

Child Properties #

The grid supports properties on the child objects that change how the child is positioned within the grid.

• alignSelf - String. Align this item individually in the grid, overriding the grids align setting.
• justifySelf - String. Justify this item individually in the grid, overriding the grids justify setting.
• colSpan - Number. Have the item take up more than 1 column. Great for menu titles.

Grid​.align #

String or an Array of Strings. The vertical alignment of the grid. Valid values are:

• start - align to the top of row
• center - align to the center of the row
• end - align to the the bottom of the row

An array of strings means the grid will set the vertical alignment for each row using the order of the array. For example, if the alignment is set to be ['end', 'start'], then every odd row will use 'end' and every even row will use 'start'.

Additionally, each child of the grid can use the alignSelf property to change it's alignment in the grid.

Grid​.breakpoints #

An Array of Objects. How the grid should change based on different metrics. Based on the concept of CSS Media Queries so you can update how the grid organizes the objects when things change (such as the scale).

Each object in the array uses the metric() function to determine when the breakpoint applies and the callback() function is called to change any properties of the grid.

let { Grid } = kontra;

let grid = Grid({
  breakpoints: [{
    metric() {
      return this.scaleX < 1
    },
    callback() {
      this.numCols = 1;
    }
  },
  {
    metric() {
      return this.scaleX >= 1
    },
    callback() {
      this.numCols = 2;
    }
  }]
});

let { Grid } = kontra;

let grid = Grid({
  breakpoints: [{
    metric() {
      return this.scaleX < 1
    },
    callback() {
      this.numCols = 1;
    }
  },
  {
    metric() {
      return this.scaleX >= 1
    },
    callback() {
      this.numCols = 2;
    }
  }]
});

let { Grid } = kontra;

let grid = Grid({
  breakpoints: [{
    metric() {
      return this.scaleX < 1
    },
    callback() {
      this.numCols = 1;
    }
  },
  {
    metric() {
      return this.scaleX >= 1
    },
    callback() {
      this.numCols = 2;
    }
  }]
});

Grid​.colGap #

Number or an Array of Numbers. The horizontal gap between each column in the grid.

An array of numbers means the grid will set the gap between columns using the order of the array. For example, if the gap is set to be [10, 5], then every odd column gap will use 10 and every even column gap will use 5.

Grid​.destroy(​) #

Call destroy() on all children.

Grid​.dir #

String. The direction of the grid. Defaults to organizing the grid objects left-to-right, but if set to rtl then the grid is organized right-to-left.

When determining the direction of the grid, the canvas dir attribute is also taken into account. Setting the attribute to rtl is equivalent to setting the dir property to rtl. The dir property is used instead of the canvas attribute if both are set.

Grid​.flow #

String. How to organize all objects in the grid. Valid values are:

• column - organize into a single column
• row - organize into a single row
• grid - organize into a grid with numCols number of columns

Grid​.justify #

String or an Array of Strings. The horizontal alignment of the grid. Valid values are:

• start - align to the left of column
• center - align to the center of the column
• end - align to the the right of the column

An array of strings means the grid will set the horizontal alignment for each column using the order of the array. For example, if the alignment is set to be ['end', 'start'], then every odd column will use 'end' and every even column will use 'start'.

If the dir property is set to rtl, then start and end are reversed.

Additionally, each child of the grid can use the justifySelf property to change it's alignment in the grid.

Grid​.numCols #

Number. The number of columns in the grid. Only applies if the flow property is set to grid.

Grid​.rowGap #

Number or an Array of Numbers. The vertical gap between each row in the grid.

An array of numbers means the grid will set the gap between rows using the order of the array. For example, if the gap is set to be [10, 5], then every odd row gap will use 10 and every even row gap will use 5.