Docs

Docs

Grid Pro

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

A commercial Vaadin subscription is required to use Grid Pro in your project.

<GridPro items={people}>
  <GridProEditColumn path="firstName" />
  <GridProEditColumn path="lastName" />
  <GridProEditColumn path="email" />
  <GridProEditColumn path="profession" />
</GridPro>

Note
Features Shared with Grid

Grid Pro is an extension of the Grid component, so all Grid features are also applicable to Grid Pro.

Usage

Begin editing by double-clicking on the editable cell and then pressing Enter, Space, or typing an alphanumeric character when an editable cell is focused.

When editing, a few keys and key combinations are available to the user:

  • Esc discards the changes and exits edit mode.

  • Enter and Shift+Enter save any changes and the user exits edit mode.

  • Tab saves any changes and shifts focus to the next editable cell. Shift+Tab does the but shifts the focus to the previous editable cell. The user remains in edit mode for either one.

Modes

Grid Pro has a few editing modes. These are described in the subsections below.

Edit on Single Click

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

<GridPro items={people} editOnClick>
  <GridProEditColumn path="firstName" />
  <GridProEditColumn path="lastName" />
  <GridProEditColumn path="email" />
  <GridProEditColumn path="profession" />
</GridPro>

Single Cell Edit

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

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

<GridPro items={people} singleCellEdit>
  <GridProEditColumn path="firstName" />
  <GridProEditColumn path="lastName" />
  <GridProEditColumn path="email" />
  <GridProEditColumn path="profession" />
</GridPro>

Enter Next Row

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

By using the Enter Next Row mode, Enter will shift the focus to the editable cell in the next row, while Shift+Enter will shift the focus to the one in the previous row.

<GridPro items={people} enterNextRow>
  <GridProEditColumn path="firstName" />
  <GridProEditColumn path="lastName" />
  <GridProEditColumn path="email" />
  <GridProEditColumn path="profession" />
</GridPro>

Edit Column

Editing is enabled on a per-column basis.

<GridPro items={people} enterNextRow>
  <GridColumn header="Name (read-only)">
    {({ item }) => (
      <>
        {item.firstName} {item.lastName}
      </>
    )}
  </GridColumn>
  <GridProEditColumn header="Profession (editable)" path="profession" />
</GridPro>

Grid Pro features three recommended built-in editors: Text Field, Checkbox, and Select. The table here lists each along with their usage recommendation.

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.

<GridPro items={people}>
  <GridProEditColumn path="firstName" />
  <GridProEditColumn
    path="membership"
    editorType="select"
    editorOptions={["Regular", "Premium", "VIP"]}
  />
  <GridProEditColumn path="subscriber" editorType="checkbox" />
  <GridProEditColumn<Person>
    path="birthday"
    renderer={({ item: { birthday } }) => (
      <>{format(parseISO(birthday), "dd/MM/yyyy")}</>
    )}
    editModeRenderer={({ item: { birthday } }) => (
      <DatePicker style={{ width: "100%" }} value={birthday} />
    )}
  />
</GridPro>

Prevent Saving Changes

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

const people = usePeople();

const showErrorNotification = (msg: string) => {
  const notification = Notification.show(msg, { position: "bottom-center" });
  notification.setAttribute("theme", "error");
};

const itemPropertyListener = ({
  detail: {
    path,
    item: {
      address: { phone },
      email,
    },
  },
  preventDefault,
}: GridProItemPropertyChangedEvent<Person>) => {
  console.log(path);
  switch (path) {
    case "address.phone":
      if (!/^[0-9-]+$/.test(phone)) {
        // Incorrect phone
        preventDefault();
        showErrorNotification("Enter a valid phone number");
      }
      break;
    case "email":
      if (!/^[\w-.]+@([\w-]+.)+[\w-]{2,4}$/.test(email)) {
        // Incorrect email
        preventDefault();
        showErrorNotification("Enter a valid email address");
      }
      break;
    default:
      break;
  }
};

return (
  <GridPro items={people} onItemPropertyChanged={itemPropertyListener}>
    <GridProEditColumn path="firstName" />
    <GridProEditColumn path="lastName" />
    <GridProEditColumn path="email" />
    <GridProEditColumn path="address.phone" />
  </GridPro>
);

Distinguish 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. How to highlight each is described in the subsections that follow.

Highlight Editable Cells

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

<GridPro items={people} theme="highlight-editable-cells">
  <GridColumn path="firstName" />
  <GridColumn path="lastName" />
  <GridColumn path="membership" />
  <GridProEditColumn path="email" header="Email (Editable)" />
</GridPro>

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 Cells

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

<GridPro items={people} theme="highlight-read-only-cells">
  <GridColumn path="firstName" />
  <GridColumn path="lastName" />
  <GridColumn path="membership" />
  <GridProEditColumn path="email" header="Email (Editable)" />
</GridPro>

Best Practices

Inline vs. Non-Inline Editing

Inline editing is recommended when the user typically needs to make plenty of small changes to different items, and quick editing is important.

Conversely, non-inline editing is preferable when:

  • Plenty of columns or fields are involved;

  • 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 larger 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; or when

  • Explicit save or cancel actions are beneficial, for example, to prevent accidental edits.

If your use case would benefit more from non-inline editing, consider using CRUD.

Component Usage Recommendation

CRUD

Component for creating, displaying, updating, and deleting tabular data.

Grid

Component for showing tabular data.
Important
 You can find more information in the corresponding article on vaadin.com.