Documentation

Documentation versions (currently viewingVaadin 23)

CRUD

Note
Commercial feature

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

CRUD is a component for managing a dataset. It allows for easy displaying, editing, creating, and deleting of items.

Open in a
new tab
<vaadin-crud
  include="firstName, lastName, email, profession"
  .items="${this.items}"
></vaadin-crud>

Columns

CRUD automatically generates columns for each field in the provided dataset. You can add columns and configure or remove existing ones.

Open in a
new tab
<!-- Use 'include' or 'exclude' to select which fields to show -->
<vaadin-crud
  exclude="lastName, address, id, subscribe, membership, pictureUrl, manager"
  .items="${this.items}"
></vaadin-crud>

Editor

Data is edited using CRUD’s editor UI.

Opening the Editor

By default, the editor is opened by clicking the edit Button in the last column, but this button column can be removed if you want to provide some alternative way to engage the editor. For example, you can have it open using a double click:

Open in a
new tab
<vaadin-crud
  include="firstName, lastName, email, profession"
  .items="${this.items}"
  .editedItem="${this.editedItem as any}"
  @edited-item-changed="${(e: CrudEditedItemChangedEvent<Person>) =>
    (this.editedItem = e.detail.value)}"
>
  <vaadin-grid slot="grid" @dblclick="${this.onDblClick}">
    <vaadin-grid-column path="firstName" header="First name"></vaadin-grid-column>
    <vaadin-grid-column path="lastName" header="Last name"></vaadin-grid-column>
    <vaadin-grid-column path="email" header="Email"></vaadin-grid-column>
    <vaadin-grid-column path="profession" header="Profession"></vaadin-grid-column>
  </vaadin-grid>
</vaadin-crud>

Editor Position

The editor can be positioned in an overlay (default), on the side, or at the bottom.

Overlay (Default)

The overlay position renders the editor in a modal overlay. Overlays are not constrained to the CRUD’s size, which makes them ideal for complex forms. However, they block the user from viewing and interacting with the Grid beneath.

Aside

The aside position displays the editor as an overlay next to the grid. Use this position when there is sufficient horizontal space to accommodate both the grid and the editor, and it is beneficial for the user to be able to view and interact with the grid while the editor is open. Aside positioning is also a good fit for single-column forms.

Open in a
new tab
<vaadin-crud
  editor-position="aside"
  include="firstName, lastName, email, profession"
  .items="${this.items}"
></vaadin-crud>
Note
Grid Width
The opening and closing of an aside editor affects the grid’s width. Fixed-width columns are recommended to prevent them from resizing each time.

Bottom

The bottom position can be useful when the user needs to see as many columns in the grid as possible while editing, when horizontal space is limited, or when a wider editor form is desired.

Open in a
new tab
<vaadin-crud
  editor-position="bottom"
  include="firstName, lastName, email, profession"
  .items="${this.items}"
></vaadin-crud>

When using a bottom-positioned editor, make sure there is enough vertical space to fit both the grid and the editor comfortably. Also note that a bottom-positioned editor is an inappropriate option for longer forms.

Note
Small viewports
On small viewports, like mobile phones, the editor always opens up as a full-screen overlay, regardless of this configuration.

Editor Content

The editor’s content is fully configurable, except for the header and footer.

Open in a
new tab
<vaadin-crud include="firstName, lastName, email, profession" .items=${this.items}>
  <vaadin-form-layout
    slot="form"
    style="max-width: 480px;"
    .responsiveSteps=${this.responsiveSteps}
  >
    <vaadin-text-field label="First name" path="firstName" required></vaadin-text-field>
    <vaadin-text-field label="Last name" path="lastName" required></vaadin-text-field>
    <vaadin-email-field colspan="2" label="Email" path="email" required></vaadin-email-field>
    <vaadin-combo-box
      colspan="2"
      label="Profession"
      path="profession"
      .items="${this.professions}"
    ></vaadin-combo-box>
  </vaadin-form-layout>
</vaadin-crud>

Editor Actions

The editor contains three Buttons:
  • “Delete” shows a confirmation dialog asking the user to verify whether they wish to delete the item

  • “Cancel” closes the editor unless there are unsaved changes, in which case a confirmation dialog is shown and the user can either discard the changes or go back to editing

  • “Save” saves the changes and closes the editor (disabled until a change is made)

Grid Replacement

CRUD’s default Grid is replaceable. This is useful when you wish to customize the Grid, for example to place the edit Button in the first column. See Grid documentation for details on configuring grids.

Open in a
new tab
<vaadin-crud include="firstName, lastName, email, profession" .items="${this.items}">
  <vaadin-grid slot="grid">
    <vaadin-crud-edit-column></vaadin-crud-edit-column>
    <vaadin-grid-column path="firstName" header="First name"></vaadin-grid-column>
    <vaadin-grid-column path="lastName" header="Last name"></vaadin-grid-column>
    <vaadin-grid-column path="email" header="Email"></vaadin-grid-column>
    <vaadin-grid-column path="profession" header="Profession"></vaadin-grid-column>
  </vaadin-grid>
</vaadin-crud>
Note
Edit Column
You need to explicitly add an edit column to the replacement Grid in order to edit items. In addition, Grid does not have sorting and filtering enabled by default.

Toolbar

Creating new items is done via the “New item” Button in CRUD’s toolbar. Both the toolbar and its Button are customizable. For example, you can use the toolbar to display statistics such as the size of the dataset or the number of search results.

Open in a
new tab
<vaadin-crud
  include="firstName, lastName"
  .items="${this.items}"
  @size-changed="${() => this.requestUpdate()}"
>
  <vaadin-horizontal-layout
    slot="toolbar"
    style="align-items: center; flex-grow: 1; justify-content: space-between;"
  >
    <span>Total: <b>${this.items.length}</b> employees</span>
    <vaadin-button theme="tertiary" new-button>
      <vaadin-icon slot="prefix" icon="vaadin:plus"></vaadin-icon>
      New employee
    </vaadin-button>
  </vaadin-horizontal-layout>
</vaadin-crud>

Hiding the Toolbar

The toolbar can be hidden if it is not needed.

Open in a
new tab
<!-- Adding the no-toolbar attribute hides the toolbar -->
<vaadin-crud
  include="firstName, lastName"
  .items="${this.items}"
  @size-changed="${() => this.requestUpdate()}"
  no-toolbar
></vaadin-crud>

Sorting and Filtering

By default, CRUD allows sorting and filtering of any column. For more information about sorting and filtering, please see the basic Grid documentation.

Disabling Sorting and Filtering

Sorting and filtering can be disabled.

Open in a
new tab
<vaadin-crud
  include="firstName, lastName, profession"
  no-sort
  no-filter
  .items="${this.items}"
></vaadin-crud>

Item Initialization

Newly created items can be initialized with data.

Open in a
new tab
handleNewItem(e: CrudNewEvent) {
  // Cancel event to allow setting a custom item instance
  e.preventDefault();
  this.crud.editedItem = {
    email: '@vaadin.com',
    profession: 'Developer',
  };
}

render() {
  return html`
    <vaadin-crud
      include="firstName, lastName, email, profession"
      .items="${this.items}"
      @new="${this.handleNewItem}"
    ></vaadin-crud>
  `;
}

Localization

CRUD supports full localization through customizable labels for its buttons and the title of the editor.

Open in a
new tab
const crud = this.shadowRoot?.querySelector('vaadin-crud');
if (crud) {
  crud.i18n = {
    newItem: 'Luo uusi',
    editItem: 'Muuta tietoja',
    saveItem: 'Tallenna',
    cancel: 'Peruuta',
    deleteItem: 'Poista...',
    editLabel: 'Muokkaa',
    confirm: {
      delete: {
        title: 'Poista kohde',
        content: 'Haluatko varmasti poistaa tämän kohteen? Poistoa ei voi perua.',
        button: {
          confirm: 'Poista',
          dismiss: 'Peruuta',
        },
      },
      cancel: {
        title: 'Hylkää muutokset',
        content: 'Kohteessa on tallentamattomia muutoksia',
        button: {
          confirm: 'Hylkää',
          dismiss: 'Peruuta',
        },
      },
    },
  };
}

  <vaadin-crud
    editor-position="aside"
    include="firstName, lastName, email, profession"
    .items="${this.items}"
  >
    <vaadin-grid slot="grid">
      <vaadin-grid-column path="firstName" header="Etunimi"></vaadin-grid-column>
      <vaadin-grid-column path="lastName" header="Sukunimi"></vaadin-grid-column>
      <vaadin-grid-column path="email" header="Sähköposti"></vaadin-grid-column>
      <vaadin-grid-column path="profession" header="Ammatti"></vaadin-grid-column>
      <vaadin-crud-edit-column></vaadin-crud-edit-column>
    </vaadin-grid>
    <vaadin-form-layout slot="form">
      <vaadin-text-field path="firstName" label="Etunimi" required></vaadin-text-field>
      <vaadin-text-field path="lastName" label="Sukunimi" required></vaadin-text-field>
      <vaadin-email-field path="email" label="Sähköposti" required></vaadin-email-field>
      <vaadin-combo-box
        path="profession"
        label="Ammatti"
        .items="${[...new Set(this.items.map((i) => i.profession))]}"
      ></vaadin-combo-box>
    </vaadin-form-layout>
  </vaadin-crud>
ComponentUsage recommendations

Grid Pro

Component for showing and editing tabular data.

Grid

Component for showing tabular data.

Tree Grid

Component for showing hierarchical data.