GpGrid Props
Reference for every prop accepted by the Vue 3 GpGrid component, including data sources, columns, sorting, filtering, selection, and editing controls today.
All properties accepted by the Vue GpGrid component. Props use kebab-case in templates.
Required Props
columns
Type: ColumnDefinition[]
Array of column definitions.
<template>
<GpGrid :columns="columns" ... />
</template>row-height
Type: number
Height of each row in pixels.
<template>
<GpGrid :row-height="36" ... />
</template>Data Props
row-data
Type: TData[]
Array of row data objects.
<script setup>
const data = ref([
{ id: 1, name: "Giovanni" },
{ id: 2, name: "Luca" },
]);
</script>
<template>
<GpGrid :row-data="data" ... />
</template>data-source
Type: DataSource<TData>
Data source for advanced data handling.
<script setup>
const dataSource = createClientDataSource(data);
</script>
<template>
<GpGrid :data-source="dataSource" ... />
</template>Optional Props
header-height
Type: number
Default: Same as row-height
<template>
<GpGrid :header-height="48" ... />
</template>overscan
Type: number
Default: 3
Number of rows to render outside viewport.
sorting-enabled
Type: boolean
Default: true
Enable/disable sorting globally.
dark-mode
Type: boolean
Default: false
Enable dark mode styling.
wheel-dampening
Type: number
Default: 0.1
Dampening factor for wheel scrolling (0-1).
Enabling this prop activates smooth scrolling for grids that exceed millions of rows by using virtual dampening, which keeps wheel-based navigation fluid on very large datasets.
max-fling-velocity
Type: number
Default: 20 × rowHeight
Maximum accumulated touch-fling velocity in logical px/ms when scroll virtualization is active. Pair higher values with overscan 10–12 for smoother fast scrolling on touch devices.
<template>
<GpGrid
:columns="columns"
:row-data="data"
:row-height="36"
:max-fling-velocity="2000"
:overscan="12"
/>
</template>Drag & Reorder Props
row-drag-entire-row
Type: boolean
Default: false
When enabled, clicking and dragging any cell initiates a row drag.
<template>
<GpGrid :row-drag-entire-row="true" :on-row-drag-end="handleRowDragEnd" ... />
</template>:on-row-drag-end
Type: ({ fromViewIndex, toViewIndex }: RowDragEndEvent) => void
Emitted when a row is dropped after dragging. The consumer handles data reordering.
:on-column-moved
Type: (event: ColumnMovedEvent) => void
Emitted when a column header is dragged to a new position.
:on-column-resized
Type: (event: ColumnResizedEvent) => void
Emitted when a column is resized by dragging the header edge.
SSR Props
initial-width
Type: number
Initial viewport width in pixels for server-side rendering. On the client, a ResizeObserver takes over automatically.
initial-height
Type: number
Initial viewport height in pixels for server-side rendering.
Identity & Edit Props
get-row-id
Type: (row: TData) => RowId
Function to extract a unique ID from each row. Required when onCellValueChanged is provided.
<template>
<GpGrid
:columns="columns"
:row-data="data"
:row-height="36"
:get-row-id="(row) => row.id"
@cell-value-changed="handleCellValueChanged"
/>
</template>@cell-value-changed
Type: (event: CellValueChangedEvent<TData>) => void
Emitted after a cell value is committed via inline editing or fill-handle drag.
Styling Props
highlighting
Type: HighlightingOptions<TData>
Dynamic row, column, and cell class computation. See the Styling guide for detailed usage.
<template>
<GpGrid
:columns="columns"
:row-data="data"
:row-height="36"
:highlighting="{
computeRowClasses: (ctx) =>
ctx.rowIndex != null && ctx.rowIndex % 2 === 1 ? ['zebra-row'] : [],
}"
/>
</template>Localization Props
labels
Type: GridLabelOverrides
Default: English defaults
Override any user-visible grid string: the filter popup, its buttons and placeholders, the empty state and the error prefix. Unspecified labels keep their English defaults.
<script setup lang="ts">
import { GpGrid, type GridLabelOverrides } from "@gp-grid/vue";
const labels: GridLabelOverrides = {
filterTitle: "Filtra: {column}", // {column} is the column header name
and: "E",
apply: "Applica",
emptyState: "Nessun dato",
};
</script>
<template>
<GpGrid :columns="columns" :row-data="rows" :row-height="36" :labels="labels" />
</template>The most common keys:
| Key | Token | Meaning |
|---|---|---|
filterTitle | {column} | Filter popup title |
and / or | - | Combination toggle |
apply / clear / addCondition / removeCondition | - | Condition buttons |
addGroup / removeGroup | - | Condition-group buttons |
valuePlaceholder / searchPlaceholder / betweenSeparator | - | Inputs |
valuesMode / conditionMode | - | Popup mode toggle |
selectAll / deselectAll / blanks | - | Values-mode controls |
tooManyValues | {count} | Too-many-values message |
emptyState | - | Empty grid message |
errorPrefix | {message} | Error message prefix |
operators.* | - | Filter dropdown labels (contains, startsWith, between, …) |
operators is also a partial override, so one operator can be changed without
copying the English defaults: operators: { contains: "Contiene" }.
Loading Props
loading-component
Type: Component<{ isLoading: boolean }>
Custom component rendered during data loading instead of the default spinner.
Renderer Props
cell-renderer
Type: VueCellRenderer
Global cell renderer.
cell-renderers
Type: Record<string, VueCellRenderer>
Named cell renderer registry.
edit-renderer / edit-renderers
Custom edit renderers.
header-renderer / header-renderers
Custom header renderers.
filter-renderer / filter-renderers
Type: VueFilterRenderer / Record<string, VueFilterRenderer>
Custom filter popup content: filter-renderer applies to every filterable column, filter-renderers is the registry a column's filterRenderer key points into. See Custom Filter Popup.
Template Ref
You can access the underlying GridCore instance via a template ref:
<script setup>
import { ref } from "vue";
const gridRef = ref(null);
function sortByName() {
gridRef.value?.core?.sortFilter.setSort("name", "asc");
}
</script>
<template>
<GpGrid ref="gridRef" :columns="columns" :row-data="data" :row-height="36" />
</template>Example
<template>
<GpGrid
:columns="columns"
:row-data="data"
:row-height="36"
:header-height="48"
:overscan="5"
:sorting-enabled="true"
:dark-mode="isDark"
:cell-renderers="{ status: StatusRenderer }"
/>
</template>Layout, grouping, and write options
The following options are shared across the bindings. Use React props, Vue kebab-case bindings, or Angular inputs; Angular callbacks are outputs.
| Option | Contract |
|---|---|
columnState | ColumnStateUpdate[]; controlled width, order, visibility, and pin overrides by columnId |
columnLayout | "fit" (default) or "fixed" |
columnOverscan | Center-column overscan in CSS pixels; default 240 |
columnGroups / columnGroupLimits | Nested column-id descriptors and creation-only validation budgets |
headerBandHeights | Configured height per header band |
freezeRows | { count }; freezes leading displayed rows below the header |
rowLoading | Row loading and cache configuration |
rowResize / autoFit | Row resize gestures and creation-only measurement bounds |
rowGrouping | Opaque grouping built by createRowGrouping, or null |
groupLabelColumn / groupLabelRenderer | Group and total label customization |
history | Creation-only { maxEntries }; requires getRowId |
pinIcon | Custom pin-toggle SVG |
onColumnPinned / onRowResized | Identity-bearing pin and row-size notifications |
onFrozenRowsChanged | Effective frozen count and limiting reason |
onColumnSchemaRejected / onRowGroupingRejected | Invalid schema or unsupported grouping notifications |
onRowGroupToggled | User-initiated group expansion notification |
onWriteRejected | Rejected write with reason and operation |
onWriteCommitted | One event per write command, with changes and skips; requires getRowId |
See the guides for contracts and examples, and the migration guide for API changes.
API Overview
Browse the full API reference for @gp-grid/vue with details on every component, prop, emit, slot, and helper exported by the Vue 3 integration package.
Column Definition
Configure each Vue 3 grid column individually with type, width, sorting, filtering, rendering, and editing options through the column definition object.