Column Rendering

Columns render the field value of the data they are bound to. This is the default behavior, which can be customized in a number of ways that we're exploring below.
If you want to explicitly use the TypeScript type definition for columns, import the InfiniteTableColumn type
import { InfiniteTableColumn } from '@infinite-table/infinite-vue'
Note that it's a generic type, so when you use it, you have to bind it to your DATA_TYPE (the type of your data object).
When using custom rendering or custom components for columns, make sure your rendering logic doesn't have local/transient state (a ref created in the setup of a custom component, for example) - what a cell renders should come from the cell information, or from state that lives outside the cell.
This is important because InfiniteTable uses virtualization heavily, in both column cells and column headers, so custom components can and will be unmounted and re-mounted multiple times, during the virtualization process (triggered by user scrolling, sorting, filtering and a few other interactions).

Change the value using valueGetter

The simplest way to change what's being rendered in a column is to use the valueGetter prop and return a new value for the column.
const nameColumn: InfiniteTableColumn<Employee> = {
  header: 'Employee Name',
  valueGetter: ({ data }) => `${data.firstName} ${data.lastName}`,
};
The columns.valueGetter prop is a function that takes a single argument - an object with data and field properties.
Note that the columns.valueGetter is only called for non-group rows, so the data property is of type DATA_TYPE.
#
Column with custom valueGetter
open
loading demo…
The column value getter should not return VNodes or other markup, because the value returned by columns.valueGetter will be used when the column is sorted (when sorting is done client-side and not remotely). For more in-depth information on sorting see the column sorting page.

Use renderValue and render to display custom content

The next step in customizing the rendering for a column is to use the columns.renderValue or the columns.render props. In those functions, you have access to more information than in the columns.valueGetter function. For example, you have access to the current value of groupBy and pivotBy props.
renderValue and render can return any value that Vue can render: a string, a number, a VNode created with h(), or an array of those.
The renderValue and render functions are called with an object that has the following properties:
  • data - the data object (of type DATA_TYPE | Partial<DATA_TYPE> | null) for the row.
  • rowInfo - very useful information about the current row:
    • rowInfo.collapsed - if the row is collased or not.
    • rowInfo.groupBy - the current group by for the row
    • rowInfo.indexInAll - the index of the row in the whole data set
    • rowInfo.indexInGroup - the index of the row in the current group
    • rowInfo.value - the value (only for group rows) that will be rendered by default in group column cells.
    • ... there are other useful properties that we'll document in the near future
  • column - the current column being rendered
  • columnsMap - the Map of columns available to the table. Note these might not be all visible. The keys in this map will be column ids.
  • fieldsToColumn a Map that links DataSource fields to columns. Columns bound to fields (so with columns.field specified) will be included in this Map.
  • api - A reference to the Infinite Table API object.

Column renderValue vs render

columns.render is the last function called in the rendering pipeline for a column cell, while columns.renderValue is called before render, towards the beginning of the rendering pipeline (read more about this below).
Avoid over-writing columns.render for special columns (like group columns) unless you know what you're doing. Special columns use the render function to render additional content inside the column (eg: collapse/expand tool for group rows). The columns.render function allows you to override this additional content. So if you specify this function, it's up to you to render whatever content, including the collapse/expand tool.
However, there are easier ways to override the collapse/expand group icon, like using columns.renderGroupIcon.
A component you render from the columns.renderValue and columns.render functions (and from the other rendering functions) can use the useInfiniteColumnCell composable to retrieve the same params that are passed to the render functions.
The composable returns a ref: read its .value in the render function of your component (or in a computed), not once in setup.
type Developer = { country: string; name: string; id: string };

const CountryInfo = defineComponent({
  setup() {
    const cell = useInfiniteColumnCell<Developer>();

    return () => {
      const { value } = cell.value;

      return h('div', `Country: ${value}`);
    };
  },
});

const columns = {
  country: {
    field: 'country',
    renderValue: () => h(CountryInfo),
  },
};
#
Column with custom renderValue
open
loading demo…
Changing the group icon using render. The icon can also be changed using columns.renderGroupIcon.
#
Column with render - custom expand/collapse icon
This snippet shows overriding the group collapse/expand tool via the columns.render function.
open
loading demo…
#
Column with custom expand/collapse tool via renderGroupIcon
This snippet shows how you can override the group collapse/expand tool via the columns.renderGroupIcon function.
open
loading demo…

Using composables for custom rendering#

The components you render from the columns.render and columns.renderValue functions can use composables - both the ones provided by InfiniteTable and any other Vue composables. Call them in the setup of the component: calling them directly in the render or renderValue function doesn't work.

Composable: useInfiniteColumnCell

In a component rendered inside a column cell, you can use the useInfiniteColumnCell composable to get access to the current cell's rendering information - the argument passed to the render or renderValue functions - as a ref.
import { defineComponent, h } from 'vue';
import { useInfiniteColumnCell } from '@infinite-table/infinite-vue';
import type { InfiniteTableColumn } from '@infinite-table/infinite-vue';

const CustomName = defineComponent({
  setup() {
    const cell = useInfiniteColumnCell<Employee>();

    return () => {
      const { data } = cell.value;

      return [h('b', data?.firstName), ', ', data?.lastName];
    };
  },
});

const nameColumn: InfiniteTableColumn<Employee> = {
  header: 'Employee Name',
  renderValue: () => h(CustomName),
};
#
Column with render & useInfiniteColumnCell
open
loading demo…

Composable: useInfiniteHeaderCell

For column headers, a component rendered inside the header can use the useInfiniteHeaderCell composable to get access to the current header's rendering information - the argument passed to the columns.header function - as a ref.
import { defineComponent, h } from 'vue';
import { useInfiniteHeaderCell } from '@infinite-table/infinite-vue';
import type { InfiniteTableColumn } from '@infinite-table/infinite-vue';

const CustomHeader = defineComponent({
  setup() {
    const headerCell = useInfiniteHeaderCell<Employee>();

    return () => h('b', headerCell.value.column.field);
  },
});

const nameColumn: InfiniteTableColumn<Employee> = {
  field: 'firstName',
  header: () => h(CustomHeader),
};
#
Column Header with render & useInfiniteHeaderCell
open
loading demo…

Use column.components to customize the column

There are cases when custom rendering via the columns.render and columns.renderValue props is not enough and you want to fully control the column cell and render your own custom component for that.
For such scenarios, you can specify column.components.HeaderCell and column.components.ColumnCell, which will use those components to render the DOM nodes of the column header and column cells respectively.
import type { InfiniteTableColumn } from '@infinite-table/infinite-vue';

const ColumnCell = defineComponent({
  inheritAttrs: false,
  setup(_props, { attrs, slots }) {
    return () =>
      h(
        'div',
        { ...attrs, style: [attrs.style, { color: 'red' }] },
        slots.default?.(),
      );
  },
});

const HeaderCell = defineComponent({
  inheritAttrs: false,
  setup(_props, { attrs }) {
    const headerCell = useInfiniteHeaderCell<Developer>();

    return () => {
      const { renderBag } = headerCell.value;

      return h('div', { ...attrs, style: [attrs.style, { color: 'red' }] }, [
        renderBag.sortIcon,
        'First name',
      ]);
    };
  },
});

const nameColumn: InfiniteTableColumn<Developer> = {
  header: 'Name',
  field: 'firstName',
  components: {
    ColumnCell,
    HeaderCell,
  },
};
A custom component needs a single root element, and the attributes the grid passes to the component have to end-up on that element (eg: class for theming and default styles, style, the event listeners, etc). Vue does this by default. If you declare the component with inheritAttrs: false - to merge the style yourself, for example - spread attrs on the root element.
// a component specified in column.components.ColumnCell
const ColumnCell = defineComponent({
  inheritAttrs: false,
  setup(_props, { attrs, slots }) {
    return () => h('div', { ...attrs }, slots.default?.());
  },
});
The default content of the cell is passed as the default slot: render slots.default?.() where you want it.
You don't have to pass the domRef returned by the composables (useInfiniteColumnCell for column cells and useInfiniteHeaderCell for header cells) to the root element - the grid uses the root element of your component.
#
Custom components
open
loading demo…
If the above columns.components is still not enough, read about the rendering pipeline below.

Rendering pipeline#

The rendering pipeline for columns is a series of functions defined on the column that are called while rendering.
All the functions that have the word render in their name will be called with an object that has a renderBag property, which contains values that will be rendered.
The default columns.render function (the last one in the pipeline) ends up rendering a few things:
  • a value - generally comes from the field the column is bound to
  • a groupIcon - for group columns
  • a selectionCheckBox - for columns that have columns.renderSelectionCheckBox defined (combined with row selection)
When the rendering process starts for a column cell, all the above end up in the renderBag object.

Rendering pipeline - renderBag.value

As already mentioned, the value defaults to the value of the column field for the current row.
If the column is not bound to a field, you can define a valueGetter. The valueGetter only has access to {data, field?} in order to compute a value and return it.
After the valueGetter is called, the valueFormatter is next in the rendering pipeline.
This is called with more details about the current cell
const column: InfiniteTableColumn<T> = {
  // the valueGetter can be useful when rows are nested objects
  // or you want to compose multiple values from the row
  valueGetter: ({ data }) => {
    return data.person.salary * 10;
  },
  valueFormatter: ({
    value,
    isGroupRow,
    data,
    field,
    rowInfo,
    rowSelected,
    rowActive,
  }) => {
    // the value here is what the `valueFormatter` returned
    return `USD ${value}`;
  },
};
After valueGetter and valueFormatter are called, the resulting value is the actual value used for the cell. This value will also be assigned to renderBag.value
When renderValue and render are called by InfiniteTable, both value and renderBag will be available as properties to the arguments object.
const column: InfiniteTableColumn<T> = {
  valueGetter: () => 'world',
  renderValue: ({ value }) => {
    // at this stage, `value` is 'world' and `renderBag.value` has the same value, 'world'
    return h('b', value);
  },

  render: ({ renderBag }) => {
    // at this stage `value` is 'world'
    // but `renderBag.value` is <b>world</b>, as this was the value returned by `renderValue`
    return h('div', ['Hello ', renderBag.value, '!']);
  },
};
After the renderValue function is called, the following are also called (if available):
You can think of them as an equivalent to renderValue, but narrowed down to group/non-group rows.
Inside those functions, the renderBag.value refers to the value returned by the renderValue function.

Rendering pipeline - renderBag.groupIcon

In a similar way to renderBag.value, the renderBag.groupIcon is also piped through to the render function.
const column: InfiniteTableColumn<T> = {
  renderGroupIcon: ({ renderBag }) => {
    return [' [ ', renderBag.groupIcon, ' ] '];
  },
  render: ({ renderBag }) => {
    return [
      // use the groupIcon from the renderBag
      renderBag.groupIcon,
      renderBag.value,
    ];
  },
};
Inside columns.renderGroupIcon, you have access to renderBag.groupIcon, which is basically the default group icon - so you can use that if you want, and build on that.
Also inside columns.renderGroupIcon, you have access to toggleGroupRow so you can properly hook the collapse/expand behaviour to your custom group icon.

Rendering pipeline - renderBag.selectionCheckBox

Like with the previous properties of renderBag, you can customize the selectionCheckBox (used when multiple selection is configured) to be piped-through - for columns that specify columns.renderSelectionCheckBox.
const column: InfiniteTableColumn<T> = {
  renderSelectionCheckBox: (params) => {
    if (!params.rowInfo) {
      // the function is also called for the column header
      return params.renderBag.selectionCheckBox;
    }
    const {
      rowSelected,
      isGroupRow,
      toggleCurrentRowSelection,
      toggleCurrentGroupRowSelection,
    } = params;
    const toggle = isGroupRow
      ? toggleCurrentGroupRowSelection
      : toggleCurrentRowSelection;

    // you could return renderBag.groupIcon to have the default icon

    const selection =
      rowSelected === null
        ? '-' // we're in a group row with indeterminate state if rowSelected === null
        : rowSelected
        ? 'x'
        : 'o';

    return h('div', { onClick: toggle }, ` [ ${selection} ] `);
  },
  render: ({ renderBag }) => {
    return [
      // use the selectionCheckBox from the renderBag
      renderBag.selectionCheckBox,
      renderBag.groupIcon,
      renderBag.value,
    ];
  },
};
To recap, here is the full list of the functions in the rendering pipeline, in order of invocation:
  1. columns.valueGetter - doesn't have access to renderBag
  2. columns.valueFormatter - doesn't have access to renderBag
  3. columns.renderGroupIcon - can use all properties in renderBag
  4. columns.renderSelectionCheckBox - can use all properties in renderBag
  5. columns.renderValue - can use all properties in renderBag
  6. columns.renderGroupValue - can use all properties in renderBag
  7. columns.renderLeafValue - can use all properties in renderBag
  8. columns.render - can use all properties in renderBag
Additionally, the columns.components.ColumnCell custom component does have access to the renderBag via useInfiniteColumnCell