Instance reference

Use useTemplateRef and the hotInstance property to get a reference to the Handsontable instance from a Vue 3 component, then call any API method on it.

Use Handsontable’s API

You can programmatically change the internal state of Handsontable beyond what’s possible with props. To do that, call API methods of the relevant Handsontable instance associated with your instance of the HotTable component.

In <script setup>, create a template reference with useTemplateRef and give the HotTable component a ref attribute whose value matches the reference key. After the component mounts, the Handsontable instance is available under the hotInstance property of that reference.

Find out which Vue 3 versions are supported

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { HotTable } from '@handsontable/vue3';

const hotTableRef = useTemplateRef<InstanceType<typeof HotTable>>('hotTableRef');

const selectCell = () => {
  hotTableRef.value?.hotInstance?.selectCell(1, 1);
};
</script>

<template>
  <HotTable ref="hotTableRef" :settings="hotSettings" />
</template>

The string passed to useTemplateRef() must match the ref attribute on HotTable. Access the grid through hotTableRef.value?.hotInstance.

The following live example selects cell B2 when you click the button.

Source code

Vue

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const hotTableRef = useTemplateRef<InstanceType<typeof HotTable>>('hotTableRef');

const hotSettings = {
  data: [
    ['A1', 'B1', 'C1', 'D1'],
    ['A2', 'B2', 'C2', 'D2'],
    ['A3', 'B3', 'C3', 'D3'],
    ['A4', 'B4', 'C4', 'D4'],
  ],
  colHeaders: true,
  height: 'auto',
  autoWrapRow: true,
  autoWrapCol: true,
  licenseKey: 'non-commercial-and-evaluation',
};

const selectCell = () => {
  // The Handsontable instance is stored under the `hotInstance` property of the wrapper component.
  hotTableRef.value?.hotInstance?.selectCell(1, 1);
}
</script>

<template>
  <div id="example1">
    <div class="example-controls-container">
      <div class="controls">
        <button @click="selectCell">Select cell B2</button>
      </div>
    </div>
    <HotTable ref="hotTableRef" :settings="hotSettings" />
  </div>
</template>

Vue versions before 3.5

useTemplateRef requires Vue 3.5 or newer. On earlier versions, use the ref function instead. Declare a ref initialized to null, then give the HotTable component a ref attribute whose value matches the variable name.

<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';

const hotTableRef = ref<InstanceType<typeof HotTable> | null>(null);

const selectCell = () => {
  hotTableRef.value?.hotInstance?.selectCell(1, 1);
}
</script>

<template>
  <HotTable ref="hotTableRef" :settings="hotSettings" />
</template>

Result

Your Vue 3 component now holds a reference to the Handsontable instance. You can call any Handsontable API method on that instance — such as selectCell() or getPlugin() — from event handlers or lifecycle hooks.