- `row`: a row coordinate (a physical index) - `col`: a column coordinate (a physical index) - `prop`: if your [`data`](@/api/options.md#data) is an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), `prop` is a property name for a column's data source object.
If your [`data`](@/api/options.md#data) is an [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), `prop` is the same as `col`. ```ts import { GridSettings } from "@handsontable/angular-wrapper"; gridSettings: GridSettings = { cells: (row, col, prop) => { if (row === 1 || row === 4) { return { // row options, which apply to each cell of the second row // and to each cell of the fifth row readOnly: true, }; } }, }; ``` ```html
- `row`: a row coordinate (a physical index) - `col`: a column coordinate (a physical index) - `prop`: if your [`data`](@/api/options.md#data) is an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), `prop` is a property name for a column's data source object.
If your [`data`](@/api/options.md#data) is an [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), `prop` is the same as `col`. Inside the `cells` function, `this` is the cell meta object, and `this.instance` is the Handsontable instance. Use `this.instance` to call core API methods -- for example, `this.instance.toVisualRow(row)`. ```js const hot = new Handsontable(container, { cells(row, col) { if ((row === 1 || row === 5) && col === 1) { return { readOnly: true, }; } } }); ``` ::: ::: only-for react The function can take three arguments:
- `row`: a row coordinate (a physical index) - `col`: a column coordinate (a physical index) - `prop`: if your [`data`](@/api/options.md#data) is an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), `prop` is a property name for a column's data source object.
If your [`data`](@/api/options.md#data) is an [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), `prop` is the same as `col`. ```jsx
- `row`: a row coordinate (a physical index) - `col`: a column coordinate (a physical index) - `prop`: if your [`data`](@/api/options.md#data) is an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), `prop` is a property name for a column's data source object.
If your [`data`](@/api/options.md#data) is an [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), `prop` is the same as `col`. ```ts import { GridSettings } from "@handsontable/angular-wrapper"; gridSettings: GridSettings = { cells: (row, col) => { if ((row === 1 || row === 5) && col === 1) { return { readOnly: true, }; } }, }; ``` ```html
As a result, the first column cells are editable. - For cell `A1` (`0, 0`), the bottom-level cell options overwrite both the mid-level column options, and the top-level grid options.
As a result, cell `A1` (`0, 0`) is read-only, despite being part of the editable first column. - For cell `C3` (`3, 3`), the [`cells`](@/api/options.md#cells) option overwrites all other options.
As a result, cell `C3` (`3, 3`) is editable, despite not being part of the editable first column. ::: only-for javascript ::: example #example6 --js 1 --ts 2 @[code](@/content/guides/getting-started/configuration-options/javascript/example6.js) @[code](@/content/guides/getting-started/configuration-options/javascript/example6.ts) ::: ::: ::: only-for react ::: example #example6 :react --js 1 --ts 2 @[code](@/content/guides/getting-started/configuration-options/react/example6.jsx) @[code](@/content/guides/getting-started/configuration-options/react/example6.tsx) ::: ::: ::: only-for react ## Non-idempotent options A non-idempotent option is one that produces different results when applied multiple times. In the context of Handsontable and `
- [List of all options](@/api/options.md)
- [cell](@/api/options.md#cell)
- [cells](@/api/options.md#cells)
- [columns](@/api/options.md#columns)
**Core methods**
- [getCellMeta()](@/api/core.md#getcellmeta)
- [getCellMetaAtRow()](@/api/core.md#getcellmetaatrow)
- [getCellsMeta()](@/api/core.md#getcellsmeta)
- [setCellMeta()](@/api/core.md#setcellmeta)
- [setCellMetaObject()](@/api/core.md#setcellmetaobject)
- [removeCellMeta()](@/api/core.md#removecellmeta)
- [getSettings()](@/api/core.md#getsettings)
- [removeCellMeta()](@/api/core.md#removecellmeta)
- [updateSettings()](@/api/core.md#updatesettings)
- [spliceCellsMeta()](@/api/core.md#splicecellsmeta)
**Hooks**
- [afterCellMetaReset](@/api/hooks.md#aftercellmetareset)
- [afterUpdateSettings](@/api/hooks.md#afterupdatesettings)
---
# Grid size
URL: https://handsontable.com/docs/javascript-data-grid/grid-size/
Set the width and height of the grid, using either absolute values or values relative to the parent container.
[[toc]]
## 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.
::: tip
Handsontable doesn't observe CSS changes for containers out of the box.
If you'd like to observe it, you can define the dimensions in the configuration object or create your own observer.
:::
### 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:
::: only-for javascript
```js
{
width: '100px',
height: '100px',
}
```
or
```js
{
width: '75%',
height: '75%',
}
```
or
```js
{
width: 100,
height: 100,
}
```
:::
::: only-for react
```jsx
- [Column widths](@/guides/columns/column-width/column-width.md)
- [Row heights](@/guides/rows/row-height/row-height.md)
**Configuration options**
- [height](@/api/options.md#height)
- [layoutDirection](@/api/options.md#layoutdirection)
- [preventOverflow](@/api/options.md#preventoverflow)
- [width](@/api/options.md#width)
**Core methods**
- [refreshDimensions()](@/api/core.md#refreshdimensions)
- [updateSettings()](@/api/core.md#updatesettings)
**Hooks**
- [afterCellMetaReset](@/api/hooks.md#aftercellmetareset)
- [afterRefreshDimensions](@/api/hooks.md#afterrefreshdimensions)
- [afterUpdateSettings](@/api/hooks.md#afterupdatesettings)
- [beforeRefreshDimensions](@/api/hooks.md#beforerefreshdimensions)
---
# Custom ID, class, and style
URL: https://handsontable.com/docs/javascript-data-grid/custom-id-class-style/
Apply a custom `id`, `class`, and inline `style` to the Handsontable container, to target the grid with your own CSS or JavaScript selectors.
[[toc]]
## Overview
The Handsontable container is a regular DOM element, so you can give it a custom `id`, `class`, and inline `style`. How you set these attributes depends on the framework you use, but two rules apply everywhere:
- `id` is not a configuration option. Handsontable does not read an `id` from the settings object passed to the constructor. The container's `id` comes from the DOM element itself, or from a prop or attribute that the framework wrapper forwards to the container.
- Handsontable assigns a random `id` when the container has none. If the container element has no `id`, or an `id` that starts with `ht_`, Handsontable overwrites it with a generated value in the form `ht_
- [Software license](@/guides/technical-specification/software-license/software-license.md)
### Related API reference
- Configuration options:
- [`licenseKey`](@/api/options.md#licensekey)
---
# Instance methods
URL: https://handsontable.com/docs/react-data-grid/instance-methods/
Use useRef and HotTableRef to get a reference to the Handsontable instance from a React component, then call any API method on it.
[[toc]]
## 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`](@/guides/getting-started/installation/installation.md#_4-use-the-hottable-component) component.
The following example implements the [`HotTable`](@/guides/getting-started/installation/installation.md#_4-use-the-hottable-component) component showing how to reference the Handsontable instance from the wrapper component.
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/getting-started/react-methods/react/example1.jsx)
@[code](@/content/guides/getting-started/react-methods/react/example1.tsx)
:::
::: tip Mobile and Android support
Handsontable is designed for desktop browsers. While the library may load on mobile browsers (including Android), features such as cell editing, context menus, and keyboard navigation may not work as expected on touch devices.
:::
## TypeScript: type the `hotInstance` reference
Since 14.1.0, `HotTable` is a functional component, not a class component. Because of this, you can no longer use `HotTable` as the type argument of `useRef` to get access to the Handsontable instance:
```typescript
// This no longer works as expected since 14.1.0
import HotTable from '@handsontable/react-wrapper';
const ref = useRefLoading the data grid...
- [Working example with Nuxt](https://handsontable.com/codesandbox-vm?example-dir=nuxt&handsontable-version=18.1.2)
## Related
- [Vue 3 installation](@/guides/getting-started/installation/installation.md)
---
# Skills for Claude Code
URL: https://handsontable.com/docs/javascript-data-grid/skills-for-claude-code/
Skills for Claude Code are bundled instructions that give Claude deep knowledge of Handsontable and HyperFormula. Install them once, then ask Claude to build, configure, or debug -- it pulls from the same product docs you're reading right now, so the code it writes matches current APIs instead of guessing from outdated training data.
## Two skills, one install
The repo ships two skills:
- **handsontable** -- the data grid component. Covers React, Angular, Vue, and vanilla JS setup, configuration, theming, cell types, sorting, filtering, formulas, hooks, performance, and version migration.
- **hyperformula** -- the headless calculation engine. Covers instance creation, CRUD, custom functions, named expressions, error handling, batch operations, and Node.js usage.
Use **handsontable** when you're building a visible grid in a web app. Use **hyperformula** when you're evaluating formulas programmatically without a UI -- server-side calculations, pricing engines, what-if analysis. Claude loads whichever is relevant based on what you ask.
## Install with one command
In Claude Code, add the marketplace and install both skills:
```bash
/plugin marketplace add handsontable/handsontable-skills
/plugin install handsontable-skills@handsontable-skills
```
For Cowork or Claude.ai web, download the zip from the latest GitHub release and drag it into chat. For the Claude API, upload the skill folder directly. Full instructions live in the repo README.
## Versioned to match releases
Each skill is tagged to the product version it targets -- `handsontable/v18.1.2` is the skill for Handsontable 18.1.2, and each HyperFormula release gets a matching `hyperformula/v*` tag. You always know which API surface Claude is working from.
Browse the Skills for Claude Code
---
# AI Theme Builder
URL: https://handsontable.com/docs/javascript-data-grid/ai-theme-builder/
The Theme Builder is a free web tool for building Handsontable themes visually, instead of writing code. You can manually adjust over 200 design tokens with UI controls and see the table update in real-time. Then you can export the theme and use it in your own app!
To go deeper on the underlying theme system, see the [Themes](@/guides/styling/themes/themes.md) and [Theme customization](@/guides/styling/theme-customization/theme-customization.md) guides.
## AI theme generation
Click the AI tab on the right to generate themes from a prompt. Describe the look you want -- for example, "minimal light theme with rounded headers" or "dark theme with high-contrast borders" -- and the builder generates the theme configuration file.
You can ask for follow up changes, or switch over to the manual editor to make any final adjustments before exporting.
## Multi-framework support
The Theme Builder generates working configurations for vanilla JavaScript, React, and Angular. So it's easy to use the generated theme in your own framework.
Click the **Generate code** button, then choose your framework, and copy the theme.
## Test in StackBlitz
Try out your theme in a live web application by clicking the **Open in StackBlitz** button. This opens a new tab in StackBlitz where you can test and edit the theme in the web instead of downloading the files to run locally.
Open the Theme Builder
---
# AI Docs Assistant
URL: https://handsontable.com/docs/javascript-data-grid/ai-docs-assistant/
The AI Docs Assistant is the **Ask AI** button in the docs header. It answers questions about Handsontable and HyperFormula, writes code examples, and links you to the relevant guide or API reference page.
::: tip
**How can I help?**
I search the docs to answer questions about APIs, configuration, and usage. I say "I don't know" when the docs don't cover it.
:::
The main search bar (Cmd + K) searches using keyword matches, but the Docs Assistant uses semantic search to match on concepts and related topics. Use the Docs Assistant when you want to chat about a topic or see code examples generated. Click the **Ask AI** button in the header to get started.
## International language support
Ask your question in any language and the assistant will reply accordingly, while keeping API methods, function names, and other key terms in English to ensure valid code generation.
## Current page context
Ask questions about the current page without copy/pasting the contents. The Docs Assistant knows what page you're on, and you can even switch pages and continue the conversation.
---
# Docs MCP Server
URL: https://handsontable.com/docs/javascript-data-grid/docs-mcp-server/
The Docs MCP Server is a public Model Context Protocol endpoint that gives any MCP-capable AI agent live semantic search over the Handsontable and HyperFormula knowledge base:
```
https://docs-assistant.handsontable.com/mcp
```
It runs on the same retrieval that powers the [AI Docs Assistant](@/guides/ai-tools/ai-docs-assistant/ai-docs-assistant.md), exposed as a tool your agent calls while it works. No install, no authentication, no API key.
## What your agent can search
The knowledge base covers more than the docs site:
- Documentation guides and the API reference
- HyperFormula guides
- Code recipes distilled from the [Skills for Claude Code](@/guides/ai-tools/skills-for-claude-code/skills-for-claude-code.md)
- Release notes for both products
- GitHub issues for both products, including resolved discussions
- Blog posts
The index always tracks the latest release of each product, so your agent retrieves current APIs instead of guessing from outdated training data.
## Connect your agent
### Claude Code
```bash
claude mcp add --transport http handsontable-docs https://docs-assistant.handsontable.com/mcp
```
If you use Claude Code, also install the [Skills for Claude Code](@/guides/ai-tools/skills-for-claude-code/skills-for-claude-code.md) -- the skills teach Claude how to work with Handsontable, and the MCP server backs that up with live retrieval.
### Cursor
Add the server to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"handsontable-docs": { "url": "https://docs-assistant.handsontable.com/mcp" }
}
}
```
### Other MCP clients
The server uses the streamable HTTP transport, so any MCP client connects with the URL alone. Add `https://docs-assistant.handsontable.com/mcp` wherever your client configures remote MCP servers.
## The search_docs tool
The server exposes one tool: `search_docs`.
| Argument | Type | Description |
|---|---|---|
| `query` | string, required | What to search for, in natural language or keywords. |
| `limit` | number, optional | Maximum number of snippets to return. |
| `ht_version` | string, optional | Expected Handsontable version. The server validates it against the knowledge base coverage. |
| `hf_version` | string, optional | Expected HyperFormula version. Validated the same way. |
Results are ranked page-level snippets. Each snippet carries a `url` when a public page exists for it, and the response reports which product versions the knowledge base covers.
## Which AI tool should you use?
- **[AI Docs Assistant](@/guides/ai-tools/ai-docs-assistant/ai-docs-assistant.md)** -- you're reading the docs and want answers in chat form.
- **[Skills for Claude Code](@/guides/ai-tools/skills-for-claude-code/skills-for-claude-code.md)** -- you code with Claude Code, Codex, or another agent that supports skills.
- **Docs MCP Server** -- any other MCP-capable agent, or any workflow where the agent should look up current documentation at run time.
They combine well: skills give the agent working knowledge up front, and the MCP server answers the questions that come up along the way.
::: tip
The Docs MCP Server searches documentation. If you want your agent to run spreadsheet calculations through HyperFormula instead, that's the separate HyperFormula MCP Server (early access).
:::
---
# Themes
URL: https://handsontable.com/docs/javascript-data-grid/themes/
Added in Handsontable 15.0.0.
Use Handsontable's built-in themes or customize its look using the Theme API or CSS variables.
[[toc]]
## Overview
Handsontable themes manage most visual elements of the data grid. Three built-in themes are available: `main`, `horizon`, and `classic`. All themes include dark and light modes.
The recommended way to apply themes is using the **Theme API**, which allows you to register and configure themes programmatically with runtime features like density modes and color schemes. Alternatively, you can use **CSS files** and pass the theme name as a string for a simpler setup.
## Built-in themes
The `main` theme offers a spreadsheet-like interface, perfect for batch-editing tasks and providing users with a familiar experience, similar to other popular spreadsheet software on the market.
The `horizon` theme, on the other hand, is better suited for data display and analysis. It hides the vertical lines between columns, giving it a cleaner and more lightweight feel.
The `classic` theme is a replacement for the old legacy style. It retains the familiar look and feel of the original legacy styles, but has been updated to allow customization with CSS variables. This theme is ideal for users who prefer the traditional appearance of Handsontable but want to benefit from the theming system. The `classic` theme supports both light and dark modes, ensuring a seamless integration with your application's color scheme preferences.
Keep in mind that starting from version `15.0`, importing a theme is required.
::: tip Default theme
If you want to use the `main` theme without any modifications, you don't need to configure anything. Handsontable will automatically use the `main` theme with default settings.
:::
::: only-for javascript
::: example #exampleTheme --html 1 --js 2 --ts 3 --css 4
@[code](@/content/guides/styling/themes/javascript/exampleTheme.html)
@[code collapse={9-110}](@/content/guides/styling/themes/javascript/exampleTheme.js)
@[code collapse={9-111}](@/content/guides/styling/themes/javascript/exampleTheme.ts)
@[code](@/content/guides/styling/themes/javascript/exampleTheme.css)
:::
:::
::: only-for react
::: example #exampleTheme .disable-auto-theme :react --js 1 --ts 2 --css 3
@[code collapse={13-114}](@/content/guides/styling/themes/react/exampleTheme.jsx)
@[code collapse={14-115}](@/content/guides/styling/themes/react/exampleTheme.tsx)
@[code](@/content/guides/styling/themes/react/exampleTheme.css)
:::
:::
::: only-for angular
::: example #example1 :angular --css 1 --ts 2 --html 3
@[code](@/content/guides/styling/themes/angular/exampleTheme.css)
@[code](@/content/guides/styling/themes/angular/example1.ts)
@[code](@/content/guides/styling/themes/angular/example1.html)
:::
:::
::: only-for vue
::: example #exampleTheme .disable-auto-theme :vue3 --css 1
@[code](@/content/guides/styling/themes/vue/exampleTheme.css)
@[code collapse={14-116,221-233}](@/content/guides/styling/themes/vue/exampleTheme.vue)
:::
:::
## Light and dark modes
Each theme comes with three modes:
- Light mode
- Dark mode
- Auto mode
When using the Theme API, you can configure the color scheme using `setColorScheme()` with `'light'`, `'dark'`, or `'auto'` values. The `'auto'` option allows programmatic control over light/dark switching based on your application's logic.
When using CSS files, color scheme switching is controlled through CSS class names. Use `ht-theme-{name}` for light mode, `ht-theme-{name}-dark` for dark mode, or `ht-theme-{name}-dark-auto` for automatic switching based on system preferences (e.g., `ht-theme-main`, `ht-theme-main-dark`, `ht-theme-main-dark-auto`).
If you don't want to declare a theme at all, set the [`colorScheme`](@/api/options.md#colorscheme) option instead. See [Set the color scheme or density without a theme](#set-the-color-scheme-or-density-without-a-theme).
## Use a theme
There are two ways to apply a theme. The recommended approach is to use the Theme API with a theme object, which provides full access to runtime configuration features like density modes and color schemes.
### Option 1: Using the Theme API (recommended)
The Theme API allows you to import and register themes programmatically. This approach provides runtime access to theme customization features.
#### Step 1. Import a theme
::: only-for javascript
```js
import Handsontable from 'handsontable';
import { classicTheme } from 'handsontable/themes';
const hot = new Handsontable(container, {
theme: classicTheme,
// ... other options
});
```
:::
::: only-for react
```jsx
import { HotTable } from '@handsontable/react-wrapper';
import { mainTheme, registerTheme } from 'handsontable/themes';
function App() {
return (
- [From components to tables: Designing a data table component in your design system](https://handsontable.com/blog/from-components-to-tables-designing-a-data-table-component-in-your-design-system)
- [Handsontable 15.0.0: Introducing Themes and Functional React Wrapper](https://handsontable.com/blog/handsontable-15.0.0-introducing-themes-and-functional-react-wrapper)
- [Handsontable 16.2.0: Simplified Theming and Advanced User Notifications](https://handsontable.com/blog/handsontable-16.2.0-simplified-theming-and-advanced-user-notifications)
## Troubleshooting
Didn't find what you need? Try this:
- [View related topics](https://github.com/handsontable/handsontable/issues/) on GitHub
- [Report an issue](https://github.com/handsontable/handsontable/issues/new/choose) on GitHub
- [Start a discussion](https://forum.handsontable.com/c/getting-help/questions) on Handsontable's forum
- [Contact our technical support](https://handsontable.com/contact?category=technical_support) to get help
---
# Design system
URL: https://handsontable.com/docs/javascript-data-grid/handsontable-design-system/
The Handsontable design system defines the tokens, themes, and components that control the grid visual appearance. Read this to understand how themes and CSS variables relate.
[[toc]]
## Overview
The Handsontable Design System is a complete toolkit for building, prototyping, and customizing data grids with Handsontable. It includes grid components and design tokens, making it easy to fit Handsontable into your app’s layout or customize it in ways that wouldn’t be possible without built-in features like auto layout, variables, and more.
## Live preview
Open the Design System in Figma
## Use tokens to generate a theme
Inside the Figma file, you’ll find local variables that define all parts of the data grid — like colors, spacing, font styles, icon sizes, and more. These variables are organized into three themes: Main, Horizon and Classic each available in both light and dark mode.
You can tweak the variables however you like to match your brand or product style. Once you’re happy with the changes, export them as JSON tokens. We recommend using the [Design Tokens](https://www.figma.com/community/plugin/888356646278934516/design-tokens) plugin from the Figma Community — it’s straightforward and does the job well.
After exporting, use our [Theme Generator](https://github.com/handsontable/handsontable/tree/develop/handsontable/scripts/themes/figma), located in the Handsontable monorepo at `handsontable/scripts/themes/figma`, to convert your tokens into a CSS theme and JavaScript variables object that works with Handsontable. Run it with `npm run generate:themes` from the `handsontable/` package root.
## Updates frequency
The design system is our primary reference when planning new features or redesigns, and it’s always kept up to date. In some cases, we update the design system independently of product releases to enhance consistency and streamline the design workflow.
## Known limitations
- The legacy style is not part of the design system. Starting from version 17.0.0, legacy styles are no longer supported and you need to migrate to the Classic theme.
## Related blog articles
- [From components to tables: Designing a data table component in your design system](https://handsontable.com/blog/from-components-to-tables-designing-a-data-table-component-in-your-design-system)
## Troubleshooting
Didn't find what you need? Try this:
- [View related topics](https://github.com/handsontable/handsontable/issues/) on GitHub
- [Report an issue](https://github.com/handsontable/handsontable/issues/new/choose) on GitHub
- [Start a discussion](https://forum.handsontable.com/c/getting-help/questions) on Handsontable's forum
- [Contact our technical support](https://handsontable.com/contact?category=technical_support) to get help
## Related
- [Themes](@/guides/styling/themes/themes.md)
- [Legacy Style](@/guides/styling/legacy-style/legacy-style.md)
---
# Theme customization
URL: https://handsontable.com/docs/javascript-data-grid/theme-customization/
Customize Handsontable's appearance using the Theme API, Figma Theme Generator, CSS variables, or the visual Theme Builder.
[[toc]]
## Overview
CSS variables provide a powerful and flexible way to customize Handsontable's appearance by adjusting design elements such as colors, spacing, borders, and typography to match your application's design system. These variables give you granular control over every visual aspect of the data grid, from basic styling to advanced component customization.
We provide multiple approaches for leveraging CSS variables to create any look that your designer can imagine. From quick theme modifications to completely custom designs, your options include:
1. **Theme API** – Modify themes via configuration parameters or register your own custom theme programmatically.
2. **Figma Theme Generator** – Modify design variables in Figma and export them using the Figma Theme Generator tool.
3. **Override CSS variables** – Directly override CSS variables or edit CSS files from the `/styles` directory for full control.
4. **Theme Builder UI** – Use the online [Theme Builder](https://handsontable.com/theme-builder) to visually customize and export your theme without writing code.
The data grid's styling system is built entirely on CSS variables, with over 200 variables organized into logical categories covering typography, colors, spacing, borders, and component-specific styling listed below.
## Option 1: Theme API
The Theme API allows you to customize themes programmatically by registering custom themes and configuring them at runtime. You can use the `theme` option with a `ThemeBuilder` object for dynamic configuration.
### Register a custom theme
Use `registerTheme` to create a custom theme with your own configuration:
::: only-for javascript
```js
import Handsontable from 'handsontable';
import { mainTheme, registerTheme } from 'handsontable/themes';
// Register main theme
const myTheme = registerTheme(mainTheme);
// Configure the theme at runtime
myTheme.setColorScheme('light'); // 'light', 'dark', or 'auto'
myTheme.setDensityType('default'); // 'compact', 'default', or 'comfortable'
const hot = new Handsontable(container, {
theme: myTheme,
// other options
});
```
:::
::: only-for react
```jsx
import Handsontable from 'handsontable';
import { HotTable } from '@handsontable/react-wrapper';
import { mainTheme, registerTheme } from 'handsontable/themes';
// Register main theme
const myTheme = registerTheme(mainTheme);
// Configure the theme at runtime
myTheme.setColorScheme('light');
myTheme.setDensityType('default');
function App() {
return (
### Sizing variables
| Variable | Description |
| -------- | ----------------------- |
|
## Related blog articles
CSS: `--ht-sizing-size-0`
JS: `size_0`
| Zero size (0px) |
| CSS: `--ht-sizing-size-0-25`
JS: `size_0_25`
| Quarter unit size (1px) |
| CSS: `--ht-sizing-size-0-5`
JS: `size_0_5`
| Half unit size (2px) |
| CSS: `--ht-sizing-size-1`
JS: `size_1`
| Base unit size (4px) |
| CSS: `--ht-sizing-size-1-5`
JS: `size_1_5`
| 1.5x unit size (6px) |
| CSS: `--ht-sizing-size-2`
JS: `size_2`
| 2x unit size (8px) |
| CSS: `--ht-sizing-size-3`
JS: `size_3`
| 3x unit size (12px) |
| CSS: `--ht-sizing-size-4`
JS: `size_4`
| 4x unit size (16px) |
| CSS: `--ht-sizing-size-5`
JS: `size_5`
| 5x unit size (20px) |
| CSS: `--ht-sizing-size-6`
JS: `size_6`
| 6x unit size (24px) |
| CSS: `--ht-sizing-size-7`
JS: `size_7`
| 7x unit size (28px) |
| CSS: `--ht-sizing-size-8`
JS: `size_8`
| 8x unit size (32px) |
| CSS: `--ht-sizing-size-9`
JS: `size_9`
| 9x unit size (36px) |
| CSS: `--ht-sizing-size-10`
JS: `size_10`
| 10x unit size (40px) |
### Density variables
| Variable | Description |
| -------- | --------------------------------- |
| CSS: `--ht-density-cell-vertical`
JS: `cellVertical`
| Vertical padding for cells |
| CSS: `--ht-density-cell-horizontal`
JS: `cellHorizontal`
| Horizontal padding for cells |
| CSS: `--ht-density-bars-horizontal`
JS: `barsHorizontal`
| Horizontal padding for bars |
| CSS: `--ht-density-bars-vertical`
JS: `barsVertical`
| Vertical padding for bars |
| CSS: `--ht-density-gap`
JS: `gap`
| Standard gap size |
| CSS: `--ht-density-button-horizontal`
JS: `buttonHorizontal`
| Horizontal padding for buttons |
| CSS: `--ht-density-button-vertical`
JS: `buttonVertical`
| Vertical padding for buttons |
| CSS: `--ht-density-dialog-horizontal`
JS: `dialogHorizontal`
| Horizontal padding for dialogs |
| CSS: `--ht-density-dialog-vertical`
JS: `dialogVertical`
| Vertical padding for dialogs |
| CSS: `--ht-density-input-horizontal`
JS: `inputHorizontal`
| Horizontal padding for inputs |
| CSS: `--ht-density-input-vertical`
JS: `inputVertical`
| Vertical padding for inputs |
| CSS: `--ht-density-menu-vertical`
JS: `menuVertical`
| Vertical padding for menus |
| CSS: `--ht-density-menu-horizontal`
JS: `menuHorizontal`
| Horizontal padding for menus |
| CSS: `--ht-density-menu-item-vertical`
JS: `menuItemVertical`
| Vertical padding for menu items |
| CSS: `--ht-density-menu-item-horizontal`
JS: `menuItemHorizontal`
| Horizontal padding for menu items |
### Color palette variables
| Variable | Description |
| -------- | --------------------------- |
| CSS: `--ht-colors-white`
JS: `white`
| Pure white color |
| CSS: `--ht-colors-black`
JS: `black`
| Pure black color |
| CSS: `--ht-colors-transparent`
JS: `transparent`
| Transparent color |
| CSS: `--ht-colors-primary-100`
JS: `primary.100`
| Lightest primary accent |
| CSS: `--ht-colors-primary-200`
JS: `primary.200`
| Light primary accent |
| CSS: `--ht-colors-primary-300`
JS: `primary.300`
| Medium-light primary accent |
| CSS: `--ht-colors-primary-400`
JS: `primary.400`
| Medium primary accent |
| CSS: `--ht-colors-primary-500`
JS: `primary.500`
| Main primary accent |
| CSS: `--ht-colors-primary-600`
JS: `primary.600`
| Dark primary accent |
| CSS: `--ht-colors-palette-50`
JS: `palette.50`
| Lightest gray |
| CSS: `--ht-colors-palette-100`
JS: `palette.100`
| Very light gray |
| CSS: `--ht-colors-palette-200`
JS: `palette.200`
| Light gray |
| CSS: `--ht-colors-palette-300`
JS: `palette.300`
| Medium-light gray |
| CSS: `--ht-colors-palette-400`
JS: `palette.400`
| Medium gray |
| CSS: `--ht-colors-palette-500`
JS: `palette.500`
| Medium-dark gray |
| CSS: `--ht-colors-palette-600`
JS: `palette.600`
| Dark gray |
| CSS: `--ht-colors-palette-700`
JS: `palette.700`
| Darker gray |
| CSS: `--ht-colors-palette-800`
JS: `palette.800`
| Very dark gray |
| CSS: `--ht-colors-palette-900`
JS: `palette.900`
| Near black |
| CSS: `--ht-colors-palette-950`
JS: `palette.950`
| Darkest gray |
### Tokens variables
#### Typography variables
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-font-family`
JS: `fontFamily`
| Font family for all text elements |
| CSS: `--ht-font-size`
JS: `fontSize`
| Base font size for all text elements |
| CSS: `--ht-font-size-small`
JS: `fontSizeSmall`
| Font size for smaller text |
| CSS: `--ht-line-height`
JS: `lineHeight`
| Line height for text elements |
| CSS: `--ht-line-height-small`
JS: `lineHeightSmall`
| Line height for smaller text |
| CSS: `--ht-font-weight`
JS: `fontWeight`
| Font weight for text elements |
| CSS: `--ht-letter-spacing`
JS: `letterSpacing`
| Letter spacing for text elements |
#### Layout & spacing variables
| Variable | Description |
| -------- | ----------------------------------------------- |
| CSS: `--ht-gap-size`
JS: `gapSize`
| Standard gap size used throughout the component |
| CSS: `--ht-icon-size`
JS: `iconSize`
| Size of icons throughout the interface |
| CSS: `--ht-table-transition`
JS: `tableTransition`
| Transition duration for table animations |
| CSS: `--ht-border-radius`
JS: `borderRadius`
| Border radius of the table |
#### Color system variables
| Variable | Description |
| -------- | ---------------------------------------------------------- |
| CSS: `--ht-border-color`
JS: `borderColor`
| Default border color for all elements |
| CSS: `--ht-accent-color`
JS: `accentColor`
| Primary accent color used for highlights and active states |
| CSS: `--ht-foreground-color`
JS: `foregroundColor`
| Primary text color |
| CSS: `--ht-foreground-secondary-color`
JS: `foregroundSecondaryColor`
| Secondary text color |
| CSS: `--ht-background-color`
JS: `backgroundColor`
| Primary background color |
| CSS: `--ht-background-secondary-color`
JS: `backgroundSecondaryColor`
| Secondary background color |
| CSS: `--ht-placeholder-color`
JS: `placeholderColor`
| Color for placeholder text |
| CSS: `--ht-read-only-color`
JS: `readOnlyColor`
| Color for read-only text |
| CSS: `--ht-disabled-color`
JS: `disabledColor`
| Color for disabled elements |
#### Shadow variables
| Variable | Description |
| -------- | ---------------------------- |
| CSS: `--ht-shadow-color`
JS: `shadowColor`
| Base color used for shadows |
| CSS: `--ht-shadow-x`
JS: `shadowX`
| Horizontal offset of shadows |
| CSS: `--ht-shadow-y`
JS: `shadowY`
| Vertical offset of shadows |
| CSS: `--ht-shadow-blur`
JS: `shadowBlur`
| Blur radius of shadows |
| CSS: `--ht-shadow-opacity`
JS: `shadowOpacity`
| Opacity of shadows |
#### Bar variables
| Variable | Description |
| -------- | -------------------------------------- |
| CSS: `--ht-bar-foreground-color`
JS: `barForegroundColor`
| Foreground color of bar elements |
| CSS: `--ht-bar-background-color`
JS: `barBackgroundColor`
| Background color of bar elements |
| CSS: `--ht-bar-horizontal-padding`
JS: `barHorizontalPadding`
| Horizontal padding inside bar elements |
| CSS: `--ht-bar-vertical-padding`
JS: `barVerticalPadding`
| Vertical padding inside bar elements |
#### Cell border variables
| Variable | Description |
| -------- | -------------------------------- |
| CSS: `--ht-cell-horizontal-border-color`
JS: `cellHorizontalBorderColor`
| Color of horizontal cell borders |
| CSS: `--ht-cell-vertical-border-color`
JS: `cellVerticalBorderColor`
| Color of vertical cell borders |
#### Row styling variables
| Variable | Description |
| -------- | ------------------------------------- |
| CSS: `--ht-row-header-odd-background-color`
JS: `rowHeaderOddBackgroundColor`
| Background color for odd row headers |
| CSS: `--ht-row-header-even-background-color`
JS: `rowHeaderEvenBackgroundColor`
| Background color for even row headers |
| CSS: `--ht-row-cell-odd-background-color`
JS: `rowCellOddBackgroundColor`
| Background color for odd row cells |
| CSS: `--ht-row-cell-even-background-color`
JS: `rowCellEvenBackgroundColor`
| Background color for even row cells |
#### Cell padding variables
| Variable | Description |
| -------- | ------------------------------- |
| CSS: `--ht-cell-horizontal-padding`
JS: `cellHorizontalPadding`
| Horizontal padding inside cells |
| CSS: `--ht-cell-vertical-padding`
JS: `cellVerticalPadding`
| Vertical padding inside cells |
#### Cell editor variables
| Variable | Description |
| -------- | ----------------------------------- |
| CSS: `--ht-cell-editor-border-width`
JS: `cellEditorBorderWidth`
| Border width of cell editors |
| CSS: `--ht-cell-editor-border-color`
JS: `cellEditorBorderColor`
| Border color of cell editors |
| CSS: `--ht-cell-editor-foreground-color`
JS: `cellEditorForegroundColor`
| Text color in cell editors |
| CSS: `--ht-cell-editor-background-color`
JS: `cellEditorBackgroundColor`
| Background color of cell editors |
| CSS: `--ht-cell-editor-shadow-blur-radius`
JS: `cellEditorShadowBlurRadius`
| Shadow blur radius for cell editors |
| CSS: `--ht-cell-editor-shadow-color`
JS: `cellEditorShadowColor`
| Shadow color for cell editors |
#### Cell state variables
| Variable | Description |
| -------- | ----------------------------------------------- |
| CSS: `--ht-cell-success-background-color`
JS: `cellSuccessBackgroundColor`
| Background color for successful cell operations |
| CSS: `--ht-cell-error-background-color`
JS: `cellErrorBackgroundColor`
| Background color for error states in cells |
| CSS: `--ht-cell-read-only-background-color`
JS: `cellReadOnlyBackgroundColor`
| Background color for read-only cells |
#### Cell selection variables
| Variable | Description |
| -------- | ----------------------------------- |
| CSS: `--ht-cell-selection-border-color`
JS: `cellSelectionBorderColor`
| Border color for selected cells |
| CSS: `--ht-cell-selection-background-color`
JS: `cellSelectionBackgroundColor`
| Background color for selected cells |
#### Cell autofill variables
| Variable | Description |
| -------- | --------------------------------------- |
| CSS: `--ht-cell-autofill-size`
JS: `cellAutofillSize`
| Size of the autofill handle |
| CSS: `--ht-cell-autofill-hit-area-size`
JS: `cellAutofillHitAreaSize`
| Size of the autofill hit area |
| CSS: `--ht-cell-autofill-border-width`
JS: `cellAutofillBorderWidth`
| Border width of autofill elements |
| CSS: `--ht-cell-autofill-border-radius`
JS: `cellAutofillBorderRadius`
| Border radius of autofill elements |
| CSS: `--ht-cell-autofill-border-color`
JS: `cellAutofillBorderColor`
| Border color of autofill elements |
| CSS: `--ht-cell-autofill-background-color`
JS: `cellAutofillBackgroundColor`
| Background color of autofill elements |
| CSS: `--ht-cell-autofill-fill-border-color`
JS: `cellAutofillFillBorderColor`
| Border color of autofill fill indicator |
#### Cell mobile handle variables
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-cell-mobile-handle-size`
JS: `cellMobileHandleSize`
| Size of mobile touch handles |
| CSS: `--ht-cell-mobile-handle-border-width`
JS: `cellMobileHandleBorderWidth`
| Border width of mobile handles |
| CSS: `--ht-cell-mobile-handle-border-radius`
JS: `cellMobileHandleBorderRadius`
| Border radius of mobile handles |
| CSS: `--ht-cell-mobile-handle-border-color`
JS: `cellMobileHandleBorderColor`
| Border color of mobile handles |
| CSS: `--ht-cell-mobile-handle-background-color`
JS: `cellMobileHandleBackgroundColor`
| Background color of mobile handles |
| CSS: `--ht-cell-mobile-handle-background-opacity`
JS: `cellMobileHandleBackgroundOpacity`
| Background opacity of mobile handles |
#### Cell selection handle variables
These variables style the handles shown at each edge midpoint of a selected range when the [`selectionHandles`](@/api/options.md#selectionhandles) option is on. They are separate from the mobile touch handles above.
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-cell-selection-handle-size`
JS: `cellSelectionHandleSize`
| Thickness of selection handles |
| CSS: `--ht-cell-selection-handle-length`
JS: `cellSelectionHandleLength`
| Length of selection handles |
| CSS: `--ht-cell-selection-handle-border-width`
JS: `cellSelectionHandleBorderWidth`
| Border width of selection handles |
| CSS: `--ht-cell-selection-handle-border-radius`
JS: `cellSelectionHandleBorderRadius`
| Border radius of selection handles |
| CSS: `--ht-cell-selection-handle-border-color`
JS: `cellSelectionHandleBorderColor`
| Border color of selection handles |
| CSS: `--ht-cell-selection-handle-background-color`
JS: `cellSelectionHandleBackgroundColor`
| Background color of selection handles |
#### Indicator variables
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-resize-indicator-color`
JS: `resizeIndicatorColor`
| Color of resize indicators |
| CSS: `--ht-move-backlight-color`
JS: `moveBacklightColor`
| Background color for move operations |
| CSS: `--ht-move-backlight-opacity`
JS: `moveBacklightOpacity`
| Opacity of move backlight |
| CSS: `--ht-move-indicator-color`
JS: `moveIndicatorColor`
| Color of move indicators |
| CSS: `--ht-hidden-indicator-color`
JS: `hiddenIndicatorColor`
| Color of hidden element indicators |
#### Scrollbar variables
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-scrollbar-border-radius`
JS: `scrollbarBorderRadius`
| Border radius of scrollbars |
| CSS: `--ht-scrollbar-track-color`
JS: `scrollbarTrackColor`
| Background color of scrollbar tracks |
| CSS: `--ht-scrollbar-thumb-color`
JS: `scrollbarThumbColor`
| Color of scrollbar thumbs |
#### Header variables
| Variable | Description |
| -------- | ---------------------------------------- |
| CSS: `--ht-header-font-weight`
JS: `headerFontWeight`
| Font weight for header text |
| CSS: `--ht-header-foreground-color`
JS: `headerForegroundColor`
| Text color for headers |
| CSS: `--ht-header-background-color`
JS: `headerBackgroundColor`
| Background color for headers |
| CSS: `--ht-header-highlighted-shadow-size`
JS: `headerHighlightedShadowSize`
| Shadow size for highlighted headers |
| CSS: `--ht-header-highlighted-foreground-color`
JS: `headerHighlightedForegroundColor`
| Text color for highlighted headers |
| CSS: `--ht-header-highlighted-background-color`
JS: `headerHighlightedBackgroundColor`
| Background color for highlighted headers |
| CSS: `--ht-header-active-border-color`
JS: `headerActiveBorderColor`
| Border color for active headers |
| CSS: `--ht-header-active-foreground-color`
JS: `headerActiveForegroundColor`
| Text color for active headers |
| CSS: `--ht-header-active-background-color`
JS: `headerActiveBackgroundColor`
| Background color for active headers |
| CSS: `--ht-header-filter-background-color`
JS: `headerFilterBackgroundColor`
| Background color for header filters |
#### Header row variables
| Variable | Description |
| -------- | -------------------------------------------- |
| CSS: `--ht-header-row-foreground-color`
JS: `headerRowForegroundColor`
| Text color for header rows |
| CSS: `--ht-header-row-background-color`
JS: `headerRowBackgroundColor`
| Background color for header rows |
| CSS: `--ht-header-row-highlighted-foreground-color`
JS: `headerRowHighlightedForegroundColor`
| Text color for highlighted header rows |
| CSS: `--ht-header-row-highlighted-background-color`
JS: `headerRowHighlightedBackgroundColor`
| Background color for highlighted header rows |
| CSS: `--ht-header-row-active-foreground-color`
JS: `headerRowActiveForegroundColor`
| Text color for active header rows |
| CSS: `--ht-header-row-active-background-color`
JS: `headerRowActiveBackgroundColor`
| Background color for active header rows |
#### Checkbox variables
| Variable | Description |
| -------- | ----------------------------------------------------- |
| CSS: `--ht-checkbox-size`
JS: `checkboxSize`
| Size of checkbox elements |
| CSS: `--ht-checkbox-border-radius`
JS: `checkboxBorderRadius`
| Border radius of checkboxes |
| CSS: `--ht-checkbox-border-color`
JS: `checkboxBorderColor`
| Border color of checkboxes |
| CSS: `--ht-checkbox-background-color`
JS: `checkboxBackgroundColor`
| Background color of checkboxes |
| CSS: `--ht-checkbox-icon-color`
JS: `checkboxIconColor`
| Color of checkbox icons |
| CSS: `--ht-checkbox-focus-border-color`
JS: `checkboxFocusBorderColor`
| Border color of focused checkboxes |
| CSS: `--ht-checkbox-focus-background-color`
JS: `checkboxFocusBackgroundColor`
| Background color of focused checkboxes |
| CSS: `--ht-checkbox-focus-icon-color`
JS: `checkboxFocusIconColor`
| Icon color of focused checkboxes |
| CSS: `--ht-checkbox-focus-ring-color`
JS: `checkboxFocusRingColor`
| Focus ring color for checkboxes |
| CSS: `--ht-checkbox-disabled-border-color`
JS: `checkboxDisabledBorderColor`
| Border color of disabled checkboxes |
| CSS: `--ht-checkbox-disabled-background-color`
JS: `checkboxDisabledBackgroundColor`
| Background color of disabled checkboxes |
| CSS: `--ht-checkbox-disabled-icon-color`
JS: `checkboxDisabledIconColor`
| Icon color of disabled checkboxes |
| CSS: `--ht-checkbox-checked-border-color`
JS: `checkboxCheckedBorderColor`
| Border color of checked checkboxes |
| CSS: `--ht-checkbox-checked-background-color`
JS: `checkboxCheckedBackgroundColor`
| Background color of checked checkboxes |
| CSS: `--ht-checkbox-checked-icon-color`
JS: `checkboxCheckedIconColor`
| Icon color of checked checkboxes |
| CSS: `--ht-checkbox-checked-focus-border-color`
JS: `checkboxCheckedFocusBorderColor`
| Border color of focused checked checkboxes |
| CSS: `--ht-checkbox-checked-focus-background-color`
JS: `checkboxCheckedFocusBackgroundColor`
| Background color of focused checked checkboxes |
| CSS: `--ht-checkbox-checked-focus-icon-color`
JS: `checkboxCheckedFocusIconColor`
| Icon color of focused checked checkboxes |
| CSS: `--ht-checkbox-checked-disabled-border-color`
JS: `checkboxCheckedDisabledBorderColor`
| Border color of disabled checked checkboxes |
| CSS: `--ht-checkbox-checked-disabled-background-color`
JS: `checkboxCheckedDisabledBackgroundColor`
| Background color of disabled checked checkboxes |
| CSS: `--ht-checkbox-checked-disabled-icon-color`
JS: `checkboxCheckedDisabledIconColor`
| Icon color of disabled checked checkboxes |
| CSS: `--ht-checkbox-indeterminate-border-color`
JS: `checkboxIndeterminateBorderColor`
| Border color of indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-background-color`
JS: `checkboxIndeterminateBackgroundColor`
| Background color of indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-icon-color`
JS: `checkboxIndeterminateIconColor`
| Icon color of indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-focus-border-color`
JS: `checkboxIndeterminateFocusBorderColor`
| Border color of focused indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-focus-background-color`
JS: `checkboxIndeterminateFocusBackgroundColor`
| Background color of focused indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-focus-icon-color`
JS: `checkboxIndeterminateFocusIconColor`
| Icon color of focused indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-disabled-border-color`
JS: `checkboxIndeterminateDisabledBorderColor`
| Border color of disabled indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-disabled-background-color`
JS: `checkboxIndeterminateDisabledBackgroundColor`
| Background color of disabled indeterminate checkboxes |
| CSS: `--ht-checkbox-indeterminate-disabled-icon-color`
JS: `checkboxIndeterminateDisabledIconColor`
| Icon color of disabled indeterminate checkboxes |
#### Radio button variables
| Variable | Description |
| -------- | -------------------------------------------------- |
| CSS: `--ht-radio-size`
JS: `radioSize`
| Size of radio button elements |
| CSS: `--ht-radio-border-color`
JS: `radioBorderColor`
| Border color of radio buttons |
| CSS: `--ht-radio-background-color`
JS: `radioBackgroundColor`
| Background color of radio buttons |
| CSS: `--ht-radio-icon-color`
JS: `radioIconColor`
| Color of radio button icons |
| CSS: `--ht-radio-focus-border-color`
JS: `radioFocusBorderColor`
| Border color of focused radio buttons |
| CSS: `--ht-radio-focus-background-color`
JS: `radioFocusBackgroundColor`
| Background color of focused radio buttons |
| CSS: `--ht-radio-focus-icon-color`
JS: `radioFocusIconColor`
| Icon color of focused radio buttons |
| CSS: `--ht-radio-focus-ring-color`
JS: `radioFocusRingColor`
| Focus ring color for radio buttons |
| CSS: `--ht-radio-disabled-border-color`
JS: `radioDisabledBorderColor`
| Border color of disabled radio buttons |
| CSS: `--ht-radio-disabled-background-color`
JS: `radioDisabledBackgroundColor`
| Background color of disabled radio buttons |
| CSS: `--ht-radio-disabled-icon-color`
JS: `radioDisabledIconColor`
| Icon color of disabled radio buttons |
| CSS: `--ht-radio-checked-border-color`
JS: `radioCheckedBorderColor`
| Border color of checked radio buttons |
| CSS: `--ht-radio-checked-background-color`
JS: `radioCheckedBackgroundColor`
| Background color of checked radio buttons |
| CSS: `--ht-radio-checked-icon-color`
JS: `radioCheckedIconColor`
| Icon color of checked radio buttons |
| CSS: `--ht-radio-checked-focus-border-color`
JS: `radioCheckedFocusBorderColor`
| Border color of focused checked radio buttons |
| CSS: `--ht-radio-checked-focus-background-color`
JS: `radioCheckedFocusBackgroundColor`
| Background color of focused checked radio buttons |
| CSS: `--ht-radio-checked-focus-icon-color`
JS: `radioCheckedFocusIconColor`
| Icon color of focused checked radio buttons |
| CSS: `--ht-radio-checked-disabled-border-color`
JS: `radioCheckedDisabledBorderColor`
| Border color of disabled checked radio buttons |
| CSS: `--ht-radio-checked-disabled-background-color`
JS: `radioCheckedDisabledBackgroundColor`
| Background color of disabled checked radio buttons |
| CSS: `--ht-radio-checked-disabled-icon-color`
JS: `radioCheckedDisabledIconColor`
| Icon color of disabled checked radio buttons |
#### Icon button variables
| Variable | Description |
| -------- | ----------------------------------------------- |
| CSS: `--ht-icon-button-border-radius`
JS: `iconButtonBorderRadius`
| Border radius of icon buttons |
| CSS: `--ht-icon-button-large-border-radius`
JS: `iconButtonLargeBorderRadius`
| Border radius of large icon buttons |
| CSS: `--ht-icon-button-large-padding`
JS: `iconButtonLargePadding`
| Padding of large icon buttons |
| CSS: `--ht-icon-button-border-color`
JS: `iconButtonBorderColor`
| Border color of icon buttons |
| CSS: `--ht-icon-button-background-color`
JS: `iconButtonBackgroundColor`
| Background color of icon buttons |
| CSS: `--ht-icon-button-icon-color`
JS: `iconButtonIconColor`
| Color of icon button icons |
| CSS: `--ht-icon-button-hover-border-color`
JS: `iconButtonHoverBorderColor`
| Border color of hovered icon buttons |
| CSS: `--ht-icon-button-hover-background-color`
JS: `iconButtonHoverBackgroundColor`
| Background color of hovered icon buttons |
| CSS: `--ht-icon-button-hover-icon-color`
JS: `iconButtonHoverIconColor`
| Icon color of hovered icon buttons |
| CSS: `--ht-icon-button-active-border-color`
JS: `iconButtonActiveBorderColor`
| Border color of active icon buttons |
| CSS: `--ht-icon-button-active-background-color`
JS: `iconButtonActiveBackgroundColor`
| Background color of active icon buttons |
| CSS: `--ht-icon-button-active-icon-color`
JS: `iconButtonActiveIconColor`
| Icon color of active icon buttons |
| CSS: `--ht-icon-button-active-hover-border-color`
JS: `iconButtonActiveHoverBorderColor`
| Border color of hovered active icon buttons |
| CSS: `--ht-icon-button-active-hover-background-color`
JS: `iconButtonActiveHoverBackgroundColor`
| Background color of hovered active icon buttons |
| CSS: `--ht-icon-button-active-hover-icon-color`
JS: `iconButtonActiveHoverIconColor`
| Icon color of hovered active icon buttons |
| CSS: `--ht-icon-button-hit-area-size`
JS: `iconButtonHitAreaSize`
| Hit area size of icon buttons |
#### Collapse button variables
| Variable | Description |
| -------- | ---------------------------------------------------- |
| CSS: `--ht-collapse-button-border-radius`
JS: `collapseButtonBorderRadius`
| Border radius of collapse buttons |
| CSS: `--ht-collapse-button-open-border-color`
JS: `collapseButtonOpenBorderColor`
| Border color of open collapse buttons |
| CSS: `--ht-collapse-button-open-background-color`
JS: `collapseButtonOpenBackgroundColor`
| Background color of open collapse buttons |
| CSS: `--ht-collapse-button-open-icon-color`
JS: `collapseButtonOpenIconColor`
| Icon color of open collapse buttons |
| CSS: `--ht-collapse-button-open-icon-active-color`
JS: `collapseButtonOpenIconActiveColor`
| Active icon color of open collapse buttons |
| CSS: `--ht-collapse-button-open-hover-border-color`
JS: `collapseButtonOpenHoverBorderColor`
| Border color of hovered open collapse buttons |
| CSS: `--ht-collapse-button-open-hover-background-color`
JS: `collapseButtonOpenHoverBackgroundColor`
| Background color of hovered open collapse buttons |
| CSS: `--ht-collapse-button-open-hover-icon-color`
JS: `collapseButtonOpenHoverIconColor`
| Icon color of hovered open collapse buttons |
| CSS: `--ht-collapse-button-open-hover-icon-active-color`
JS: `collapseButtonOpenHoverIconActiveColor`
| Active icon color of hovered open collapse buttons |
| CSS: `--ht-collapse-button-close-border-color`
JS: `collapseButtonCloseBorderColor`
| Border color of closed collapse buttons |
| CSS: `--ht-collapse-button-close-background-color`
JS: `collapseButtonCloseBackgroundColor`
| Background color of closed collapse buttons |
| CSS: `--ht-collapse-button-close-icon-color`
JS: `collapseButtonCloseIconColor`
| Icon color of closed collapse buttons |
| CSS: `--ht-collapse-button-close-icon-active-color`
JS: `collapseButtonCloseIconActiveColor`
| Active icon color of closed collapse buttons |
| CSS: `--ht-collapse-button-close-hover-border-color`
JS: `collapseButtonCloseHoverBorderColor`
| Border color of hovered closed collapse buttons |
| CSS: `--ht-collapse-button-close-hover-background-color`
JS: `collapseButtonCloseHoverBackgroundColor`
| Background color of hovered closed collapse buttons |
| CSS: `--ht-collapse-button-close-hover-icon-color`
JS: `collapseButtonCloseHoverIconColor`
| Icon color of hovered closed collapse buttons |
| CSS: `--ht-collapse-button-close-hover-icon-active-color`
JS: `collapseButtonCloseHoverIconActiveColor`
| Active icon color of hovered closed collapse buttons |
#### Button variables
| Variable | Description |
| -------- | ----------------------------- |
| CSS: `--ht-button-border-radius`
JS: `buttonBorderRadius`
| Border radius of buttons |
| CSS: `--ht-button-horizontal-padding`
JS: `buttonHorizontalPadding`
| Horizontal padding of buttons |
| CSS: `--ht-button-vertical-padding`
JS: `buttonVerticalPadding`
| Vertical padding of buttons |
#### Primary button variables
| Variable | Description |
| -------- | -------------------------------------------- |
| CSS: `--ht-primary-button-border-color`
JS: `primaryButtonBorderColor`
| Border color of primary buttons |
| CSS: `--ht-primary-button-foreground-color`
JS: `primaryButtonForegroundColor`
| Text color of primary buttons |
| CSS: `--ht-primary-button-background-color`
JS: `primaryButtonBackgroundColor`
| Background color of primary buttons |
| CSS: `--ht-primary-button-disabled-border-color`
JS: `primaryButtonDisabledBorderColor`
| Border color of disabled primary buttons |
| CSS: `--ht-primary-button-disabled-foreground-color`
JS: `primaryButtonDisabledForegroundColor`
| Text color of disabled primary buttons |
| CSS: `--ht-primary-button-disabled-background-color`
JS: `primaryButtonDisabledBackgroundColor`
| Background color of disabled primary buttons |
| CSS: `--ht-primary-button-hover-border-color`
JS: `primaryButtonHoverBorderColor`
| Border color of hovered primary buttons |
| CSS: `--ht-primary-button-hover-foreground-color`
JS: `primaryButtonHoverForegroundColor`
| Text color of hovered primary buttons |
| CSS: `--ht-primary-button-hover-background-color`
JS: `primaryButtonHoverBackgroundColor`
| Background color of hovered primary buttons |
| CSS: `--ht-primary-button-focus-border-color`
JS: `primaryButtonFocusBorderColor`
| Border color of focused primary buttons |
| CSS: `--ht-primary-button-focus-foreground-color`
JS: `primaryButtonFocusForegroundColor`
| Text color of focused primary buttons |
| CSS: `--ht-primary-button-focus-background-color`
JS: `primaryButtonFocusBackgroundColor`
| Background color of focused primary buttons |
#### Secondary button variables
| Variable | Description |
| -------- | ---------------------------------------------- |
| CSS: `--ht-secondary-button-border-color`
JS: `secondaryButtonBorderColor`
| Border color of secondary buttons |
| CSS: `--ht-secondary-button-foreground-color`
JS: `secondaryButtonForegroundColor`
| Text color of secondary buttons |
| CSS: `--ht-secondary-button-background-color`
JS: `secondaryButtonBackgroundColor`
| Background color of secondary buttons |
| CSS: `--ht-secondary-button-disabled-border-color`
JS: `secondaryButtonDisabledBorderColor`
| Border color of disabled secondary buttons |
| CSS: `--ht-secondary-button-disabled-foreground-color`
JS: `secondaryButtonDisabledForegroundColor`
| Text color of disabled secondary buttons |
| CSS: `--ht-secondary-button-disabled-background-color`
JS: `secondaryButtonDisabledBackgroundColor`
| Background color of disabled secondary buttons |
| CSS: `--ht-secondary-button-hover-border-color`
JS: `secondaryButtonHoverBorderColor`
| Border color of hovered secondary buttons |
| CSS: `--ht-secondary-button-hover-foreground-color`
JS: `secondaryButtonHoverForegroundColor`
| Text color of hovered secondary buttons |
| CSS: `--ht-secondary-button-hover-background-color`
JS: `secondaryButtonHoverBackgroundColor`
| Background color of hovered secondary buttons |
| CSS: `--ht-secondary-button-focus-border-color`
JS: `secondaryButtonFocusBorderColor`
| Border color of focused secondary buttons |
| CSS: `--ht-secondary-button-focus-foreground-color`
JS: `secondaryButtonFocusForegroundColor`
| Text color of focused secondary buttons |
| CSS: `--ht-secondary-button-focus-background-color`
JS: `secondaryButtonFocusBackgroundColor`
| Background color of focused secondary buttons |
#### Chip variables
| Variable | Description |
| -------- | ----------------------------------- |
| CSS: `--ht-chip-background`
JS: `chipBackground`
| Background color of chip elements |
| CSS: `--ht-chip-border-radius`
JS: `chipBorderRadius`
| Border radius of chip elements |
| CSS: `--ht-chip-vertical-padding`
JS: `chipVerticalPadding`
| Vertical padding of chip elements |
| CSS: `--ht-chip-horizontal-padding`
JS: `chipHorizontalPadding`
| Horizontal padding of chip elements |
| CSS: `--ht-chip-gap`
JS: `chipGap`
| Gap between chip elements |
#### Comments variables
| Variable | Description |
| -------- | --------------------------------------------- |
| CSS: `--ht-comments-textarea-horizontal-padding`
JS: `commentsTextareaHorizontalPadding`
| Horizontal padding of comment textareas |
| CSS: `--ht-comments-textarea-vertical-padding`
JS: `commentsTextareaVerticalPadding`
| Vertical padding of comment textareas |
| CSS: `--ht-comments-textarea-border-width`
JS: `commentsTextareaBorderWidth`
| Border width of comment textareas |
| CSS: `--ht-comments-textarea-border-color`
JS: `commentsTextareaBorderColor`
| Border color of comment textareas |
| CSS: `--ht-comments-textarea-foreground-color`
JS: `commentsTextareaForegroundColor`
| Text color of comment textareas |
| CSS: `--ht-comments-textarea-background-color`
JS: `commentsTextareaBackgroundColor`
| Background color of comment textareas |
| CSS: `--ht-comments-textarea-focus-border-width`
JS: `commentsTextareaFocusBorderWidth`
| Border width of focused comment textareas |
| CSS: `--ht-comments-textarea-focus-border-color`
JS: `commentsTextareaFocusBorderColor`
| Border color of focused comment textareas |
| CSS: `--ht-comments-textarea-focus-foreground-color`
JS: `commentsTextareaFocusForegroundColor`
| Text color of focused comment textareas |
| CSS: `--ht-comments-textarea-focus-background-color`
JS: `commentsTextareaFocusBackgroundColor`
| Background color of focused comment textareas |
| CSS: `--ht-comments-indicator-size`
JS: `commentsIndicatorSize`
| Size of comment indicators |
| CSS: `--ht-comments-indicator-color`
JS: `commentsIndicatorColor`
| Color of comment indicators |
#### License variables
| Variable | Description |
| -------- | -------------------------------------- |
| CSS: `--ht-license-horizontal-padding`
JS: `licenseHorizontalPadding`
| Horizontal padding of license elements |
| CSS: `--ht-license-vertical-padding`
JS: `licenseVerticalPadding`
| Vertical padding of license elements |
| CSS: `--ht-license-foreground-color`
JS: `licenseForegroundColor`
| Text color of license elements |
| CSS: `--ht-license-background-color`
JS: `licenseBackgroundColor`
| Background color of license elements |
#### Link variables
| Variable | Description |
| -------- | ---------------------- |
| CSS: `--ht-link-color`
JS: `linkColor`
| Color of links |
| CSS: `--ht-link-hover-color`
JS: `linkHoverColor`
| Color of hovered links |
#### Input variables
| Variable | Description |
| -------- | ------------------------------------------- |
| CSS: `--ht-input-border-width`
JS: `inputBorderWidth`
| Border width of input elements |
| CSS: `--ht-input-border-radius`
JS: `inputBorderRadius`
| Border radius of input elements |
| CSS: `--ht-input-horizontal-padding`
JS: `inputHorizontalPadding`
| Horizontal padding of input elements |
| CSS: `--ht-input-vertical-padding`
JS: `inputVerticalPadding`
| Vertical padding of input elements |
| CSS: `--ht-input-border-color`
JS: `inputBorderColor`
| Border color of input elements |
| CSS: `--ht-input-foreground-color`
JS: `inputForegroundColor`
| Text color of input elements |
| CSS: `--ht-input-background-color`
JS: `inputBackgroundColor`
| Background color of input elements |
| CSS: `--ht-input-hover-border-color`
JS: `inputHoverBorderColor`
| Border color of hovered input elements |
| CSS: `--ht-input-hover-foreground-color`
JS: `inputHoverForegroundColor`
| Text color of hovered input elements |
| CSS: `--ht-input-hover-background-color`
JS: `inputHoverBackgroundColor`
| Background color of hovered input elements |
| CSS: `--ht-input-disabled-border-color`
JS: `inputDisabledBorderColor`
| Border color of disabled input elements |
| CSS: `--ht-input-disabled-foreground-color`
JS: `inputDisabledForegroundColor`
| Text color of disabled input elements |
| CSS: `--ht-input-disabled-background-color`
JS: `inputDisabledBackgroundColor`
| Background color of disabled input elements |
| CSS: `--ht-input-focus-border-color`
JS: `inputFocusBorderColor`
| Border color of focused input elements |
| CSS: `--ht-input-focus-foreground-color`
JS: `inputFocusForegroundColor`
| Text color of focused input elements |
| CSS: `--ht-input-focus-background-color`
JS: `inputFocusBackgroundColor`
| Background color of focused input elements |
#### Menu variables
| Variable | Description |
| -------- | --------------------------------------- |
| CSS: `--ht-menu-border-width`
JS: `menuBorderWidth`
| Border width of menu elements |
| CSS: `--ht-menu-border-radius`
JS: `menuBorderRadius`
| Border radius of menu elements |
| CSS: `--ht-menu-horizontal-padding`
JS: `menuHorizontalPadding`
| Horizontal padding of menu elements |
| CSS: `--ht-menu-vertical-padding`
JS: `menuVerticalPadding`
| Vertical padding of menu elements |
| CSS: `--ht-menu-item-horizontal-padding`
JS: `menuItemHorizontalPadding`
| Horizontal padding of menu items |
| CSS: `--ht-menu-item-vertical-padding`
JS: `menuItemVerticalPadding`
| Vertical padding of menu items |
| CSS: `--ht-menu-border-color`
JS: `menuBorderColor`
| Border color of menu elements |
| CSS: `--ht-menu-shadow-x`
JS: `menuShadowX`
| Horizontal shadow offset of menus |
| CSS: `--ht-menu-shadow-y`
JS: `menuShadowY`
| Vertical shadow offset of menus |
| CSS: `--ht-menu-shadow-blur`
JS: `menuShadowBlur`
| Shadow blur radius of menus |
| CSS: `--ht-menu-shadow-color`
JS: `menuShadowColor`
| Shadow color of menus |
| CSS: `--ht-menu-shadow-opacity`
JS: `menuShadowOpacity`
| Shadow opacity of menus |
| CSS: `--ht-menu-item-hover-color`
JS: `menuItemHoverColor`
| Background color of hovered menu items |
| CSS: `--ht-menu-item-hover-color-opacity`
JS: `menuItemHoverColorOpacity`
| Opacity of hovered menu item background |
| CSS: `--ht-menu-item-active-color`
JS: `menuItemActiveColor`
| Background color of active menu items |
| CSS: `--ht-menu-item-active-color-opacity`
JS: `menuItemActiveColorOpacity`
| Opacity of active menu item background |
#### Dialog variables
| Variable | Description |
| -------- | --------------------------------------------------- |
| CSS: `--ht-dialog-semi-transparent-background-color`
JS: `dialogSemiTransparentBackgroundColor`
| Semi-transparent background color of dialog overlay |
| CSS: `--ht-dialog-semi-transparent-background-opacity`
JS: `dialogSemiTransparentBackgroundOpacity`
| Opacity of semi-transparent dialog background |
| CSS: `--ht-dialog-solid-background-color`
JS: `dialogSolidBackgroundColor`
| Solid background color of dialog overlay |
| CSS: `--ht-dialog-content-padding-horizontal`
JS: `dialogContentPaddingHorizontal`
| Horizontal padding of dialog content |
| CSS: `--ht-dialog-content-padding-vertical`
JS: `dialogContentPaddingVertical`
| Vertical padding of dialog content |
| CSS: `--ht-dialog-content-border-radius`
JS: `dialogContentBorderRadius`
| Border radius of dialog content |
| CSS: `--ht-dialog-content-background-color`
JS: `dialogContentBackgroundColor`
| Background color of dialog content |
#### Notification variables
These variables style the [Notification](@/guides/dialog/notification/notification.md) plugin toasts. Shared layout tokens (for example `borderRadius`, `tableTransition`, `gapSize`) and icon-button tokens still apply to the close control and spacing.
| Variable | Description |
| -------- | --------------------------------------------------- |
| CSS: `--ht-notification-foreground-color`
JS: `notificationForegroundColor`
| Text color of notification toasts |
| CSS: `--ht-notification-background-color`
JS: `notificationBackgroundColor`
| Background color of notification toasts |
| CSS: `--ht-notification-border-color`
JS: `notificationBorderColor`
| Border color of notification toasts |
| CSS: `--ht-notification-success-accent`
JS: `notificationSuccessAccent`
| Accent bar color for success toasts |
| CSS: `--ht-notification-warning-accent`
JS: `notificationWarningAccent`
| Accent bar color for warning toasts |
| CSS: `--ht-notification-error-accent`
JS: `notificationErrorAccent`
| Accent bar color for error toasts |
#### Pagination variables
| Variable | Description |
| -------- | ------------------------------------ |
| CSS: `--ht-pagination-bar-foreground-color`
JS: `paginationBarForegroundColor`
| Text color of pagination bar |
| CSS: `--ht-pagination-bar-background-color`
JS: `paginationBarBackgroundColor`
| Background color of pagination bar |
| CSS: `--ht-pagination-bar-horizontal-padding`
JS: `paginationBarHorizontalPadding`
| Horizontal padding of pagination bar |
| CSS: `--ht-pagination-bar-vertical-padding`
JS: `paginationBarVerticalPadding`
| Vertical padding of pagination bar |
| CSS: `--ht-pagination-button-border-color`
JS: `paginationButtonBorderColor`
| Border color of pagination navigation button |
| CSS: `--ht-pagination-button-foreground-color`
JS: `paginationButtonForegroundColor`
| Icon color of pagination navigation button |
| CSS: `--ht-pagination-button-background-color`
JS: `paginationButtonBackgroundColor`
| Background color of pagination navigation button |
| CSS: `--ht-pagination-button-hover-border-color`
JS: `paginationButtonHoverBorderColor`
| Border color of pagination navigation button on hover |
| CSS: `--ht-pagination-button-hover-foreground-color`
JS: `paginationButtonHoverForegroundColor`
| Icon color of pagination navigation button on hover |
| CSS: `--ht-pagination-button-hover-background-color`
JS: `paginationButtonHoverBackgroundColor`
| Background color of pagination navigation button on hover |
| CSS: `--ht-pagination-button-disabled-border-color`
JS: `paginationButtonDisabledBorderColor`
| Border color of pagination navigation button when disabled |
| CSS: `--ht-pagination-button-disabled-foreground-color`
JS: `paginationButtonDisabledForegroundColor`
| Icon color of pagination navigation button when disabled |
| CSS: `--ht-pagination-button-disabled-background-color`
JS: `paginationButtonDisabledBackgroundColor`
| Background color of pagination navigation button when disabled |
| CSS: `--ht-pagination-button-focus-border-color`
JS: `paginationButtonFocusBorderColor`
| Border color of pagination navigation button on focus |
| CSS: `--ht-pagination-button-focus-foreground-color`
JS: `paginationButtonFocusForegroundColor`
| Icon color of pagination navigation button on focus |
| CSS: `--ht-pagination-button-focus-background-color`
JS: `paginationButtonFocusBackgroundColor`
| Background color of pagination navigation button on focus |
- [From components to tables: Designing a data table component in your design system](https://handsontable.com/blog/from-components-to-tables-designing-a-data-table-component-in-your-design-system)
- [Handsontable 14.6.0: Easier styling and enhanced undo-redo](https://handsontable.com/blog/handsontable-14-6-0-easier-styling-and-enhanced-undo-redo)
---
# Legacy style
URL: https://handsontable.com/docs/javascript-data-grid/legacy-style/
Starting from **version 17.0.0**, the legacy stylesheet has been removed from Handsontable. If you're upgrading from an earlier version, you must migrate to the **Classic** theme.
[[toc]]
## Legacy styles are no longer available
The legacy CSS file (`handsontable.full.min.css`) was the default stylesheet up until **version 15** (released in December 2024). In version 16.1, Handsontable introduced a new theming system with the **Classic** theme as a replacement. As of **version 17.0.0**, the legacy stylesheet has been completely removed.
If you're upgrading from a version prior to 17.0.0, you must migrate to the Classic theme to ensure your grid displays correctly.
## Migrate to the Classic theme
There are two ways to apply the Classic theme. The recommended approach is to use the Theme API with a theme object.
### Option 1: Using the Theme API (recommended)
The Theme API allows you to import and register themes programmatically. This approach provides full access to theme customization features like density modes and color schemes.
::: only-for javascript
```js
import Handsontable from 'handsontable';
import { classicTheme } from 'handsontable/themes';
const hot = new Handsontable(container, {
theme: classicTheme,
// ... other options
});
```
:::
::: only-for react
```jsx
import { HotTable } from '@handsontable/react-wrapper';
import { classicTheme } from 'handsontable/themes';
function App() {
return (
- [Migrate from 16.2 to 17.0](@/guides/upgrade-and-migration/migrating-from-16.2-to-17.0/migrating-from-16.2-to-17.0.md)
- [Themes](@/guides/styling/themes/themes.md)
## Result
Your grid now uses the legacy stylesheet. The visual style matches pre-14.0 Handsontable.
---
# Column headers
URL: https://handsontable.com/docs/javascript-data-grid/column-header/
Use default column headers (A, B, C), or set them to custom values provided by an array or a function.
[[toc]]
## Overview
Column headers are gray-colored rows used to label each column or group of columns. By default, these headers are populated with letters in alphabetical order.
To reflect the type or category of data in a particular column, give it a custom name and then display it in a column header. For example, instead of letters as labels such as `A, B, C, ...` name them `ID, Full name, Country, ...`.
## Default headers
Setting the [`colHeaders`](@/api/options.md#colheaders) option to `true` enables the default column headers as shown in the example below:
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example1.js)
@[code](@/content/guides/columns/column-header/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example1.jsx)
@[code](@/content/guides/columns/column-header/react/example1.tsx)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-header/vue/example1.vue)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example1.ts)
@[code](@/content/guides/columns/column-header/angular/example1.html)
:::
:::
## Header labels as an array
An array of labels can be used to set the [`colHeaders`](@/api/options.md#colheaders) as shown in the example below:
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example2.js)
@[code](@/content/guides/columns/column-header/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example2.jsx)
@[code](@/content/guides/columns/column-header/react/example2.tsx)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-header/vue/example2.vue)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example2.ts)
@[code](@/content/guides/columns/column-header/angular/example2.html)
:::
:::
## Header labels as a function
The [`colHeaders`](@/api/options.md#colheaders) can also be populated using a function as shown in the example below:
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example3.js)
@[code](@/content/guides/columns/column-header/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example3.jsx)
@[code](@/content/guides/columns/column-header/react/example3.tsx)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/columns/column-header/vue/example3.vue)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example3.ts)
@[code](@/content/guides/columns/column-header/angular/example3.html)
:::
:::
## Header labels in the columns option
When you configure columns individually with the [`columns`](@/api/options.md#columns) option, set a column's header label with that column's [`title`](@/api/options.md#title) option. If both are set, a column's `title` takes precedence over the matching [`colHeaders`](@/api/options.md#colheaders) entry.
::: only-for javascript
::: example #example6 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example6.js)
@[code](@/content/guides/columns/column-header/javascript/example6.ts)
:::
:::
::: only-for react
::: example #example6 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example6.jsx)
@[code](@/content/guides/columns/column-header/react/example6.tsx)
:::
:::
::: only-for vue
::: example #example6 :vue3
@[code](@/content/guides/columns/column-header/vue/example6.vue)
:::
:::
::: only-for angular
::: example #example6 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example6.ts)
@[code](@/content/guides/columns/column-header/angular/example6.html)
:::
:::
## Customize column headers
You can align the text in the header label with the [`headerClassName`](@/api/options.md#headerclassname) option. Setting it to `htLeft`, `htCenter`, or `htRight` will align the header labels to the left, center, or right, respectively.
You can also set the alignment for a specific column by using the [`columns`](@/api/options.md#columns) option.
::: only-for javascript
::: example #example4 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example4.js)
@[code](@/content/guides/columns/column-header/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example4.jsx)
@[code](@/content/guides/columns/column-header/react/example4.tsx)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/columns/column-header/vue/example4.vue)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example4.ts)
@[code](@/content/guides/columns/column-header/angular/example4.html)
:::
:::
If you want to style the header labels, you can pass any number of class names, separated by a space, to the [`headerClassName`](@/api/options.md#headerclassname) option.
::: only-for javascript
::: example #example5 --css 1 --js 2 --ts 3
@[code](@/content/guides/columns/column-header/javascript/example5.css)
@[code](@/content/guides/columns/column-header/javascript/example5.js)
@[code](@/content/guides/columns/column-header/javascript/example5.ts)
:::
:::
::: only-for react
::: example #example5 :react --css 1 --js 2 --ts 3
@[code](@/content/guides/columns/column-header/react/example5.css)
@[code](@/content/guides/columns/column-header/react/example5.jsx)
@[code](@/content/guides/columns/column-header/react/example5.tsx)
:::
:::
::: only-for vue
::: example #example5 :vue3
@[code](@/content/guides/columns/column-header/vue/example5.vue)
:::
:::
::: only-for angular
::: example #example5 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example5.ts)
@[code](@/content/guides/columns/column-header/angular/example5.html)
:::
:::
## Column header height
When column labels are longer, header text can wrap and require more vertical space. To control the header size, set [`columnHeaderHeight`](@/api/options.md#columnheaderheight).
You can set this option to one of the following:
- A number - set the same height for every column header.
- An array - set different heights for individual column header levels.
The example below uses longer labels together with `columnHeaderHeight: 50`.
::: only-for javascript
::: example #example7 --js 1 --ts 2
@[code](@/content/guides/columns/column-header/javascript/example7.js)
@[code](@/content/guides/columns/column-header/javascript/example7.ts)
:::
:::
::: only-for react
::: example #example7 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-header/react/example7.jsx)
@[code](@/content/guides/columns/column-header/react/example7.tsx)
:::
:::
::: only-for vue
::: example #example7 :vue3
@[code](@/content/guides/columns/column-header/vue/example7.vue)
:::
:::
::: only-for angular
::: example #example7 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-header/angular/example7.ts)
@[code](@/content/guides/columns/column-header/angular/example7.html)
:::
:::
## Nested headers
More complex data structures can be displayed with multiple headers, each representing a different category of data. To learn more about nested headers, see the [column groups](@/guides/columns/column-groups/column-groups.md) page.
## Related articles
**Related guides**
- [Column groups](@/guides/columns/column-groups/column-groups.md)
**Related blog articles**
- [Handsontable 14.5.0: Improved performance and flexible column header class](https://handsontable.com/blog/handsontable-14.5.0-improved-performance-and-flexible-column-header-class)
**Configuration options**
- [activeHeaderClassName](@/api/options.md#activeheaderclassname)
- [colHeaders](@/api/options.md#colheaders)
- [columnHeaderHeight](@/api/options.md#columnheaderheight)
- [currentHeaderClassName](@/api/options.md#currentheaderclassname)
- [nestedHeaders](@/api/options.md#nestedheaders)
- [title](@/api/options.md#title)
**Core methods**
- [getColHeader()](@/api/core.md#getcolheader)
- [hasColHeaders()](@/api/core.md#hascolheaders)
**Hooks**
- [afterGetColHeader](@/api/hooks.md#aftergetcolheader)
- [afterGetColumnHeaderRenderers](@/api/hooks.md#aftergetcolumnheaderrenderers)
- [beforeHighlightingColumnHeader](@/api/hooks.md#beforehighlightingcolumnheader)
- [modifyColHeader](@/api/hooks.md#modifycolheader)
- [modifyColumnHeaderHeight](@/api/hooks.md#modifycolumnheaderheight)
**Plugins**
- [NestedHeaders](@/api/nestedHeaders.md)
---
# Column groups
URL: https://handsontable.com/docs/javascript-data-grid/column-groups/
Group your columns, using multiple levels of nested column headers, to better reflect the structure of your data.
[[toc]]
## Nested column headers
The [`NestedHeaders`](@/api/nestedHeaders.md) plugin allows you to create a nested headers structure by using the HTML `colspan` and `rowspan` attributes.
To create a header that spans multiple columns, its corresponding configuration array element should be provided as an object with `label` and `colspan`
properties. The `label` property defines the header's label, while the `colspan` property defines the number of columns that the header should cover.
To create a header that spans multiple header rows, add a `rowspan` property to that object. See [Rowspan](#rowspan) below.
### Header configuration object
Each `nestedHeaders` entry is either a string label or an object with these properties:
| Property | Type | Description |
| ----------------- | -------- | ----------- |
| `label` | `string` | The header's text. |
| `colspan` | `number` | Columns the header spans (an integer greater than `1`); groups the columns it covers. |
| `rowspan` | `number` | Header rows the header spans (an integer greater than `1`). See [Rowspan](#rowspan). |
| `headerClassName` | `string` | One or more space-separated CSS class names added to the header element (for example, `'htRight'`). |
| `visibleWhen` | `string` | For a header in a collapsible group, which collapse state keeps it visible: `'collapsed'`, `'expanded'`, or `'always'`. See [Choose which columns stay visible when collapsed](#choose-which-columns-stay-visible-when-collapsed). |
| `columnDropMode` | `string` | What the group does when a foreign column is moved into its span: `'adopt'` (default) or `'split'`. See [Keep a group cohesive or let it split](#keep-a-group-cohesive-or-let-it-split). |
| `collapsible` | `boolean` | Whether the group can be collapsed and expanded. You enable it through the [`collapsibleColumns`](@/api/options.md#collapsiblecolumns) option, not in the `nestedHeaders` object. See [Collapsible headers](#collapsible-headers). |
For defaults and full details, see the [`nestedHeaders` API reference](@/api/options.md#nestedheaders).
::: warning
A `label` is written to the DOM as HTML, so a label built from user input or an external system can inject markup. Handsontable does not sanitize it by default. Set the [`sanitizer`](@/api/options.md#sanitizer) option, which receives nested header labels under the `'header'` source. See [Content sanitizing](@/guides/security/security/security.md#content-sanitizing).
:::
### Configuration
::: only-for javascript
```js
nestedHeaders: [
['A', { label: 'B', colspan: 8 }, 'C'],
['D', { label: 'E', colspan: 4 }, { label: 'F', colspan: 4 }, 'G'],
['H', { label: 'I', colspan: 2 }, { label: 'J', colspan: 2 }, { label: 'K', colspan: 2 }, { label: 'L', colspan: 2 }, 'M'],
['N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W'],
];
```
:::
::: only-for react
```jsx
nestedHeaders={[
['A', { label: 'B', colspan: 8 }, 'C'],
['D', { label: 'E', colspan: 4 }, { label: 'F', colspan: 4 }, 'G'],
['H', { label: 'I', colspan: 2 }, { label: 'J', colspan: 2 }, { label: 'K', colspan: 2 }, { label: 'L', colspan: 2 }, 'M'],
['N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W']
]}
```
:::
::: only-for vue
```js
nestedHeaders: [
['A', { label: 'B', colspan: 8 }, 'C'],
['D', { label: 'E', colspan: 4 }, { label: 'F', colspan: 4 }, 'G'],
['H', { label: 'I', colspan: 2 }, { label: 'J', colspan: 2 }, { label: 'K', colspan: 2 }, { label: 'L', colspan: 2 }, 'M'],
['N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W'],
],
```
:::
### Example
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/javascript/example1.js)
@[code](@/content/guides/columns/column-groups/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/react/example1.jsx)
@[code](@/content/guides/columns/column-groups/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-groups/angular/example1.ts)
@[code](@/content/guides/columns/column-groups/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-groups/vue/example1.vue)
:::
:::
### Rowspan
The `rowspan` property sets how many header rows a single header cell should cover. Use an integer greater than `1`. Positions in lower rows that sit under that cell can use an empty string `''` as a placeholder, but those placeholders are optional. Handsontable can infer covered slots when you omit them.
You can combine `rowspan` and `colspan` on the same header object. The same rules apply as for colspan only: a header cannot be wider than its parent in the hierarchy, and overlapping header definitions are not supported.
#### Configuration
::: only-for javascript
```js
nestedHeaders: [
[{ label: 'A', rowspan: 2 }, { label: 'B', colspan: 2 }],
['', 'C', 'D'],
];
```
:::
::: only-for react
```jsx
nestedHeaders={[
[{ label: 'A', rowspan: 2 }, { label: 'B', colspan: 2 }],
['', 'C', 'D'],
]}
```
:::
::: only-for angular
```ts
nestedHeaders: [
[{ label: 'A', rowspan: 2 }, { label: 'B', colspan: 2 }],
['', 'C', 'D'],
];
```
:::
::: only-for vue
```js
nestedHeaders: [
[{ label: 'A', rowspan: 2 }, { label: 'B', colspan: 2 }],
['', 'C', 'D'],
],
```
:::
## Collapsible headers
The [`CollapsibleColumns`](@/api/collapsibleColumns.md) plugin enables columns and their headers to be collapsed/expanded.
This plugin adds multi-column headers which have buttons. Clicking these buttons will collapse or expand all "child" headers, leaving the first one visible.
The [`NestedHeaders`](@/api/nestedHeaders.md) plugin needs to be enabled for this to work properly.
### Configuration
To enable the Collapsible Columns plugin, either set the [`collapsibleColumns`](@/api/options.md#collapsiblecolumns) configuration option to:
- `true` - this will enable the functionality for _all_ multi-column headers, every column with the `colspan` attribute defined will be extended with the
"expand/collapse" button
- An array of objects containing information specifying which headers should have the "expand/collapse" buttons for example:
::: only-for javascript
```js
collapsibleColumns: [
{ row: -4, col: 1, collapsible: true }, // Add the button to the 4th-level header of the 1st column - counting from the first table row upwards.
{ row: -3, col: 5, collapsible: true }, // Add the button to the 3rd-level header of the 5th column - counting from the first table row upwards.
];
```
:::
::: only-for react
```jsx
collapsibleColumns={[
{ row: -4, col: 1, collapsible: true }, // Add the button to the 4th-level header of the 1st column - counting from the first table row upwards.
{ row: -3, col: 5, collapsible: true } // Add the button to the 3rd-level header of the 5th column - counting from the first table row upwards.
]}
```
:::
::: only-for angular
```js
collapsibleColumns: [
{ row: -4, col: 1, collapsible: true }, // Add the button to the 4th-level header of the 1st column - counting from the first table row upwards.
{ row: -3, col: 5, collapsible: true }, // Add the button to the 3rd-level header of the 5th column - counting from the first table row upwards.
];
```
:::
::: only-for vue
```js
collapsibleColumns: [
{ row: -4, col: 1, collapsible: true }, // Add the button to the 4th-level header of the 1st column - counting from the first table row upwards.
{ row: -3, col: 5, collapsible: true }, // Add the button to the 3rd-level header of the 5th column - counting from the first table row upwards.
],
```
:::
The `row` coordinate is negative - counting from the first table row upwards - so `-1` points to the header row directly above the first table row, and `-4` points to the top header row of four nested levels. The `col` coordinate is the zero-based index of the column where the header starts.
### Example
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/javascript/example2.js)
@[code](@/content/guides/columns/column-groups/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/react/example2.jsx)
@[code](@/content/guides/columns/column-groups/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-groups/angular/example2.ts)
@[code](@/content/guides/columns/column-groups/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-groups/vue/example2.vue)
:::
:::
### Choose which columns stay visible when collapsed
By default, collapsing a group leaves its first column visible. To choose which columns stay visible in each state, add the `visibleWhen` property to a header in the `nestedHeaders` configuration. It accepts three values:
- `'collapsed'` - the column is visible only while its group is collapsed (hidden while expanded).
- `'expanded'` - the column is visible only while its group is expanded (hidden while collapsed).
- `'always'` - the column is visible in both states.
Once a group uses `visibleWhen` on any of its headers, the headers you leave unmarked default to `'expanded'` - they are hidden when the group collapses. So you only mark the column(s) you want to keep: tag one with `'always'` (stays in both states) or `'collapsed'` (a summary column that appears only on collapse). At least one column of a group always stays visible, so its collapse button is never lost.
In the example below, collapse the **Q1 2025** group: the per-month columns (marked `'expanded'`) hide and the **Total** column (`'collapsed'`) appears. Expanding the group reverses it.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/javascript/example3.js)
@[code](@/content/guides/columns/column-groups/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/react/example3.jsx)
@[code](@/content/guides/columns/column-groups/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-groups/angular/example3.ts)
@[code](@/content/guides/columns/column-groups/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/columns/column-groups/vue/example3.vue)
:::
:::
A group whose headers use no `visibleWhen` markers keeps the default behavior - collapsing leaves its first column visible. The `visibleWhen` property applies only to headers within a [`collapsible`](@/api/options.md#collapsiblecolumns) group.
## Moving grouped columns
When you enable the [`ManualColumnMove`](@/api/manualColumnMove.md) plugin, nested column headers follow their columns. Moving a column moves both its data and its header label, so the labels always describe the columns beneath them.
When a move separates the columns of a group, that group renders as more than one header. Each header covers a contiguous run of the group's columns and repeats the group's label. No move is blocked.
Moving an entire group relocates the group and its label as a single unit. The group can land between other groups.
When a group is both [collapsible](#collapsible-headers) and collapsed:
- A move that keeps the group's columns together keeps the group collapsed and moves it to its new position.
- A move that would separate the group's columns expands the group first, so none of its columns stay hidden without a way to expand them.
### Keep a group cohesive or let it split
By default, a group is _cohesive_. When you move a column into the group's span, the group adopts that column as a member and stays a single header that grows to cover it.
Set `columnDropMode: 'split'` on the group's header object to change this. A group in split mode does not adopt a _foreign_ column - one that belongs to a different group - moved into its span. It keeps its identity and renders as several same-label banners around that column.
`columnDropMode` controls only whether a group absorbs columns from outside it. A group always reclaims its own columns: moving one of a group's columns out and then back into the group's span merges it into a single banner again, regardless of its `columnDropMode`.
Moving a column _out of_ a group separates a group in either mode the same way: the group renders as more than one header, each repeating its label.
::: only-for javascript
```js
nestedHeaders: [
// "Q1 2025" is cohesive (the default); "Q2 2025" splits when a column moves into it.
[{ label: 'Q1 2025 (adopt mode)', colspan: 3 }, { label: 'Q2 2025 (split mode)', colspan: 3, columnDropMode: 'split' }],
['January', 'February', 'March', 'April', 'May', 'June'],
];
```
:::
::: only-for react
```jsx
nestedHeaders={[
// "Q1 2025" is cohesive (the default); "Q2 2025" splits when a column moves into it.
[{ label: 'Q1 2025 (adopt mode)', colspan: 3 }, { label: 'Q2 2025 (split mode)', colspan: 3, columnDropMode: 'split' }],
['January', 'February', 'March', 'April', 'May', 'June']
]}
```
:::
::: only-for angular
```ts
nestedHeaders: [
// "Q1 2025" is cohesive (the default); "Q2 2025" splits when a column moves into it.
[{ label: 'Q1 2025 (adopt mode)', colspan: 3 }, { label: 'Q2 2025 (split mode)', colspan: 3, columnDropMode: 'split' }],
['January', 'February', 'March', 'April', 'May', 'June'],
];
```
:::
::: only-for vue
```js
nestedHeaders: [
// "Q1 2025" is cohesive (the default); "Q2 2025" splits when a column moves into it.
[{ label: 'Q1 2025 (adopt mode)', colspan: 3 }, { label: 'Q2 2025 (split mode)', colspan: 3, columnDropMode: 'split' }],
['January', 'February', 'March', 'April', 'May', 'June'],
],
```
:::
In the example below, both quarters group three months. **Q1 2025** uses adopt mode (the default) and **Q2 2025** uses split mode. Drag a month from **Q2 2025** into the middle of **Q1 2025**: the **Q1 2025** group adopts it and spans four columns. Drag a month from **Q1 2025** into the middle of **Q2 2025**: the **Q2 2025** group splits into two **Q2 2025** banners around the inserted column. Drag a **Q2 2025** month out and then back into **Q2 2025**: it rejoins the single banner, because it belongs to that group.
::: only-for javascript
::: example #example4 --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/javascript/example4.js)
@[code](@/content/guides/columns/column-groups/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-groups/react/example4.jsx)
@[code](@/content/guides/columns/column-groups/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-groups/angular/example4.ts)
@[code](@/content/guides/columns/column-groups/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/columns/column-groups/vue/example4.vue)
:::
:::
## Known limitations
- A column header can span up to 1000 columns, as the [HTML table specification](https://html.spec.whatwg.org/multipage/tables.html#dom-tdth-colspan) sets the
limit of `colspan` to `1000`.
- A nested column header can't be wider than its parent element (headers can't overlap).
- If `rowspan` is larger than the number of header rows below the cell, Handsontable clamps it to the remaining header levels.
## Related keyboard shortcuts
This header-focused shortcut works only when a collapsible column group header is focused. Enable [`navigableHeaders: true`](@/api/options.md#navigableheaders) to move focus onto headers with the arrow keys. For more details, see [Keyboard navigation](@/guides/accessibility/accessibility/accessibility.md#keyboard-navigation).
| Windows | macOS | Action | Excel | Sheets |
| ------------------------------------------- | -------------------------------------------- | ------------------------------------------------------- | :-----: | :-----: |
| **Enter** | **Enter** | Collapse or expand the selected column group | ✗ | ✗ |
## Related API reference
**Configuration options**
- [collapsibleColumns](@/api/options.md#collapsiblecolumns)
- [nestedHeaders](@/api/options.md#nestedheaders)
- [manualColumnMove](@/api/options.md#manualcolumnmove)
**Core methods**
- [isColumnModificationAllowed()](@/api/core.md#iscolumnmodificationallowed)
**Hooks**
- [afterColumnCollapse](@/api/hooks.md#aftercolumncollapse)
- [afterColumnExpand](@/api/hooks.md#aftercolumnexpand)
- [beforeColumnCollapse](@/api/hooks.md#beforecolumncollapse)
- [beforeColumnExpand](@/api/hooks.md#beforecolumnexpand)
**Plugins**
- [CollapsibleColumns](@/api/collapsibleColumns.md)
- [NestedHeaders](@/api/nestedHeaders.md)
---
# Column hiding
URL: https://handsontable.com/docs/javascript-data-grid/column-hiding/
Hide individual columns to reduce screen clutter and improve the grid's performance.
[[toc]]
## Overview
"Hiding a column" means that the hidden column doesn't get rendered as a DOM element.
When you're hiding a column:
- The source data doesn't get modified.
- The [`HiddenColumns`](@/api/hiddenColumns.md) plugin doesn't participate in data
transformation(the shape of the data returned by the [`getData*()` methods](@/api/core.md#getdata) stays intact). ## Enable column hiding To enable column hiding, use the [`hiddenColumns`](@/api/options.md#hiddencolumns) option. ::: only-for javascript ::: example #example1 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example1.js) @[code](@/content/guides/columns/column-hiding/javascript/example1.ts) ::: ::: ::: only-for react ::: example #example1 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example1.jsx) @[code](@/content/guides/columns/column-hiding/react/example1.tsx) ::: ::: [//]: # (The empty HTML comment above is a workaround for the `example` container error.) [//]: # (DON'T REMOVE IT!) ::: only-for angular ::: example #example1 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example1.ts) @[code](@/content/guides/columns/column-hiding/angular/example1.html) ::: ::: ::: only-for vue ::: example #example1 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example1.vue) ::: ::: ## Set up column hiding To set up your column hiding configuration, follow the steps below. ### Step 1: Specify columns hidden by default To both enable column hiding and specify columns hidden by default, set the [`hiddenColumns`](@/api/options.md#hiddencolumns) configuration option to an object. In the object, add a [`columns`](@/api/options.md#columns) configuration option, and set it to an array of column indexes. Now, those columns are hidden by default: ::: only-for javascript ::: example #example2 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example2.js) @[code](@/content/guides/columns/column-hiding/javascript/example2.ts) ::: ::: ::: only-for react ::: example #example2 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example2.jsx) @[code](@/content/guides/columns/column-hiding/react/example2.tsx) ::: ::: ::: only-for angular ::: example #example2 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example2.ts) @[code](@/content/guides/columns/column-hiding/angular/example2.html) ::: ::: ::: only-for vue ::: example #example2 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example2.vue) ::: ::: ### Step 2: Show UI indicators To easily see which columns are currently hidden, display UI indicators. To enable the UI indicators, in the [`hiddenColumns`](@/api/options.md#hiddencolumns) object, set the [`indicators`](@/api/hiddenColumns.md) property to `true`: ::: tip If you use both the [`NestedHeaders`](@/api/nestedHeaders.md) plugin and the [`HiddenColumns`](@/api/hiddenColumns.md) plugin, you also need to set the [`colHeaders`](@/api/options.md#colheaders) property to `true`. Otherwise, [`indicators`](@/api/hiddenColumns.md) won't work. ::: ::: only-for javascript ::: example #example3 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example3.js) @[code](@/content/guides/columns/column-hiding/javascript/example3.ts) ::: ::: ::: only-for react ::: example #example3 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example3.jsx) @[code](@/content/guides/columns/column-hiding/react/example3.tsx) ::: ::: ::: only-for angular ::: example #example3 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example3.ts) @[code](@/content/guides/columns/column-hiding/angular/example3.html) ::: ::: ::: only-for vue ::: example #example3 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example3.vue) ::: ::: ### Step 3: Set up context menu items To easily hide and unhide columns, add column hiding items to Handsontable's [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md). Enable both the [`ContextMenu`](@/api/contextMenu.md) plugin and the [`HiddenColumns`](@/api/hiddenColumns.md) plugin. Now, the context menu automatically displays additional items for hiding and unhiding columns. ::: only-for javascript ::: example #example4 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example4.js) @[code](@/content/guides/columns/column-hiding/javascript/example4.ts) ::: ::: ::: only-for react ::: example #example4 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example4.jsx) @[code](@/content/guides/columns/column-hiding/react/example4.tsx) ::: ::: ::: only-for angular ::: example #example4 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example4.ts) @[code](@/content/guides/columns/column-hiding/angular/example4.html) ::: ::: ::: only-for vue ::: example #example4 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example4.vue) ::: ::: You can also add the column hiding menu items individually, by adding the [`hidden_columns_show`](@/guides/accessories-and-menus/context-menu/context-menu.md#context-menu-with-specific-options) and [`hidden_columns_hide`](@/guides/accessories-and-menus/context-menu/context-menu.md#context-menu-with-specific-options) strings to the[ `contextMenu`](@/api/contextMenu.md) parameter: ::: only-for javascript ::: example #example5 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example5.js) @[code](@/content/guides/columns/column-hiding/javascript/example5.ts) ::: ::: ::: only-for react ::: example #example5 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example5.jsx) @[code](@/content/guides/columns/column-hiding/react/example5.tsx) ::: ::: ::: only-for angular ::: example #example5 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example5.ts) @[code](@/content/guides/columns/column-hiding/angular/example5.html) ::: ::: ::: only-for vue ::: example #example5 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example5.vue) ::: ::: ### Step 4: Set up copy and paste behavior By default, hidden columns are included in copying and pasting. To exclude hidden columns from copying and pasting, in the [`hiddenColumns`](@/api/hiddenColumns.md) object, set the [`copyPasteEnabled`](@/api/hiddenColumns.md) property to `false`: ::: only-for javascript ::: example #example6 --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/javascript/example6.js) @[code](@/content/guides/columns/column-hiding/javascript/example6.ts) ::: ::: ::: only-for react ::: example #example6 :react --js 1 --ts 2 @[code](@/content/guides/columns/column-hiding/react/example6.jsx) @[code](@/content/guides/columns/column-hiding/react/example6.tsx) ::: ::: ::: only-for angular ::: example #example6 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-hiding/angular/example6.ts) @[code](@/content/guides/columns/column-hiding/angular/example6.html) ::: ::: ::: only-for vue ::: example #example6 :vue3 @[code](@/content/guides/columns/column-hiding/vue/example6.vue) ::: ::: ## Result After completing this guide, you can hide columns from the grid without changing source data. You can configure default hidden columns, UI indicators, context menu items, and copy-paste behavior. ## Column hiding API methods For the most popular column hiding tasks, use the API methods below. ::: only-for react ::: tip To use the Handsontable API, you'll need access to the Handsontable instance. You can do that by utilizing a reference to the `HotTable` component, and reading its `hotInstance` property. For more information, see the [Instance methods](@/guides/getting-started/react-methods/react-methods.md) page. ::: ::: ::: only-for vue ::: tip To use the Handsontable API, you'll need access to the Handsontable instance. You can do that by utilizing a reference to the `HotTable` component, and reading its `hotInstance` property. For more information, see the [Referencing the Handsontable instance](@/guides/getting-started/vue3-hot-reference/vue3-hot-reference.md) page. ::: ::: To see your changes, re-render your Handsontable instance with the [`render()`](@/api/core.md#render) method. ### Access the [`HiddenColumns`](@/api/hiddenColumns.md) plugin instance To access the [`HiddenColumns`](@/api/hiddenColumns.md) plugin instance, use the [`getPlugin()`](@/api/core.md#getplugin) method: ```js const plugin = hot.getPlugin('hiddenColumns'); ``` ### Hide a single column To hide a single column, use the [`hideColumn()`](@/api/hiddenColumns.md#hidecolumn) method: ```js const plugin = hot.getPlugin('hiddenColumns'); plugin.hideColumn(4); // re-render your Handsontable instance hot.render(); ``` ### Hide multiple columns To hide multiple columns: - Either pass column indexes as arguments to the [`hideColumn()`](@/api/hiddenColumns.md#hidecolumn) method - Or pass an array of column indexes to the [`hideColumns()`](@/api/hiddenColumns.md#hidecolumn) method ```js const plugin = hot.getPlugin('hiddenColumns'); plugin.hideColumn(0, 4, 6); // or plugin.hideColumns([0, 4, 6]); // re-render your Handsontable instance hot.render(); ``` ### Unhide a single column To unhide a single column, use the [`showColumn()`](@/api/hiddenColumns.md#showcolumn) method: ```js const plugin = hot.getPlugin('hiddenColumns'); plugin.showColumn(4); // re-render your Handsontable instance hot.render(); ``` ### Unhide multiple columns To unhide multiple columns: - Either pass column indexes as arguments to the [`showColumn()`](@/api/hiddenColumns.md#showcolumn) method - Or pass an array of column indexes to the [`showColumns()`](@/api/hiddenColumns.md#showcolumns) method ```js const plugin = hot.getPlugin('hiddenColumns'); plugin.showColumn(0, 4, 6); // or plugin.showColumns([0, 4, 6]); // re-render your Handsontable instance hot.render(); ``` ## Related API reference **Configuration options**
- [hiddenColumns](@/api/options.md#hiddencolumns)
**Hooks**
- [afterHideColumns](@/api/hooks.md#afterhidecolumns)
- [afterUnhideColumns](@/api/hooks.md#afterunhidecolumns)
- [beforeHideColumns](@/api/hooks.md#beforehidecolumns)
- [beforeUnhideColumns](@/api/hooks.md#beforeunhidecolumns)
**Plugins**
- [HiddenColumns](@/api/hiddenColumns.md)
---
# Adding and removing columns
URL: https://handsontable.com/docs/javascript-data-grid/column-adding/
Insert and remove columns programmatically with the [`alter()`](@/api/core.md#alter) method, through the context menu, or automatically with spare columns.
[[toc]]
## Insert and remove columns with the API
Call the [`alter()`](@/api/core.md#alter) method to change the column structure programmatically. Pass an action name, a column index, and the number of columns to insert or remove:
- `alter('insert_col_start', index, amount)` inserts columns to the left of the given column index.
- `alter('insert_col_end', index, amount)` inserts columns to the right of the given column index.
- `alter('remove_col', index, amount)` removes columns, starting at the given column index.
In the example below, **Insert column** appends a column to the right of the last column, and **Remove last column** removes the last column.
::: only-for javascript
::: example #example1 --html 1 --js 2 --ts 3
@[code](@/content/guides/columns/column-adding/javascript/example1.html)
@[code](@/content/guides/columns/column-adding/javascript/example1.js)
@[code](@/content/guides/columns/column-adding/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-adding/react/example1.jsx)
@[code](@/content/guides/columns/column-adding/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-adding/angular/example1.ts)
@[code](@/content/guides/columns/column-adding/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-adding/vue/example1.vue)
:::
:::
The `index` argument uses visual column indexes. The `amount` argument defaults to `1` when omitted.
## Add and remove columns from the context menu
Enable the [`contextMenu`](@/api/options.md#contextmenu) option to let users insert and remove columns by right-clicking a column. The relevant menu items are `col_left` (**Insert column left**), `col_right` (**Insert column right**), and `remove_col` (**Remove column**).
Setting [`contextMenu`](@/api/options.md#contextmenu) to `true` shows the full default menu. To show only the column actions, pass an array of item keys, as in the example below. Right-click a column header or cell to open the menu.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-adding/javascript/example2.js)
@[code](@/content/guides/columns/column-adding/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-adding/react/example2.jsx)
@[code](@/content/guides/columns/column-adding/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-adding/angular/example2.ts)
@[code](@/content/guides/columns/column-adding/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-adding/vue/example2.vue)
:::
:::
The [`allowInsertColumn`](@/api/options.md#allowinsertcolumn) and [`allowRemoveColumn`](@/api/options.md#allowremovecolumn) options control whether these context menu items are available. Both default to `true`. Set [`allowInsertColumn`](@/api/options.md#allowinsertcolumn) to `false` to hide the insert items, or [`allowRemoveColumn`](@/api/options.md#allowremovecolumn) to `false` to hide the remove item.
## Add spare columns automatically
Set the [`minSpareCols`](@/api/options.md#minsparecols) option to keep a number of empty columns at the end of the grid. When a user enters data in the last empty column, Handsontable adds another empty column, so the grid always has at least the configured number of spare columns.
```js
const configurationOptions = {
// keep at least one empty column at the end of the grid
minSpareCols: 1,
};
```
[`minSpareCols`](@/api/options.md#minsparecols) defaults to `0`.
## Control and react to column changes
Use Handsontable's hooks to validate or respond to column changes:
- [`beforeCreateCol`](@/api/hooks.md#beforecreatecol) runs before columns are inserted. Return `false` to cancel the insertion.
- [`afterCreateCol`](@/api/hooks.md#aftercreatecol) runs after columns are inserted.
- [`beforeRemoveCol`](@/api/hooks.md#beforeremovecol) runs before columns are removed. Return `false` to cancel the removal.
- [`afterRemoveCol`](@/api/hooks.md#afterremovecol) runs after columns are removed.
For example, block removing the last remaining column:
```js
const configurationOptions = {
beforeRemoveCol(index, amount) {
if (this.countCols() - amount < 1) {
// cancel the removal
return false;
}
},
};
```
## Result
After completing this guide, you can insert and remove columns with the [`alter()`](@/api/core.md#alter) method, let users add and remove columns through the context menu, keep spare columns at the end of the grid, and validate or react to column changes with hooks.
## Related API reference
**Configuration options**
- [allowInsertColumn](@/api/options.md#allowinsertcolumn)
- [allowRemoveColumn](@/api/options.md#allowremovecolumn)
- [contextMenu](@/api/options.md#contextmenu)
- [minSpareCols](@/api/options.md#minsparecols)
**Core methods**
- [alter()](@/api/core.md#alter)
- [countCols()](@/api/core.md#countcols)
**Hooks**
- [afterCreateCol](@/api/hooks.md#aftercreatecol)
- [afterRemoveCol](@/api/hooks.md#afterremovecol)
- [beforeCreateCol](@/api/hooks.md#beforecreatecol)
- [beforeRemoveCol](@/api/hooks.md#beforeremovecol)
---
# Column moving
URL: https://handsontable.com/docs/javascript-data-grid/column-moving/
Change the order of columns, either manually (dragging them to another location), or programmatically (using Handsontable's API methods).
[[toc]]
## Enable the plugin
To enable column moving, set the [`manualColumnMove`](@/api/options.md#manualcolumnmove) configuration option to `true`.
A draggable move handle appears above the selected column header. You can click and drag it to any location in the grid.
A column has to be selected before you can drag it. You can start the drag anywhere on the selected column's
header, including on the sorting label when [column sorting](@/guides/rows/rows-sorting/rows-sorting.md) is
enabled. Handsontable tells a click from a drag by whether the pointer moves: press and release without moving
to sort the column, and press and drag to move it.
When column sorting is enabled, only the header label and its sort indicator sort on click. Pressing the header
around them selects the column without sorting it, so you can select a column and drag it in one gesture.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/javascript/example1.js)
@[code](@/content/guides/columns/column-moving/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/react/example1.jsx)
@[code](@/content/guides/columns/column-moving/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-moving/angular/example1.ts)
@[code](@/content/guides/columns/column-moving/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-moving/vue/example1.vue)
:::
:::
#### Move column headers
When you move columns, the default column headers (A, B, C) stay in place.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/javascript/example2.js)
@[code](@/content/guides/columns/column-moving/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/react/example2.jsx)
@[code](@/content/guides/columns/column-moving/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-moving/angular/example2.ts)
@[code](@/content/guides/columns/column-moving/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-moving/vue/example2.vue)
:::
:::
But, if you configure the [`colHeaders`](@/api/options.md#colheaders) option with your own column labels (e.g., One, Two, Three), your headers move along with the columns.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/javascript/example3.js)
@[code](@/content/guides/columns/column-moving/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-moving/react/example3.jsx)
@[code](@/content/guides/columns/column-moving/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-moving/angular/example3.ts)
@[code](@/content/guides/columns/column-moving/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/columns/column-moving/vue/example3.vue)
:::
:::
## Set a pre-defined column order
Instead of setting [`manualColumnMove`](@/api/options.md#manualcolumnmove) to `true`, you can pass an **array of physical column indexes** to define the initial visual order of columns on render.
Each position in the array corresponds to a visual (display) position, and the value at that position is the physical (source data) column index. For example:
```js
manualColumnMove: [1, 0, 2]
```
This renders the columns in the following order:
- Visual position 0 → physical column `1`
- Visual position 1 → physical column `0`
- Visual position 2 → physical column `2`
The array must contain all physical column indexes (its length must equal the total number of columns). After the initial render, users can still drag columns to change the order further.
For more on how physical and visual indexes relate, see [Understanding data and indexes](@/guides/getting-started/understanding-data-and-indexes/understanding-data-and-indexes.md).
## Data model behavior
Moving columns does not reorder your source data. Handsontable stores the new order as index metadata through its [`IndexMapper`](@/api/indexMapper.md), and leaves the original data untouched. This affects how you read and save the data:
- [`getData()`](@/api/core.md#getdata) returns cells in their current visual order, so it reflects any moves. Call it inside the [`afterColumnMove`](@/api/hooks.md#aftercolumnmove) hook to get an order-accurate snapshot to persist.
- [`getSourceData()`](@/api/core.md#getsourcedata) returns cells in their original physical order, ignoring any moves.
### Don't feed the snapshot back into the grid
Sending the reordered snapshot back to the grid as its new data applies the move a second time. [`updateData()`](@/api/core.md#updatedata) keeps the current column order on purpose, so Handsontable re-applies the order map it already holds on top of your already-reordered data. One drag then moves the column twice.
Treat the snapshot as output only. Send it to your backend, and leave the grid's own data alone.
::: only-for react angular vue
The data you bind to [`data`](@/api/options.md#data) does not change when a user moves a column, so you have to decide who owns the order. The two models are the same as for rows, and mixing them causes the same double move -- see [Choose who owns the row order](@/guides/rows/row-moving/row-moving.md#choose-who-owns-the-row-order).
If you let Handsontable own the order, seed the starting order with [`initialState`](@/api/options.md#initialstate) rather than [`manualColumnMove`](@/api/options.md#manualcolumnmove). Handsontable reads [`initialState`](@/api/options.md#initialstate) only when it creates the grid, so a re-render can't apply the order a second time:
```js
initialState: {
manualColumnMove: [1, 0, 2],
},
```
The array both enables column moving and sets the starting order, so don't also pass [`manualColumnMove`](@/api/options.md#manualcolumnmove) at the top level. A regular setting takes precedence over the same key in [`initialState`](@/api/options.md#initialstate), so `manualColumnMove: true` alongside the code above would discard the order.
If you own the order yourself, cancel the move by returning `false` from [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove) and reorder your own data. Two things follow from that.
[`afterColumnMove`](@/api/hooks.md#aftercolumnmove) never fires. The move stops at [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove), before that hook runs, so persist the order from your own update rather than from the snapshot recipe above.
Reordering columns also takes more work than reordering rows. You either reorder each row's cells, or reorder your [`columns`](@/api/options.md#columns) definitions. Reordering the cells is the safer route: passing `columns` through [`updateSettings()`](@/api/core.md#updatesettings) resets the states tied to rows and columns, including the row and column sequence, column widths, row heights, and frozen columns.
:::
## Control column moving
Use the [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove) hook to decide whether each column move is allowed. Returning `false` cancels the move while keeping the [`manualColumnMove`](@/api/options.md#manualcolumnmove) plugin enabled.
Both [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove) and [`afterColumnMove`](@/api/hooks.md#aftercolumnmove) run only when the pointer actually drags a column. A click on a column header does not fire them.
In the following example, select **Allow column moving** before you drag a column to a new position. Clear the checkbox to block column moving again.
:::: only-for javascript
::: example #example4 --html 1 --js 2 --ts 3
@[code](@/content/guides/columns/column-moving/javascript/example4.html)
@[code](@/content/guides/columns/column-moving/javascript/example4.js)
@[code](@/content/guides/columns/column-moving/javascript/example4.ts)
:::
::::
:::: only-for react
::: example #example4 :react --jsx 1 --tsx 2
@[code](@/content/guides/columns/column-moving/react/example4.jsx)
@[code](@/content/guides/columns/column-moving/react/example4.tsx)
:::
::::
:::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-moving/angular/example4.ts)
@[code](@/content/guides/columns/column-moving/angular/example4.html)
:::
::::
:::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/columns/column-moving/vue/example4.vue)
:::
::::
## Result
After completing this guide, you can reorder columns by dragging them with the mouse or by calling `dragColumns()` and `moveColumns()` programmatically. You can also set a pre-defined column order at initialization or use `beforeColumnMove` to block individual moves.
## Drag and move actions of the [`ManualColumnMove`](@/api/manualColumnMove.md) plugin
There are significant differences between the plugin's [`dragColumns`](@/api/manualColumnMove.md#dragcolumns) and [`moveColumns`](@/api/manualColumnMove.md#movecolumns) API functions. Both of them change the order of columns, but they rely on different kinds of indexes. The differences between them are shown in the diagrams below.
Both of these methods trigger the [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove) and [`afterColumnMove`](@/api/hooks.md#aftercolumnmove) hooks, but only [`dragColumns`](@/api/manualColumnMove.md#dragcolumns) passes the [`dropIndex`](@/api/manualColumnMove.md#dragcolumns) argument to them.
The [`dragColumns`](@/api/manualColumnMove.md#dragcolumns) method has a [`dropIndex`](@/api/manualColumnMove.md#dragcolumns) parameter, which points to where the elements are being dropped.
The [`moveColumns`](@/api/manualColumnMove.md#movecolumns) method has a `finalIndex` parameter, which points to where the elements will be placed after the _moving_ action - `finalIndex` being the index of the first moved element.
The [`moveColumns`](@/api/manualColumnMove.md#movecolumns) function cannot perform some actions, e.g., more than one element can't be moved to the last position. In this scenario, the move will be cancelled. The Plugin's [`isMovePossible`](@/api/manualColumnMove.md#ismovepossible) API method and the `movePossible` parameters [`beforeColumnMove`](@/api/hooks.md#beforecolumnmove) and [`afterColumnMove`](@/api/hooks.md#aftercolumnmove) hooks help in determine such situations.
## Related API reference
**Configuration options**
- [manualColumnMove](@/api/options.md#manualcolumnmove)
**Core methods**
- [colToProp()](@/api/core.md#coltoprop)
- [isColumnModificationAllowed()](@/api/core.md#iscolumnmodificationallowed)
- [propToCol()](@/api/core.md#proptocol)
- [toPhysicalColumn()](@/api/core.md#tophysicalcolumn)
- [toVisualColumn()](@/api/core.md#tovisualcolumn)
**Hooks**
- [afterColumnMove](@/api/hooks.md#aftercolumnmove)
- [beforeColumnMove](@/api/hooks.md#beforecolumnmove)
**Plugins**
- [ManualColumnMove](@/api/manualColumnMove.md)
---
# Column freezing
URL: https://handsontable.com/docs/javascript-data-grid/column-freezing/
Lock the position of specified columns, keeping them visible when scrolling.
[[toc]]
## Overview
Column freezing locks specific columns of a grid in place, keeping them visible while scrolling to
another area of the grid. We refer to frozen columns as _fixed_.
You can freeze columns during initialization and by the user.
## Freeze columns at initialization
To freeze columns at initialization, use the [`fixedColumnsStart`](@/api/options.md#fixedcolumnsstart) option. Then, configure the container of your grid with the following CSS attributes: `width` and
`overflow: hidden`.
If your [layout direction](@/guides/internationalization/layout-direction/layout-direction.md) is `ltr`, columns get frozen from the left side of the table. If your layout direction is `rtl`, columns get frozen from the right side of the table.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-freezing/javascript/example1.js)
@[code](@/content/guides/columns/column-freezing/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-freezing/react/example1.jsx)
@[code](@/content/guides/columns/column-freezing/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-freezing/angular/example1.ts)
@[code](@/content/guides/columns/column-freezing/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-freezing/vue/example1.vue)
:::
:::
## User-triggered freeze
To enable manual column freezing, set [`manualColumnFreeze`](@/api/options.md#manualcolumnfreeze) to `true`. This lets you freeze and unfreeze columns by using the grid's [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md).
Mind that when you unfreeze a frozen column, it doesn't go back to the original position.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-freezing/javascript/example2.js)
@[code](@/content/guides/columns/column-freezing/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-freezing/react/example2.jsx)
@[code](@/content/guides/columns/column-freezing/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-freezing/angular/example2.ts)
@[code](@/content/guides/columns/column-freezing/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-freezing/vue/example2.vue)
:::
:::
## Related API reference
**Configuration options**
- [fixedColumnsStart](@/api/options.md#fixedcolumnsstart)
- [manualColumnFreeze](@/api/options.md#manualcolumnfreeze)
**Plugins**
- [ManualColumnFreeze](@/api/manualColumnFreeze.md)
---
# Column widths
URL: https://handsontable.com/docs/javascript-data-grid/column-width/
Configure column widths, using an array or a function. Let your users manually change column widths using Handsontable's interface.
[[toc]]
## Overview
By default, the column width adjusts to the width of the content. However, if the width of the content is less than `50px`, including `1px` for borders on the sides, the column width remains constant at `50px`. You can pass the column size as a constant, an array, or a function.
The content inside a cell will be wrapped if it doesn't fit the cell's width.
## Set the column width as a constant
In this example we set the same width of `100px` for all columns across the entire grid.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example1.js)
@[code](@/content/guides/columns/column-width/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example1.jsx)
@[code](@/content/guides/columns/column-width/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example1.ts)
@[code](@/content/guides/columns/column-width/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-width/vue/example1.vue)
:::
:::
## Set the column width in an array
In this example, the width is only set for the first four columns. Each additional column would automatically adjust to the content.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example2.js)
@[code](@/content/guides/columns/column-width/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example2.jsx)
@[code](@/content/guides/columns/column-width/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example2.ts)
@[code](@/content/guides/columns/column-width/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/columns/column-width/vue/example2.vue)
:::
:::
## Set the column width using a function
In this example, the size of all columns is set using a function by taking a column `index` (1, 2 ...) and multiplying it by `40px` for each consecutive column.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example3.js)
@[code](@/content/guides/columns/column-width/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example3.jsx)
@[code](@/content/guides/columns/column-width/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example3.ts)
@[code](@/content/guides/columns/column-width/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/columns/column-width/vue/example3.vue)
:::
:::
## Set a dynamic maximum column width
Use the [`modifyColWidth`](@/api/hooks.md#modifycolwidth) hook to cap how wide a column can grow based on its content. The hook receives the width that Handsontable already calculated for the column. Return a smaller number to limit it. This pattern is [middleware](@/guides/getting-started/events-and-hooks/events-and-hooks.md#middleware): you modify a value on its way through the width pipeline instead of setting a fixed size up front.
Unlike [`colWidths`](@/api/options.md#colwidths), a cap in `modifyColWidth` does not force every cell onto one width. Short values keep a narrow column on a single line. When content would exceed your threshold, the column shrinks to your cap and the text wraps.
Leave `colWidths` unset for columns you want to auto-size (or set the entry to `undefined` in an array). The [`AutoColumnSize`](@/api/autoColumnSize.md) plugin must stay enabled so Handsontable can measure content first. Setting `colWidths` as a single number disables auto-sizing for all columns.
You can also enforce a minimum width by returning `Math.max(width, minWidth)` from the same hook.
::: tip
- Auto-sized columns never go below 50px.
- [`stretchH`](@/api/options.md#stretchh) runs after your hook and can widen columns beyond your cap.
- When [`manualColumnResize`](@/api/options.md#manualcolumnresize) is enabled, a width the user set by dragging overrides the hook for that column.
:::
::: only-for javascript
::: example #example7 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example7.js)
@[code](@/content/guides/columns/column-width/javascript/example7.ts)
:::
:::
::: only-for react
::: example #example7 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example7.jsx)
@[code](@/content/guides/columns/column-width/react/example7.tsx)
:::
:::
::: only-for angular
::: example #example7 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example7.ts)
@[code](@/content/guides/columns/column-width/angular/example7.html)
:::
:::
::: only-for vue
::: example #example7 :vue3
@[code](@/content/guides/columns/column-width/vue/example7.vue)
:::
:::
## Adjust the column width manually
Set the option [`manualColumnResize`](@/api/options.md#manualcolumnresize) to `true` to allow users to manually resize the column width by dragging the handle between the adjacent column headers. If you double-click on that handle, the width will be instantly adjusted to the size of the longest value in the column. Don't forget to enable column headers by setting [`colHeaders`](@/api/options.md#colheaders) to `true`.
You can adjust the size of one or multiple columns simultaneously, even if the selected columns are not placed next to each other.
::: tip
When you set a column width programmatically with [`ManualColumnResize#setManualSize()`](@/api/manualColumnResize.md#setmanualsize), call `hot.render()` after the method call to repaint the grid. Values below `20px` are stored as `20px`.
:::
::: only-for javascript
::: example #example4 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example4.js)
@[code](@/content/guides/columns/column-width/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example4.jsx)
@[code](@/content/guides/columns/column-width/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example4.ts)
@[code](@/content/guides/columns/column-width/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/columns/column-width/vue/example4.vue)
:::
:::
## Column stretching
You can adjust the width of the columns to make them fit the table's width automatically. The width of a particular column will be calculated based on the size and number of other columns in the grid. This option only makes sense when you have at least one column in your data set and fewer columns than needed to enable the horizontal scrollbar.
::: tip
Use the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md) to insert or remove columns. This will help you understand how the grid reacts to changes.
:::
### Fit all columns equally
This example fits all columns to the container's width equally by setting the option [`stretchH: 'all'`](@/api/options.md#stretchh).
::: only-for javascript
::: example #example5 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example5.js)
@[code](@/content/guides/columns/column-width/javascript/example5.ts)
:::
:::
::: only-for react
::: example #example5 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example5.jsx)
@[code](@/content/guides/columns/column-width/react/example5.tsx)
:::
:::
::: only-for angular
::: example #example5 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example5.ts)
@[code](@/content/guides/columns/column-width/angular/example5.html)
:::
:::
::: only-for vue
::: example #example5 :vue3
@[code](@/content/guides/columns/column-width/vue/example5.vue)
:::
:::
### Stretch only the last column
In this example, the first three columns are set to be 80px wide, and the last column automatically fills the remaining space. This is achieved by setting the option [`stretchH: 'last'`](@/api/options.md#stretchh).
::: only-for javascript
::: example #example6 --js 1 --ts 2
@[code](@/content/guides/columns/column-width/javascript/example6.js)
@[code](@/content/guides/columns/column-width/javascript/example6.ts)
:::
:::
::: only-for react
::: example #example6 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-width/react/example6.jsx)
@[code](@/content/guides/columns/column-width/react/example6.tsx)
:::
:::
::: only-for angular
::: example #example6 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-width/angular/example6.ts)
@[code](@/content/guides/columns/column-width/angular/example6.html)
:::
:::
::: only-for vue
::: example #example6 :vue3
@[code](@/content/guides/columns/column-width/vue/example6.vue)
:::
:::
### Column stretching and manual resizing
Column stretching interacts with [`manualColumnResize`](@/api/options.md#manualcolumnresize) in two ways:
- When `stretchH` is `'all'` or `'last'` together with `manualColumnResize: true`, you can still drag to resize a column. Stretching then recalculates, and the other columns adjust so the grid keeps filling the container. If your manual widths add up to more than the container width, stretching stops and the columns keep the sizes you set.
- When you pass `manualColumnResize` an array of pre-defined widths (for example, `manualColumnResize: [80, 100, 120]`), the columns with explicit widths are excluded from stretching. Only the remaining columns are stretched to fill the container.
## A note about the performance
As mentioned above, the default width of the column is based on the widest value in any cell within the column. You may be wondering how it's possible for data sets containing hundreds of thousands of records.
This feature is made possible thanks to the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin, which is enabled by default. Internally it divides the data set into smaller sets and renders only some of them to measure their size. The size is then applied to the entire column based on the width of the widest found value.
To increase the performance, you can turn off this feature by defining the fixed size for the specified column or all columns.
::: tip
If you call [`scrollViewportTo()`](@/api/core.md#scrollviewportto) and your columns have non-standard widths (for example, set by a custom renderer or CSS), make sure `AutoColumnSize` is enabled. Without it, the method may scroll to an incorrect position.
:::
## Size of the container
Setting the dimensions of the container that holds Handsontable is described in detail on the [Grid size](@/guides/getting-started/grid-size/grid-size.md) page.
## Related API reference
**Configuration options**
- [autoColumnSize](@/api/options.md#autocolumnsize)
- [colWidths](@/api/options.md#colwidths)
- [manualColumnResize](@/api/options.md#manualcolumnresize)
- [stretchH](@/api/options.md#stretchh)
**Core methods**
- [getColWidth()](@/api/core.md#getcolwidth)
- [scrollViewportTo()](@/api/core.md#scrollviewportto)
**Hooks**
- [afterColumnResize](@/api/hooks.md#aftercolumnresize)
- [beforeColumnResize](@/api/hooks.md#beforecolumnresize)
- [beforeStretchingColumnWidth](@/api/hooks.md#beforestretchingcolumnwidth)
- [modifyAutoColumnSizeSeed](@/api/hooks.md#modifyautocolumnsizeseed)
- [modifyColWidth](@/api/hooks.md#modifycolwidth)
**Plugins**
- [AutoColumnSize](@/api/autoColumnSize.md)
- [ManualColumnResize](@/api/manualColumnResize.md)
---
# Column summary
URL: https://handsontable.com/docs/javascript-data-grid/column-summary/
Calculate sum, min, max, count, average or custom aggregates of individual columns' data, using Handsontable's aggregate functions.
[[toc]]
## Overview
The [`ColumnSummary`](@/api/columnSummary.md) plugin lets you quickly calculate and display a column summary.
Handsontable's aggregates are column-based: `ColumnSummary` summarizes a range of rows within a column. There is no separate row summary (`rowSummary`) feature. To show a per-row total across columns, compute it in your data source or a [custom renderer](@/guides/cell-functions/cell-renderer/cell-renderer.md).
To customize your column summaries, you can:
- Decide how a summary is calculated:
- Either select one of the [built-in summary functions](#built-in-summary-functions)
- Or implement a [custom summary function](#implement-a-custom-summary-function)
- [Select columns and ranges of rows](#step-2-select-cells-that-you-want-to-summarize) that you want to summarize
- [Display your summary result](#step-4-provide-the-destination-cell-s-coordinates) in a specific cell
### Column summary example
This example calculates and displays five different column summaries:
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-summary/javascript/example1.js)
@[code](@/content/guides/columns/column-summary/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-summary/react/example1.jsx)
@[code](@/content/guides/columns/column-summary/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-summary/angular/example1.ts)
@[code](@/content/guides/columns/column-summary/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-summary/vue/example1.vue)
:::
:::
### Built-in summary functions
To decide how a column summary is calculated, you can use one of the following summary functions:
| Function | Description |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `sum` | Returns the sum of all values in a column. |
| `min` | Returns the lowest value in a column. |
| `max` | Returns the highest value in a column. |
| `count` | Returns the number of all non-empty cells in a column. |
| `average` | Returns the sum of all values in a column,divided by the number of non-empty cells in that column. | | `custom` | Lets you implement a [custom summary function](#implement-a-custom-summary-function). | ### Column summary options You can customize each of your column summaries with configuration options. For the full list of available options, see the [API reference](@/api/columnSummary.md#options). ## Set up a column summary To set up a column summary, follow the steps below. ### Step 1: Enable the [`ColumnSummary`](@/api/columnSummary.md) plugin To enable the [`ColumnSummary`](@/api/columnSummary.md) plugin, set the [`columnSummary`](@/api/options.md#columnsummary) configuration option to an array of objects. Each object represents a single column summary. ::: only-for javascript ```js import Handsontable from 'handsontable/base'; import { registerAllModules } from 'handsontable/registry'; // Register all Handsontable's modules. registerAllModules(); const hot = new Handsontable(document.querySelector('#example'), { licenseKey: 'non-commercial-and-evaluation', data: [ [1, 2, 3, 4, 5], [6, 7, 8, 9, 10], [11, 12, 13, 14, 15] ], colHeaders: true, rowHeaders: true, // set the `columnSummary` configuration option to an array of // objects columnSummary: [ {}, {} ], }); ``` ::: ::: only-for react ```jsx import { HotTable } from '@handsontable/react-wrapper'; import { registerAllModules } from 'handsontable/registry'; // register Handsontable's modules registerAllModules(); const ExampleComponent = () => { return (
- [columnSummary](@/api/options.md#columnsummary)
**Plugins**
- [ColumnSummary](@/api/columnSummary.md)
---
# Column virtualization
URL: https://handsontable.com/docs/javascript-data-grid/column-virtualization/
Render hundreds of columns without freezing the browser, using column virtualization.
[[toc]]
## Overview
To process a large number of columns in a browser Handsontable utilizes the virtualization process to display only the visible part of the grid with a small
offset for a better scrolling experience.
This feature is enabled by default and can be turned off by setting the [`renderAllColumns`](@/api/options.md#renderallcolumns) option to `true`.
## Configure the column virtualization
You can experiment with the [`viewportColumnRenderingOffset`](@/api/options.md#viewportcolumnrenderingoffset) config option, which determines the number of
columns being displayed outside the visible viewport. If the number passed to that option is greater than the total columns in your data set, the virtualization
will be practically turned off.
To make the grid scrollable, set the constant width and height to same as the container holding Handsontable and height and set the `overflow` property to
`hidden` in the container's stylesheet. If the table contains enough rows or columns, it will be scrollable.
The scrolling performance depends mainly on four factors:
- Number of cells - number of rows multiplied by the number of columns
- Amount and complexity of custom renderers in cells
- Number of options enabled in the configuration
- Performance of your setup - physical machine and browser
The demo below presents a data grid displaying one million cells (1000 rows x 1000 columns).
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/columns/column-virtualization/javascript/example1.js)
@[code](@/content/guides/columns/column-virtualization/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/column-virtualization/react/example1.jsx)
@[code](@/content/guides/columns/column-virtualization/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-virtualization/angular/example1.ts)
@[code](@/content/guides/columns/column-virtualization/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/columns/column-virtualization/vue/example1.vue)
:::
:::
## Horizontal scrolling
Hold Shift and scroll the mouse wheel to scroll the grid horizontally. No configuration is required.
## Known limitations
Using column virtualization has the following side effects:
- The browser's native search will work only for the visible part of the grid.
- Screen readers may announce the wrong total number of columns. Read more in the
[Accessibility](@/guides/accessibility/accessibility/accessibility.md#disabling-dom-virtualization-for-improved-accessibility) guide.
## Related articles
**Related guides**
- [Row virtualization](@/guides/rows/row-virtualization/row-virtualization.md)
- [Performance](@/guides/optimization/performance/performance.md)
**Configuration options**
- [viewportColumnRenderingOffset](@/api/options.md#viewportcolumnrenderingoffset)
- [renderAllColumns](@/api/options.md#renderallcolumns)
---
# Column filter
URL: https://handsontable.com/docs/javascript-data-grid/column-filter/
Filter data by values or by a set of conditions, using Handsontable's intuitive user interface or
flexible API.
[[toc]]
## Overview
Filtering lets you quickly find the information that you're looking for, based on specific criteria.
This makes data analysis easier and faster, especially with large data sets.
Handsontable's built-in filtering interface resembles Excel's, so it's intuitive even to
non-technical users. And if you want to implement your own interface, you can easily filter data
programmatically, using Handsontable's API.
You can filter data by value, or use the built-in conditions, which are different for each of the
available column types.
## Filtering demo
Click on one of the column menu buttons (▼) and play around with filtering by selecting values or
conditions-based criteria.
After filtering, the column readjusts its width to the longest value displayed on screen. To disable
this behavior, set
[fixed column widths](@/guides/columns/column-width/column-width.md#set-the-column-width-as-a-constant).
::: only-for javascript
::: example #exampleFilterBasicDemo --html 1 --js 2 --ts 3
@[code](@/content/guides/columns/column-filter/javascript/exampleFilterBasicDemo.html)
@[code](@/content/guides/columns/column-filter/javascript/exampleFilterBasicDemo.js)
@[code](@/content/guides/columns/column-filter/javascript/exampleFilterBasicDemo.ts)
:::
:::
::: only-for react
::: example #exampleFilterBasicDemo :react --js 1 --ts 2
@[code](@/content/guides/columns/column-filter/react/exampleFilterBasicDemo.jsx)
@[code](@/content/guides/columns/column-filter/react/exampleFilterBasicDemo.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/columns/column-filter/angular/example1.ts)
@[code](@/content/guides/columns/column-filter/angular/example1.html)
:::
:::
::: only-for vue
::: example #exampleFilterBasicDemo :vue3
@[code](@/content/guides/columns/column-filter/vue/exampleFilterBasicDemo.vue)
:::
:::
## Enable filtering
To enable the filtering interface for all columns, you need to do two things:
1. Set the `filters` option to `true`.
2. Enable the interface by setting the `dropdownMenu` option to `true`.
Enabling the `filters` option without the interface can be useful if you plan to create your own
custom interface for filtering by using the API.
::: only-for javascript
```js
const configurationOptions = {
// enable filtering
filters: true,
// enable the column menu
dropdownMenu: true,
};
```
:::
::: only-for react
```jsx
None
Is empty
Is not empty
Is equal to
Is not equal to | | text
time
checkbox
dropdown
autocomplete
password | Default operators plus:
Begins with
Ends with
Contains
Does not contain | | numeric | Default operators plus:
Greater than
Greater than or equal to
Less than
Less than or equal to
Is between
Is not between | | date | Default operators plus:
Before (exclusive -- boundary date excluded)
Before or equal to (boundary date included)
After (exclusive -- boundary date excluded)
After or equal to (boundary date included)
Is between
Tomorrow
Today
Yesterday | | intl-date | Default operators plus:
Before (exclusive -- boundary date excluded)
Before or equal to (boundary date included)
After (exclusive -- boundary date excluded)
After or equal to (boundary date included)
Is between
Tomorrow
Today
Yesterday | | intl-time | Default operators plus:
Begins with
Ends with
Contains
Does not contain
Before (exclusive -- boundary time excluded)
Before or equal to (boundary time included)
After (exclusive -- boundary time excluded)
After or equal to (boundary time included)
Is between | The **None** operator clears the column's filter. Its programmatic equivalent is [`filters.removeConditions(column)`](@/api/filters.md#removeconditions). For more on clearing filters with the API, see [Clear a column filter](#clear-a-column-filter). For the **Before**, **After**, **Before or equal to**, **After or equal to**, and **Is between** operators on `date`, `intl-date`, and `intl-time` columns, the filter menu shows a native date or time input. Pick the value from the browser's picker or type it in your locale's format. When you set the condition through the API instead, pass the value as an ISO 8601 string (`YYYY-MM-DD` for dates, `HH:mm` for times). ## Filter data on initialization You can filter data on Handsontable's initialization. This lets you apply pre-defined filters every time you launch your grid. ::: only-for javascript To do this, you can use Handsontable's [`afterInit()`](@/api/hooks.md#afterinit) hook, along with the API provided by the Filters plugin. For instance, the demo below demonstrates how you can start with a pre-applied filter to display only items priced less than $200. ::: example #exampleFilterOnInitialization --html 1 --js 2 --ts 3 @[code](@/content/guides/columns/column-filter/javascript/exampleFilterOnInitialization.html) @[code](@/content/guides/columns/column-filter/javascript/exampleFilterOnInitialization.js) @[code](@/content/guides/columns/column-filter/javascript/exampleFilterOnInitialization.ts) ::: ::: ::: only-for react To do this, use the API provided by the [`Filters`](@/api/filters.md) plugin. For instance, the demo below demonstrates how you can start with a pre-applied filter to display only items priced less than $200. ::: example #exampleFilterOnInitialization :react --js 1 --ts 2 @[code](@/content/guides/columns/column-filter/react/exampleFilterOnInitialization.jsx) @[code](@/content/guides/columns/column-filter/react/exampleFilterOnInitialization.tsx) ::: ::: ::: only-for angular To do this, you can use Handsontable's [`afterInit()`](@/api/hooks.md#afterinit) hook, along with the API provided by the Filters plugin. For instance, the demo below demonstrates how you can start with a pre-applied filter to display only items priced less than $200. ::: example #example5 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example5.ts) @[code](@/content/guides/columns/column-filter/angular/example5.html) ::: ::: ::: only-for vue To do this, use the API provided by the [`Filters`](@/api/filters.md) plugin. For instance, the demo below demonstrates how you can start with a pre-applied filter to display only items priced less than $200. ::: example #exampleFilterOnInitialization :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleFilterOnInitialization.vue) ::: ::: ## External quick filter Handsontable's quick filter feature lets you search for a particular phrase in a specific column. To accomplish this, use methods [`filters.addCondition()`](@/api/filters.md#addcondition) and [`filters.filter()`](@/api/filters.md#filter). ::: only-for javascript ::: example #exampleQuickFilter --html 1 --js 2 --ts 3 --css 4 @[code](@/content/guides/columns/column-filter/javascript/exampleQuickFilter.html) @[code](@/content/guides/columns/column-filter/javascript/exampleQuickFilter.js) @[code](@/content/guides/columns/column-filter/javascript/exampleQuickFilter.ts) @[code](@/content/guides/columns/column-filter/javascript/exampleQuickFilter.css) ::: ::: ::: only-for react ::: example #exampleQuickFilter :react --js 1 --css 2 --ts 3 @[code](@/content/guides/columns/column-filter/react/exampleQuickFilter.jsx) @[code](@/content/guides/columns/column-filter/react/exampleQuickFilter.css) @[code](@/content/guides/columns/column-filter/react/exampleQuickFilter.tsx) ::: ::: ::: only-for angular ::: example #example6 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example6.ts) @[code](@/content/guides/columns/column-filter/angular/example6.html) ::: ::: ::: only-for vue ::: example #exampleQuickFilter :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleQuickFilter.vue) ::: ::: ## Customize the filter button The default button that opens the column menu can be styled with CSS by modifying `button.changeType` variables and its `::before` pseudoclass that contains svg mask-image displaying an arrow down icon. ::: only-for javascript ::: example #exampleCustomFilterButton --html 1 --js 2 --ts 3 --css 4 @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton.html) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton.js) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton.ts) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton.css) ::: ::: ::: only-for react ::: example #exampleCustomFilterButton :react --js 1 --css 2 --ts 3 @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton.jsx) @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton.css) @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton.tsx) ::: ::: ::: only-for angular ::: example #example7 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example7.ts) @[code](@/content/guides/columns/column-filter/angular/example7.html) ::: ::: ::: only-for vue ::: example #exampleCustomFilterButton :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleCustomFilterButton.vue) ::: ::: The column menu button is always visible, but if you want it to appear only when the mouse cursor is over the header, apply additional styling to `th .relative:hover .changeType`. ::: only-for javascript ::: example #exampleCustomFilterButton2 --html 1 --js 2 --ts 3 --css 4 @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton2.html) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton2.js) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton2.ts) @[code](@/content/guides/columns/column-filter/javascript/exampleCustomFilterButton2.css) ::: ::: ::: only-for react ::: example #exampleCustomFilterButton2 :react --js 1 --css 2 --ts 3 @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton2.jsx) @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton2.css) @[code](@/content/guides/columns/column-filter/react/exampleCustomFilterButton2.tsx) ::: ::: ::: only-for angular ::: example #example8 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example8.ts) @[code](@/content/guides/columns/column-filter/angular/example8.html) ::: ::: ::: only-for vue ::: example #exampleCustomFilterButton2 :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleCustomFilterButton2.vue) ::: ::: ## Change the width of the filter menu If the text data in your columns is too long to fit in the filters container, you can adjust the column menu's width for better user experience. You can achieve this with by styling `.htDropdownMenu table.htCore`. ```css .handsontable .htDropdownMenu table.htCore { width: 300px !important; } ``` ## Exclude rows from filtering You can exclude any number of top or bottom rows from filtering. In the following demo, the first and the last row are [frozen](@/guides/rows/row-freezing/row-freezing.md), and filtering doesn't affect them. ::: only-for javascript ::: example #exampleExcludeRowsFromFiltering --html 1 --js 2 --ts 3 @[code](@/content/guides/columns/column-filter/javascript/exampleExcludeRowsFromFiltering.html) @[code](@/content/guides/columns/column-filter/javascript/exampleExcludeRowsFromFiltering.js) @[code](@/content/guides/columns/column-filter/javascript/exampleExcludeRowsFromFiltering.ts) ::: ::: ::: only-for react ::: example #exampleExcludeRowsFromFiltering :react --js 1 --ts 2 @[code](@/content/guides/columns/column-filter/react/exampleExcludeRowsFromFiltering.jsx) @[code](@/content/guides/columns/column-filter/react/exampleExcludeRowsFromFiltering.tsx) ::: ::: ::: only-for angular ::: example #example9 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example9.ts) @[code](@/content/guides/columns/column-filter/angular/example9.html) ::: ::: ::: only-for vue ::: example #exampleExcludeRowsFromFiltering :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleExcludeRowsFromFiltering.vue) ::: ::: If you use [`bindRowsWithHeaders`](@/guides/rows/row-header/row-header.md#bind-rows-with-headers) to keep row headers tied to a row's position in the source data, filtering doesn't affect that binding. Filtering removes non-matching rows from view instead of renumbering the rows that remain, so bound row headers keep pointing to the same row after you filter or clear a filter. ## Server-side filtering You can decide to use Handsontable as an intuitive filtering interface, but perform the actual filtering on the server. To help you with that, Handsontable's [`beforeFilter()`](@/api/hooks.md#beforefilter) hook allows you to: - Gather information about the filters that the user wants to apply, to send it to the server. - Disable filtering on the front end, so it doesn't interfere with filtering on the server. In the following demo, click on one of the column menu buttons (▼) and play around with filtering by selecting values or conditions-based criteria. After you click **OK**, the ▼ button turns green to indicate filtering, but the data is not filtered. Instead, the information about the specified filters is logged to the console. ::: only-for javascript ::: example #exampleServerSideFilter --html 1 --js 2 --ts 3 @[code](@/content/guides/columns/column-filter/javascript/exampleServerSideFilter.html) @[code](@/content/guides/columns/column-filter/javascript/exampleServerSideFilter.js) @[code](@/content/guides/columns/column-filter/javascript/exampleServerSideFilter.ts) ::: ::: ::: only-for react ::: example #exampleServerSideFilter :react --js 1 --ts 2 @[code](@/content/guides/columns/column-filter/react/exampleServerSideFilter.jsx) @[code](@/content/guides/columns/column-filter/react/exampleServerSideFilter.tsx) ::: ::: ::: only-for angular ::: example #example10 :angular --ts 1 --html 2 @[code](@/content/guides/columns/column-filter/angular/example10.ts) @[code](@/content/guides/columns/column-filter/angular/example10.html) ::: ::: ::: only-for vue ::: example #exampleServerSideFilter :vue3 @[code](@/content/guides/columns/column-filter/vue/exampleServerSideFilter.vue) ::: ::: ## Control filtering programmatically You can control filtering at the grid's runtime by using Handsontable's [hooks](@/guides/getting-started/events-and-hooks/events-and-hooks.md) and [API methods](@/api/filters.md#methods). This allows you to enable or disable filtering based on specific conditions. For example, you may create a user interface outside of the grid to manage Handsontable's filtering behavior. ### Enable or disable filtering programmatically To enable or disable filtering programmatically, use the [`updateSettings()`](@/api/core.md#updatesettings) method. ::: only-for javascript ```js handsontableInstance.updateSettings({ // enable filtering filters: true, // enable the column menu dropdownMenu: true, }); handsontableInstance.updateSettings({ // disable filtering filters: false, }); ``` ::: ::: only-for react ```jsx const hotTableComponentRef = useRef(null); hotTableComponentRef.current.hotInstance.updateSettings({ // enable filtering filters: true, // enable the column menu dropdownMenu: true, }); hotTableComponentRef.current.hotInstance.updateSettings({ // disable filtering filters: false, }); ``` ::: ::: only-for angular ```ts @ViewChild(HotTableComponent, {static: false}) hotTable!: HotTableComponent; this.hotTable.hotInstance!.updateSettings({ // enable filtering filters: true, // enable the column menu dropdownMenu: true, }); this.hotTable.hotInstance!.updateSettings({ // disable filtering filters: false, }); ``` ::: ::: only-for vue ```js const hotTableRef = useTemplateRef
- [Filters](@/api/filters.md)
- [DropdownMenu](@/api/dropdownMenu.md)
## Troubleshooting
Didn't find what you need? Try this:
- [View related topics](https://github.com/handsontable/handsontable/labels/Filtering) on GitHub
- [Report an issue](https://github.com/handsontable/handsontable/issues/new/choose) on GitHub
- [Start a discussion](https://forum.handsontable.com/c/getting-help/questions) on Handsontable's forum
- [Contact our technical support](https://handsontable.com/contact?category=technical_support) to get help
---
# Column component
URL: https://handsontable.com/docs/react-data-grid/hot-column/
Configure your grid's columns, using the props of the `HotColumn` component. Pass your component as a custom cell editor or a custom cell renderer.
[[toc]]
## Declare column settings
To declare column-specific settings, pass the settings as `HotColumn` props, exactly as you would with `HotTable`.
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/columns/react-hot-column/react/example1.jsx)
@[code](@/content/guides/columns/react-hot-column/react/example1.tsx)
:::
## Object data source
When you use object data binding for `
- [Row parent-child](@/guides/rows/row-parent-child/row-parent-child.md)
**Configuration options**
- [activeHeaderClassName](@/api/options.md#activeheaderclassname)
- [currentHeaderClassName](@/api/options.md#currentheaderclassname)
- [bindRowsWithHeaders](@/api/options.md#bindrowswithheaders)
- [rowHeaders](@/api/options.md#rowheaders)
- [rowHeaderWidth](@/api/options.md#rowheaderwidth)
**Core methods**
- [getRowHeader()](@/api/core.md#getrowheader)
- [hasRowHeaders()](@/api/core.md#hasrowheaders)
**Hooks**
- [afterGetRowHeader](@/api/hooks.md#aftergetrowheader)
- [afterGetRowHeaderRenderers](@/api/hooks.md#aftergetrowheaderrenderers)
- [beforeHighlightingRowHeader](@/api/hooks.md#beforehighlightingrowheader)
- [modifyRowHeader](@/api/hooks.md#modifyrowheader)
- [modifyRowHeaderWidth](@/api/hooks.md#modifyrowheaderwidth)
**Plugins**
- [BindRowsWithHeaders](@/api/bindRowsWithHeaders.md)
---
# Row parent-child
URL: https://handsontable.com/docs/javascript-data-grid/row-parent-child/
Reflect the parent-child relationship of your data, using the [`NestedRows`](@/api/nestedRows.md) plugin's interactive UI elements such as expand and collapse
buttons or an extended context menu.
Handsontable renders this structure as a tree grid. The same pattern is also called a master-detail view or grouping rows.
[[toc]]
## Quick setup
To enable the [`NestedRows`](@/api/nestedRows.md) plugin, set the [`nestedRows`](@/api/options.md#nestedrows) option to `true`.
::: only-for javascript
```js
const hot = new Handsontable(container, {
nestedRows: true,
});
```
:::
::: only-for react
```jsx
- [Row header](@/guides/rows/row-header/row-header.md)
**Configuration options**
- [bindRowsWithHeaders](@/api/options.md#bindrowswithheaders)
- [contextMenu](@/api/options.md#contextmenu)
- [nestedRows](@/api/options.md#nestedrows)
- [rowHeaders](@/api/options.md#rowheaders)
**Core methods**
- [getRowHeader()](@/api/core.md#getrowheader)
- [toPhysicalRow()](@/api/core.md#tophysicalrow)
- [toVisualRow()](@/api/core.md#tovisualrow)
**Plugin methods**
- [collapseAll()](@/api/nestedRows.md#collapseall)
- [collapseParent()](@/api/nestedRows.md#collapseparent)
- [countChildren()](@/api/nestedRows.md#countchildren)
- [expandAll()](@/api/nestedRows.md#expandall)
- [expandParent()](@/api/nestedRows.md#expandparent)
- [expandToLevel()](@/api/nestedRows.md#expandtolevel)
- [expandToRow()](@/api/nestedRows.md#expandtorow)
- [getCollapsedParents()](@/api/nestedRows.md#getcollapsedparents)
- [getRowLevel()](@/api/nestedRows.md#getrowlevel)
- [getRowParent()](@/api/nestedRows.md#getrowparent)
- [isParent()](@/api/nestedRows.md#isparent)
- [isParentCollapsed()](@/api/nestedRows.md#isparentcollapsed)
- [toggleParent()](@/api/nestedRows.md#toggleparent)
**Hooks**
- [afterAddChild](@/api/hooks.md#afteraddchild)
- [afterDetachChild](@/api/hooks.md#afterdetachchild)
- [afterRowCollapse](@/api/hooks.md#afterrowcollapse)
- [afterRowExpand](@/api/hooks.md#afterrowexpand)
- [beforeAddChild](@/api/hooks.md#beforeaddchild)
- [beforeDetachChild](@/api/hooks.md#beforedetachchild)
- [beforeRowCollapse](@/api/hooks.md#beforerowcollapse)
- [beforeRowExpand](@/api/hooks.md#beforerowexpand)
**Plugins**
- [BindRowsWithHeaders](@/api/bindRowsWithHeaders.md)
- [ContextMenu](@/api/contextMenu.md)
- [NestedRows](@/api/nestedRows.md)
---
# Row hiding
URL: https://handsontable.com/docs/javascript-data-grid/row-hiding/
Hide individual rows to avoid rendering them as DOM elements. It helps you reduce screen clutter and improve the grid's performance.
[[toc]]
## Overview
"Hiding a row" means that the hidden row doesn't get rendered as a DOM element.
When you're hiding a row:
- The source data doesn't get modified.
- The [`HiddenRows`](@/api/hiddenRows.md) plugin doesn't participate in data transformation(the shape of the data returned by the [`getData*()` methods](@/api/core.md#getdata) stays intact). Hidden rows stay in [`getData()`](@/api/core.md#getdata) and keep their visual index -- unlike [row trimming](@/guides/rows/row-trimming/row-trimming.md), which removes rows from the visual dataset entirely. For a full comparison, see [Understanding data and indexes](@/guides/getting-started/understanding-data-and-indexes/understanding-data-and-indexes.md#how-features-affect-the-two-datasets). ## Enable row hiding To enable row hiding, use the [`hiddenRows`](@/api/options.md#hiddenrows) option. ::: only-for javascript ::: example #example1 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example1.js) @[code](@/content/guides/rows/row-hiding/javascript/example1.ts) ::: ::: ::: only-for react ::: example #example1 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example1.jsx) @[code](@/content/guides/rows/row-hiding/react/example1.tsx) ::: ::: ::: only-for angular ::: example #example1 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example1.ts) @[code](@/content/guides/rows/row-hiding/angular/example1.html) ::: ::: ::: only-for vue ::: example #example1 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example1.vue) ::: ::: ## Set up row hiding To set up your row hiding configuration, follow the steps below. ### Step 1: Specify rows hidden by default To both enable row hiding and specify rows hidden by default, set the [`hiddenRows`](@/api/options.md#hiddenrows) configuration option to an object. In the object, add a `rows` property, and set it to an array of row indexes. Now, those rows are hidden by default: ::: only-for javascript ::: example #example2 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example2.js) @[code](@/content/guides/rows/row-hiding/javascript/example2.ts) ::: ::: ::: only-for react ::: example #example2 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example2.jsx) @[code](@/content/guides/rows/row-hiding/react/example2.tsx) ::: ::: ::: only-for angular ::: example #example2 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example2.ts) @[code](@/content/guides/rows/row-hiding/angular/example2.html) ::: ::: ::: only-for vue ::: example #example2 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example2.vue) ::: ::: ### Step 2: Show UI indicators To easily see which rows are currently hidden, display UI indicators. To enable the UI indicators, in the `hiddenRows` object, set the `indicators` property to `true`: ::: only-for javascript ::: example #example3 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example3.js) @[code](@/content/guides/rows/row-hiding/javascript/example3.ts) ::: ::: ::: only-for react ::: example #example3 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example3.jsx) @[code](@/content/guides/rows/row-hiding/react/example3.tsx) ::: ::: ::: only-for angular ::: example #example3 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example3.ts) @[code](@/content/guides/rows/row-hiding/angular/example3.html) ::: ::: ::: only-for vue ::: example #example3 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example3.vue) ::: ::: ### Step 3: Set up context menu items To easily hide and unhide rows, add row hiding items to Handsontable's [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md). Enable both the [`ContextMenu`](@/api/contextMenu.md) plugin and the [`HiddenRows`](@/api/hiddenRows.md) plugin. Now, the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md) automatically displays additional items for hiding and unhiding rows. ::: only-for javascript ::: example #example4 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example4.js) @[code](@/content/guides/rows/row-hiding/javascript/example4.ts) ::: ::: ::: only-for react ::: example #example4 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example4.jsx) @[code](@/content/guides/rows/row-hiding/react/example4.tsx) ::: ::: ::: only-for angular ::: example #example4 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example4.ts) @[code](@/content/guides/rows/row-hiding/angular/example4.html) ::: ::: ::: only-for vue ::: example #example4 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example4.vue) ::: ::: You can also add the row hiding menu items individually, by adding the [`hidden_rows_show`](@/guides/accessories-and-menus/context-menu/context-menu.md#context-menu-with-specific-options) and [`hidden_rows_hide`](@/guides/accessories-and-menus/context-menu/context-menu.md#context-menu-with-specific-options) strings to the `contextMenu` parameter: ::: only-for javascript ::: example #example5 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example5.js) @[code](@/content/guides/rows/row-hiding/javascript/example5.ts) ::: ::: ::: only-for react ::: example #example5 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example5.jsx) @[code](@/content/guides/rows/row-hiding/react/example5.tsx) ::: ::: ::: only-for angular ::: example #example5 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example5.ts) @[code](@/content/guides/rows/row-hiding/angular/example5.html) ::: ::: ::: only-for vue ::: example #example5 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example5.vue) ::: ::: ### Step 4: Set up copy and paste behavior By default, hidden rows are included in copying and pasting. To exclude hidden rows from copying and pasting, in the `hiddenRows` object, set the `copyPasteEnabled` property to `false`: ::: only-for javascript ::: example #example6 --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/javascript/example6.js) @[code](@/content/guides/rows/row-hiding/javascript/example6.ts) ::: ::: ::: only-for react ::: example #example6 :react --js 1 --ts 2 @[code](@/content/guides/rows/row-hiding/react/example6.jsx) @[code](@/content/guides/rows/row-hiding/react/example6.tsx) ::: ::: ::: only-for angular ::: example #example6 :angular --ts 1 --html 2 @[code](@/content/guides/rows/row-hiding/angular/example6.ts) @[code](@/content/guides/rows/row-hiding/angular/example6.html) ::: ::: ::: only-for vue ::: example #example6 :vue3 @[code](@/content/guides/rows/row-hiding/vue/example6.vue) ::: ::: ## Result After completing this guide, you can hide rows from the grid without changing source data. You can configure default hidden rows, UI indicators, context menu items, and copy-paste behavior. ## Row hiding API methods ::: only-for react ::: tip To use the Handsontable API, you'll need access to the Handsontable instance. You can do that by utilizing a reference to the `HotTable` component, and reading its `hotInstance` property. For more information, see the [Instance methods](@/guides/getting-started/react-methods/react-methods.md) page. ::: ::: For the most popular row hiding tasks, use the API methods below. To see your changes, re-render your Handsontable instance with the [`render()`](@/api/core.md#render) method. ::: only-for angular To obtain the Handsontable instance from the Angular wrapper component, you can use Angular's `@ViewChild` decorator to reference the `HotTableComponent` and then access its `hotInstance` property. ```ts @ViewChild(HotTableComponent, {static: false}) hotTable!: HotTableComponent; ngAfterViewInit() { // The Handsontable instance is available through the hotInstance property const hot = this.hotTable.hotInstance; // You can now use the "hot" instance to call Handsontable's API methods // ... } ``` ::: :::: only-for vue ::: tip To use the Handsontable API, you'll need access to the Handsontable instance. You can do that by utilizing a reference to the `HotTable` component, and reading its `hotInstance` property. For more information, see the [Instance methods](@/guides/getting-started/vue3-hot-reference/vue3-hot-reference.md) page. ::: :::: ### Access the `HiddenRows` plugin instance To access the [`HiddenRows`](@/api/hiddenRows.md) plugin instance, use the [`getPlugin()`](@/api/core.md#getplugin) method: ```js const plugin = hot.getPlugin('hiddenRows'); ``` ### Hide a single row To hide a single row, use the [`hideRow()`](@/api/hiddenRows.md#hiderow) method: ```js const plugin = hot.getPlugin('hiddenRows'); plugin.hideRow(4); ``` ### Hide multiple rows To hide multiple rows: - Either pass row indexes as arguments to the `hideRow()` method - Or pass an array of row indexes to the `hideRows()` method ```js const plugin = hot.getPlugin('hiddenRows'); plugin.hideRow(0, 4, 6); // or plugin.hideRows([0, 4, 6]); ``` ### Unhide a single row To unhide a single row, use the `showRow()` method: ```js const plugin = hot.getPlugin('hiddenRows'); plugin.showRow(4); ``` ### Unhide multiple rows To unhide multiple rows: - Either pass row indexes as arguments to the `showRow()` method - Or pass an array of row indexes to the `showRows()` method ```js const plugin = hot.getPlugin('hiddenRows'); plugin.showRow(0, 4, 6); // or plugin.showRows([0, 4, 6]); ``` ## Related API reference **Configuration options**
- [hiddenRows](@/api/options.md#hiddenrows)
**Hooks**
- [afterHideRows](@/api/hooks.md#afterhiderows)
- [afterUnhideRows](@/api/hooks.md#afterunhiderows)
- [beforeHideRows](@/api/hooks.md#beforehiderows)
- [beforeUnhideRows](@/api/hooks.md#beforeunhiderows)
**Plugins**
- [HiddenRows](@/api/hiddenRows.md)
---
# Row moving
URL: https://handsontable.com/docs/javascript-data-grid/row-moving/
Change the order of rows, either manually (dragging them to another location), or programmatically (using Handsontable's API methods).
[[toc]]
## Enable the `ManualRowMove` plugin
To enable row moving, set the [`manualRowMove`](@/api/options.md#manualrowmove) option to `true`.
A draggable move handle appears above the selected row header. You can click and drag it to any location in the row header body.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/rows/row-moving/javascript/example1.js)
@[code](@/content/guides/rows/row-moving/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-moving/react/example1.jsx)
@[code](@/content/guides/rows/row-moving/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-moving/angular/example1.ts)
@[code](@/content/guides/rows/row-moving/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/row-moving/vue/example1.vue)
:::
:::
## Set a pre-defined row order
Instead of setting [`manualRowMove`](@/api/options.md#manualrowmove) to `true`, you can pass an **array of physical row indexes** to define the initial visual order of rows on render.
Each position in the array corresponds to a visual (display) position, and the value at that position is the physical (source data) row index. For example:
```js
manualRowMove: [2, 0, 1]
```
This renders the rows in the following order:
- Visual position 0 → physical row `2`
- Visual position 1 → physical row `0`
- Visual position 2 → physical row `1`
The array must contain all physical row indexes (its length must equal the total number of rows). After the initial render, users can still drag rows to change the order further.
## Data model behavior
Moving rows does not reorder your source data array. Handsontable stores the new order as index metadata through its [`IndexMapper`](@/api/indexMapper.md), and leaves the original `sourceData` array untouched. This affects how you read and save the data:
- [`getData()`](@/api/core.md#getdata) returns rows in their current visual order, so it reflects any moves. Call it inside the [`afterRowMove`](@/api/hooks.md#afterrowmove) hook to get an order-accurate snapshot to persist.
- [`getSourceData()`](@/api/core.md#getsourcedata) returns rows in their original physical order, ignoring any moves.
To save the new order after a move, listen to the [`afterRowMove`](@/api/hooks.md#afterrowmove) hook:
```js
afterRowMove(movedRows, finalIndex, dropIndex, movePossible, orderChanged) {
if (orderChanged) {
const reorderedData = this.getData();
// persist reorderedData to your backend
}
}
```
### Don't feed the snapshot back into the grid
Sending the reordered snapshot back to the grid as its new data applies the move a second time. [`updateData()`](@/api/core.md#updatedata) keeps the current row order on purpose, so Handsontable re-applies the order map it already holds on top of your already-reordered array. One drag then moves the row twice.
Treat the snapshot as output only. Send it to your backend, and leave the grid's own data alone.
::: only-for javascript
To replace the data and reset the order together, call [`loadData()`](@/api/core.md#loaddata) instead. It clears the row order map along with the data, and it clears the undo history.
One exception: if you passed [`manualRowMove`](@/api/options.md#manualrowmove) as an array of indexes, the plugin re-applies that array right after the reset. You get the configured order back, not the source order.
:::
:::: only-for react angular vue
### Choose who owns the row order
The array you bind to [`data`](@/api/options.md#data) does not change when a user moves a row. The order lives in Handsontable's index map, not in your array. There are two ways to handle that, and you have to stay inside one of them:
- **Handsontable owns the order.** You bind the data once, and read the order out when you need it.
- **Your app owns the order.** You cancel each move, and reorder your own array instead.
Writing [`getData()`](@/api/core.md#getdata) back into the bound `data` mixes the two models. The grid still holds the order map for a move it has already made, so it applies that order on top of your already-reordered array. Your data and the grid end up out of sync, and the row can jump a second time.
#### Let Handsontable own the order
This is the default. Bind `data` once and leave it alone. Read the current order with [`getData()`](@/api/core.md#getdata) whenever you need to persist it.
To start the grid with a non-default order, pass the array through [`initialState`](@/api/options.md#initialstate) rather than [`manualRowMove`](@/api/options.md#manualrowmove). Handsontable reads [`initialState`](@/api/options.md#initialstate) only when it creates the grid, so a re-render can't apply the order a second time:
```js
initialState: {
manualRowMove: [2, 0, 1],
},
```
The array both enables row moving and sets the starting order, so don't also pass [`manualRowMove`](@/api/options.md#manualrowmove) at the top level. A regular setting takes precedence over the same key in [`initialState`](@/api/options.md#initialstate), so `manualRowMove: true` alongside the code above would discard the order.
A `manualRowMove` array passed as a regular option can be re-applied on a later update, which reorders the rows again on top of the order they are already in. How often that happens depends on the framework, so don't rely on it not happening.
::: only-for react
For more on this, see [Non-idempotent options](@/guides/getting-started/configuration-options/configuration-options.md#non-idempotent-options).
:::
#### Let your app own the order
Return `false` from [`beforeRowMove`](@/api/hooks.md#beforerowmove) to cancel Handsontable's move, then apply the same move to your own array. Handsontable keeps its rows in physical order, so your array is the only place the order is stored.
In this model you also own the order's history. Reverting a move is your code's job, not the grid's.
Cancelling the move changes what the grid does for you, so plan for these:
- [`afterRowMove`](@/api/hooks.md#afterrowmove) never fires. The move stops at [`beforeRowMove`](@/api/hooks.md#beforerowmove), before that hook runs, so the snapshot recipe shown earlier on this page does not apply here. Persist the order from your own update instead.
- The grid does not re-render or restore the selection, because both wait for a move that actually happened. After the drag, the highlighted row headers stay where they were, and those positions now hold different rows. Re-select the moved rows yourself if that matters.
- The hook reports visual row indexes, and the helper below uses them as positions in your array. Those match only while nothing else reorders or hides rows. Add [`columnSorting`](@/api/options.md#columnsorting), [`filters`](@/api/options.md#filters), or trimmed rows, and a visual index no longer points at the same row in your array, so you have to translate the indexes yourself. `finalIndex` is a visual index too.
- Cell metadata is keyed by the physical row. Reordering your own array moves the values but not the metadata, so per-row settings such as [`readOnly`](@/api/options.md#readonly), a cell `className`, or a comment stay on the position they were set on and end up on a different row.
This helper applies a move to a plain array. `movedRows` holds visual row indexes, and `finalIndex` is the index that the first moved row lands on:
```js
function reorderRows(rows, movedRows, finalIndex) {
const result = rows.slice();
const moved = movedRows.map(index => rows[index]);
// remove from the highest index down, so the lower indexes stay valid
movedRows
.slice()
.sort((a, b) => b - a)
.forEach(index => result.splice(index, 1));
result.splice(finalIndex, 0, ...moved);
return result;
}
```
::: only-for react
Keep the rows in state, and write the new order back from the hook:
```jsx
const ExampleComponent = () => {
const [rows, setRows] = useState(initialRows);
return (
- [manualRowMove](@/api/options.md#manualrowmove)
**Core methods**
- [toVisualRow](@/api/core.md#tovisualrow)
**Hooks**
- [afterRowMove](@/api/hooks.md#afterrowmove)
- [beforeRowMove](@/api/hooks.md#beforerowmove)
**Plugins**
- [ManualRowMove](@/api/manualRowMove.md)
---
# Row freezing
URL: https://handsontable.com/docs/javascript-data-grid/row-freezing/
Lock the position of specified rows, keeping them visible when scrolling.
[[toc]]
## Overview
Row freezing locks specific rows of a grid in place, keeping them visible while scrolling to another area of the grid.
This feature is sometimes called "pinned rows".
## Example
The following example specifies two fixed rows with `fixedRowsTop: 2`. Horizontal scroll bars are needed, so set a container `width` and `overflow: hidden` in CSS.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/rows/row-freezing/javascript/example1.js)
@[code](@/content/guides/rows/row-freezing/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-freezing/react/example1.jsx)
@[code](@/content/guides/rows/row-freezing/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-freezing/angular/example1.ts)
@[code](@/content/guides/rows/row-freezing/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/row-freezing/vue/example1.vue)
:::
:::
## Freeze rows at the bottom
To pin rows to the bottom edge of the grid -- sometimes called footer rows -- use the `fixedRowsBottom` option. The specified number of rows stays visible at the bottom of the viewport while you scroll through the rest of the data.
```js
const hot = new Handsontable(container, {
data: getData(),
// freeze the last two rows as a footer
fixedRowsBottom: 2,
licenseKey: 'non-commercial-and-evaluation',
});
```
You can combine `fixedRowsTop` and `fixedRowsBottom` to keep both a header and a footer row in view at the same time.
## Result
After completing this guide, the rows you specify with `fixedRowsTop` or `fixedRowsBottom` stay visible while you scroll through the rest of the grid.
## Related API reference
**Configuration options**
- [fixedRowsBottom](@/api/options.md#fixedrowsbottom)
- [fixedRowsTop](@/api/options.md#fixedrowstop)
---
# Row heights
URL: https://handsontable.com/docs/javascript-data-grid/row-height/
Configure row heights, using a number, an array or a function. Let your users manually change row heights using Handsontable's interface.
[[toc]]
## Overview
The default (and minimum) row height is calculated based on the used theme's line height, vertical padding and cell border values and in the `main` theme it's 29px, in the `horizon` it's 37px and in the `classic` styles it's 26 px. Unless configured otherwise, Handsontable assumes that your cell contents fit in this default row height.
If your cell contents require heights greater than default (because you use multiline text, or [custom renderers](@/guides/cell-functions/cell-renderer/cell-renderer.md), or custom styles), use one of the following configurations to avoid potential layout problems:
- Configure your row heights in advance: set the [`minRowHeights`](@/api/options.md#minrowheights) option to a [number](#set-row-heights-to-a-number), or an [array](#set-row-heights-with-an-array), or a [function](#set-row-heights-with-a-function). This requires you to know the heights beforehand, but results in the best runtime performance.
- Set the [`manualRowResize`](@/api/options.md#manualrowresize) option to an array, to configure initial row heights and let your users [adjust the row heights manually](#adjust-row-heights-manually).
- Enable the [`AutoRowSize`](@/api/autoRowSize.md) plugin, by setting `autoRowSize: true`. This tells Handsontable to measure the actual row heights in the DOM. It impacts runtime performance but is accurate. Also enable `AutoRowSize` if you call [`scrollViewportTo()`](@/api/core.md#scrollviewportto) -- the method relies on accurate row height measurements to scroll to the correct position.
## Set row heights to a number
We set the same height of `40px` for all rows across the entire grid in this example.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/rows/row-height/javascript/example1.js)
@[code](@/content/guides/rows/row-height/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-height/react/example1.jsx)
@[code](@/content/guides/rows/row-height/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-height/angular/example1.ts)
@[code](@/content/guides/rows/row-height/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/row-height/vue/example1.vue)
:::
:::
## Set row heights with an array
In this example, the height is only set for the first rows. Each additional row would be automatically adjusted to the content.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/rows/row-height/javascript/example2.js)
@[code](@/content/guides/rows/row-height/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-height/react/example2.jsx)
@[code](@/content/guides/rows/row-height/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-height/angular/example2.ts)
@[code](@/content/guides/rows/row-height/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/rows/row-height/vue/example2.vue)
:::
:::
## Set row heights with a function
The row height can be set using a function. In this example, the size of all rows is set using a function that takes a row `index` (1, 2 ...) and multiplies it by `20px` for each consecutive row.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/rows/row-height/javascript/example3.js)
@[code](@/content/guides/rows/row-height/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-height/react/example3.jsx)
@[code](@/content/guides/rows/row-height/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-height/angular/example3.ts)
@[code](@/content/guides/rows/row-height/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/rows/row-height/vue/example3.vue)
:::
:::
## Adjust row heights manually
Set the option [`manualRowResize`](@/api/options.md#manualrowresize) to `true` to allow users to manually resize the row height by dragging the handle between the adjacent row headers. Don't forget to enable row headers by setting [`rowHeaders`](@/api/options.md#rowheaders) to `true`.
You can adjust the size of one or multiple rows simultaneously, even if the selected rows are not placed next to each other.
::: tip
When you set a row height programmatically with [`ManualRowResize#setManualSize()`](@/api/manualRowResize.md#setmanualsize), call `hot.render()` after the method call to repaint the grid. Values below the theme's default row height are stored as the default row height.
:::
::: only-for javascript
::: example #example4 --js 1 --ts 2
@[code](@/content/guides/rows/row-height/javascript/example4.js)
@[code](@/content/guides/rows/row-height/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-height/react/example4.jsx)
@[code](@/content/guides/rows/row-height/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-height/angular/example4.ts)
@[code](@/content/guides/rows/row-height/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/rows/row-height/vue/example4.vue)
:::
:::
## Related API reference
**Configuration options**
- [autoRowSize](@/api/options.md#autorowsize)
- [manualRowResize](@/api/options.md#manualrowresize)
- [minRowHeights](@/api/options.md#minRowHeights)
**Core methods**
- [getRowHeight()](@/api/core.md#getrowheight)
- [scrollViewportTo()](@/api/core.md#scrollviewportto)
**Hooks**
- [afterRowResize](@/api/hooks.md#afterrowresize)
- [beforeRowResize](@/api/hooks.md#beforerowresize)
- [modifyRowHeight](@/api/hooks.md#modifyrowheight)
**Plugins**
- [AutoRowSize](@/api/autoRowSize.md)
- [ManualRowResize](@/api/manualRowResize.md)
---
# Row virtualization
URL: https://handsontable.com/docs/javascript-data-grid/row-virtualization/
Render thousands of rows without freezing the browser, using row virtualization.
[[toc]]
## Overview
Virtualization allows Handsontable to process hundreds of thousands of records without causing the browser to hang. This feature draws only the visible part of the grid, displaying the minimum items physically rendered in the DOM. The elements outside the viewport are rendered when you scroll across the grid. Depending on your configuration, there might be a small offset of columns or rows rendered outside the viewport to make the scrolling performance smoother.
This feature is enabled by default and can be turned off by setting the [`renderAllRows`](@/api/options.md#renderallrows) option to `true`.
## Configuring row virtualization
You can experiment with the [`viewportRowRenderingOffset`](@/api/options.md#viewportrowrenderingoffset) configuration option, which determines the number of rows displayed outside the visible viewport. If the number passed to that option is greater than the total columns in your data set, then the virtualization will be practically turned off.
To make the grid scrollable, set the constant width and height to the same as the container holding Handsontable and set the `overflow` property to `hidden` in the container's stylesheet. If the table contains enough rows or columns, it will be scrollable.
The scrolling performance depends mainly on four factors:
- Number of cells - number of rows multiplied by the number of columns
- Amount and complexity of custom renderers in cells
- Number of options enabled in the configuration
- Performance of your setup - physical machine and a browser
The example below presents a data grid displaying 1 million cells (1000 rows x 1000 columns):
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/rows/row-virtualization/javascript/example1.js)
@[code](@/content/guides/rows/row-virtualization/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-virtualization/react/example1.jsx)
@[code](@/content/guides/rows/row-virtualization/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-virtualization/angular/example1.ts)
@[code](@/content/guides/rows/row-virtualization/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/row-virtualization/vue/example1.vue)
:::
:::
## Known limitations
Using row virtualization has the following side effects:
- The browser's native search will work only for the visible part of the grid.
- Screen readers may announce the wrong total number of rows. Read more in the
[Accessibility](@/guides/accessibility/accessibility/accessibility.md#disabling-dom-virtualization-for-improved-accessibility) guide.
## Related articles
**Related guides**
- [Column virtualization](@/guides/columns/column-virtualization/column-virtualization.md)
- [Performance](@/guides/optimization/performance/performance.md)
**Configuration options**
- [renderAllRows](@/api/options.md#renderallrows)
- [viewportRowRenderingOffset](@/api/options.md#viewportrowrenderingoffset)
## Related
- [Performance](@/guides/optimization/performance/performance.md) -- tips for optimizing grid rendering speed with large data sets
- [Row height](@/guides/rows/row-height/row-height.md) -- configure fixed or dynamic row heights, which affects viewport calculations during virtualization
---
# Rows sorting
URL: https://handsontable.com/docs/javascript-data-grid/rows-sorting/
Sort rows alphabetically or numerically, in ascending, descending, or a custom order, by one or multiple columns.
[[toc]]
## Overview
Handsontable provides two plugins for sorting rows:
- [`ColumnSorting`](@/api/columnSorting.md) -- sorts rows by a **single column** at a time. Clicking a column header cycles through ascending, descending, and unsorted states.
- [`MultiColumnSorting`](@/api/multiColumnSorting.md) -- sorts rows by **multiple columns** simultaneously. Hold Ctrl/Cmd and click column headers to add more sort criteria.
Sorting runs when you release the mouse button, not when you press it, and only the header label and its sort
indicator respond to the click. Pressing the header around them selects the column without sorting it. If the
pointer moves while the button is held, Handsontable treats the gesture as a column drag instead of a sort, so
[column moving](@/guides/columns/column-moving/column-moving.md) can share the same header.
Both plugins sort the view only. The source data array is never modified. To persist the sorted order back to the data source, see [Saving data](@/guides/getting-started/saving-data/saving-data.md).
`ColumnSorting` and `MultiColumnSorting` are mutually exclusive. Enable only one at a time. If both options are set to `true`, `ColumnSorting` is automatically disabled.
## Sorting demo
Click a column header to sort in ascending (↑) or descending (↓) order. Click again to return to the original order.
::: only-for javascript
::: example #exampleSortingDemo --html 1 --js 2 --ts 3
@[code](@/content/guides/rows/rows-sorting/javascript/exampleSortingDemo.html)
@[code](@/content/guides/rows/rows-sorting/javascript/exampleSortingDemo.js)
@[code](@/content/guides/rows/rows-sorting/javascript/exampleSortingDemo.ts)
:::
:::
::: only-for react
::: example #exampleSortingDemo :react --js 1 --ts 2
@[code](@/content/guides/rows/rows-sorting/react/exampleSortingDemo.jsx)
@[code](@/content/guides/rows/rows-sorting/react/exampleSortingDemo.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/rows-sorting/angular/example1.ts)
@[code](@/content/guides/rows/rows-sorting/angular/example1.html)
:::
:::
::: only-for vue
::: example #exampleSortingDemo :vue3
@[code](@/content/guides/rows/rows-sorting/vue/exampleSortingDemo.vue)
:::
:::
## Enable sorting
To enable sorting for all columns, set [`columnSorting`](@/api/options.md#columnsorting) to `true`.
::: only-for javascript
```js
const configurationOptions = {
columnSorting: true,
};
```
:::
::: only-for react
```jsx
- [View related topics](https://github.com/handsontable/handsontable/labels/Column%20sorting) on GitHub
- [Report an issue](https://github.com/handsontable/handsontable/issues/new/choose) on GitHub
- [Start a discussion](https://forum.handsontable.com/c/getting-help/questions) on Handsontable's forum
- [Contact our technical support](https://handsontable.com/contact?category=technical_support) to get help
---
# Rows pagination
URL: https://handsontable.com/docs/javascript-data-grid/rows-pagination/
Added in Handsontable 16.1.0.
Split large data sets into pages to improve usability and rendering performance. Pagination operates fully on the client side and automatically recomputes the total page count whenever rows are added, removed, filtered, or otherwise modified.
[[toc]]
## Pagination demo
Use the controls below the grid to switch between pages.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code collapse={8-107, 117-162}](@/content/guides/rows/rows-pagination/javascript/example1.js)
@[code collapse={8-107, 117-162}](@/content/guides/rows/rows-pagination/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code collapse={8-107, 126-156}](@/content/guides/rows/rows-pagination/react/example1.jsx)
@[code collapse={8-107, 126-156}](@/content/guides/rows/rows-pagination/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code collapse={16-115, 122-168}](@/content/guides/rows/rows-pagination/angular/example1.ts)
@[code](@/content/guides/rows/rows-pagination/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/rows-pagination/vue/example1.vue)
:::
:::
## Enable pagination
To enable pagination set the [`pagination`](@/api/options.md#pagination) option to `true`.
```javascript
const configurationOptions = {
pagination: true,
};
```
Defining the option as `true` is equivalent to defining the following options:
```javascript
const configurationOptions = {
pagination: {
pageSize: 10,
pageSizeList: ['auto', 5, 10, 20, 50, 100],
initialPage: 1,
showPageSize: true,
showCounter: true,
showNavigation: true,
uiContainer: null,
},
};
```
## Configure pagination
You can customize pagination using available settings, such as showing or hiding specific UI sections like the page size selector, page counter, or page navigation.
Control aspects such as the number of rows per page, the initial page on load, or whether the grid should automatically adjust page size based on the container's height.
You can configure the following options:
```javascript
const configurationOptions = {
pagination: {
// Set number of rows per page. If the value is `auto` then the
// page size is calculated
// based on available height.
pageSize: 20,
// Provide a list of selectable page sizes
pageSizeList: ['auto', 10, 20, 50],
// Set the initial page when the grid loads
initialPage: 2,
// Show or hide the page size section
showPageSize: false,
// Show or hide the page counter section
showCounter: true,
// Show or hide the page navigation section
showNavigation: true,
// Custom container where the pagination UI will be injected
// (optional)
uiContainer: null,
}
};
```
In the data grid below, several pagination options are applied to provide a customized experience. The demo allows you to resize the table container and observe how the auto page size feature (`pageSize: 'auto'`) dynamically adjusts the number of visible rows to fit the available space.
::: only-for javascript
::: example #example2 --html 1 --js 2 --ts 3
@[code](@/content/guides/rows/rows-pagination/javascript/example2.html)
@[code collapse={8-107, 124-169}](@/content/guides/rows/rows-pagination/javascript/example2.js)
@[code collapse={8-107, 124-169}](@/content/guides/rows/rows-pagination/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --css 2 --ts 3
@[code collapse={8-107, 137-167}](@/content/guides/rows/rows-pagination/react/example2.jsx)
@[code](@/content/guides/rows/rows-pagination/react/example2.css)
@[code collapse={8-107, 137-167}](@/content/guides/rows/rows-pagination/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code collapse={16-115, 142-188}](@/content/guides/rows/rows-pagination/angular/example2.ts)
@[code](@/content/guides/rows/rows-pagination/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/rows/rows-pagination/vue/example2.vue)
:::
:::
## Control pagination programmatically
Build your own pagination UI using API methods such as [`setPage()`](@/api/pagination.md#setpage), [`nextPage()`](@/api/pagination.md#nextpage), [`prevPage()`](@/api/pagination.md#prevpage), and more. For a complete list of available methods and hooks, see the [`Pagination`](@/api/pagination.md) plugin API reference.
::: only-for javascript
::: example #example3 --html 1 --js 2 --ts 3
@[code](@/content/guides/rows/rows-pagination/javascript/example3.html)
@[code collapse={8-107, 122-167}](@/content/guides/rows/rows-pagination/javascript/example3.js)
@[code collapse={8-107, 123-168}](@/content/guides/rows/rows-pagination/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --css 2 --ts 3
@[code collapse={8-107, 200-230}](@/content/guides/rows/rows-pagination/react/example3.jsx)
@[code](@/content/guides/rows/rows-pagination/react/example3.css)
@[code collapse={8-107, 200-230}](@/content/guides/rows/rows-pagination/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code collapse={42-141, 154-200}](@/content/guides/rows/rows-pagination/angular/example3.ts)
@[code](@/content/guides/rows/rows-pagination/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/rows/rows-pagination/vue/example3.vue)
:::
:::
## Choose where to display the pagination UI
By default, the pagination UI is displayed at the bottom of the grid. You can change the place of the pagination component by setting the [`uiContainer`](@/api/options.md#uicontainer) option to a custom container element.
::: only-for javascript
::: example #example4 --html 1 --js 2 --ts 3
@[code](@/content/guides/rows/rows-pagination/javascript/example4.html)
@[code collapse={8-107, 119-164}](@/content/guides/rows/rows-pagination/javascript/example4.js)
@[code collapse={8-107, 119-164}](@/content/guides/rows/rows-pagination/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --css 2 --ts 3
@[code collapse={8-107, 140-170}](@/content/guides/rows/rows-pagination/react/example4.jsx)
@[code](@/content/guides/rows/rows-pagination/react/example4.css)
@[code collapse={8-107, 140-170}](@/content/guides/rows/rows-pagination/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code collapse={16-115, 144-190}](@/content/guides/rows/rows-pagination/angular/example4.ts)
@[code](@/content/guides/rows/rows-pagination/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/rows/rows-pagination/vue/example4.vue)
:::
:::
## Modify paged data
Sometimes you need to modify data only on the currently visible page. Core method like [`setDataAtCell`](@/api/core.md#setdataatcell) operates on all rows, including those hidden by pagination. To modify data only on the current page, you can use the [`getPaginationData`](@/api/pagination.md#getpaginationdata) method to get the pagination state and use it in conjunction with Core method.
::: only-for javascript
::: example #example5 --html 1 --js 2 --ts 3
@[code](@/content/guides/rows/rows-pagination/javascript/example5.html)
@[code collapse={8-107, 116-161}](@/content/guides/rows/rows-pagination/javascript/example5.js)
@[code collapse={8-107, 117-162}](@/content/guides/rows/rows-pagination/javascript/example5.ts)
:::
:::
::: only-for react
::: example #example5 :react --js 1 --css 2 --ts 3
@[code collapse={8-107, 158-188}](@/content/guides/rows/rows-pagination/react/example5.jsx)
@[code](@/content/guides/rows/rows-pagination/react/example5.css)
@[code collapse={8-107, 159-189}](@/content/guides/rows/rows-pagination/react/example5.tsx)
:::
:::
::: only-for angular
::: example #example5 :angular --ts 1 --html 2
@[code collapse={25-124, 131-177}](@/content/guides/rows/rows-pagination/angular/example5.ts)
@[code](@/content/guides/rows/rows-pagination/angular/example5.html)
:::
:::
::: only-for vue
::: example #example5 :vue3
@[code](@/content/guides/rows/rows-pagination/vue/example5.vue)
:::
:::
## Use pagination hooks
You can run your code before or after different stages of pagination, using the following [Handsontable hooks](@/guides/getting-started/events-and-hooks/events-and-hooks.md):
- [`beforePageChange()`](@/api/hooks.md#beforepagechange)
- [`afterPageChange()`](@/api/hooks.md#afterpagechange)
- [`beforePageSizeChange()`](@/api/hooks.md#beforepagesizechange)
- [`afterPageSizeChange()`](@/api/hooks.md#afterpagesizechange)
- [`afterPageSizeVisibilityChange()`](@/api/hooks.md#afterpagesizevisibilitychange)
- [`afterPageCounterVisibilityChange()`](@/api/hooks.md#afterpagecountervisibilitychange)
- [`afterPageNavigationVisibilityChange()`](@/api/hooks.md#afterpagenavigationvisibilitychange)
::: only-for javascript
```js
const configurationOptions = {
beforePageChange() {
// add your code here
return false; // to block page change
},
afterPageChange() {
// add your code here
},
beforePageSizeChange() {
// add your code here
return false; // to block page size change
},
// ...
};
```
:::
::: only-for react
```jsx
- [Handsontable 16.1: Row Pagination, Loading Plugin, and Long-Term Support Policy](https://handsontable.com/blog/handsontable-16.1-row-pagination-loading-plugin-and-long-term-support-policy)
## Related API reference
**Configuration options**
- [pagination](@/api/options.md#pagination)
- [fixedRowsBottom](@/api/options.md#fixedrowsbottom)
- [fixedRowsTop](@/api/options.md#fixedrowstop)
**Hooks**
- [beforePageChange()](@/api/hooks.md#beforepagechange)
- [afterPageChange()](@/api/hooks.md#afterpagechange)
- [beforePageSizeChange()](@/api/hooks.md#beforepagesizechange)
- [afterPageSizeChange()](@/api/hooks.md#afterpagesizechange)
- [afterPageSizeVisibilityChange()](@/api/hooks.md#afterpagesizevisibilitychange)
- [afterPageCounterVisibilityChange()](@/api/hooks.md#afterpagecountervisibilitychange)
- [afterPageNavigationVisibilityChange()](@/api/hooks.md#afterpagenavigationvisibilitychange)
**Plugins**
- [Pagination](@/api/pagination.md)
- [NestedRows](@/api/nestedRows.md)
- [MergeCells](@/api/mergeCells.md)
## Troubleshooting
Didn't find what you need? Try this:
- [View related topics](https://github.com/handsontable/handsontable/labels/Pagination) on GitHub
- [Report an issue](https://github.com/handsontable/handsontable/issues/new/choose) on GitHub
- [Start a discussion](https://forum.handsontable.com/c/getting-help/questions) on Handsontable's forum
- [Contact our technical support](https://handsontable.com/contact?category=technical_support) to get help
---
# Row trimming
URL: https://handsontable.com/docs/javascript-data-grid/row-trimming/
Hide individual rows from your interface and exclude them from the rendering process and `DataMap`.
[[toc]]
## Overview
Row trimming is similar to [row hiding](@/guides/rows/row-hiding/row-hiding.md), but works a bit differently.
The [`TrimRows`](@/api/trimRows.md) plugin allows the trimming of specific rows from the table. Rows being trimmed aren't rendered and aren't included in the `DataMap`, which can be retrieved by calling the [`getData`](@/api/core.md#getdata) method.
Unlike hidden rows, trimmed rows are removed from the visual dataset entirely, so rows after them shift to a lower visual index. For a full comparison, see [Understanding data and indexes](@/guides/getting-started/understanding-data-and-indexes/understanding-data-and-indexes.md#how-features-affect-the-two-datasets).
## Setup
To enable row trimming, set the [`trimRows`](@/api/options.md#trimrows) option to `true`.
::: only-for javascript
```js
// enable the `TrimRows` plugin
trimRows: true,
```
:::
::: only-for react
```jsx
// enable the `TrimRows` plugin
- [trimRows](@/api/options.md#trimrows)
**Hooks**
- [afterTrimRow](@/api/hooks.md#aftertrimrow)
- [afterUntrimRow](@/api/hooks.md#afteruntrimrow)
- [beforeTrimRow](@/api/hooks.md#beforetrimrow)
- [beforeUntrimRow](@/api/hooks.md#beforeuntrimrow)
**Plugins**
- [TrimRows](@/api/trimRows.md)
---
# Row pre-populating
URL: https://handsontable.com/docs/javascript-data-grid/row-prepopulating/
Pre-populate new rows with default values when users add rows to the grid.
[[toc]]
## Basic spare rows
To keep one empty row at the bottom of the grid, set [`minSpareRows`](@/api/options.md#minsparerows) to `1`.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/javascript/example1.js)
@[code](@/content/guides/rows/row-prepopulating/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/react/example1.jsx)
@[code](@/content/guides/rows/row-prepopulating/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-prepopulating/angular/example1.ts)
@[code](@/content/guides/rows/row-prepopulating/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/rows/row-prepopulating/vue/example1.vue)
:::
:::
## Spare rows with placeholder styling
To hint what to enter in the spare row, add a custom cell renderer that displays greyed-out placeholder text in empty cells. The renderer checks whether the whole row is empty, then shows a template value in a lighter color.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/javascript/example2.js)
@[code](@/content/guides/rows/row-prepopulating/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/react/example2.jsx)
@[code](@/content/guides/rows/row-prepopulating/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-prepopulating/angular/example2.ts)
@[code](@/content/guides/rows/row-prepopulating/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/rows/row-prepopulating/vue/example2.vue)
:::
:::
## Auto-populating with template values
For full pre-population, use the [`beforeChange`](@/api/hooks.md#beforechange) hook to fill all cells in a spare row with template values the moment the user starts editing. The `isEmptyRow()` helper detects whether the row is untouched, and the hook pushes changes for every column except the one the user is editing.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/javascript/example3.js)
@[code](@/content/guides/rows/row-prepopulating/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/rows/row-prepopulating/react/example3.jsx)
@[code](@/content/guides/rows/row-prepopulating/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/rows/row-prepopulating/angular/example3.ts)
@[code](@/content/guides/rows/row-prepopulating/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/rows/row-prepopulating/vue/example3.vue)
:::
:::
## Pre-populate from an adjacent row
You can copy values from the row above when the user inserts a new row. Use the [`afterCreateRow`](@/api/hooks.md#aftercreaterow) hook to read the source row's data and write it to the newly created row.
```js
const hot = new Handsontable(container, {
data: [
['Product A', 10, 'active'],
['Product B', 20, 'inactive'],
],
colHeaders: ['Name', 'Quantity', 'Status'],
afterCreateRow(index) {
if (index > 0) {
const sourceRow = hot.getSourceDataAtRow(index - 1);
sourceRow.forEach((value, col) => {
hot.setDataAtCell(index, col, value);
});
}
},
licenseKey: 'non-commercial-and-evaluation',
});
```
## Pre-populate from a server-fetched default
You can fetch default row values from a server and apply them when the user adds a new row. Use the [`afterCreateRow`](@/api/hooks.md#aftercreaterow) hook to trigger the request and populate the row once the response arrives.
```js
const hot = new Handsontable(container, {
data: [],
colHeaders: ['Name', 'Quantity', 'Status'],
afterCreateRow(index) {
fetch('/api/row-defaults')
.then((response) => response.json())
.then((defaults) => {
hot.setDataAtRow(index, [defaults.name, defaults.quantity, defaults.status]);
});
},
licenseKey: 'non-commercial-and-evaluation',
});
```
## Result
Your grid keeps one or more empty rows at the bottom. Depending on the approach, spare rows show greyed-out placeholder text or auto-fill all cells with template values when the user starts editing.
## Related API reference
**Hooks**
- [afterCreateRow](@/api/hooks.md#aftercreaterow)
- [beforeChange](@/api/hooks.md#beforechange)
---
# Selection
URL: https://handsontable.com/docs/javascript-data-grid/selection/
Select a single cell, a range of adjacent cells, or multiple non-adjacent ranges of cells.
[[toc]]
Use the selection API to control how users select cells -- single cells, ranges, columns, or rows -- and to read or set selections programmatically.
## Overview
Selection enables you to select a single cell or ranges of cells within Handsontable. Once selected, you can retrieve data from the cell, edit the cell's contents, or change the style of the cell.
## Basic configuration
With this feature, you can select single cells or ranges of cells across a grid. Easily retrieve the coordinates of the selected cells to clear or change the cells' content.
Use ⌘ on Mac or **Ctrl** on Windows to select non-adjacent ranges of cells.
Click a column header to select all cells in that column. Click a row header to select all cells in that row. Both require [`colHeaders`](@/api/options.md#colheaders) or [`rowHeaders`](@/api/options.md#rowheaders) to be enabled.
## Select ranges
There are different modes in which you can use this plugin. Choose between selecting a single cell, a range of adjacent cells, and multiple ranges of non-contiguous cells.
Possible values of [`selectionMode`](@/api/options.md#selectionmode):
- [`single`](@/api/options.md#selectionmode) - You can select a single cell.
- [`range`](@/api/options.md#selectionmode) - You can select multiple cells within a single rangeselected.
- [`multiple`](@/api/options.md#selectionmode) - Multiple non-contiguous ranges of cells can be selected.
::: only-for javascript
::: example #example1 --html 1 --js 2 --ts 3 --css 4
@[code](@/content/guides/cell-features/selection/javascript/example1.html)
@[code](@/content/guides/cell-features/selection/javascript/example1.js)
@[code](@/content/guides/cell-features/selection/javascript/example1.ts)
@[code](@/content/guides/cell-features/selection/javascript/example1.css)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/selection/react/example1.jsx)
@[code](@/content/guides/cell-features/selection/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example1.ts)
@[code](@/content/guides/cell-features/selection/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-features/selection/vue/example1.vue)
:::
:::
## Get data from the selected ranges
To retrieve the selected cells as an array of arrays, you use the [`getSelected()`](@/api/core.md#getselected) or [`getSelectedRange()`](@/api/core.md#getselectedrange) methods.
::: only-for javascript
::: example #example2 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/javascript/example2.html)
@[code](@/content/guides/cell-features/selection/javascript/example2.js)
@[code](@/content/guides/cell-features/selection/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/selection/react/example2.jsx)
@[code](@/content/guides/cell-features/selection/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example2.ts)
@[code](@/content/guides/cell-features/selection/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/cell-features/selection/vue/example2.vue)
:::
:::
## Modify the selected cells
You may want to delete, format, or otherwise change the selected cells. For example, you can change a value or add CSS classes to the selected cells using the demo below.
::: only-for javascript
::: example #example3 --html 1 --css 2 --js 3 --ts 4
@[code](@/content/guides/cell-features/selection/javascript/example3.html)
@[code](@/content/guides/cell-features/selection/javascript/example3.css)
@[code](@/content/guides/cell-features/selection/javascript/example3.js)
@[code](@/content/guides/cell-features/selection/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/react/example3.css)
@[code](@/content/guides/cell-features/selection/react/example3.jsx)
@[code](@/content/guides/cell-features/selection/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example3.ts)
@[code](@/content/guides/cell-features/selection/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/cell-features/selection/vue/example3.vue)
:::
:::
## Style the selection area
You can change the background color of selected cells using CSS. The base selection color is defined in the `.area` class.
When using multiple non-adjacent selections (**Cmd**/**Ctrl** + click), each additional selection layer receives a numbered class: `area-1` for the second layer, `area-2` for the third, and so on. Each class is cumulative — a cell in the second layer has both `area` and `area-1`.
The example below customizes the color of each selection layer using these CSS classes.
::: only-for javascript
::: example #example4 --html 1 --css 2 --js 3 --ts 4
@[code](@/content/guides/cell-features/selection/javascript/example4.html)
@[code](@/content/guides/cell-features/selection/javascript/example4.css)
@[code](@/content/guides/cell-features/selection/javascript/example4.js)
@[code](@/content/guides/cell-features/selection/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/react/example4.css)
@[code](@/content/guides/cell-features/selection/react/example4.jsx)
@[code](@/content/guides/cell-features/selection/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example4.ts)
@[code](@/content/guides/cell-features/selection/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/cell-features/selection/vue/example4.vue)
:::
:::
Unfortunately, there is no easy way to change the border color of the selection.
### Add a class name to selected cells
Use the [`afterDrawSelection`](@/api/hooks.md#afterdrawselection) hook to give selected cells your own class name. Handsontable calls the hook for each cell of the selection area while it draws the selection. If the hook returns a string, Handsontable adds that string as a class name to the cell. If the hook returns anything else, the cell gets no extra class.
The hook receives the visual row and column index of the cell, the corners of the current selection layer, and the number of the layer being drawn.
## Resize a selection with handles
When you set [`selectionHandles`](@/api/options.md#selectionhandles) to `true`, hovering over a selected range shows a pill-shaped handle at the midpoint of each edge. Drag a handle to move that edge and resize the selection. The handles adjust the selected area only -- they do not move, fill, or change any cell data.
To enable selection handles:
```javascript
selectionHandles: true,
```
This option applies at the grid level and defaults to `false`.
**Limitations:**
- Handles appear on desktop only. Touch devices keep their existing native selection handles and are not affected by this option.
- The option has no effect when [`selectionMode`](@/api/options.md#selectionmode) is `'single'`.
- Handles are not shown for full-row, full-column, or select-all selections.
- A handle is not shown on an edge that is flush with the grid boundary or that lands on a frozen-pane line ([`fixedRowsTop`](@/api/options.md#fixedrowstop), [`fixedRowsBottom`](@/api/options.md#fixedrowsbottom), [`fixedColumnsStart`](@/api/options.md#fixedcolumnsstart)).
- The handles are pointer-only -- there is no keyboard equivalent. To resize a selection with the keyboard, use Shift+Arrow.
::: only-for javascript
::: example #example7 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/javascript/example7.html)
@[code](@/content/guides/cell-features/selection/javascript/example7.js)
@[code](@/content/guides/cell-features/selection/javascript/example7.ts)
:::
:::
::: only-for react
::: example #example7 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/selection/react/example7.jsx)
@[code](@/content/guides/cell-features/selection/react/example7.tsx)
:::
:::
::: only-for angular
::: example #example7 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example7.ts)
@[code](@/content/guides/cell-features/selection/angular/example7.html)
:::
:::
::: only-for vue
::: example #example7 :vue3
@[code](@/content/guides/cell-features/selection/vue/example7.vue)
:::
:::
## Move a selection by dragging
When you set [`moveCells`](@/api/options.md#movecells) to `true`, you can drag the border of a selected cell range to move or copy the range's data to a new location. For configuration details, limitations, hooks, and a live demo, see the [Move cells](@/guides/cell-features/move-cells/move-cells.md) guide. To move whole rows or columns instead, see the [Row moving](@/guides/rows/row-moving/row-moving.md) and [Column moving](@/guides/columns/column-moving/column-moving.md) guides.
## Select cells programmatically
Use [`selectCell()`](@/api/core.md#selectcell) to select a single cell or a range of cells from code. Pass the start and end row/column indices to define a range. Use [`deselectCell()`](@/api/core.md#deselectcell) to clear the selection.
::: only-for javascript
::: example #example5 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/javascript/example5.html)
@[code](@/content/guides/cell-features/selection/javascript/example5.js)
@[code](@/content/guides/cell-features/selection/javascript/example5.ts)
:::
:::
::: only-for react
::: example #example5 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/selection/react/example5.jsx)
@[code](@/content/guides/cell-features/selection/react/example5.tsx)
:::
:::
::: only-for angular
::: example #example5 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example5.ts)
@[code](@/content/guides/cell-features/selection/angular/example5.html)
:::
:::
::: only-for vue
::: example #example5 :vue3
@[code](@/content/guides/cell-features/selection/vue/example5.vue)
:::
:::
## Jump across the grid's edges
When you use keyboard navigation to cross an edge of the grid, you can set cell selection to jump to the opposite edge.
#### Jump across vertical edges
To enable jumping across the left and right edges:
- Set the [`autoWrapRow`](@/api/options.md#autowraprow) configuration option to `true`.
To jump across a vertical edge:
- When cell selection is on a row's first cell, press **←**.
- When cell selection is on a row's last cell, press **→**, or press **Tab**.
#### Jump across horizontal edges
To enable jumping across the top and bottom edges:
- Set the [`autoWrapCol`](@/api/options.md#autowrapcol) configuration option to `true`.
To jump across a horizontal edge:
- When cell selection is on a column's first cell, press **↑**.
- When cell selection is on a column's last cell, press **↓**, or press **Enter**.
Use the checkboxes in the demo below to toggle `autoWrapRow` and `autoWrapCol`, then select a cell and use the keyboard to test the wrap-around behavior at the grid's edges.
::: only-for javascript
::: example #example6 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/selection/javascript/example6.html)
@[code](@/content/guides/cell-features/selection/javascript/example6.js)
@[code](@/content/guides/cell-features/selection/javascript/example6.ts)
:::
:::
::: only-for react
::: example #example6 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/selection/react/example6.jsx)
@[code](@/content/guides/cell-features/selection/react/example6.tsx)
:::
:::
::: only-for angular
::: example #example6 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/selection/angular/example6.ts)
@[code](@/content/guides/cell-features/selection/angular/example6.html)
:::
:::
::: only-for vue
::: example #example6 :vue3
@[code](@/content/guides/cell-features/selection/vue/example6.vue)
:::
:::
## Result
Users can select cells using the configured mode -- single cell, range, or multiple ranges. Programmatic selections take effect immediately and fire the relevant selection hooks.
## Related keyboard shortcuts
| Windows | macOS | Action | Excel | Sheets |
| ------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- | :-----: | :-----: |
| **Ctrl**+**A** | ⌘+**A** | Select all cells | ✓ | ✓ |
|**Ctrl**+**Shift**+**Space** |⌘+⇧+**Space** | Select all cells and headers | ✓ | ✓ |
| **Ctrl**+**Space** | ⌃+**Space** | Select the entire column | ✓ | ✓ |
| **Shift**+**Space** | ⇧+**Space** | Select the entire row | ✓ | ✓ |
| **Ctrl**+**Shift**+**↑** | ⌘+⇧+**↑** | Extend the selection to the first cell of the current column** | ✓ | ✓ |
| **Ctrl**+**Shift**+**↓** | ⌘+⇧+**↓** | Extend the selection to the last cell of the current column** | ✓ | ✓ |
| **Ctrl**+**Shift**+**←** | ⌘+⇧+**←** | Extend the selection to the leftmost cell of the current row** | ✓ | ✓ |
| **Ctrl**+**Shift**+**→** | ⌘+⇧+**→** | Extend the selection to the rightmost cell of the current row** | ✓ | ✓ |
| **Shift** + Arrow keys | ⇧ + Arrow keys | Extend the selection by one cell | ✓ | ✓ |
| **Shift**+**Home** | ⇧+**Home** | Extend the selection to the first non-frozen cell of the current row* | ✓ | ✗ |
| **Shift**+**End** | ⇧+**End** | Extend the selection to the last non-frozen cell of the current row* | ✗ | ✗ |
| **Shift**+**Page Up** | ⇧+**Page Up** | Extend the selection by one screen up | ✓ | ✓ |
| **Shift**+**Page Down** | ⇧+**Page Down** | Extend the selection by one screen down | ✓ | ✓ |
| **Ctrl**+**Enter** | ⌘+**Enter** | Fill the selected range of cells with the value of the active cell | ✗ | ✓ |
| **Delete** | **Delete** | Clear the contents of the selected cells | ✓ | ✓ |
| **Backspace** | **Backspace** | Clear the contents of the selected cells | ✓ | ✓ |
* This action depends on your [layout direction](@/guides/internationalization/layout-direction/layout-direction.md).** In case of multiple selection layers, only the last selection layer gets extended. ## Related API reference **Configuration options**
- [autoWrapCol](@/api/options.md#autowrapcol)
- [autoWrapRow](@/api/options.md#autowraprow)
- [fragmentSelection](@/api/options.md#fragmentselection)
- [disableVisualSelection](@/api/options.md#disablevisualselection)
- [dragToScroll](@/api/options.md#dragtoscroll)
- [moveCells](@/api/options.md#movecells)
- [selectionHandles](@/api/options.md#selectionhandles)
- [selectionMode](@/api/options.md#selectionmode)
- [outsideClickDeselects](@/api/options.md#outsideclickdeselects)
**Core methods**
- [deselectCell()](@/api/core.md#deselectcell)
- [getSelected()](@/api/core.md#getselected)
- [getSelectedLast()](@/api/core.md#getselectedlast)
- [getSelectedRange()](@/api/core.md#getselectedrange)
- [getSelectedRangeLast()](@/api/core.md#getselectedrangelast)
- [selectAll()](@/api/core.md#selectall)
- [selectCell()](@/api/core.md#selectcell)
- [selectCells()](@/api/core.md#selectcells)
- [selectColumns()](@/api/core.md#selectcolumns)
- [selectRows()](@/api/core.md#selectrows)
**Hooks**
- [afterMoveCells](@/api/hooks.md#aftermovecells)
- [afterDeselect](@/api/hooks.md#afterdeselect)
- [afterDrawSelection](@/api/hooks.md#afterdrawselection)
- [afterModifyTransformEnd](@/api/hooks.md#aftermodifytransformend)
- [afterModifyTransformStart](@/api/hooks.md#aftermodifytransformstart)
- [afterSelection](@/api/hooks.md#afterselection)
- [afterSelectionByProp](@/api/hooks.md#afterselectionbyprop)
- [afterSelectionEnd](@/api/hooks.md#afterselectionend)
- [afterSelectionEndByProp](@/api/hooks.md#afterselectionendbyprop)
- [beforeMoveCells](@/api/hooks.md#beforemovecells)
- [afterOnSelectionHandleMouseDown](@/api/hooks.md#afteronselectionhandlemousedown)
- [modifyTransformStart](@/api/hooks.md#modifytransformstart)
**Plugins**
- [DragToScroll](@/api/dragToScroll.md)
Microsoft and Excel are registered trademarks of Microsoft Corporation. Google Sheets is a trademark of Google LLC.
---
# Move cells
URL: https://handsontable.com/docs/javascript-data-grid/move-cells/
Added in Handsontable 18.1.0.
Move or copy a selected range of cells by dragging its border, the same way you would in a spreadsheet application.
[[toc]]
## Overview
When you set [`moveCells`](@/api/options.md#movecells) to `true`, hovering the border of a selected cell range shows a grab cursor. Dragging that border moves the block's data -- cell values and formatting -- to the new location. Hold **Ctrl** (Windows) or ⌘ (Mac) during the drag to copy instead of move. Press **Escape** to cancel a drag before releasing.
The `moveCells` option was introduced in Handsontable 18.1.0. To move whole rows or columns instead of a cell range, see the [Row moving](@/guides/rows/row-moving/row-moving.md) and [Column moving](@/guides/columns/column-moving/column-moving.md) guides.
## Enable cell moving
To enable drag-to-move, set the [`moveCells`](@/api/options.md#movecells) option to `true`:
```javascript
moveCells: true,
```
This option applies at the grid level and defaults to `false`.
Select a range of cells in the demo below, then drag its border to a new location. Hold **Ctrl** or ⌘ to copy the range instead of moving it.
::: only-for javascript
::: example #example1 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/move-cells/javascript/example1.html)
@[code](@/content/guides/cell-features/move-cells/javascript/example1.js)
@[code](@/content/guides/cell-features/move-cells/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/move-cells/react/example1.jsx)
@[code](@/content/guides/cell-features/move-cells/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/move-cells/angular/example1.ts)
@[code](@/content/guides/cell-features/move-cells/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-features/move-cells/vue/example1.vue)
:::
:::
## Moving cells with formulas
When the [`formulas`](@/api/options.md#formulas) plugin is active, formula references adjust automatically on move -- the same way they do in Excel.
## Limitations
- Drag-to-move works on a single contiguous cell range only. It has no effect on full-row, full-column, select-all, or multiple selections.
- The target must stay within the grid. Neither the target nor the source may overlap read-only cells, because a move has to clear the source. Copying with **Ctrl** or ⌘ leaves the source in place, so a read-only source cell blocks a move but not a copy.
- Drag-to-move is hidden when [`disableVisualSelection`](@/api/options.md#disablevisualselection) is set.
- A move that would split a merged cell is blocked.
## Hooks
- [`beforeMoveCells`](@/api/hooks.md#beforemovecells) fires before the data relocates. Return `false` from the handler to cancel the move.
- [`afterMoveCells`](@/api/hooks.md#aftermovecells) fires after the data has been relocated.
## Move cells programmatically
To move or copy a range from code, call the plugin's `moveCellRange()` method:
```javascript
hot.getPlugin('moveCells').moveCellRange(sourceRange, targetTopLeft, isCopy);
```
## Related articles
**Related guides**
- [Selection](@/guides/cell-features/selection/selection.md)
- [Row moving](@/guides/rows/row-moving/row-moving.md)
- [Column moving](@/guides/columns/column-moving/column-moving.md)
**Configuration options**
- [moveCells](@/api/options.md#movecells)
- [disableVisualSelection](@/api/options.md#disablevisualselection)
**Hooks**
- [afterMoveCells](@/api/hooks.md#aftermovecells)
- [beforeMoveCells](@/api/hooks.md#beforemovecells)
**Plugins**
- [MoveCells](@/api/moveCells.md)
Microsoft and Excel are registered trademarks of Microsoft Corporation.
---
# Merge cells
URL: https://handsontable.com/docs/javascript-data-grid/merge-cells/
Merge adjacent cells, using the **Ctrl**+**M** shortcut or the context menu. Control merged cells, using Handsontable's API.
[[toc]]
## Overview
By merging, you can combine two or more adjacent cells into a single cell that spans several rows or columns.
Handsontable merges cells in the same way as Microsoft Excel: keeps only the upper-left value of the selected range and clears other values. This clearing happens in the underlying data, not just on screen -- see [Effect on the underlying data](#effect-on-the-underlying-data).
## How to merge cells
To enable the merge cells feature, set the [`mergeCells`](@/api/options.md#mergecells) option to `true` or to an array.
To initialize Handsontable with predefined merged cells, provide merged cells details in form of an array:
The `row` and `col` properties use visual indexes. They refer to positions as displayed in the grid, in the same coordinate space as `selectCell()` and `getCellMeta()`.
::: only-for javascript
```js
mergeCells: [
{ row: 1, col: 1, rowspan: 3, colspan: 3 },
{ row: 3, col: 4, rowspan: 2, colspan: 2 },
{ row: 5, col: 6, rowspan: 3, colspan: 3 },
]
```
:::
::: only-for react
```jsx
mergeCells={[
{ row: 1, col: 1, rowspan: 3, colspan: 3 },
{ row: 3, col: 4, rowspan: 2, colspan: 2 },
{ row: 5, col: 6, rowspan: 3, colspan: 3 },
]}
```
:::
::: only-for angular
```ts
settings = {
mergeCells: [
{ row: 1, col: 1, rowspan: 3, colspan: 3 },
{ row: 3, col: 4, rowspan: 2, colspan: 2 },
{ row: 5, col: 6, rowspan: 3, colspan: 3 },
],
};
```
:::
::: only-for vue
```js
const hotSettings = {
mergeCells: [
{ row: 1, col: 1, rowspan: 3, colspan: 3 },
{ row: 3, col: 4, rowspan: 2, colspan: 2 },
{ row: 5, col: 6, rowspan: 3, colspan: 3 },
],
};
```
:::
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/javascript/example1.js)
@[code](@/content/guides/cell-features/merge-cells/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/react/example1.jsx)
@[code](@/content/guides/cell-features/merge-cells/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/merge-cells/angular/example1.ts)
@[code](@/content/guides/cell-features/merge-cells/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-features/merge-cells/vue/example1.vue)
:::
:::
## Optimizing rendering of the wide/tall merged cells
When cells span thousands of rows or columns, scrolling may feel slower compared to unmerged cells. To improve performance, consider enabling the dedicated virtualization feature for merged cells, which is disabled by default.
To enable the merged cells virtualization mode, enable the `virtualized` option:
::: only-for javascript
```js
mergeCells: {
virtualized: true,
cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }]
}
```
:::
::: only-for react
```jsx
mergeCells={{
virtualized: true,
cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }]
}}
```
:::
::: only-for angular
```ts
settings = {
mergeCells: {
virtualized: true,
cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }],
},
};
```
:::
::: only-for vue
```js
const hotSettings = {
mergeCells: {
virtualized: true,
cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }],
},
};
```
:::
The example below uses virtualized merged cells. It's also recommended to increase the buffer of rendered rows/columns to minimize the flickering effects.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/javascript/example2.js)
@[code](@/content/guides/cell-features/merge-cells/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/react/example2.jsx)
@[code](@/content/guides/cell-features/merge-cells/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/merge-cells/angular/example2.ts)
@[code](@/content/guides/cell-features/merge-cells/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/cell-features/merge-cells/vue/example2.vue)
:::
:::
## React to merge and unmerge events
To run your own logic when cells merge or unmerge, use the [`beforeMergeCells`](@/api/hooks.md#beforemergecells), [`afterMergeCells`](@/api/hooks.md#aftermergecells), [`beforeUnmergeCells`](@/api/hooks.md#beforeunmergecells), and [`afterUnmergeCells`](@/api/hooks.md#afterunmergecells) hooks. Each hook receives the affected `cellRange`, and `afterMergeCells` also receives the resulting `mergeParent` object (`row`, `col`, `rowspan`, `colspan`).
The example below logs a message every time you merge or unmerge cells, using the context menu or the **Ctrl**+**M** shortcut.
::: only-for javascript
::: example #example3 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/merge-cells/javascript/example3.html)
@[code](@/content/guides/cell-features/merge-cells/javascript/example3.js)
@[code](@/content/guides/cell-features/merge-cells/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/react/example3.jsx)
@[code](@/content/guides/cell-features/merge-cells/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/merge-cells/angular/example3.ts)
@[code](@/content/guides/cell-features/merge-cells/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/cell-features/merge-cells/vue/example3.vue)
:::
:::
## Merge and unmerge cells programmatically
To merge or unmerge a range without a user action, call the [`MergeCells`](@/api/mergeCells.md) plugin's `merge()` and `unmerge()` methods. Both methods take a visual `startRow`, `startColumn`, `endRow`, and `endColumn`, the same coordinate space as `selectCell()`.
```js
hot.getPlugin('mergeCells').merge(startRow, startColumn, endRow, endColumn);
hot.getPlugin('mergeCells').unmerge(startRow, startColumn, endRow, endColumn);
```
This clears the underlying data the same way as merging through the UI or the [`mergeCells`](@/api/options.md#mergecells) configuration option. See [Effect on the underlying data](#effect-on-the-underlying-data).
The example below merges and unmerges a footnote row that spans every column, using buttons instead of a manual selection.
::: only-for javascript
::: example #example4 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/merge-cells/javascript/example4.html)
@[code](@/content/guides/cell-features/merge-cells/javascript/example4.js)
@[code](@/content/guides/cell-features/merge-cells/javascript/example4.ts)
:::
:::
::: only-for react
::: example #example4 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/merge-cells/react/example4.jsx)
@[code](@/content/guides/cell-features/merge-cells/react/example4.tsx)
:::
:::
::: only-for angular
::: example #example4 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/merge-cells/angular/example4.ts)
@[code](@/content/guides/cell-features/merge-cells/angular/example4.html)
:::
:::
::: only-for vue
::: example #example4 :vue3
@[code](@/content/guides/cell-features/merge-cells/vue/example4.vue)
:::
:::
## Effect on the underlying data
Merging doesn't only hide the covered cells visually -- it clears their values in the underlying data too, whether you merge through the UI, the [`mergeCells`](@/api/options.md#mergecells) configuration option, or the `merge()` method. Only the top-left cell of the range keeps its value; every other cell covered by the merge is set to `null`.
For a range merged at `(0, 0)` with `rowspan: 2` and `colspan: 2`:
```js
hot.getData();
// -> [['Top-left value', null], [null, null]]
hot.getSourceData();
// -> [['Top-left value', null], [null, null]] (the same)
```
Both [`getData()`](@/api/core.md#getdata) and [`getSourceData()`](@/api/core.md#getsourcedata) return `null` for the covered cells, because the clearing runs through the normal change pipeline: it fires [`beforeChange`](@/api/hooks.md#beforechange) and [`afterChange`](@/api/hooks.md#afterchange) with `source === 'MergeCells'` (see [Events and hooks: Definition for `source` argument](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument)).
Unmerging does not restore the cleared values. If you need the original values back, keep a copy before merging, or restore them yourself in a [`beforeUnmergeCells`](@/api/hooks.md#beforeunmergecells) or [`afterUnmergeCells`](@/api/hooks.md#afterunmergecells) handler.
## Effect on viewport getter methods
With merged cells, the rendered range extends to fit any merged cell that crosses the viewport edge. This is the same expansion that the `virtualized` option turns off. As a result, the rendered-range getters can return indexes beyond what you see on the screen:
- [`getFirstRenderedVisibleRow()`](@/api/core.md#getfirstrenderedvisiblerow), [`getLastRenderedVisibleRow()`](@/api/core.md#getlastrenderedvisiblerow), [`getFirstRenderedVisibleColumn()`](@/api/core.md#getfirstrenderedvisiblecolumn), and [`getLastRenderedVisibleColumn()`](@/api/core.md#getlastrenderedvisiblecolumn).
- [`AutoRowSize.getFirstVisibleRow()`](@/api/autoRowSize.md#getfirstvisiblerow) and [`AutoRowSize.getLastVisibleRow()`](@/api/autoRowSize.md#getlastvisiblerow), which delegate to the rendered-row getters.
- [`AutoColumnSize.getFirstVisibleColumn()`](@/api/autoColumnSize.md#getfirstvisiblecolumn) and [`AutoColumnSize.getLastVisibleColumn()`](@/api/autoColumnSize.md#getlastvisiblecolumn), which delegate to the rendered-column getters.
For example, a merged cell that spans columns 0 to 100 makes `getLastVisibleColumn()` return an index near 100, even when the viewport shows far fewer columns.
To read the actual visible viewport, use the fully-visible or partially-visible getters, which ignore the merge-cell expansion:
- [`getFirstFullyVisibleRow()`](@/api/core.md#getfirstfullyvisiblerow), [`getLastFullyVisibleRow()`](@/api/core.md#getlastfullyvisiblerow), [`getFirstFullyVisibleColumn()`](@/api/core.md#getfirstfullyvisiblecolumn), and [`getLastFullyVisibleColumn()`](@/api/core.md#getlastfullyvisiblecolumn).
- [`getFirstPartiallyVisibleRow()`](@/api/core.md#getfirstpartiallyvisiblerow), [`getLastPartiallyVisibleRow()`](@/api/core.md#getlastpartiallyvisiblerow), [`getFirstPartiallyVisibleColumn()`](@/api/core.md#getfirstpartiallyvisiblecolumn), and [`getLastPartiallyVisibleColumn()`](@/api/core.md#getlastpartiallyvisiblecolumn).
Setting `virtualized` to `true` also removes the range expansion, but it is a performance option -- the rendered-range getters still include buffered rows and columns outside the viewport.
## Behavior during row/column reorder and column freeze
When a merged cell's underlying rows or columns are reordered (through [`manualColumnMove`](@/api/options.md#manualcolumnmove), [`manualRowMove`](@/api/options.md#manualrowmove), or [`manualColumnFreeze`](@/api/options.md#manualcolumnfreeze)), Handsontable follows the merge to the new visual position. Two side effects can occur:
- **Auto-split**: if the move bisects a merge so the underlying cells are no longer contiguous in the new visual order, the merge is split into separate merges, one per contiguous run. The cross-axis span (`rowspan` for column moves, `colspan` for row moves) is preserved on every fragment.
- **Silent drop of single-cell fragments**: any resulting fragment that ends up as a single cell (`rowspan === 1 && colspan === 1`) is removed, because a single cell is no longer a merge. The [`afterMergeCells`](@/api/hooks.md#aftermergecells) hook is not fired for the dropped fragment.
[`undo`](@/api/options.md#undo) and [`redo`](@/api/options.md#redo) restore the pre-move state, including any merges that were split or dropped by the reorder.
## Result
Cells at the configured positions are now merged. Users see a single cell spanning multiple rows or columns.
## Related keyboard shortcuts
| Windows | macOS | Action | Excel | Sheets |
| -------------------------------------- | -------------------------------------- | ----------------------------------- | :-----: | :-----: |
| **Ctrl**+**M** | ⌃+**M** | Merge or unmerge the selected cells | ✗ | ✗ |
## Related API reference
**Configuration options**
- [mergeCells](@/api/options.md#mergecells)
- [viewportColumnRenderingThreshold](@/api/options.md#viewportcolumnrenderingthreshold)
- [viewportRowRenderingThreshold](@/api/options.md#viewportrowrenderingthreshold)
- [viewportColumnRenderingOffset](@/api/options.md#viewportcolumnrenderingoffset)
- [viewportRowRenderingOffset](@/api/options.md#viewportrowrenderingoffset)
**Hooks**
- [afterMergeCells](@/api/hooks.md#aftermergecells)
- [afterUnmergeCells](@/api/hooks.md#afterunmergecells)
- [beforeMergeCells](@/api/hooks.md#beforemergecells)
- [beforeUnmergeCells](@/api/hooks.md#beforeunmergecells)
**Plugins**
- [MergeCells](@/api/mergeCells.md)
---
# Conditional formatting
URL: https://handsontable.com/docs/javascript-data-grid/conditional-formatting/
Style cells dynamically based on their values, so you can highlight outliers, flag errors, or visualize data ranges.
[[toc]]
## Overview
Conditional formatting changes a cell's appearance based on the data it holds. As values change, the formatting updates on the next render.
Choose an approach based on your goal:
- Use [`className`](@/api/options.md#classname) with the [`cells`](@/api/options.md#cells) callback when you want reusable CSS classes driven by cell values. This is the recommended default.
- Use the [`renderer`](@/api/options.md#renderer) option when you need inline styles or want to transform the displayed value.
- Combine a `renderer` with a computed background color when you want a color scale that reflects each value's magnitude.
For static styling that does not depend on cell values, see [Formatting cells](@/guides/cell-features/formatting-cells/formatting-cells.md).
## Prerequisites
- A Handsontable instance with data loaded.
- A stylesheet, if you format cells through custom CSS classes.
- Familiarity with the cascading configuration model, where cell settings override column settings, which override global settings. See [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md).
## Highlight cells by value with a CSS class
Return a [`className`](@/api/options.md#classname) from the [`cells`](@/api/options.md#cells) callback to style cells by value. The callback runs for every cell, so you can inspect the value and assign a class conditionally.
This example uses the cascading model on two levels: the Company column sets a static `className` through its `columns` entry, while the [`cells`](@/api/options.md#cells) callback adds a `loss` class to negative quarters and a `strong-quarter` class to quarters above 10. The `loss` class pairs its red color with a leading marker, so the value stays readable without color.
::: only-for javascript
::: example #example1 --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example1.css)
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example1.js)
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/conditional-formatting/react/example1.css)
@[code](@/content/guides/cell-features/conditional-formatting/react/example1.jsx)
@[code](@/content/guides/cell-features/conditional-formatting/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/conditional-formatting/angular/example1.ts)
@[code](@/content/guides/cell-features/conditional-formatting/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-features/conditional-formatting/vue/example1.vue)
:::
:::
## Format cells with a custom renderer
Use a [`renderer`](@/api/options.md#renderer) when a CSS class is not enough - for example, when you need to transform the displayed value or apply inline styles computed at render time.
This renderer formats each quarter as a currency amount and shows losses in an accounting format, `($1.3M)`. The parentheses convey a loss on their own, so the red color is a secondary signal.
::: only-for javascript
::: example #example2 --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example2.css)
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example2.js)
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --css 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/conditional-formatting/react/example2.css)
@[code](@/content/guides/cell-features/conditional-formatting/react/example2.jsx)
@[code](@/content/guides/cell-features/conditional-formatting/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/conditional-formatting/angular/example2.ts)
@[code](@/content/guides/cell-features/conditional-formatting/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/cell-features/conditional-formatting/vue/example2.vue)
:::
:::
## Build a color scale
To visualize magnitude, compute a background color from each value and apply it in a [`renderer`](@/api/options.md#renderer). This example maps every quarter to a green-to-red scale based on the minimum and maximum across the data, producing a heatmap. The numeric value remains visible in each cell, so the color adds meaning rather than replacing it.
::: only-for javascript
::: example #example3 --js 1 --ts 2
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example3.js)
@[code](@/content/guides/cell-features/conditional-formatting/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/conditional-formatting/react/example3.jsx)
@[code](@/content/guides/cell-features/conditional-formatting/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/conditional-formatting/angular/example3.ts)
@[code](@/content/guides/cell-features/conditional-formatting/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/cell-features/conditional-formatting/vue/example3.vue)
:::
:::
## Make conditional formatting accessible
Color alone does not satisfy [WCAG 2.2 Success Criterion 1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/quickref/#use-of-color), a Level A criterion. Readers with color vision deficiencies, or anyone viewing the grid in high-contrast mode, can miss a signal that relies only on color.
- Pair color with a second cue: a symbol, text label, or font weight. In the first example, the `loss` class adds a marker; in the second, losses appear in parentheses.
- In a color scale, keep the underlying value visible so the color stays supplementary.
- Verify that text keeps a contrast ratio of at least 4.5:1 against the cell background you apply.
## Result
Cells that match your conditions display the configured styles - classes, inline styles, or a color scale - and update automatically as the data changes.
## Related articles
**Related guides**
- [Formatting cells](@/guides/cell-features/formatting-cells/formatting-cells.md)
- [Text alignment](@/guides/cell-features/text-alignment/text-alignment.md)
- [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md)
**Configuration options**
- [className](@/api/options.md#classname)
- [cells](@/api/options.md#cells)
- [renderer](@/api/options.md#renderer)
---
# Text alignment
URL: https://handsontable.com/docs/javascript-data-grid/text-alignment/
Align values within cells: horizontally (to the right, left, center, or by justifying them), and vertically (to the top, middle, or bottom of the cell).
[[toc]]
Apply text alignment to cells using CSS class names or the `className` configuration option.
## Overview
You can set cell alignment in two ways:
| Configuration option`className`/`cells` | Context menu
`alignment` item | |---|---| | Set programmatically, for the whole grid, a column, or individual cells | Set interactively, by the person using the grid | | Requires no additional plugin | Requires the [`ContextMenu`](@/guides/accessories-and-menus/context-menu/context-menu.md) plugin, with the `alignment` item enabled | | Not tracked by [`UndoRedo`](@/guides/accessories-and-menus/undo-redo/undo-redo.md) | Tracked by [`UndoRedo`](@/guides/accessories-and-menus/undo-redo/undo-redo.md) | ## To align a cell To set alignment for individual cells, configure them using the [`cells`](@/api/options.md#cells) option or the [`cell`](@/api/options.md#cell) array. Available class names: - Horizontal: `htLeft`, `htCenter`, `htRight`, `htJustify` - Vertical: `htTop`, `htMiddle`, `htBottom` You can track alignment changes by using the [`afterSetCellMeta`](@/api/hooks.md#aftersetcellmeta) hook. ## To align a column To apply alignment globally or per column, provide the alignment details in the [`className`](@/api/options.md#classname) option, for example: ::: only-for javascript ```js className: 'htCenter' ``` ::: ::: only-for react ```jsx className="htCenter" ``` ::: ::: only-for angular ```ts settings = { className: "htCenter" }; ``` ::: ::: only-for vue ```js const hotSettings = { className: 'htCenter', }; ``` ::: ## Align cells using the context menu Let the person using the grid set alignment interactively, through the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md). Enable the `ContextMenu` plugin and include the `alignment` item: ```js contextMenu: ['alignment'], ``` Select one or more cells, right-click to open the context menu, and choose an option from the **Align** submenu: - Horizontal: **Left**, **Center**, **Right**, **Justify** - Vertical: **Top**, **Middle**, **Bottom** Each option sets the matching CSS class name (`htLeft`, `htCenter`, `htRight`, `htJustify`, `htTop`, `htMiddle`, `htBottom`) on the selected cells, and fires the [`beforeCellAlignment`](@/api/hooks.md#beforecellalignment) hook before applying the change. ### Undo and redo alignment changes Alignment changes made through the context menu are tracked by the [`UndoRedo`](@/guides/accessories-and-menus/undo-redo/undo-redo.md) plugin. Press **Ctrl**/⌘+**Z** to undo an alignment change, and **Ctrl**/⌘+**Y** to redo it. Alignment changes made through the `className` or `cells` configuration options aren't tracked by `UndoRedo`. ## Basic example The following code sample configures the grid to use `htCenter` and configures individual cells to use different alignments. ::: only-for javascript ::: example #example1 --js 1 --ts 2 @[code](@/content/guides/cell-features/text-alignment/javascript/example1.js) @[code](@/content/guides/cell-features/text-alignment/javascript/example1.ts) ::: ::: ::: only-for react ::: example #example1 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/text-alignment/react/example1.jsx) @[code](@/content/guides/cell-features/text-alignment/react/example1.tsx) ::: ::: ::: only-for angular ::: example #example1 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/text-alignment/angular/example1.ts) @[code](@/content/guides/cell-features/text-alignment/angular/example1.html) ::: ::: ::: only-for vue ::: example #example1 :vue3 @[code](@/content/guides/cell-features/text-alignment/vue/example1.vue) ::: ::: ## Result Cells display the configured horizontal or vertical alignment. Global settings apply to all cells, and per-cell settings take precedence over the global defaults. ## Related API reference **Configuration options**
- [className](@/api/options.md#classname)
- [contextMenu](@/api/options.md#contextmenu)
**Hooks**
- [afterSetCellMeta](@/api/hooks.md#aftersetcellmeta)
- [beforeCellAlignment](@/api/hooks.md#beforecellalignment)
**Plugins**
- [ContextMenu](@/api/contextMenu.md)
- [UndoRedo](@/api/undoRedo.md)
---
# Read-only cells
URL: https://handsontable.com/docs/javascript-data-grid/read-only-cells/
Make specified cells read-only to protect them from unwanted changes but still allow navigation and copying of data.
[[toc]]
Disable individual cells, entire columns, or entire rows to prevent user edits. Use `readOnly` on cells, columns, or the whole grid.
## Overview
Disabling a cell makes the cell read-only or non-editable. Both have similar outcomes, with the following differences:
| Read-only cell`readOnly: true` | Non-editable cell
`editor: false` | |------------------------------------------------------------------------------| -------------------------------------------------------------------------- | | Has an additional CSS class (`htDimmed`) | Has no additional CSS class | | Copy works, paste doesn't work | Copy-paste works | | Drag-to-fill doesn't work | Drag-to-fill works | | Can't be changed by [`populateFromArray()`](@/api/core.md#populatefromarray) | Can be changed by [`populateFromArray()`](@/api/core.md#populatefromarray) | ## Make the grid read-only To make the entire grid read-only, set [`readOnly`](@/api/options.md#readonly) to `true` as a [top-level grid option](@/guides/getting-started/configuration-options/configuration-options.md#set-grid-options). ::: only-for javascript ::: example #exampleReadOnlyGrid --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/exampleReadOnlyGrid.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/exampleReadOnlyGrid.ts) ::: ::: ::: only-for react ::: example #exampleReadOnlyGrid :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/exampleReadOnlyGrid.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/exampleReadOnlyGrid.tsx) ::: ::: ::: only-for angular ::: example #exampleReadOnlyGrid :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/exampleReadOnlyGrid.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/exampleReadOnlyGrid.html) ::: ::: ::: only-for vue ::: example #exampleReadOnlyGrid :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/exampleReadOnlyGrid.vue) ::: ::: ## Make a column read-only To make a column read-only, declare it in the [`columns`](@/api/options.md#columns) configuration option. The column remains available for keyboard navigation and copying data (**Ctrl**/**Cmd**+**C**), but editing and pasting are disabled. The example below also defines a custom renderer that dims the read-only column, giving the user a visual cue that its cells are read-only. ::: only-for javascript ::: example #example1 --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/example1.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/example1.ts) ::: ::: ::: only-for react ::: example #example1 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/example1.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/example1.tsx) ::: ::: ::: only-for angular ::: example #example1 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/example1.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/example1.html) ::: ::: ::: only-for vue ::: example #example1 :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/example1.vue) ::: ::: ## Make a row read-only To make an entire row read-only, use the [`cells`](@/api/options.md#cells) function and set the [`readOnly`](@/api/options.md#readonly) property based on the row index, regardless of the column. The example below makes the second row (index `1`) read-only. ::: only-for javascript ::: example #example5 --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/example5.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/example5.ts) ::: ::: ::: only-for react ::: example #example5 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/example5.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/example5.tsx) ::: ::: ::: only-for angular ::: example #example5 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/example5.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/example5.html) ::: ::: ::: only-for vue ::: example #example5 :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/example5.vue) ::: ::: ## Make specific cells read-only To make specific cells read-only, use the [`cells`](@/api/options.md#cells) function to set the [`readOnly`](@/api/options.md#readonly) property conditionally. The example below makes cells that contain the word "Nissan" read-only. ::: only-for javascript ::: example #example2 --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/example2.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/example2.ts) ::: ::: ::: only-for react ::: example #example2 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/example2.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/example2.tsx) ::: ::: ::: only-for angular ::: example #example2 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/example2.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/example2.html) ::: ::: ::: only-for vue ::: example #example2 :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/example2.vue) ::: ::: Non-editable cells behave like any other cells apart from preventing you from manually changing their values. ## Make a column non-editable To make a column non-editable, declare it in the [`columns`](@/api/options.md#columns) configuration option. The column's basic behavior does not change -- you can still use keyboard navigation, **Ctrl**/**Cmd**+**C**, **Ctrl**/**Cmd**+**V**, and drag-to-fill. The example below also defines a custom renderer that dims the non-editable column, giving the user a visual cue that its cells are non-editable. ::: only-for javascript ::: example #example3 --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/example3.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/example3.ts) ::: ::: ::: only-for react ::: example #example3 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/example3.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/example3.tsx) ::: ::: ::: only-for angular ::: example #example3 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/example3.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/example3.html) ::: ::: ::: only-for vue ::: example #example3 :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/example3.vue) ::: ::: ## Make specific cells non-editable To make specific cells non-editable, set `editor: false` in the cell configuration. The following example shows a table with non-editable cells containing the word "Nissan". ::: only-for javascript ::: example #example4 --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/javascript/example4.js) @[code](@/content/guides/cell-features/read-only-cells/javascript/example4.ts) ::: ::: ::: only-for react ::: example #example4 :react --js 1 --ts 2 @[code](@/content/guides/cell-features/read-only-cells/react/example4.jsx) @[code](@/content/guides/cell-features/read-only-cells/react/example4.tsx) ::: ::: ::: only-for angular ::: example #example4 :angular --ts 1 --html 2 @[code](@/content/guides/cell-features/read-only-cells/angular/example4.ts) @[code](@/content/guides/cell-features/read-only-cells/angular/example4.html) ::: ::: ::: only-for vue ::: example #example4 :vue3 @[code](@/content/guides/cell-features/read-only-cells/vue/example4.vue) ::: ::: ## Block the entire grid The [`readOnly`](@/api/options.md#readonly) and [`editor`](@/api/options.md#editor) options control editing, but users can still navigate and select cells. To block all interaction with the grid temporarily -- for example, during a loading state or a blocking workflow step -- use the [Dialog](@/guides/dialog/dialog/dialog.md) plugin. An open dialog overlays the grid and moves keyboard input into its own [focus scope](@/guides/navigation/focus-scopes/focus-scopes.md), so users can't reach the cells until the dialog closes. The grid regains focus automatically. ## Accessibility When [`ariaTags`](@/api/options.md#ariatags) is enabled (the default), Handsontable adds `aria-readonly="true"` to the DOM element of every read-only cell, so screen readers announce that the cell can't be edited. Non-editable cells (`editor: false`) don't get this attribute, because Handsontable doesn't treat them as read-only in the data model -- only their editor is disabled. For more accessibility features and testing guidance, see [Accessibility](@/guides/accessibility/accessibility/accessibility.md). ## Result Read-only cells display with the `htDimmed` CSS class and block paste and drag-to-fill operations. Non-editable cells block manual editing but allow copy-paste and drag-to-fill. ## Related API reference **Configuration options**
- [ariaTags](@/api/options.md#ariatags)
- [readOnly](@/api/options.md#readonly)
- [readOnlyCellClassName](@/api/options.md#readonlycellclassname)
---
# Comments
URL: https://handsontable.com/docs/javascript-data-grid/comments/
Add a comment (a note) to a cell, using the context menu, just like in Excel. Edit and delete comments. Make comments read-only.
[[toc]]
The Comments plugin lets users attach text notes to individual cells. Use it when reviewers need to annotate data without changing cell values.
The plugin shows and edits a comment in a text field, so it doesn't parse the comment as HTML. If you use the comment text elsewhere, for example in your own interface, escape or sanitize it first.
## Enable the plugin
Set the [`comments`](@/api/options.md#comments) configuration option to `true` to enable the feature and add all the needed context menu items. For example:
::: only-for javascript
```js
const hot = new Handsontable(container, {
data: [
['Update API docs', 'Ana García', 'In progress'],
['Deploy hotfix', 'James Okafor', 'Blocked'],
],
comments: true,
autoWrapRow: true,
autoWrapCol: true
});
```
:::
::: only-for react
```jsx
- [commentedCellClassName](@/api/options.md#commentedcellclassname)
- [comments](@/api/options.md#comments)
**Hooks**
- [afterRemoveCellMeta](@/api/hooks.md#afterremovecellmeta)
- [afterSetCellMeta](@/api/hooks.md#aftersetcellmeta)
- [beforeRemoveCellMeta](@/api/hooks.md#beforeremovecellmeta)
- [beforeSetCellMeta](@/api/hooks.md#beforesetcellmeta)
**Plugins**
- [Comments](@/api/comments.md)
---
# Autofill values
URL: https://handsontable.com/docs/javascript-data-grid/autofill-values/
Copy a cell's value into multiple other cells, using the "fill handle" UI element. Configure the direction of copying, and more, through Handsontable's API.
[[toc]]
Autofill lets users drag the fill handle to copy or extend values across adjacent cells. Use it to speed up repetitive data entry.
## Autofill in all directions
Using the tiny square known as the 'fill handle' in the corner of the selected cell, you can drag it to repeat or extend values across adjacent cells.
You can also **double-click the fill handle** to autofill downward without dragging. Select the four cells from Symbol to Known Isotopes in the `Lithium` row (row header 3) and double-click the fill handle to see this in action.
### How double-click autofill determines the range
Handsontable scans the rows below your selection and fills down to the last row where the column immediately to the left or right of your selection contains a value. In the example below, the Name column acts as the guide -- the rows with row headers 4 and 5 have values there, so the fill extends through both rows.
Two conditions must be met for the fill to happen:
- **All cells below the selection in the filled column(s) must be empty.** If any cell below the selection in those columns contains data, double-clicking does nothing.
- At least one column adjacent to your selection must have data in the rows below.
**Visual difference from drag-fill:** When you drag the fill handle, a preview border shows the target range as you drag. When you double-click, no drag-preview appears -- the cells populate immediately based on the adjacent column data.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/cell-features/autofill-values/javascript/example1.js)
@[code](@/content/guides/cell-features/autofill-values/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/autofill-values/react/example1.jsx)
@[code](@/content/guides/cell-features/autofill-values/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/autofill-values/angular/example1.ts)
@[code](@/content/guides/cell-features/autofill-values/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-features/autofill-values/vue/example1.vue)
:::
:::
## Autofill in a vertical direction only and creating new rows
In this configuration, the fill handle is restricted to move only vertically. New rows are automatically added to the bottom of the table by changing [`autoInsertRow`](@/api/options.md#fillhandle) to `true`.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/cell-features/autofill-values/javascript/example2.js)
@[code](@/content/guides/cell-features/autofill-values/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/autofill-values/react/example2.jsx)
@[code](@/content/guides/cell-features/autofill-values/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/autofill-values/angular/example2.ts)
@[code](@/content/guides/cell-features/autofill-values/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/cell-features/autofill-values/vue/example2.vue)
:::
:::
## Altering and tracking autofilled values
Use the [`beforeAutofill`](@/api/hooks.md#beforeautofill) hook to change the values Handsontable is about to fill in, and the [`afterAutofill`](@/api/hooks.md#afterautofill) hook to react once the fill completes.
In the example below, select the four cells from Symbol to Known Isotopes in the `Lithium` row and drag the fill handle down through the rows with row headers 4 and 5. The `afterAutofill` hook logs the affected range and direction to the output box below the grid. The logged row and column numbers are 0-based indices, so the two filled rows appear as `3-4`, not `4-5`.
The `beforeAutofill` hook in this example rounds every filled number up to the nearest multiple of 5. This is a demonstration of what the hook can do, not the default autofill result: without the hook, Handsontable repeats the selected values as they are.
When Handsontable fires [`beforeChange`](@/api/hooks.md#beforechange) or [`afterChange`](@/api/hooks.md#afterchange) as part of an autofill operation, their `source` argument is `Autofill.fill`. Read more about the `source` argument in [Events and hooks: Definition for `source` argument](@/guides/getting-started/events-and-hooks/events-and-hooks.md#definition-for-source-argument).
::: only-for javascript
::: example #example3 --html 1 --js 2 --ts 3
@[code](@/content/guides/cell-features/autofill-values/javascript/example3.html)
@[code](@/content/guides/cell-features/autofill-values/javascript/example3.js)
@[code](@/content/guides/cell-features/autofill-values/javascript/example3.ts)
:::
:::
::: only-for react
::: example #example3 :react --js 1 --ts 2
@[code](@/content/guides/cell-features/autofill-values/react/example3.jsx)
@[code](@/content/guides/cell-features/autofill-values/react/example3.tsx)
:::
:::
::: only-for angular
::: example #example3 :angular --ts 1 --html 2
@[code](@/content/guides/cell-features/autofill-values/angular/example3.ts)
@[code](@/content/guides/cell-features/autofill-values/angular/example3.html)
:::
:::
::: only-for vue
::: example #example3 :vue3
@[code](@/content/guides/cell-features/autofill-values/vue/example3.vue)
:::
:::
## Autofill and formulas
With the [`Formulas`](@/guides/formulas/formula-calculation/formula-calculation.md) plugin enabled, autofill delegates to the HyperFormula engine instead of copying cell contents literally:
- **Relative references adjust per target cell.** Filling `=A1+B1` down from row 1 to row 2 produces `=A2+B2` in the new cell, the same way a spreadsheet application adjusts formulas on fill.
- **Absolute references stay fixed.** Filling `=$A$1+B1` down keeps `$A$1` unchanged in every filled cell, while the relative `B1` part still adjusts.
- **The fill is cancelled** if the engine reports that the target cells can't be written to (for example, because they're part of another formula's dependency chain), leaving the target range unchanged.
## Result
The fill handle appears on the selected cell. Dragging it copies or extends values into adjacent cells in the configured direction.
## Related API reference
**Configuration options**
- [fillHandle](@/api/options.md#fillhandle)
**Hooks**
- [afterAutofill](@/api/hooks.md#afterautofill)
- [beforeAutofill](@/api/hooks.md#beforeautofill)
- [modifyAutofillRange](@/api/hooks.md#modifyautofillrange)
**Plugins**
- [Autofill](@/api/autofill.md)
---
# Formatting cells
URL: https://handsontable.com/docs/javascript-data-grid/formatting-cells/
Change the appearance of cells, using custom CSS classes, inline styles, or custom cell borders.
[[toc]]
## Overview
Handsontable renders an HTML `table`, so you can style existing `tr` and `td` elements or attach your own classes.
Choose an approach based on your goal:
- Use [`className`](@/api/options.md#classname) when you want reusable static styles.
- Use [`renderer`](@/api/options.md#renderer) when you need to apply inline styles to specific cells at render time.
- Use [`customBorders`](@/api/options.md#customborders) when you need custom border widths, colors, or styles for selected ranges.
## Prerequisites
- A Handsontable instance with data loaded.
- A stylesheet, if you format cells through custom CSS classes.
## Apply custom CSS class styles
In this example, you add a custom class `custom-cell` to the cell in the top-left corner and a `custom-table` CSS class that highlights the table headers.
To add a CSS class to a cell, column, or row, use the [`className`](@/api/options.md#classname) option. Set it in the grid configuration, in a `columns` entry, or per cell through the [`cells`](@/api/options.md#cells) callback. The class you provide is added to the cell's `
- [Conditional formatting](@/guides/cell-features/conditional-formatting/conditional-formatting.md)
**Configuration options**
- [activeHeaderClassName](@/api/options.md#activeheaderclassname)
- [className](@/api/options.md#classname)
- [commentedCellClassName](@/api/options.md#commentedcellclassname)
- [currentColClassName](@/api/options.md#currentcolclassname)
- [currentHeaderClassName](@/api/options.md#currentheaderclassname)
- [currentRowClassName](@/api/options.md#currentrowclassname)
- [customBorders](@/api/options.md#customborders)
- [customBordersProgressive](@/api/options.md#custombordersprogressive)
- [invalidCellClassName](@/api/options.md#invalidcellclassname)
- [noWordWrapClassName](@/api/options.md#nowordwrapclassname)
- [placeholder](@/api/options.md#placeholder)
- [placeholderCellClassName](@/api/options.md#placeholdercellclassname)
- [readOnlyCellClassName](@/api/options.md#readonlycellclassname)
- [tableClassName](@/api/options.md#tableclassname)
**Plugins**
- [CustomBorders](@/api/customBorders.md)
---
# Cell functions
URL: https://handsontable.com/docs/javascript-data-grid/cell-function/
A cell function is one of three components -- renderer, editor, or validator -- that controls how a cell displays, accepts, and validates data.
[[toc]]
## Overview
Every Handsontable cell has three associated functions that handle distinct concerns:
| Function | Role | Implemented as |
| --- | --- | --- |
| [`renderer`](@/guides/cell-functions/cell-renderer/cell-renderer.md) | Controls how a cell looks: DOM structure, CSS classes, HTML content | A plain function |
| [`editor`](@/guides/cell-functions/cell-editor/cell-editor.md) | Controls how a cell is edited: input element, keyboard handling, open/close lifecycle | A class extending `BaseEditor` |
| [`validator`](@/guides/cell-functions/cell-validator/cell-validator.md) | Decides whether a cell value is acceptable | A function or `RegExp` |
The three functions are **independent**. You can mix and match any combination: use the built-in numeric editor with a custom renderer, override just the validator while keeping a built-in type, or write all three from scratch.
### Function signatures
```js
// renderer — called for every visible cell on every render
renderer(hotInstance, td, row, col, prop, value, cellProperties)
// hotInstance – Handsontable instance
// td – HTMLTableCellElement to modify
// row, col – visual row and column indexes
// prop – data property name (string) or column index (number)
// value – current cell value
// cellProperties – merged cell configuration object
// validator — may be synchronous or asynchronous
validator(value, callback)
// value – value to validate
// callback – call with true (valid) or false (invalid)
// RegExp alternative: /pattern/.test(value) must return true
// editor — a class; see the Cell editor guide for the full lifecycle API
class MyEditor extends BaseEditor { ... }
```
`validator` is **optional**. If no validator is defined for a cell, the cell is skipped entirely during validation — afterValidate will not fire for it, and it will not contribute to the validation cycle.
### `allowInvalid`
By default, `allowInvalid: true` — invalid cells are accepted into the data source but marked with the `htInvalid` CSS class. Set `allowInvalid: false` to reject invalid values and keep the editor open until a valid value is entered.
## Cell types bundle all three
A [cell type](@/guides/cell-types/cell-type/cell-type.md) is a preset that assigns a matching `renderer`, `editor`, and `validator` together under a single `type` alias. Using `type: 'numeric'` is shorthand for:
```js
{
renderer: Handsontable.renderers.NumericRenderer,
editor: Handsontable.editors.NumericEditor,
validator: Handsontable.validators.NumericValidator,
}
```
Built-in types: `text`, `numeric`, `checkbox`, `date`, `time`, `dropdown`, `autocomplete`, `password`, `handsontable`.
When you set an explicit `renderer`, `editor`, or `validator` alongside a `type`, the explicit function always takes precedence over the type for that function only:
```js
columns: [{
type: 'numeric', // sets NumericEditor + NumericValidator
renderer: myRenderer, // overrides only NumericRenderer; editor and validator stay numeric
}]
```
**When to use a type vs individual functions:**
- Use `type` when you want the standard, bundled behavior for a data kind (numbers, dates, checkboxes).
- Override a single function from a type when one aspect needs customizing but the rest is fine as-is.
- Set individual `renderer`/`editor`/`validator` directly when no built-in type fits or you need full control.
## Configuration priority
Cell functions resolve using the cascading configuration model. The most specific level wins:
```
cell[row][col] > column > global (root settings)
```
::: only-for javascript
```js
new Handsontable(container, {
type: 'text', // global fallback for all cells
columns: [
{ type: 'numeric' }, // overrides global for all cells in column 0
{ type: 'text' }, // same as global for column 1
],
cell: [
{ row: 0, col: 0, type: 'checkbox' }, // overrides column setting for cell [0, 0] only
],
});
```
:::
::: only-for react
```jsx
- [Cell editor](@/guides/cell-functions/cell-editor/cell-editor.md)
- [Cell renderer](@/guides/cell-functions/cell-renderer/cell-renderer.md)
- [Cell validator](@/guides/cell-functions/cell-validator/cell-validator.md)
- [Cell type](@/guides/cell-types/cell-type/cell-type.md)
**Configuration options**
- Configuration options:
- [`editor`](@/api/options.md#editor)
- [`renderer`](@/api/options.md#renderer)
- [`type`](@/api/options.md#type)
- [`validator`](@/api/options.md#validator)
- [`allowInvalid`](@/api/options.md#allowinvalid)
- [`valueFormatter`](@/api/options.md#valueformatter)
- Core methods:
- [`destroyEditor()`](@/api/core.md#destroyeditor)
- [`getActiveEditor()`](@/api/core.md#getactiveeditor)
- [`getCellEditor()`](@/api/core.md#getcelleditor)
- [`getCellMeta()`](@/api/core.md#getcellmeta)
- [`getCellMetaAtRow()`](@/api/core.md#getcellmetaatrow)
- [`getCellsMeta()`](@/api/core.md#getcellsmeta)
- [`getCellRenderer()`](@/api/core.md#getcellrenderer)
- [`getCellValidator()`](@/api/core.md#getcellvalidator)
- [`setCellMeta()`](@/api/core.md#setcellmeta)
- [`setCellMetaObject()`](@/api/core.md#setcellmetaobject)
- [`removeCellMeta()`](@/api/core.md#removecellmeta)
- Hooks:
- [`afterBeginEditing`](@/api/hooks.md#afterbeginediting)
- [`afterGetCellMeta`](@/api/hooks.md#aftergetcellmeta)
- [`afterGetColumnHeaderRenderers`](@/api/hooks.md#aftergetcolumnheaderrenderers)
- [`afterGetRowHeaderRenderers`](@/api/hooks.md#aftergetrowheaderrenderers)
- [`afterValidate`](@/api/hooks.md#aftervalidate)
- [`afterRenderer`](@/api/hooks.md#afterrenderer)
- [`beforeGetCellMeta`](@/api/hooks.md#beforegetcellmeta)
- [`beforeRenderer`](@/api/hooks.md#beforerenderer)
- [`beforeValidate`](@/api/hooks.md#beforevalidate)
## Related
- [Cell renderer](@/guides/cell-functions/cell-renderer/cell-renderer.md) -- how to control cell display using renderer functions
- [Cell editor](@/guides/cell-functions/cell-editor/cell-editor.md) -- how to control cell editing using editor classes
- [Cell validator](@/guides/cell-functions/cell-validator/cell-validator.md) -- how to enforce data rules using validator functions
---
# Cell renderer
URL: https://handsontable.com/docs/javascript-data-grid/cell-renderer/
A cell renderer is a function that controls how cell content is displayed in the DOM. Override a built-in renderer or write your own to customize the visual output.
[[toc]]
## Use a cell renderer
You can use any of the built-in renderers by specifying their alias name in your column configuration. The example below shows how to use the `numeric` renderer, which formats numeric values according to the cell's formatting options:
::: only-for javascript
```js
const container = document.querySelector("#container");
const hot = new Handsontable(container, {
data: someData,
columns: [
{
renderer: "numeric",
},
],
});
```
:::
::: only-for react
```jsx
- [Autocomplete cell type](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md)
- [Checkbox cell type](@/guides/cell-types/checkbox-cell-type/checkbox-cell-type.md)
- [Date cell type](@/guides/cell-types/date-cell-type/date-cell-type.md)
- [Dropdown cell type](@/guides/cell-types/dropdown-cell-type/dropdown-cell-type.md)
- [Handsontable cell type](@/guides/cell-types/handsontable-cell-type/handsontable-cell-type.md)
- [MultiSelect cell type](@/guides/cell-types/multiselect-cell-type/multiselect-cell-type.md)
- [Numeric cell type](@/guides/cell-types/numeric-cell-type/numeric-cell-type.md)
- [Password cell type](@/guides/cell-types/password-cell-type/password-cell-type.md)
- [Select cell type](@/guides/cell-types/select-cell-type/select-cell-type.md)
- [Text cell type](@/guides/cell-types/text-cell-type/text-cell-type.md)
- [Time cell type](@/guides/cell-types/time-cell-type/time-cell-type.md)
## Related articles
**Related guides**
- [Cell function](@/guides/cell-functions/cell-function/cell-function.md)
- [Cell editor](@/guides/cell-functions/cell-editor/cell-editor.md)
- [Cell renderer](@/guides/cell-functions/cell-renderer/cell-renderer.md)
- [Cell validator](@/guides/cell-functions/cell-validator/cell-validator.md)
**Configuration options**
- [editor](@/api/options.md#editor)
- [renderer](@/api/options.md#renderer)
- [type](@/api/options.md#type)
- [validator](@/api/options.md#validator)
**Core methods**
- [getCellEditor()](@/api/core.md#getcelleditor)
- [getCellMeta()](@/api/core.md#getcellmeta)
- [getCellMetaAtRow()](@/api/core.md#getcellmetaatrow)
- [getCellsMeta()](@/api/core.md#getcellsmeta)
- [getCellRenderer()](@/api/core.md#getcellrenderer)
- [getCellValidator()](@/api/core.md#getcellvalidator)
- [getDataType()](@/api/core.md#getdatatype)
- [setCellMeta()](@/api/core.md#setcellmeta)
- [setCellMetaObject()](@/api/core.md#setcellmetaobject)
- [removeCellMeta()](@/api/core.md#removecellmeta)
**Hooks**
- [afterBeginEditing](@/api/hooks.md#afterbeginediting)
- [afterGetCellMeta](@/api/hooks.md#aftergetcellmeta)
- [afterGetColumnHeaderRenderers](@/api/hooks.md#aftergetcolumnheaderrenderers)
- [afterGetRowHeaderRenderers](@/api/hooks.md#aftergetrowheaderrenderers)
- [afterSetCellMeta](@/api/hooks.md#aftersetcellmeta)
- [afterValidate](@/api/hooks.md#aftervalidate)
- [afterRenderer](@/api/hooks.md#afterrenderer)
- [beforeGetCellMeta](@/api/hooks.md#beforegetcellmeta)
- [beforeRenderer](@/api/hooks.md#beforerenderer)
- [beforeSetCellMeta](@/api/hooks.md#beforesetcellmeta)
- [beforeValidate](@/api/hooks.md#beforevalidate)
---
# Text cell type
URL: https://handsontable.com/docs/javascript-data-grid/text-cell-type/
Use the text cell type, the default cell type in Handsontable, to display and edit plain text values.
[[toc]]
## Overview
The text cell type is the default [cell type](@/guides/cell-types/cell-type/cell-type.md) in Handsontable. It renders a cell's value as plain text and lets you edit it with a standard text input. It has no built-in validator.
Because `text` is the default, you don't need to set `type: 'text'` for it to apply. Set it explicitly when you want to override a different type inherited from a higher configuration level, or when you want the configuration to state the type directly, for example to guard alphanumeric codes or values with leading zeros against being reformatted by another type.
::: only-for javascript
::: example #example1 --js 1 --ts 2
@[code](@/content/guides/cell-types/text-cell-type/javascript/example1.js)
@[code](@/content/guides/cell-types/text-cell-type/javascript/example1.ts)
:::
:::
::: only-for react
::: example #example1 :react --js 1 --ts 2
@[code](@/content/guides/cell-types/text-cell-type/react/example1.jsx)
@[code](@/content/guides/cell-types/text-cell-type/react/example1.tsx)
:::
:::
::: only-for angular
::: example #example1 :angular --ts 1 --html 2
@[code](@/content/guides/cell-types/text-cell-type/angular/example1.ts)
@[code](@/content/guides/cell-types/text-cell-type/angular/example1.html)
:::
:::
::: only-for vue
::: example #example1 :vue3
@[code](@/content/guides/cell-types/text-cell-type/vue/example1.vue)
:::
:::
In the example above, the `sku` and `category` columns use `type: 'text'` explicitly, even though it's the default. This makes the configuration self-documenting: values such as `'004821'` are alphanumeric codes with leading zeros, not numbers, and the explicit type states that intent even if a later change sets a different type at the grid or column level.
## Adding a validator
The text cell type ships without a built-in [validator](@/guides/cell-functions/cell-validator/cell-validator.md). To validate text values, combine `type: 'text'` with your own validator function, and set [`allowInvalid`](@/api/options.md#allowinvalid) to `false` to reject invalid entries.
With `allowInvalid: false`, the cell editor doesn't close on an invalid value. It stays open until you either enter a value that passes validation or press **Esc** to cancel the edit and restore the previous value. See [invalid cell commit semantics](@/guides/cell-functions/cell-validator/cell-validator.md#invalid-cell-commit-semantics-vs-visual-marking) for the full behavior, including how it differs from `allowInvalid: true`.
::: only-for javascript
::: example #example2 --js 1 --ts 2
@[code](@/content/guides/cell-types/text-cell-type/javascript/example2.js)
@[code](@/content/guides/cell-types/text-cell-type/javascript/example2.ts)
:::
:::
::: only-for react
::: example #example2 :react --js 1 --ts 2
@[code](@/content/guides/cell-types/text-cell-type/react/example2.jsx)
@[code](@/content/guides/cell-types/text-cell-type/react/example2.tsx)
:::
:::
::: only-for angular
::: example #example2 :angular --ts 1 --html 2
@[code](@/content/guides/cell-types/text-cell-type/angular/example2.ts)
@[code](@/content/guides/cell-types/text-cell-type/angular/example2.html)
:::
:::
::: only-for vue
::: example #example2 :vue3
@[code](@/content/guides/cell-types/text-cell-type/vue/example2.vue)
:::
:::
## Result
After configuring the text cell type, cells display and edit their value as plain text, with no formatting or masking applied. Combine it with a custom [`validator`](@/api/options.md#validator) to restrict which values a text cell accepts.
## Keyboard shortcuts
The text cell editor uses the standard [edition keyboard shortcuts](@/guides/navigation/keyboard-shortcuts/keyboard-shortcuts.md#edition-keyboard-shortcuts). It has no type-specific key bindings.
## Related articles
**Related guides**
- [Cell type](@/guides/cell-types/cell-type/cell-type.md)
- [Cell validator](@/guides/cell-functions/cell-validator/cell-validator.md)
**Configuration options**
- [type](@/api/options.md#type)
- [validator](@/api/options.md#validator)
- [allowInvalid](@/api/options.md#allowinvalid)
**Core methods**
- [getCellMeta()](@/api/core.md#getcellmeta)
- [getCellMetaAtRow()](@/api/core.md#getcellmetaatrow)
- [getCellsMeta()](@/api/core.md#getcellsmeta)
- [getDataType()](@/api/core.md#getdatatype)
- [setCellMeta()](@/api/core.md#setcellmeta)
- [setCellMetaObject()](@/api/core.md#setcellmetaobject)
- [removeCellMeta()](@/api/core.md#removecellmeta)
**Hooks**
- [afterGetCellMeta](@/api/hooks.md#aftergetcellmeta)
- [afterSetCellMeta](@/api/hooks.md#aftersetcellmeta)
- [afterValidate](@/api/hooks.md#aftervalidate)
- [beforeGetCellMeta](@/api/hooks.md#beforegetcellmeta)
- [beforeSetCellMeta](@/api/hooks.md#beforesetcellmeta)
- [beforeValidate](@/api/hooks.md#beforevalidate)
---
# Numeric cell type
URL: https://handsontable.com/docs/javascript-data-grid/numeric-cell-type/
Display, format, sort, and filter numbers correctly by using the numeric cell type.
The numeric cell type formats numbers using Intl.NumberFormat, right-aligns values, and validates input, marking non-numeric values as invalid.
[[toc]]
## Overview
The default cell type in Handsontable is text. The data of a text cell is processed as a `string`
type that corresponds to the value of the text editor's internal `