> Markdown version of [Grid Pro](https://vaadin.com/docs/v23/components/grid-pro). Section index: [llms.txt](https://vaadin.com/docs/v23/components/llms.txt)

# Grid Pro

> **Note: Commercial feature**
>
> A commercial Vaadin subscription is required to use Grid Pro in your project.
>
> - [Start Free Trial](https://vaadin.com/trial)
>
> - [See Pricing](https://vaadin.com/pricing)

Grid Pro is an extension of the Grid component that provides inline editing with full keyboard navigation.

**TypeScript** — `grid-pro-basic.ts`

```typescript
<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>
```

**Java** — `GridProBasic.java`

```java
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName).text(Person::setFirstName)
        .setHeader("First name");

grid.addEditColumn(Person::getLastName).text(Person::setLastName)
        .setHeader("Last name");

grid.addEditColumn(Person::getEmail).text(Person::setEmail)
        .setHeader("Email");

grid.addEditColumn(Person::getProfession).text(Person::setProfession)
        .setHeader("Profession");
```

> **Note: Features shared with Grid**
>
> Grid Pro is an extension of the [Grid](https://vaadin.com/docs/v23/components/grid.md) component, so that all Grid’s features are applicable to Grid Pro, as well.

## <a id="usage"></a>Usage

Begin editing by:

- double-clicking on the editable cell

- pressing `Enter`, `Space` or typing an alphanumeric character when an editable cell is focused

When editing:

- `Esc` discards the changes and exits edit mode

- `Enter` and `Shift`+`Enter` save the changes and exit edit mode

- `Tab` and `Shift`+`Tab` save the changes and focus the next and previous editable cell, respectively, while remaining in edit mode

## <a id="modes"></a>Modes

### <a id="edit-on-single-click"></a>Edit on Single Click

Single Click Edit is a mode that enables the user to begin editing by single-clicking on an editable cell.

**TypeScript** — `grid-pro-single-click.ts`

```typescript
<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>
```

**Java** — `GridProSingleClick.java`

```java
GridPro<Person> grid = new GridPro<>();
grid.setEditOnClick(true);
```

### <a id="single-cell-edit"></a>Single Cell Edit

By default, when in edit mode, `Tab` and `Shift`+`Tab` move to the next and previous editable cell, respectively, while remaining in edit mode.

Single Cell Edit is a mode that makes tabbing from one cell to another exit from edit mode.

**TypeScript** — `grid-pro-single-cell-edit.ts`

```typescript
<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>
```

**Java** — `GridProSingleCellEdit.java`

```java
GridPro<Person> grid = new GridPro<>();
grid.setSingleCellEdit(true);
```

### <a id="enter-next-row"></a>Enter Next Row

Pressing `Enter` and `Shift`+`Enter` saves the changes and exits edit mode by default.

`Enter` and `Shift`+`Enter` can be made to focus the editable cell in the next and previous row, respectively, by using the Enter Next Row mode.

**TypeScript** — `grid-pro-enter-next-row.ts`

```typescript
<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>
```

**Java** — `GridProEnterNextRow.java`

```java
GridPro<Person> grid = new GridPro<>();
grid.setEnterNextRow(true);
```

## <a id="edit-column"></a>Edit Column

Editing is enabled on a per-column basis.

**TypeScript** — `grid-pro-edit-column.ts`

```typescript
<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>
```

**Java** — `GridProEditColumn.java`

```java
GridPro<Person> grid = new GridPro<>();

grid.addColumn(Person::getFullName).setHeader("Name (read-only)");

grid.addEditColumn(Person::getProfession).text(Person::setProfession)
        .setHeader("Profession (editable)");
```

### <a id="recommended-built-in-editors"></a>Recommended Built-in Editors

Grid Pro features three recommended built-in editors: Text Field, Checkbox, and Select.

| 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.

**TypeScript** — `grid-pro-editors.ts`

```typescript
<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>
```

**Java** — `GridProEditor.java`

```java
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName).text(Person::setFirstName)
        .setHeader("First name");

List<String> membershipOptions = Arrays.asList("Regular", "Premium",
        "VIP");
grid.addEditColumn(Person::getMembership)
        .select(Person::setMembership, membershipOptions)
        .setHeader("Membership");

grid.addEditColumn(Person::isSubscriber).checkbox(Person::setSubscriber)
        .setHeader("Subscriber");

DatePicker datePicker = new DatePicker();
datePicker.setWidthFull();

grid.addEditColumn(GridProEditor::getBirthdayAsLocalDate,
        birthdayDateRenderer)
        .custom(datePicker,
                (person, newValue) -> person
                        .setBirthday(dateFromLocalDate(newValue)))
        .setHeader("Birthday");
```

## <a id="prevent-saving-changes"></a>Prevent Saving Changes

You can rollback changes when the entered input is incorrect or invalid.

**TypeScript** — `grid-pro-prevent-save.ts`

```typescript
<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>
```

**Java** — `GridProPreventSave.java`

```java
GridPro<Person> grid = new GridPro<>();

grid.addEditColumn(Person::getFirstName).text(Person::setFirstName)
        .setHeader("First name");

grid.addEditColumn(Person::getLastName).text(Person::setLastName)
        .setHeader("Last name");

grid.addEditColumn(Person::getEmail).text((person, newValue) -> {
    if (isValidEmail(newValue)) {
        person.setEmail(newValue);
    } else {
        showErrorNotification("Enter a valid email address");
    }
}).setHeader("Email");

grid.addEditColumn(person -> person.getAddress().getPhone())
        .text((person, newValue) -> {
            if (isValidPhoneNumber(newValue)) {
                person.getAddress().setPhone(newValue);
            } else {
                showErrorNotification("Enter a valid phone number");
            }
        }).setHeader("Phone");
```

## <a id="distinguish-editable-read-only-cells"></a>Distinguish Editable / Read-Only Cells

Editable cells are indicated with a hover effect by default, but you can give further help to users in distinguishing these by highlighting either editable or read-only cells. This is recommended for grids with both editable and read-only cells.

### <a id="highlight-editable-cells"></a>Highlight Editable Cells

Editable cells can be highlighted by applying the `highlight-editable-cells` theme variant.

**TypeScript** — `grid-pro-highlight-editable-cells.ts`

```typescript
<vaadin-grid-pro theme="highlight-editable-cells" .items="${this.items}">
</vaadin-grid-pro>
```

**Java** — `GridProThemeHighlightEditableCells.java`

```java
GridPro<Person> grid = new GridPro<>();
grid.addThemeVariants(GridProVariant.LUMO_HIGHLIGHT_EDITABLE_CELLS);
```

### <a id="highlight-read-only-cells"></a>Highlight Read-Only Cells

Read-only cells can be highlighted by applying the `highlight-read-only-cells` theme variant.

**TypeScript** — `grid-pro-highlight-read-only-cells.ts`

```typescript
<vaadin-grid-pro theme="highlight-read-only-cells" .items="${this.items}">
</vaadin-grid-pro>
```

**Java** — `GridProThemeHighlightReadOnlyCells.java`

```java
GridPro<Person> grid = new GridPro<>();
grid.addThemeVariants(GridProVariant.LUMO_HIGHLIGHT_READ_ONLY_CELLS);
```

You can also apply custom styling to both editable and read-only cells by targeting the `editable-cell` part name in CSS.

`vaadin-grid-pro-editable-cells.css`

```css
:host(.editable-custom-effect) [part~="editable-cell"]:hover,
:host(.editable-custom-effect) [part~="editable-cell"]:focus {
  background: var(--lumo-contrast-10pct);
}

:host(.editable-custom-effect) [part~="editable-cell"] {
  background: var(--lumo-contrast-5pct);
}
```

## <a id="best-practices"></a>Best Practices

### <a id="inline-vs-non-inline-editing"></a>Inline vs Non-Inline Editing

Inline editing is recommended when:

- the user typically needs to make a lot of small changes to different items

- quick editing is important.

Non-inline editing is preferable when:

- there are a lot of columns/fields

- users typically need to edit only one item at a time

- 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)

- any of the editors need to be bigger than a simple field, such as a Text Area or multi-select field of any kind

- fields alone may be insufficient, for example when helpers, validation errors or other features are needed

- explicit save/cancel actions are beneficial, for example to prevent accidental edits.

If your use case would benefit more from non-inline editing, consider using [CRUD](https://vaadin.com/docs/v23/components/crud.md).

## <a id="related-components"></a>Related Components

| Component                                              | Usage recommendations                                                   |
| ------------------------------------------------------ | ----------------------------------------------------------------------- |
| [CRUD](https://vaadin.com/docs/v23/components/crud.md) | Component for creating, displaying, updating and deleting tabular data. |
| [Grid](https://vaadin.com/docs/v23/components/grid.md) | Component for showing tabular data.                                     |

`AACED59D-0972-417E-BA70-9464FEA8895C`
