/ S

This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# CustomBorders

Table of contents

# Description

This plugin enables an option to apply custom borders through the context menu (configurable with context menu key borders).

To initialize Handsontable with predefined custom borders, provide cell coordinates and border styles in a form of an array.

See Custom Borders demo for more examples.

Example

customBorders: [
  {
   range: {
     from: {
       row: 1,
       col: 1
     },
     to: {
       row: 3,
       col: 4
     },
   },
   left: {},
   right: {},
   top: {},
   bottom: {},
  },
],

// or
customBorders: [
  { row: 2,
    col: 2,
    left: {
      width: 2,
      color: 'red',
    },
    right: {
      width: 1,
      color: 'green',
    },
    top: '',
    bottom: '',
  }
],

# Options

# customBorders

Source code (opens new window)

customBorders.customBorders : boolean | Array<object>

The customBorders option configures the CustomBorders plugin.

To enable the CustomBorders plugin (and add its menu items to the context menu), set the customBorders option to true.

To enable the CustomBorders plugin and add a predefined border around a particular cell, set the customBorders option to an array of objects. Each object represents a border configuration for one cell, and has the following properties:

Property Sub-properties Types Description
row - row: Number The cell's row coordinate.
col - col: Number The cell's column coordinate.
left width
color		 width: Number
color: String		 Sets the left border's width (width)
and color (color).
right width
color		 width: Number
color: String		 Sets the right border's width (width)
and color (color).
top width
color		 width: Number
color: String		 Sets the top border's width (width)
and color (color).
bottom width
color		 width: Number
color: String		 Sets the bottom border's width (width)
and color (color).

To enable the CustomBorders plugin and add a predefined border around a range of cells, set the customBorders option to an array of objects. Each object represents a border configuration for a single range of cells, and has the following properties:

Property Sub-properties Types Description
range from {row, col}
to {row, col}		 from: Object
to: Object
row: Number
col: Number		 from selects the range's top-left corner.
to selects the range's bottom-right corner.
left width
color		 width: Number
color: String		 Sets the left border's width and color.
right width
color		 width: Number
color: String		 Sets the right border's width and color.
top width
color		 width: Number
color: String		 Sets the top border's width and color.
bottom width
color		 width: Number
color: String		 Sets the bottom border's width and color.

Read more:

Default: false Example

// enable the `CustomBorders` plugin
customBorders: true,

// enable the `CustomBorders` plugin
// and add a predefined border for a particular cell
customBorders: [
  // add an object with a border configuration for one cell
  {
    // set the cell's row coordinate
    row: 2,
    // set the cell's column coordinate
    col: 2,
    // set the left border's width and color
    left: {
      width: 2,
      color: 'red'
    },
    // set the right border's width and color
    right: {
      width: 1,
      color: 'green'
    },
    // set the top border's width and color
    top: '',
    // set the bottom border's width and color
    bottom: ''
  }
],

// enable the `CustomBorders` plugin
// and add a predefined border for a range of cells
customBorders: [
  // add an object with a border configuration for one range of cells
  {
    // select a range of cells
    range: {
      // set the range's top-left corner
      from: {
        row: 1,
        col: 1
      },
      // set the range's bottom-right corner
      to: {
        row: 3,
        col: 4
      }
    },
    // set the left border's width and color
    left: {
      width: 2,
      color: 'red'
    },
    // set the right border's width and color
    right: {},
    // set the top border's width and color
    top: {},
    // set the bottom border's width and color
    bottom: {}
  }
],

# Methods

# clearBorders

Source code (opens new window)

customBorders.clearBorders(selectionRanges)

Clear custom borders.

Example

const customBordersPlugin = hot.getPlugin('customBorders');

// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.clearBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
customBordersPlugin.clearBorders(hot.getSelectedRange());
// Using without param - clear all customBorders.
customBordersPlugin.clearBorders();
Param Type Description
selectionRanges Array<Array>
Array<CellRange>		 Array of selection ranges.

# destroy

Source code (opens new window)

customBorders.destroy()

Destroys the plugin instance.

# disablePlugin

Source code (opens new window)

customBorders.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

# enablePlugin

Source code (opens new window)

customBorders.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

# getBorders

Source code (opens new window)

customBorders.getBorders(selectionRanges) ⇒ Array<object>

Get custom borders.

Example

const customBordersPlugin = hot.getPlugin('customBorders');

// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.getBorders([[1, 1, 2, 2], [6, 2, 0, 2]]);
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
customBordersPlugin.getBorders(hot.getSelectedRange());
// Using without param - return all customBorders.
customBordersPlugin.getBorders();
Param Type Description
selectionRanges Array<Array>
Array<CellRange>		 Array of selection ranges.

Returns: Array<object> - Returns array of border objects.

# isEnabled

Source code (opens new window)

customBorders.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit hook and if it returns true than the CustomBorders#enablePlugin method is called.

# setBorders

Source code (opens new window)

customBorders.setBorders(selectionRanges, borderObject)

Set custom borders.

Example

const customBordersPlugin = hot.getPlugin('customBorders');

// Using an array of arrays (produced by `.getSelected()` method).
customBordersPlugin.setBorders([[1, 1, 2, 2], [6, 2, 0, 2]], {left: {width: 2, color: 'blue'}});

// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
//  Selecting a cell range.
hot.selectCell(0, 0, 2, 2);
// Returning selected cells' range with the getSelectedRange method.
customBordersPlugin.setBorders(hot.getSelectedRange(), {left: {hide: false, width: 2, color: 'blue'}});
Param Type Description
selectionRanges Array<Array>
Array<CellRange>		 Array of selection ranges.
borderObject object Object with top, right, bottom and left properties.

# updatePlugin

Source code (opens new window)

customBorders.updatePlugin()

Updates the plugin state. This method is executed when Core#updateSettings is invoked.

Last Updated: Apr 12, 2024

← DragToScroll →