Grid Pro
- Usage
- Styling
|
Note
|
Commercial feature
A commercial Vaadin subscription is required to use Grid Pro in your project. |
Grid Pro is an extension of the Grid component that provides inline editing with full keyboard navigation.
new tab
<vaadin-grid-pro .items="${this.items}">
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="email"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="profession"></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>|
Note
|
Features Shared with Grid
Grid Pro is an extension of the Grid component. As a result, all of Grid’s features are also available with Grid Pro.
|
Usage
To use Grid Pro, begin by double-clicking on an editable cell. Then press Enter, Space, or type an alphanumeric character when an editable cell is focused.
When editing, there are a few keyboard shortcuts available:
-
Esc discards the changes and exits edit mode.
-
Enter and Shift+Enter save changes and exit edit mode.
-
Tab and Shift+Tab save changes and move focus to the next or previous editable cell, respectively, while remaining in edit mode.
Modes
Grid Pro has a few modes: edit on single-click; single cell edit; and enter next row. These are described in the sub-sections that follow.
Edit on Single-Click
Single-Click Edit is a mode that enables the user to begin editing by single-clicking on an editable cell.
new tab
<vaadin-grid-pro .items="${this.items}" edit-on-click>
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="email"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="profession"></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Single Cell Edit
By default, when in edit mode, Tab moves the focus to the next cell and Shift+Tab moves the focus to the previous editable cell — while remaining in edit mode. With Single Cell Edit, tabbing from one cell to another will exit from edit mode.
new tab
<vaadin-grid-pro .items="${this.items}" single-cell-edit>
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="email"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="profession"></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Enter Next Row
Pressing Enter or Shift+Enter saves any changes and exits edit mode, by default. However, Enter can be made to move focus to the editable cell in the next row, by using the Enter Next Row mode. The same can be done for Shift+Enter, but to move the focus to the editable cell in the previous row.
new tab
<vaadin-grid-pro .items="${this.items}" enter-next-row>
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="email"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="profession"></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Edit Column
Editing is enabled on a per-column basis.
new tab
<vaadin-grid-pro .items="${this.items}" enter-next-row>
<vaadin-grid-column
header="Name (read-only)"
${columnBodyRenderer<Person>(
(person) => html`${person.firstName} ${person.lastName}`,
[]
)}
></vaadin-grid-column>
<vaadin-grid-pro-edit-column
header="Profession (editable)"
path="profession"
></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Recommended Built-in Editors
Grid Pro features three recommended built-in editors: Text Field; Checkbox; and Select. They’re described in the table here.
| Editor | Usage Recommendation |
|---|---|
Text | Editing basic text. |
Checkbox | Editing boolean (binary) values. |
Select | Selecting a single value from a set of options. |
Although Grid Pro can be configured to use any input field for editing, the built-in editors have better keyboard usability and rendering.
new tab
<vaadin-grid-pro .items="${this.items}" enter-next-row>
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column
path="membership"
editor-type="select"
.editorOptions="${['Regular', 'Premium', 'VIP']}"
></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="subscriber" editor-type="checkbox">
</vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column
path="birthday"
${columnBodyRenderer<Person>(
({ birthday }) => html`${format(parseISO(birthday), 'MM/dd/yyyy')}`,
[]
)}
${columnEditModeRenderer<Person>(
({ birthday }) => html`
<vaadin-date-picker style="width: 100%" .value="${birthday}"></vaadin-date-picker>
`,
[]
)}
></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Prevent Saving Changes
Whenever you enter incorrect or invalid data, it’s possible to rollback changes.
new tab
<vaadin-grid-pro .items="${this.items}" @item-property-changed="${this.itemPropertyListener}">
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="email"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="address.phone"></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Conditional Editability
In some situations you may need to disable editing of specific cells in an edit column. This can be done through a function that determines the editability of each cell. This function is automatically re-evaluated when an item in the Grid is modified. As a result, modifying the value in one cell can immediately affect the editability of other cells.
new tab
<vaadin-grid-pro .items="${this.items}">
<vaadin-grid-pro-edit-column path="firstName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column path="lastName"></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column
path="email"
.isCellEditable="${this.isSubscriber}"
></vaadin-grid-pro-edit-column>
<vaadin-grid-pro-edit-column
path="subscriber"
editor-type="checkbox"
></vaadin-grid-pro-edit-column>
</vaadin-grid-pro>Distinguish Editable from Read-Only
Editable cells are indicated with a hover effect, by default. You can also distinguish them by highlighting either editable or read-only cells. This is good for grids containing both types of cells.
Highlight Editable
Editable cells can be highlighted by applying the highlight-editable-cells theme variant.
new tab
<vaadin-grid-pro theme="highlight-editable-cells" .items="${this.items}">
</vaadin-grid-pro>You can also apply custom styling to editable cells by targeting the editable-cell part in CSS. The following example shows how to apply custom styling to all Grid Pro elements that have the editable-custom-effect class name:
/* Add this to your global CSS, for example in: */
/* frontend/theme/[my-theme]/styles.css */
vaadin-grid-pro.editable-custom-effect::part(editable-cell):hover,
vaadin-grid-pro.editable-custom-effect::part(editable-cell focused-cell) {
background: var(--lumo-contrast-10pct);
}
vaadin-grid-pro.editable-custom-effect::part(editable-cell) {
background: var(--lumo-contrast-5pct);
}Highlight Read-Only
Read-only cells can be highlighted by applying the highlight-read-only-cells theme variant.
new tab
<vaadin-grid-pro theme="highlight-read-only-cells" .items="${this.items}">
</vaadin-grid-pro>Best Practices
Inline vs. Non-Inline Editing
Inline editing is recommended when the user will usually need to make many small changes to different items, and when quick editing is essential.
Non-inline editing is preferable when there are plenty of columns or fields, and when users typically need to edit only one item at a time. It’s also preferred when adding new items is common, as you might want to have edit and create modes work the same way, and creating new items with inline editing isn’t recommended with Grid Pro.
Use non-inline editing when any of the editors need to be larger than a simple field (e.g., Text Area and multi-select fields), or when fields alone may be insufficient (e.g., when helpers, validation errors or other features are needed). Also, use it when explicit save or cancel actions are beneficial, for example, to prevent accidental edits.
Incidentally, if your situation would benefit more from non-inline editing, consider using CRUD.