> Markdown version of [Columns](https://vaadin.com/docs/next/components/grid/columns). Section index: [llms.txt](https://vaadin.com/docs/next/components/llms.txt)
# Grid Columns
Column alignment, freezing (i.e. fixed positioning), grouping, headers and footers, visibility, and width can be configured. Users can be allowed to resize and reorder columns.
## Column Alignment
Three different column alignments are supported: left, which is the default; center; and right.
Right alignment is useful when comparing numeric values, as it helps with readability and scannability. Notice how the *Amount* column in the example here aligns the euro values to the right. Those values would be difficult to scan visually if they were left aligned or centered. Tabular numbers — if the font offers them — or a monospace font could be used to further improve digit alignment.
**Lit** — `grid-column-alignment.ts`
```typescript
html`${this.randomDate()}`, [])}
>
html`
${this.randomAmount()}
`,
[]
)}
>
```
**Flow** — `GridColumnAlignment.java`
```java
grid.addColumn(GridColumnAlignment::generateRandomAmountText)
.setHeader("Amount").setTextAlign(ColumnTextAlign.END);
```
**React** — `grid-column-alignment.tsx`
```tsx
```
## Column Freezing
Columns and column groups can be frozen — made *sticky* — to exclude them from horizontally scrolling a grid. This can be useful for keeping the most important columns always visible in a grid that contains so many columns they might otherwise scroll out of view. Freezing columns at the end of the grid is useful, for example, for keeping row actions always visible.
In the example here, try scrolling the data to the right and back left. Notice that the name of each person is stationary so that you can see easily which data relates to which person as you scroll. The *Edit* button at the end also remains in place so that it’s available at any point while scrolling.
**Lit** — `grid-column-freezing.ts`
```typescript
(
(person) => html`${person.firstName} ${person.lastName}`,
[]
)}
>
html`Edit`,
[]
)}
>
```
**Flow** — `GridColumnFreezing.java`
```java
grid.addColumn(createPersonRenderer()).setHeader("Name").setFrozen(true)
.setAutoWidth(true).setFlexGrow(0);
grid.addColumn(createActionRenderer()).setFrozenToEnd(true)
.setAutoWidth(true).setFlexGrow(0);
```
**React** — `grid-column-freezing.tsx`
```tsx
```
Although it’s technically possible to freeze any column, it should be used primarily to freeze columns at the start or end of the grid, leaving the remaining columns unfrozen.
## Column Grouping
It’s possible to group columns. They share a common header and footer. Use this feature to better visualize and organize related or hierarchical data.
In the example below, the first and last names are grouped under *Name*. Whereas, the street address, the city, and so forth are grouped under *Address*.
**Lit** — `grid-column-grouping.ts`
```typescript
@customElement('grid-column-grouping')
export class Example extends LitElement {
protected override createRenderRoot() {
const root = super.createRenderRoot();
applyTheme(root);
return root;
}
@state()
private items: Person[] = [];
protected override async firstUpdated() {
const { people } = await getPeople();
this.items = people;
}
protected override render() {
return html`
`;
}
}
```
**Flow** — `GridColumnGrouping.java`
```java
Grid grid = new Grid<>(Person.class, false);
Grid.Column firstNameColumn = grid
.addColumn(Person::getFirstName).setHeader("First name");
Grid.Column lastNameColumn = grid.addColumn(Person::getLastName)
.setHeader("Last name");
Grid.Column streetColumn = grid
.addColumn(person -> person.getAddress().getStreet())
.setHeader("Street");
Grid.Column cityColumn = grid
.addColumn(person -> person.getAddress().getCity())
.setHeader("City");
Grid.Column zipColumn = grid
.addColumn(person -> person.getAddress().getZip())
.setHeader("Zip");
Grid.Column stateColumn = grid
.addColumn(person -> person.getAddress().getState())
.setHeader("State");
HeaderRow headerRow = grid.prependHeaderRow();
headerRow.join(firstNameColumn, lastNameColumn).setText("Name");
headerRow.join(streetColumn, cityColumn, zipColumn, stateColumn)
.setText("Address");
```
**React** — `grid-column-grouping.tsx`
```tsx
const items = useSignal([]);
useEffect(() => {
getPeople().then(({ people }) => {
items.value = people;
});
}, []);
return (
);
```
## Column Headers & Footers
Each column has a customizable header and footer. A basic column header shows the name in plain text. Footers are empty by default and therefore hidden. However, if you add content for the footer, it becomes visible. Incidentally, both the header and footer can contain rich content and components — notice the header and footer in the example here.
**Lit** — `grid-column-header-footer.ts`
```typescript
@state()
private items: Person[] = [];
protected override async firstUpdated() {
const { people } = await getPeople();
this.items = people.map((person) => ({
...person,
displayName: `${person.firstName} ${person.lastName}`,
}));
}
protected override render() {
return html`
html`200 total members`, [])}
>
html`102 subscribers`, [])}
>
html`103 regular, 71 premium , 66 VIP`, [])}
>
`;
}
private subscriberHeaderRenderer = () => html`
Subscriber
`;
private subscriberRenderer: GridColumnBodyLitRenderer = (person) =>
html`${person.subscriber ? 'Yes' : 'No'}`;
private membershipHeaderRenderer = () => html`
Membership
`;
```
**Flow** — `GridColumnHeaderFooter.java`
```java
List people = DataService.getPeople();
Grid grid = new Grid<>(Person.class, false);
grid.addColumn(Person::getFullName).setHeader("Name")
.setFooter(String.format("%s total members", people.size()));
grid.addColumn(person -> person.isSubscriber() ? "Yes" : "No")
.setHeader(createSubscriberHeader())
.setFooter(createSubscriberFooterText(people));
grid.addColumn(Person::getMembership)
.setHeader(createMembershipHeader())
.setFooter(createMembershipFooterText(people));
...
private static Component createSubscriberHeader() {
Span span = new Span("Subscriber");
Icon icon = VaadinIcon.INFO_CIRCLE.create();
icon.getElement().setAttribute("title",
"Subscribers are paying customers");
icon.getStyle().set("--vaadin-icon-visual-size", "80%").set("color",
"var(--vaadin-text-color-secondary)");
HorizontalLayout layout = new HorizontalLayout(span, icon);
layout.setAlignItems(FlexComponent.Alignment.CENTER);
layout.setSpacing("var(--vaadin-gap-xs)");
return layout;
}
private static String createSubscriberFooterText(List people) {
long subscriberCount = people.stream().filter(Person::isSubscriber)
.count();
return String.format("%s subscribers", subscriberCount);
}
private static Component createMembershipHeader() {
Span span = new Span("Membership");
Icon icon = VaadinIcon.INFO_CIRCLE.create();
icon.getElement().setAttribute("title",
"Membership levels determines which features a client has access to");
icon.getStyle().set("--vaadin-icon-visual-size", "80%").set("color",
"var(--vaadin-text-color-secondary)");
HorizontalLayout layout = new HorizontalLayout(span, icon);
layout.setAlignItems(FlexComponent.Alignment.CENTER);
layout.setSpacing("var(--vaadin-gap-xs)");
return layout;
}
private static String createMembershipFooterText(List people) {
long regularCount = people.stream()
.filter(person -> "Regular".equals(person.getMembership()))
.count();
long premiumCount = people.stream()
.filter(person -> "Premium".equals(person.getMembership()))
.count();
long vipCount = people.stream()
.filter(person -> "VIP".equals(person.getMembership())).count();
return String.format("%s regular, %s premium, %s VIP", regularCount,
premiumCount, vipCount);
}
```
**React** — `grid-column-header-footer.tsx`
```tsx
function SubscriberHeader() {
return (
Subscriber
);
}
function MembershipHeader() {
return (
Membership
);
}
function subscriberRenderer({ item }: { item: Person }) {
return {item.subscriber ? 'Yes' : 'No'};
}
function Example() {
const items = useSignal([]);
useEffect(() => {
getPeople().then(({ people }) => {
items.value = people.map((person) => ({
...person,
displayName: `${person.firstName} ${person.lastName}`,
}));
});
}, []);
return (
200 total members} />
}
footer={102 subscribers}
renderer={subscriberRenderer}
/>
}
footer={103 regular, 71 premium , 66 VIP}
/>
);
}
```
## Column Visibility
When you want, columns and column groups can be hidden. You can provide the user with a menu for toggling column visibilities, for example, using Popover. Allowing the user to hide columns is useful when only a subset of the columns is relevant to their task, and if there are plenty of columns.
**Lit** — `popover-anchored-dialog.ts`
```html
${this.gridColumns.map(
(column) => html`
`
)}
```
**Flow** — `PopoverAnchoredDialog.java`
```java
Grid grid = new Grid<>(Person.class, false);
grid.addColumn(Person::getFirstName).setKey("firstName")
.setHeader("First name");
grid.addColumn(Person::getLastName).setKey("lastName")
.setHeader("Last name");
grid.addColumn(Person::getEmail).setKey("email").setHeader("Email");
grid.addColumn(person -> person.getAddress().getPhone()).setKey("phone")
.setHeader("Phone");
grid.addColumn(new LocalDateRenderer<>(
PopoverAnchoredDialog::getPersonBirthday, "yyyy-MM-dd"))
.setKey("birthday").setHeader("Birthday");
grid.addColumn(Person::getProfession).setKey("profession")
.setHeader("Profession");
CheckboxGroup group = new CheckboxGroup<>();
group.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);
group.getStyle().set("padding", "0").set("margin",
"var(--vaadin-gap-s) 0");
group.setItems(columns);
group.setItemLabelGenerator((item) -> {
String label = StringUtils
.join(StringUtils.splitByCharacterTypeCamelCase(item), " ");
return StringUtils.capitalize(label.toLowerCase());
});
group.addValueChangeListener((e) -> {
columns.stream().forEach((key) -> {
grid.getColumnByKey(key).setVisible(e.getValue().contains(key));
});
});
```
**React** — `popover-anchored-dialog.tsx`
```tsx
{columns.value.map((item) => (
))}
```
Column visibility can also be adjusted based on the Grid’s width. For example, when the Grid is narrow, you can hide the individual columns and show a single column that combines their content.
The example below toggles the columns whenever the Grid is resized. In Flow, the width comes from the Grid’s [size signal](https://vaadin.com/docs/next/flow/ui-state/building-ui.md#element-size-signal) (since V25.3), and in Lit and React from a `ResizeObserver`. Try dragging the split handle to make the Grid narrower and see the columns change.
**Lit** — `grid-responsive-columns.ts`
```typescript
const BREAKPOINT_PX = 500;
@customElement('grid-responsive-columns')
export class Example extends LitElement {
protected override createRenderRoot() {
const root = super.createRenderRoot();
applyTheme(root);
return root;
}
@query('vaadin-grid')
private grid!: Grid;
@state()
private items: Person[] = [];
@state()
private wide = true;
// Toggles the columns whenever the grid is resized
private resizeObserver = new ResizeObserver(([entry]) => {
this.wide = entry.contentRect.width >= BREAKPOINT_PX;
});
override connectedCallback() {
super.connectedCallback();
this.updateComplete.then(() => this.resizeObserver.observe(this.grid));
}
override disconnectedCallback() {
super.disconnectedCallback();
this.resizeObserver.disconnect();
}
protected override firstUpdated() {
getPeople().then(({ people }) => {
this.items = people;
});
}
protected override render() {
return html`
`;
}
private employeeRenderer: GridColumnBodyLitRenderer = (person) => html`
${person.firstName} ${person.lastName}
${person.email}
`;
private nameRenderer: GridColumnBodyLitRenderer = (person) =>
html`${person.firstName} ${person.lastName}`;
}
```
**Flow** — `GridResponsiveColumns.java`
```java
private static final int BREAKPOINT_PX = 500;
public GridResponsiveColumns() {
Grid grid = new Grid<>(DataService.getPeople());
// A single column that combines the content when the grid is narrow
String template = "${item.name}
${item.email}";
Grid.Column combinedColumn = grid
.addColumn(LitRenderer. of(template)
.withProperty("name", Person::getFullName)
.withProperty("email", Person::getEmail))
.setHeader("Employee");
// Separate columns for when the grid is wide
List> wideColumns = List.of(
grid.addColumn(Person::getFullName).setHeader("Name"),
grid.addColumn(Person::getProfession).setHeader("Profession"),
grid.addColumn(Person::getEmail).setHeader("Email"));
// The effect runs when the grid is attached and again whenever the
// grid is resized
Signal size = grid.getElement().sizeSignal();
Signal.effect(grid, () -> {
int width = size.get().width();
// The width is 0 until the browser has reported the size. Keep
// all columns hidden until then.
boolean sizeKnown = width > 0;
boolean wide = width >= BREAKPOINT_PX;
combinedColumn.setVisible(sizeKnown && !wide);
wideColumns.forEach(column -> column.setVisible(sizeKnown && wide));
});
}
```
**React** — `grid-responsive-columns.tsx`
```tsx
const BREAKPOINT_PX = 500;
const employeeRenderer = ({ item: person }: { item: Person }) => (
<>
{person.firstName} {person.lastName}
{person.email}
);
const nameRenderer = ({ item: person }: { item: Person }) => (
<>
{person.firstName} {person.lastName}
);
function Example() {
const gridRef = useRef(null);
const items = useSignal([]);
const wide = useSignal(true);
useEffect(() => {
getPeople().then(({ people }) => {
items.value = people;
});
}, []);
// Toggles the columns whenever the grid is resized
useEffect(() => {
const resizeObserver = new ResizeObserver(([entry]) => {
wide.value = entry.contentRect.width >= BREAKPOINT_PX;
});
if (gridRef.current) {
resizeObserver.observe(gridRef.current);
}
return () => resizeObserver.disconnect();
}, []);
return (
{/* A single column that combines the content when the grid is narrow */}
{/* Separate columns for when the grid is wide */}
);
}
```
> **Note:** In Flow, the size signal starts at 0 and only gets the real value after the browser has rendered the Grid and reported its width. This means the Grid initially uses the layout for a zero width and may briefly flash before switching to the correct one. If your application’s requirements allow it, consider basing the layout on the [window size signal](https://vaadin.com/docs/next/flow/ui-state/building-ui.md#window-size-signal) instead. Its initial value is already known when the Grid is created, so there is no flash. However, this is less flexible, because the Grid then responds to the browser window rather than to its own container.
## Column Reordering & Resizing
Enabling the user to reorder columns is useful when they want to compare data that isn’t adjacent by default. Grouped columns can only be reordered within their group. Resizing is helpful when a column’s content doesn’t fit and is cut off or varies in length.
Instead of hiding columns as in the earlier example, in the example here the user can resize a truncated column to be able to read it, fully. Try doing that. Hover your mouse pointer over the space on the header row between the *Street* and *City* columns, until the mouse pointer changes to a resizing tool. Then, while holding the left mouse button, pull on the right edge of the *Street* column until you can see all of the street addresses.
**Lit** — `grid-column-reordering-resizing.ts`
```typescript
@customElement('grid-column-reordering-resizing')
export class Example extends LitElement {
protected override createRenderRoot() {
const root = super.createRenderRoot();
applyTheme(root);
return root;
}
@state()
private items: Person[] = [];
protected override async firstUpdated() {
const { people } = await getPeople();
this.items = people;
}
protected override render() {
return html`
`;
}
}
```
**Flow** — `GridColumnReorderingResizing.java`
```java
Grid grid = new Grid<>(Person.class, false);
grid.setColumnReorderingAllowed(true);
Grid.Column firstNameColumn = grid
.addColumn(Person::getFirstName).setHeader("First name")
.setResizable(true);
Grid.Column lastNameColumn = grid.addColumn(Person::getLastName)
.setHeader("Last name").setResizable(true);
Grid.Column streetColumn = grid
.addColumn(person -> person.getAddress().getStreet())
.setHeader("Street").setResizable(true);
Grid.Column cityColumn = grid
.addColumn(person -> person.getAddress().getCity())
.setHeader("City").setResizable(true);
Grid.Column zipColumn = grid
.addColumn(person -> person.getAddress().getZip())
.setHeader("Zip").setResizable(true);
Grid.Column stateColumn = grid
.addColumn(person -> person.getAddress().getState())
.setHeader("State").setResizable(true);
HeaderRow headerRow = grid.prependHeaderRow();
headerRow.join(firstNameColumn, lastNameColumn).setText("Name");
headerRow.join(streetColumn, cityColumn, zipColumn, stateColumn)
.setText("Address");
```
**React** — `grid-column-reordering-resizing.tsx`
```tsx
const items = useSignal([]);
useEffect(() => {
getPeople().then(({ people }) => {
items.value = people;
});
}, []);
return (
);
```
## Column Width
Unless specified, all columns are the same width. You can set a specific width for any column, though, or allow the Grid to set the width based on the content. Column widths can be fixed or non-fixed, which is the default. Fixed-width columns don’t grow or shrink as the available space changes, while non-fixed-width columns do.
> **Note:** The `em` length unit is a relative setting for font sizes. Don’t use it for column widths. If the font sizes of the header, body or footer cells differ, may cause column widths to be inconsistent, leading to misaligned content. When length relative to the font size is needed, use instead the `rem` length unit — or make sure that the font size is consistent across the cells.
In the following example, the first and last columns have fixed widths. The second column’s width is set to be based on the content, while the third consumes the remaining space.
**Lit** — `grid-column-width.ts`
```typescript
@customElement('grid-column-width')
export class Example extends LitElement {
protected override createRenderRoot() {
const root = super.createRenderRoot();
applyTheme(root);
return root;
}
@state()
private items: Person[] = [];
protected override async firstUpdated() {
const { people } = await getPeople();
this.items = people;
}
protected override render() {
return html`
((item) => html`${item.subscriber ? 'Yes' : 'No'}`, [])}
>
`;
}
}
```
**Flow** — `GridColumnWidth.java`
```java
Grid grid = new Grid<>(Person.class, false);
grid.setSelectionMode(Grid.SelectionMode.MULTI);
grid.addColumn(Person::getFirstName).setHeader("First name")
.setWidth("7rem").setFlexGrow(0);
grid.addColumn(Person::getProfession).setHeader("Profession")
.setAutoWidth(true).setFlexGrow(0);
grid.addColumn(Person::getEmail).setHeader("Email");
grid.addColumn(person -> person.isSubscriber() ? "Yes" : "No")
.setHeader("Has Sub").setWidth("6rem").setFlexGrow(0);
```
**React** — `grid-column-width.tsx`
```tsx
function Example() {
const items = useSignal([]);
useEffect(() => {
getPeople().then(({ people }) => {
items.value = people;
});
}, []);
return (
);
}
```