Grid size

Set the width and height of the grid, using either absolute values or values relative to the parent container.

Set your grid’s size

You need to define the grid’s container as a starting point to initialize it. Usually, the div element becomes this container. This container should have defined dimensions as well as the rest of your layout. Handsontable supports relative units such as %, rem, em, vh, vw, and px.

Define the size in your CSS

Both width and height could be defined as inline styles or as a CSS class property. In this case, it’s important to define what should be an overflow parent properly. Handsontable looks for the closest element with overflow: auto or overflow: hidden to use it as a scrollable container. If no such element is found, a window will be used.

A container with a CSS height but no overflow does not size the grid. The grid then follows the window and grows past that container. Handsontable’s own bars (the pagination bar, the sheets bar) share the scrollable container with the grid, and the grid leaves room for them.

Pass the size in the configuration

You can pass width and height values to Handsontable as numbers or possible CSS values for the “width”/“height” properties:

1
  <HotTable height={100} width={100} />

1
  <HotTable height="75%" width="75%" />

1
  <HotTable height="100px" width="100px" />

You can also pass a function to width and height. Use this when you calculate dimensions from your current layout. The function can return a number (pixels) or a CSS size string.

1
const getGridWidth = () => `${window.innerWidth - 64}px`;
2
const getGridHeight = () => 400;
3

4
<HotTable width={getGridWidth} height={getGridHeight} />

These dimensions will be set as inline styles in a container element, and overflow: hidden will be added automatically.

If container is a block element, then its parent has to have defined height. By default block element is 0px height, so 100% from 0px is still 0px.

Changes called in updateSettings() will re-render the grid with the new properties.

Compare size units

Use the dropdown in the demo below to switch the grid’s width and height between px, %, em, rem, vh, and vw, and see how the same grid responds to each unit.

1
import { useState } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const UNIT_SIZES = {
9
  px: { width: '600px', height: '300px' },
10
  '%': { width: '75%', height: '75%' },
11
  em: { width: '37.5em', height: '18.75em' },
12
  rem: { width: '37.5rem', height: '18.75rem' },
13
  vh: { width: '50vh', height: '50vh' },
14
  vw: { width: '50vw', height: '50vw' },
15
};
16

17
const UNIT_CAPTIONS = {
18
  px: 'A fixed pixel size, independent of any parent element or font size.',
19
  '%': "A percentage of the parent container's size (the dashed box).",
20
  em: "A multiple of this element's own font size.",
21
  rem: "A multiple of the document's root font size.",
22
  vh: "A percentage of the browser viewport's height.",
23
  vw: "A percentage of the browser viewport's width.",
24
};
25

26
const data = [
27
  ['SKU-4821', 'Wireless Mouse', 'Electronics', 'Harbor Goods', 142],
28
  ['SKU-0093', 'Canvas Tote Bag', 'Apparel', 'Alpine Supply Co.', 67],
29
  ['SKU-2210', 'USB-C Hub', 'Electronics', 'Harbor Goods', 0],
30
  ['SKU-7734', 'Ceramic Mug Set', 'Home Goods', 'Nordic Traders', 58],
31
  ['SKU-1145', 'Wool Scarf', 'Apparel', 'Alpine Supply Co.', 213],
32
  ['SKU-3399', 'Bluetooth Speaker', 'Electronics', 'Harbor Goods', 84],
33
  ['SKU-5567', 'Cotton T-Shirt', 'Apparel', 'Alpine Supply Co.', 310],
34
  ['SKU-8842', 'Desk Lamp', 'Home Goods', 'Nordic Traders', 45],
35
  ['SKU-6621', 'Laptop Stand', 'Electronics', 'Harbor Goods', 29],
36
  ['SKU-4470', 'Throw Blanket', 'Home Goods', 'Nordic Traders', 76],
37
  ['SKU-9983', 'Leather Wallet', 'Apparel', 'Alpine Supply Co.', 132],
38
  ['SKU-2287', 'Wireless Charger', 'Electronics', 'Harbor Goods', 97],
39
];
40

41
const ExampleComponent = () => {
42
  const [unit, setUnit] = useState('px');
43
  const { width, height } = UNIT_SIZES[unit];
44

45
  return (
46
    <>
47
      <div className="example-controls-container">
48
        <div className="controls">
49
          <label htmlFor="unitSelect">Grid size unit</label>
50
          <select id="unitSelect" value={unit} onChange={(event) => setUnit(event.target.value)}>
51
            {Object.keys(UNIT_SIZES).map((key) => (
52
              <option key={key} value={key}>{key}</option>
53
            ))}
54
          </select>
55
        </div>
56
        <p className="unit-caption">{UNIT_CAPTIONS[unit]}</p>
57
      </div>
58
      <div id="exampleParent2">
59
        <HotTable
60
          data={data}
61
          colHeaders={['SKU', 'Product', 'Category', 'Supplier', 'Quantity']}
62
          rowHeaders={true}
63
          width={width}
64
          height={height}
65
          licenseKey="non-commercial-and-evaluation"
66
        />
67
      </div>
68
    </>
69
  );
70
};
71

72
export default ExampleComponent;

1
import { useState } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const UNIT_SIZES: Record<string, { width: string; height: string }> = {
9
  px: { width: '600px', height: '300px' },
10
  '%': { width: '75%', height: '75%' },
11
  em: { width: '37.5em', height: '18.75em' },
12
  rem: { width: '37.5rem', height: '18.75rem' },
13
  vh: { width: '50vh', height: '50vh' },
14
  vw: { width: '50vw', height: '50vw' },
15
};
16

17
const UNIT_CAPTIONS: Record<string, string> = {
18
  px: 'A fixed pixel size, independent of any parent element or font size.',
19
  '%': "A percentage of the parent container's size (the dashed box).",
20
  em: "A multiple of this element's own font size.",
21
  rem: "A multiple of the document's root font size.",
22
  vh: "A percentage of the browser viewport's height.",
23
  vw: "A percentage of the browser viewport's width.",
24
};
25

26
const data = [
27
  ['SKU-4821', 'Wireless Mouse', 'Electronics', 'Harbor Goods', 142],
28
  ['SKU-0093', 'Canvas Tote Bag', 'Apparel', 'Alpine Supply Co.', 67],
29
  ['SKU-2210', 'USB-C Hub', 'Electronics', 'Harbor Goods', 0],
30
  ['SKU-7734', 'Ceramic Mug Set', 'Home Goods', 'Nordic Traders', 58],
31
  ['SKU-1145', 'Wool Scarf', 'Apparel', 'Alpine Supply Co.', 213],
32
  ['SKU-3399', 'Bluetooth Speaker', 'Electronics', 'Harbor Goods', 84],
33
  ['SKU-5567', 'Cotton T-Shirt', 'Apparel', 'Alpine Supply Co.', 310],
34
  ['SKU-8842', 'Desk Lamp', 'Home Goods', 'Nordic Traders', 45],
35
  ['SKU-6621', 'Laptop Stand', 'Electronics', 'Harbor Goods', 29],
36
  ['SKU-4470', 'Throw Blanket', 'Home Goods', 'Nordic Traders', 76],
37
  ['SKU-9983', 'Leather Wallet', 'Apparel', 'Alpine Supply Co.', 132],
38
  ['SKU-2287', 'Wireless Charger', 'Electronics', 'Harbor Goods', 97],
39
];
40

41
const ExampleComponent = () => {
42
  const [unit, setUnit] = useState('px');
43
  const { width, height } = UNIT_SIZES[unit];
44

45
  return (
46
    <>
47
      <div className="example-controls-container">
48
        <div className="controls">
49
          <label htmlFor="unitSelect">Grid size unit</label>
50
          <select id="unitSelect" value={unit} onChange={(event) => setUnit(event.target.value)}>
51
            {Object.keys(UNIT_SIZES).map((key) => (
52
              <option key={key} value={key}>{key}</option>
53
            ))}
54
          </select>
55
        </div>
56
        <p className="unit-caption">{UNIT_CAPTIONS[unit]}</p>
57
      </div>
58
      <div id="exampleParent2">
59
        <HotTable
60
          data={data}
61
          colHeaders={['SKU', 'Product', 'Category', 'Supplier', 'Quantity']}
62
          rowHeaders={true}
63
          width={width}
64
          height={height}
65
          licenseKey="non-commercial-and-evaluation"
66
        />
67
      </div>
68
    </>
69
  );
70
};
71

72
export default ExampleComponent;

1
#exampleParent2 {
2
  width: 800px;
3
  max-width: 100%;
4
  height: 400px;
5
  box-sizing: border-box;
6
  border: 1px dashed var(--sl-color-gray-5, #d1d5db);
7
}
8

9
#exampleParent2 > div {
10
  height: 100%;
11
}
12

13
.unit-caption {
14
  margin-top: 8px;
15
  color: var(--sl-color-text, #485164);
16
}

Use `'auto'` sizing

Set height: 'auto' to make the grid behave like a plain block element. Handsontable writes height: auto as an inline style on the root element, and nothing else. The grid grows to fit its rows, the nearest scrolling ancestor or the page scrolls it, and off-screen rows stay virtualized.

1
  <HotTable height="auto" />

You can combine it with width="auto" to let the grid follow its parent container’s width:

1
  <HotTable height="auto" width="auto" />

height: 'auto' is different from leaving height unset:

Setting	Inline styles on root	Scroll parent	Row virtualization
`height: 'auto'`	`height: auto;`	Nearest ancestor with `overflow: auto` or `overflow: hidden`, else the window	Enabled
`height: <number or CSS length>`	`height: <value>; overflow: clip;`	The grid itself	Enabled
`height` unset	None, Handsontable does not touch the root inline styles	Nearest ancestor with `overflow: auto` or `overflow: hidden`, else the window	Enabled

The one difference between 'auto' and an unset height is the inline height: auto, which overrides a height that a stylesheet sets on the root element.

Accepted values

width and height accept the same set of values:

Value	Example
A number of pixels	`height: 500`
A string with a number of pixels	`height: '500'`, `height: '500px'`
A string with a CSS unit	`height: '50%'`, `height: '75vh'`
`'auto'`	`height: 'auto'`
A function that returns one of the above	`height() { return 500; }`

Any other value the browser can read as a CSS length or expression ('20em', 'calc(100% - 40px)', 'var(--grid-height)') is passed through as written.

A value the browser cannot read as a size ('abc', -100, true) is ignored, and so are these CSS keywords:

'inherit', 'initial', 'unset', 'revert', 'revert-layer', 'none', and 'normal', which do not set a size.
'min-content', 'max-content', and 'fit-content', which size the grid to its full content, so it cannot scroll inside its box.
'stretch', '-webkit-fill-available', and '-moz-available', which fill the container but read as a fixed size. Use '100%' or 'auto' instead.

An ignored value leaves the grid’s size as it was, and Handsontable prints a warning once per grid and value.

Passing null to either option through updateSettings() restores that axis to the root element’s initial inline style and leaves the other axis in place.

The two options accept the same values, but they clip differently:

Any height other than 'auto', including a percentage or a viewport unit, sizes the grid’s box. The grid clips both axes and scrolls inside that box, as the table above shows.
A width clips only when it is definite (a number, '500px', '20em'). The grid then scrolls its columns inside that width on its own, with or without a height. A relative width ('100%', '80vw', 'var(--grid-width)') leaves the horizontal overflow to the page, so the columns past it stay reachable.

Troubleshooting with 100% height

When the height option is set to 100%, there are three ways to define the container’s height. Assuming you’re creating an Handsontable instance that has 100% height and container is element with id #example.

1
const container = document.querySelector('#example');
2

3
const hot = new Handsontable(container, {
4
  height: '100%',
5
  // ...rest of config
6
}

Set a fixed height (in pixels) directly on the example element where Handsontable is mounted

1
<div class="page-wrapper">
2
  <!-- Other HTML element -->
3
  <div id="example" style="height: 500px">
4
    <div class="ht-root-wrapper ht-theme-main">
5
      <div class="ht-grid">
6
        <div class="ht-wrapper">
7
          <!-- Table content -->
8
        </div>
9
      </div>
10
      <!-- Table components -->
11
    </div>
12
  </div>
13
</div>

Set a fixed height on the parent element, and then give the example itself a height of 100%

1
<div class="page-wrapper" style="height: 500px">
2
  <!-- Other HTML element -->
3
  <div id="example" style="height: 100%">
4
    <div class="ht-root-wrapper ht-theme-main">
5
      <div class="ht-grid">
6
        <div class="ht-wrapper">
7
          <!-- Table content -->
8
        </div>
9
      </div>
10
      <!-- Table components -->
11
    </div>
12
  </div>
13
</div>

Use flexbox on the wrapper element to make the example fill the available space

1
<div class="page-wrapper" style="display: flex; height: 500px">
2
  <!-- Other HTML element -->
3
  <div id="example" style="flex: 1">
4
    <div class="ht-root-wrapper ht-theme-main">
5
      <div class="ht-grid">
6
        <div class="ht-wrapper">
7
          <!-- Table content -->
8
        </div>
9
      </div>
10
      <!-- Table components -->
11
    </div>
12
  </div>
13
</div>

When using Flexbox, the container automatically expands to fill the available space in the flex container. This is particularly useful when you want the grid to take up all the available space within its parent.

What if the size is not set

If you don’t define any dimensions, Handsontable generates as many rows and columns as needed to fill the available space.

If your grid’s contents don’t fit in the viewport, the browser’s native scrollbars are used for scrolling. For this to work properly, Handsontable’s layout direction (e.g., layoutDirection: 'rtl') must be the same as your HTML document’s layout direction (<html dir='rtl'>). Otherwise, horizontal scrolling doesn’t work.

Stretch columns to fit the grid width

Setting the grid’s width doesn’t change the width of your columns. When the columns are narrower than the grid, the space on the right stays empty. To redistribute the column widths so they fill the grid’s width, use the stretchH option: 'all' stretches all columns proportionally, and 'last' stretches only the last column.

For live examples of both modes, see the column stretching section of the Column width guide.

Autoresizing

Handsontable observes window resizing. If the window’s dimensions have changed, then we check if Handsontable should resize itself too. Due to the performance issue, we use the debounce method to respond on window resize.

You can easily overwrite this behavior by returning false in the beforeRefreshDimensions hook.

1
  <HotTable beforeRefreshDimensions={() => false} />

Manual resizing

The Handsontable instance exposes the refreshDimensions() method, which helps you to resize grid elements properly.

1
hot.refreshDimensions();

You can listen for two hooks, beforeRefreshDimensions and afterRefreshDimensions.

1
import { useRef, useState, useEffect } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
// generate an array of arrays with dummy data
9
const data = new Array(100) // number of rows
10
  .fill(null)
11
  .map((_, row) =>
12
    new Array(50) // number of columns
13
      .fill(null)
14
      .map((_, column) => `${row}, ${column}`)
15
  );
16

17
const ExampleComponent = () => {
18
  const [isContainerExpanded, setIsContainerExpanded] = useState(false);
19
  const hotRef = useRef(null);
20
  const triggerBtnClickCallback = () => {
21
    setIsContainerExpanded(!isContainerExpanded);
22
  };
23

24
  useEffect(() => {
25
    // simulate layout change outside of React lifecycle
26
    // @ts-ignore
27
    document.getElementById('exampleParent').style.height = isContainerExpanded ? '410px' : '157px';
28
    hotRef.current?.hotInstance?.refreshDimensions();
29
  });
30

31
  return (
32
    <>
33
      <div className="example-controls-container">
34
        <div className="controls">
35
          <button id="triggerBtn" className="button button--primary" onClick={() => triggerBtnClickCallback()}>
36
            {isContainerExpanded ? 'Collapse container' : 'Expand container'}
37
          </button>
38
        </div>
39
      </div>
40
      <div id="exampleParent" className="exampleParent">
41
        <HotTable
42
          data={data}
43
          rowHeaders={true}
44
          colHeaders={true}
45
          width="100%"
46
          height="100%"
47
          colWidths={100}
48
          autoWrapRow={true}
49
          autoWrapCol={true}
50
          licenseKey="non-commercial-and-evaluation"
51
          ref={hotRef}
52
        />
53
      </div>
54
    </>
55
  );
56
};
57

58
export default ExampleComponent;

1
import { useRef, useState, useEffect } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
// generate an array of arrays with dummy data
9
const data = new Array(100) // number of rows
10
  .fill(null)
11
  .map((_, row) =>
12
    new Array(50) // number of columns
13
      .fill(null)
14
      .map((_, column) => `${row}, ${column}`)
15
  );
16

17
const ExampleComponent = () => {
18
  const [isContainerExpanded, setIsContainerExpanded] = useState(false);
19
  const hotRef = useRef<HotTableRef>(null);
20

21
  const triggerBtnClickCallback = () => {
22
    setIsContainerExpanded(!isContainerExpanded);
23
  };
24

25
  useEffect(() => {
26
    // simulate layout change outside of React lifecycle
27
    // @ts-ignore
28
    document.getElementById('exampleParent').style.height = isContainerExpanded ? '410px' : '157px';
29
    hotRef.current?.hotInstance?.refreshDimensions();
30
  });
31

32
  return (
33
    <>
34
      <div className="example-controls-container">
35
        <div className="controls">
36
          <button id="triggerBtn" className="button button--primary" onClick={() => triggerBtnClickCallback()}>
37
            {isContainerExpanded ? 'Collapse container' : 'Expand container'}
38
          </button>
39
        </div>
40
      </div>
41
      <div id="exampleParent" className="exampleParent">
42
        <HotTable
43
          data={data}
44
          rowHeaders={true}
45
          colHeaders={true}
46
          width="100%"
47
          height="100%"
48
          colWidths={100}
49
          autoWrapRow={true}
50
          autoWrapCol={true}
51
          licenseKey="non-commercial-and-evaluation"
52
          ref={hotRef}
53
        />
54
      </div>
55
    </>
56
  );
57
};
58

59
export default ExampleComponent;

1
#exampleParent {
2
  height: 157px;
3
}
4

5
#exampleParent > div{
6
  height: 100%;
7
}

Known limitations

Handsontable relies on the browser’s native scrollbars. Browsers cap how tall (or wide) a scrollable area can be, measured in CSS pixels. The taller the scroll area grows past that cap, the more rendering glitches appear - rows become misaligned, the autofill handle turns blurry, and eventually cell borders disappear.

The point where these glitches start depends on the browser, the operating system, and the device. The following approximate values were measured on macOS, and mark where problems begin rather than a hard cutoff:

Browser	Glitches start around
Chrome	~8,000,000 px
Firefox	~3,500,000 px
Safari	~16,000,000 px

These values are approximate, were measured on specific browser versions, and can change as browsers update.

To estimate the maximum number of rows, divide the browser’s pixel limit by your row height. With the default row height of 23 px, Chrome stays reliable up to about 350,000 rows (8,000,000 / 23). To estimate the maximum number of columns, divide the pixel limit by your column width. With a column width of 50 px, that’s about 160,000 columns (8,000,000 / 50).

Taller rows or wider columns lower these limits proportionally. For example, with a row height of 100 px, Chrome’s limit drops to about 80,000 rows (8,000,000 / 100).

If your dataset can grow past these limits, load it in smaller chunks, for example with server-side or lazy data loading.

Frozen rows and columns carry a separate limit: the frozen area must fit within the grid’s width and height. Handsontable always draws that area in full, so when it needs more room than the grid has, it covers the whole grid and the rest can no longer be scrolled into view. Read more in Column freezing and Row freezing.

Result

Your grid now renders at the dimensions you specified, responding to container size or fixed pixel values as configured.

Related guides

Column widths

Row heights

Configuration options

Core methods

Hooks

afterRefreshDimensions

afterUpdateSettings

beforeRefreshDimensions