---
title: Crud
description: Crud
element: vaadin-crud
---

## Description

`<vaadin-crud>` is a Web Component for [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations.

### Quick Start

Assign an array to the [`items`](/elements/vaadin-crud#items) property.

A grid and an editor will be automatically generated and configured based on the data structure provided.

```html
<vaadin-crud></vaadin-crud>
```

```js
const crud = document.querySelector('vaadin-crud');

crud.items = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];
```

### Data Provider Function

Otherwise, you can provide a [`dataProvider`](/elements/vaadin-crud#dataprovider) function.

```js
const crud = document.querySelector('vaadin-crud');

const users = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];

crud.dataProvider = (params, callback) => {
  const chunk = users.slice(params.page * params.pageSize, params.page * params.pageSize + params.pageSize);
  callback(chunk, people.length);
};
```

NOTE: The auto-generated editor only supports string types. If you need to handle special cases
customizing the editor is discussed below.

### Customization

Alternatively you can fully configure the component by using `slot` names.

Slot name      | Description
---------------|----------------
`grid`         | To replace the auto-generated grid with a custom one.
`form`         | To replace the auto-generated form.
`save-button`  | To replace the "Save" button.
`cancel-button`| To replace the "Cancel" button.
`delete-button`| To replace the "Delete" button.
`toolbar`      | To provide the toolbar content (by default, it's empty).
`new-button`   | To replace the "New item" button.

#### Example:

```html
<vaadin-crud id="crud">
  <vaadin-grid slot="grid">
    <vaadin-crud-edit-column></vaadin-crud-edit-column>
    <vaadin-grid-column id="column1"></vaadin-grid-column>
    <vaadin-grid-column id="column2"></vaadin-grid-column>
  </vaadin-grid>

  <vaadin-form-layout slot="form">
    <vaadin-text-field label="First" path="name"></vaadin-text-field>
    <vaadin-text-field label="Surname" path="surname"></vaadin-text-field>
  </vaadin-form-layout>

  <div slot="toolbar">Total singers: 2</div>
  <button slot="new-button">New singer</button>

  <button slot="save-button">Save changes</button>
  <button slot="cancel-button">Discard changes</button>
  <button slot="delete-button">Delete singer</button>
</vaadin-crud>
```
```js
const crud = document.querySelector('#crud');

const column1 = document.querySelector('#column1');
column1.headerRenderer = (root, column) => {
  root.textContent = 'Name';
};
column1.renderer = (root, column, model) => {
  root.textContent = model.item.name;
};

const column2 = document.querySelector('#column2');
column2.headerRenderer = (root, column) => {
  root.textContent = 'Surname';
};
column2.renderer = (root, column, model) => {
  root.textContent = model.item.surname;
};

crud.items = [
  { name: 'John', surname: 'Lennon', role: 'singer' },
  { name: 'Ringo', surname: 'Starr', role: 'drums' },
  // ... more items
];
```

### Helpers

The following elements are used to auto-configure the grid and the editor
- [`<vaadin-crud-edit-column>`](/elements/vaadin-crud-edit-column)
- `<vaadin-crud-grid>` - can be replaced with custom [`<vaadin-grid>`](/elements/vaadin-grid)
- `<vaadin-crud-form>` - can be replaced with custom [`<vaadin-form-layout>`](/elements/vaadin-form-layout)

### Styling

The following shadow DOM parts are available for styling when the editor is rendered next to, or below, the grid:

Part name | Description
----------------|----------------
`toolbar`  | Toolbar container at the bottom of the grid. By default, it contains the `new` button
`editor`   | The editor container
`scroller` | The wrapper for the header and the form
`header`   | The header of the editor
`footer`   | The footer of the editor

The following shadow DOM parts are available for styling when the editor renders as a dialog:

Part name | Description
----------------|----------------
`toolbar`  | Toolbar container at the bottom of the grid. By default, it contains the `new` button
`overlay`  | The dialog overlay
`backdrop` | The dialog backdrop
`header`   | The header of the dialog
`footer`   | The footer of the dialog
`content`  | The wrapper for the form

The following custom CSS properties are available for styling:

Custom CSS property                    |
:--------------------------------------|
| `--vaadin-crud-background`           |
| `--vaadin-crud-border-color`         |
| `--vaadin-crud-border-radius`        |
| `--vaadin-crud-border-width`         |
| `--vaadin-crud-editor-max-height`    |
| `--vaadin-crud-editor-max-width`     |
| `--vaadin-crud-footer-background`    |
| `--vaadin-crud-footer-gap`           |
| `--vaadin-crud-footer-padding`       |
| `--vaadin-crud-form-padding`         |
| `--vaadin-crud-header-color`         |
| `--vaadin-crud-header-font-size`     |
| `--vaadin-crud-header-font-weight`   |
| `--vaadin-crud-header-line-height`   |
| `--vaadin-crud-header-padding`       |
| `--vaadin-crud-toolbar-background`   |
| `--vaadin-crud-toolbar-padding`      |

See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.

## Properties

### dataProvider

**Type:** `CrudDataProvider<any> | null | undefined`

Function that provides items lazily. Receives arguments `params`, `callback`

`params.page` Requested page index
`params.pageSize` Current page size
`params.filters` Currently applied filters
`params.sortOrders` Currently applied sorting orders

`callback(items, size)` Callback function with arguments:
  - `items` Current page of items
  - `size` Total number of items

See also: [CrudDataProvider](#cruddataprovider)

### editedItem

**Type:** `any`

The item being edited in the dialog.

### editOnClick

**Type:** `boolean`

Enables user to click on row to edit it.
Note: When enabled, auto-generated grid won't show the edit column.

### editorOpened

**Type:** `boolean | null | undefined`

Reflects the opened status of the editor.

### editorPosition

**Type:** `CrudEditorPosition`

Sets how editor will be presented on desktop screen.

Accepted values are:
  - `` (default) - form will open as overlay
  - `bottom` - form will open below the grid
  - `aside` - form will open on the grid side (_right_, if lft and _left_ if rtl)

See also: [CrudEditorPosition](#crudeditorposition)

### exclude

**Type:** `string | null | undefined`

A comma-separated list of fields to be excluded from the generated grid and the generated editor.

When [`include`](/elements/vaadin-crud#include) is defined, this parameter is ignored.

Default is to exclude all private fields (those properties starting with underscore)

### i18n

**Type:** `CrudI18n`

The object used to localize this component. To change the default
localization, replace this with an object that provides all properties, or
just the individual properties you want to change.

The object has the following JSON structure and default values:

```js
{
  newItem: 'New item',
  editItem: 'Edit item',
  saveItem: 'Save',
  cancel: 'Cancel',
  deleteItem: 'Delete...',
  editLabel: 'Edit',
  confirm: {
    delete: {
      title: 'Confirm delete',
      content: 'Are you sure you want to delete the selected item? This action cannot be undone.',
      button: {
        confirm: 'Delete',
        dismiss: 'Cancel'
      }
    },
    cancel: {
      title: 'Unsaved changes',
      content: 'There are unsaved modifications to the item.',
      button: {
        confirm: 'Discard',
        dismiss: 'Continue editing'
      }
    }
  }
}
```

See also: [CrudI18n](#crudi18n)

### include

**Type:** `string | null | undefined`

A comma-separated list of fields to include in the generated grid and the generated editor.

It can be used to explicitly define the field order.

When it is defined [`exclude`](/elements/vaadin-crud#exclude) is ignored.

Default is undefined meaning that all properties in the object should be mapped to fields.

### items

**Type:** `any[] | null | undefined`

An array containing the items which will be stamped to the column template instances.

### noFilter

**Type:** `boolean | null | undefined`

Disable filtering when grid is autoconfigured.

### noHead

**Type:** `boolean | null | undefined`

Remove grid headers when it is autoconfigured.

### noSort

**Type:** `boolean | null | undefined`

Disable sorting when grid is autoconfigured.

### noToolbar

**Type:** `boolean`

Controls visibility state of toolbar.
When set to false toolbar is hidden and shown when set to true.

### size

**Type:** `number | null | undefined`

Number of items in the data set which is reported by the grid.
Typically it reflects the number of filtered items displayed in the grid.

Note: As with `<vaadin-grid>`, this property updates automatically only
if `items` is used for data.

## Events

### cancel

**Type:** [CrudCancelEvent](#crudcancelevent)

Fired when user discards edition. If the default is prevented, then
no action is performed, user is responsible to close dialog and reset
item and grid.

### delete

**Type:** [CrudDeleteEvent](#cruddeleteevent)

Fired when user wants to delete item. If the default is prevented, then
no action is performed, items array is not modified nor dialog closed

### edit

**Type:** [CrudEditEvent](#crudeditevent)

Fired when user wants to edit an existing item. If the default is prevented, then
a new item is not assigned to the form, giving that responsibility to the app, though
dialog is always opened.

### edited-item-changed

**Type:** [CrudEditedItemChangedEvent](#crudediteditemchangedevent)

Fired when the `editedItem` property changes.

### editor-opened-changed

**Type:** [CrudEditorOpenedChangedEvent](#crudeditoropenedchangedevent)

Fired when the `editorOpened` property changes.

### items-changed

**Type:** [CrudItemsChangedEvent](#cruditemschangedevent)

Fired when the `items` property changes.

### new

**Type:** [CrudNewEvent](#crudnewevent)

Fired when user wants to create a new item.

### save

**Type:** [CrudSaveEvent](#crudsaveevent)

Fired when user wants to save a new or an existing item. If the default is prevented, then
no action is performed, items array is not modified nor dialog closed

### size-changed

**Type:** [CrudSizeChangedEvent](#crudsizechangedevent)

Fired when the `size` property changes.

## Types

### CrudCancelEvent

```ts
/**
 * Fired when user discards edition.
 */
export type CrudCancelEvent<T> = CustomEvent<{ item: T }>;
```

### CrudDataProvider

```ts
export type CrudDataProvider<T> = (params: CrudDataProviderParams, callback: CrudDataProviderCallback<T>) => void;
```

### CrudDataProviderCallback

```ts
export type CrudDataProviderCallback<T> = (items: T[], size?: number) => void;
```

### CrudDataProviderParams

```ts
export type CrudDataProviderParams = {
  page: number;
  pageSize: number;
  filters: GridFilterDefinition[];
  sortOrders: GridSorterDefinition[];
};
```

### CrudDeleteEvent

```ts
/**
 * Fired when user wants to delete item.
 */
export type CrudDeleteEvent<T> = CustomEvent<{ item: T }>;
```

### CrudEditedItemChangedEvent

```ts
/**
 * Fired when the `editedItem` property changes.
 */
export type CrudEditedItemChangedEvent<T> = CustomEvent<{ value: T }>;
```

### CrudEditEvent

```ts
/**
 * Fired when user wants to edit an existing item.
 */
export type CrudEditEvent<T> = CustomEvent<{ item: T; index: number }>;
```

### CrudEditorOpenedChangedEvent

```ts
/**
 * Fired when the `editorOpened` property changes.
 */
export type CrudEditorOpenedChangedEvent = CustomEvent<{ value: boolean }>;
```

### CrudEditorPosition

```ts
export type CrudEditorPosition = '' | 'aside' | 'bottom';
```

### CrudI18n

```ts
export interface CrudI18n {
  newItem?: string;
  editItem?: string;
  saveItem?: string;
  cancel?: string;
  deleteItem?: string;
  editLabel?: string;
  confirm?: {
    delete?: {
      title?: string;
      content?: string;
      button?: {
        confirm?: string;
        dismiss?: string;
      };
    };
    cancel?: {
      title?: string;
      content?: string;
      button?: {
        confirm?: string;
        dismiss?: string;
      };
    };
  };
}
```

### CrudItemsChangedEvent

```ts
/**
 * Fired when the `items` property changes.
 */
export type CrudItemsChangedEvent<T> = CustomEvent<{ value: T[] }>;
```

### CrudNewEvent

```ts
/**
 * Fired when user wants to create a new item.
 */
export type CrudNewEvent = CustomEvent<{ item: null }>;
```

### CrudSaveEvent

```ts
/**
 * Fired when user wants to save a new or an existing item.
 */
export type CrudSaveEvent<T> = CustomEvent<{ item: T; new: boolean }>;
```

### CrudSizeChangedEvent

```ts
/**
 * Fired when the `size` property changes.
 */
export type CrudSizeChangedEvent = CustomEvent<{ value: number }>;
```

### GridFilterDefinition

```ts
export interface GridFilterDefinition {
  path: string;
  value: string;
}
```

### GridSorterDefinition

```ts
export interface GridSorterDefinition {
  path: string;
  direction: GridSorterDirection;
}
```

### GridSorterDirection

```ts
export type GridSorterDirection = 'asc' | 'desc' | null;
```