TOAST UI Grid Documentation

By default, providing a template function enables auto-calculation. You can disable this behavior using the useAutoSummary property within columnContent or defaultContent.

Set useAutoSummary: false if you want to provide a custom template that does not rely on the Grid's automatic calculations.

Additionally, if you assign a plain HTML string directly to a column in columnContent or defaultContent (instead of an object with a template function), the Grid automatically sets useAutoSummary: false to prevent unnecessary calculations.

// Disabling auto summary via property
const grid = new Grid({
  // ...,
  summary: {
    columnContent: {
      col1: {
        useAutoSummary: false,
        template(summary) {
          return 'max: ' + summary.max + '<br>min: ' + summary.min;
        }
      }
    },
    defaultContent: {
      useAutoSummary: false,
      template(summary) {
        return 'default: ' + summary.sum;
      }
    }
  }
});

// Disabling auto summary by providing a static string
const gridStatic = new Grid({
  // ...,
  summary: {
    columnContent: {
      col1: 'col1 content'
    },
    defaultContent: 'static content'
  }
});

TOAST UI Grid allows you to replace the default cell rendering with a custom UI by providing a CellRenderer class. This is more powerful than a formatter because it allows you to inject actual DOM elements (like inputs, buttons, or sliders) into the cell.

CellRenderer Interface

To create a custom renderer, implement a class with the following structure:

• constructor(props): Called when the cell (<td>) is added to the DOM. The props object contains:
  • grid: The Grid instance.
  • rowKey: The rowKey of the current row.
  • columnInfo: Information about the column, including any custom renderer.options.
  • value: The current cell value.
• getElement(): Required. Returns the root DOM element of the custom renderer. This element is automatically inserted into the cell.
• render(props): Required. Used to synchronize the cell's value with the UI. This is called whenever the cell value changes.
• mounted(props): Optional. Called immediately after the root element is mounted to the DOM. Useful for initializing third-party libraries or input elements.
• focused(props): Optional. Called every time the cell receives focus.

class CustomSliderRenderer {
  constructor(props) {
    const el = document.createElement('input');
    const { min, max } = props.columnInfo.renderer.options;

    el.type = 'range';
    el.min = String(min);
    el.max = String(max);

    el.addEventListener('mousedown', (ev) => {
      ev.stopPropagation();
    });

    this.el = el;
    this.render(props);
  }

  getElement() {
    return this.el;
  }

  render(props) {
    this.el.value = String(props.value);
  }
}

You can customize the visual representation of row headers using header or renderer:

• header: Accepts an HTML string to be placed in the header section (e.g., for a custom 'Select All' checkbox).
• renderer: Accepts a Custom Renderer constructor function to customize the row header section for every individual row. This is useful for implementing custom logic or UI elements like radio buttons (which were discontinued in v4.0).

// Example: Customizing the header with an HTML string
const grid = new Grid({
  // ...,
  rowHeaders: [
    {
      type: 'checkbox',
      header: `
        <label for="all-checkbox" class="checkbox">
          <input type="checkbox" id="all-checkbox" class="hidden-input" name="_checked" />
          <span class="custom-input"></span>
        </label>
      `
    }
  ]
});

// Example: Using a Custom Renderer
class CheckboxRenderer {
  constructor(props) {
    const { grid, rowKey } = props;
    // ... implementation logic ...
    this.el = label;
    this.render(props);
  }

  getElement() {
    return this.el;
  }

  render(props) {
    const hiddenInput = this.el.querySelector('.hidden-input');
    const checked = Boolean(props.value);
    hiddenInput.checked = checked;
  }
}

const grid = new tui.Grid({
  el: document.getElementById('grid'),
  data,
  rowHeaders: [
    {
      type: 'checkbox',
      renderer: {
        type: CheckboxRenderer
      }
    }
  ]
});

When you provide a template function within columnContent or defaultContent, TOAST UI Grid automatically calculates summary statistics whenever column values change.

The template function receives a summary object as an argument, which contains the following properties:

• sum: Sum of the column values.
• avg: Average value of the column.
• min: Minimum value in the column.
• max: Maximum value in the column.
• cnt: Number of rows.

The template function must return an HTML string used to render the summary cell.

const grid = new Grid({
  // ...,
  summary: {
    columnContent: {
      col1: {
        template(summary) {
          return 'sum: ' + summary.sum + '<br>avg: ' + summary.avg;
        }
      },
      col2: {
        template(summary) {
          return 'max: ' + summary.max + '<br>min: ' + summary.min;
        }
      }
    },
    defaultContent: {
      template(summary) {
        return 'default: ' + summary.sum;
      }
    }
  }
})

When an event is triggered, the handler receives a GridEvent instance. This object provides context about the event and allows you to control event behavior.

Key properties and methods:

• rowKey: The identifier for the row involved in the event.
• columnName: The name of the column involved in the event.
• targetType: The type of the target element.
• nativeEvent: The browser's native event object (e.g., MouseEvent).
• stop(): A method to prevent the default action of the event (e.g., preventing a cell from being selected).

// Accessing event details
grid.on('click', function(ev) {
  if (ev.rowKey === 3 && ev.columnName === 'col1') {
    // do something
  }
});

// Preventing default action
grid.on('click', function(ev) {
  if (ev.rowKey === 3) {
    ev.stop();  
  }
});

// Accessing native browser event
grid.on('mousedown', function(ev) {
  console.log(ev.nativeEvent);
});