Docs

Docs

CRUD

CRUD is a component for managing a dataset. It allows for easy Displaying, Editing, Creating, and Deleting of items.
Note
Commercial feature

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

<Crud items={people} include="firstName, lastName, email, profession" />

Columns

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

<Crud
  items={people}
  exclude="lastName, address, id, subscribe, membership, pictureUrl, manager"
/>

Editor

Data is edited using CRUD’s editor UI.

Opening Editor

By default, the editor is opened by clicking the Edit button in the last column. However, this button column can be removed if you want to implement another way to open the editor. For example, you can have it open using a double-click like so:

<Crud
  title="Work in progress"
  include="firstName, lastName, email, profession"
  editedItem={editedItem}
  items={people}
  onEditedItemChanged={onEditedItemChanged}
>
  <Grid slot="grid" onDoubleClick={onDoubleClick}>
    <GridColumn path="firstName" header="First name"></GridColumn>
    <GridColumn path="lastName" header="Last name"></GridColumn>
    <GridColumn path="email" header="Email"></GridColumn>
    <GridColumn path="profession" header="Profession"></GridColumn>
  </Grid>
</Crud>

Editor Position

The editor can be positioned in an overlay, on the side, or at the bottom. The subsections below explain each position.

Overlay

The overlay position, which is the default, renders the editor in a modal overlay. Overlays aren’t constrained to the CRUD’s size. This 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 enough horizontal space to accommodate both the grid and the editor. Use it also when it’s beneficial for the user to see and interact with the grid while the editor is open. Aside positioning is also a good fit for single-column forms.

<Crud
  editorPosition="aside"
  include="firstName, lastName, email, profession"
  items={people}
/>
Note
Grid Width
The opening and closing of an aside editor can affect 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. This occurs typically while editing, when horizontal space is limited, or when a wider editor form is desired.

<Crud
  editorPosition="bottom"
  include="firstName, lastName, email, profession"
  items={people}
/>

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

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

Editor Content

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

const people = usePeople();
const [professions, setProfessions] = useState<String[]>([]);

const responsiveSteps = [
  { minWidth: "0", columns: 1 },
  { minWidth: "30em", columns: 2 },
];

useEffect(() => {
  setProfessions(
    Array.from(new Set(people.map((person) => person.profession))).sort()
  );
}, [people]);

return (
  <Crud include="firstName, lastName, email, profession" items={people}>
    <FormLayout
      slot="form"
      style={{ maxWidth: "480px" }}
      responsiveSteps={responsiveSteps}
    >
      <TextField label="First name" path="firstName" required />
      <TextField label="Last name" path="lastName" required />
      <EmailField colspan="2" label="Email" path="email" required />
      <ComboBox
        colspan="2"
        label="Profession"
        path="profession"
        items={professions}
        required
      />
    </FormLayout>
  </Crud>
);

Editor Actions

The editor contains three Buttons:

  • Delete is used to delete the item, permanently. After the user clicks this button, they’re asked to confirm this action.

  • Cancel closes the editor, unless there are unsaved changes. When there are, the user is asked to either discard the changes or go back to editing.

  • Save saves any changes and closes the editor. This is disabled until there is a change.

Grid Replacement

The default Grid in CRUD is replaceable. This is useful when you wish to customize the Grid. An example might be if you want to place the edit Button in the first column, or to apply tooltips. See Grid documentation for details on configuring grids.

<Crud include="firstName, lastName, email, profession" items={people}>
  <Grid slot="grid">
    <CrudEditColumn />
    <GridColumn path="firstName" header="First name" />
    <GridColumn path="lastName" header="Last name" />
    <GridColumn path="email" header="Email" />
    <GridColumn path="profession" header="Profession" />
  </Grid>
</Crud>
Note
Edit Column
You need to add explicitly an Edit Column to the replacement Grid to edit items. Also notice that Grid doesn’t have sorting and filtering enabled by default.

Toolbar

The New item Button in CRUD’s toolbar creates new items. 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.

<Crud include="firstName, lastName, email, profession" items={people}>
  <div slot="toolbar">
    Total: <b>{people.length}</b> employees
  </div>
</Crud>

Hiding the Toolbar

Sometimes the toolbar isn’t needed. When this is so, you can hide it.

<Crud include="firstName, lastName" items={people} noToolbar />
Component Usage Recommendation

Grid Pro

Component for showing and editing tabular data.

Grid

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