0
# Layout Components
1

2
Layout components provide the structural foundation for organizing and arranging content in Vaadin applications. These components handle responsive behavior, flexible layouts, and application structure.
3

4
## Capabilities
5

6
### App Layout
7

8
Main application layout component providing navigation drawer, header, and content areas with responsive behavior.
9

10
```typescript { .api }
11
/**
12
 * Main application layout with drawer navigation and header
13
 * Provides responsive navigation patterns for web applications
14
 */
15
interface AppLayout extends HTMLElement {
16
  /** Controls drawer visibility (open/closed) */
17
  drawerOpened: boolean;
18
  /** Overlay mode for mobile responsive behavior */
19
  overlay: boolean;
20
  /** Primary section placement: navbar or drawer */
21
  primarySection: 'navbar' | 'drawer';
22

23
  /** Open the navigation drawer */
24
  openDrawer(): void;
25
  /** Close the navigation drawer */
26
  closeDrawer(): void;
27
}
28

29
/**
30
 * Toggle button for opening/closing drawer navigation
31
 * Usually placed in the application header
32
 */
33
interface DrawerToggle extends HTMLElement {
34
  /** Accessibility label for the toggle button */
35
  ariaLabel: string;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import '@vaadin/app-layout';
43
import '@vaadin/app-layout/vaadin-drawer-toggle';
44

45
// Create app layout structure
46
const layout = document.createElement('vaadin-app-layout');
47

48
// Add navigation drawer toggle
49
const toggle = document.createElement('vaadin-drawer-toggle');
50
toggle.slot = 'navbar touch-optimized';
51
layout.appendChild(toggle);
52

53
// Add drawer content
54
const nav = document.createElement('nav');
55
nav.slot = 'drawer';
56
nav.innerHTML = `
57
  <ul>
58
    <li><a href="/dashboard">Dashboard</a></li>
59
    <li><a href="/users">Users</a></li>
60
  </ul>
61
`;
62
layout.appendChild(nav);
63

64
// Add main content
65
const main = document.createElement('main');
66
main.slot = 'content';
67
main.innerHTML = '<h1>Welcome to Dashboard</h1>';
68
layout.appendChild(main);
69

70
// Control drawer programmatically
71
layout.drawerOpened = true; // Open drawer
72
layout.closeDrawer(); // Close drawer
73
```
74

75
### Horizontal Layout
76

77
Flexbox-based horizontal layout component for arranging items in a row.
78

79
```typescript { .api }
80
/**
81
 * Horizontal flexbox layout container
82
 * Arranges children in a horizontal row with flex properties
83
 */
84
interface HorizontalLayout extends HTMLElement {
85
  /** Theme variant for spacing and alignment */
86
  theme: string;
87
}
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import '@vaadin/horizontal-layout';
94

95
const horizontalLayout = document.createElement('vaadin-horizontal-layout');
96
horizontalLayout.theme = 'spacing padding';
97

98
// Add items to horizontal layout
99
const button1 = document.createElement('vaadin-button');
100
button1.textContent = 'First';
101

102
const button2 = document.createElement('vaadin-button');
103
button2.textContent = 'Second';
104

105
horizontalLayout.appendChild(button1);
106
horizontalLayout.appendChild(button2);
107
```
108

109
### Vertical Layout
110

111
Flexbox-based vertical layout component for arranging items in a column.
112

113
```typescript { .api }
114
/**
115
 * Vertical flexbox layout container
116
 * Arranges children in a vertical column with flex properties
117
 */
118
interface VerticalLayout extends HTMLElement {
119
  /** Theme variant for spacing and alignment */
120
  theme: string;
121
}
122
```
123

124
### Form Layout
125

126
Responsive form layout that automatically adjusts field arrangement based on viewport size.
127

128
```typescript { .api }
129
/**
130
 * Responsive form layout with configurable breakpoints
131
 * Automatically arranges form fields based on screen size
132
 */
133
interface FormLayout extends HTMLElement {
134
  /** Array of responsive step configurations */
135
  responsiveSteps: FormLayoutResponsiveStep[];
136
}
137

138
/**
139
 * Individual form item container within FormLayout
140
 * Provides consistent spacing and alignment for form fields
141
 */
142
interface FormItem extends HTMLElement {
143
  /** Number of columns this item should span */
144
  colspan: number;
145
}
146

147
/**
148
 * Configuration for responsive form layout behavior
149
 */
150
interface FormLayoutResponsiveStep {
151
  /** Minimum viewport width for this step */
152
  minWidth?: string;
153
  /** Number of columns at this breakpoint */
154
  columns: number;
155
  /** Label positioning: beside fields or above */
156
  labelsPosition?: 'aside' | 'top';
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import '@vaadin/form-layout';
164

165
const formLayout = document.createElement('vaadin-form-layout');
166

167
// Configure responsive steps
168
formLayout.responsiveSteps = [
169
  { columns: 1 }, // Mobile: single column
170
  { minWidth: '500px', columns: 2 }, // Tablet: two columns
171
  { minWidth: '800px', columns: 3, labelsPosition: 'top' } // Desktop: three columns
172
];
173

174
// Add form fields
175
const firstName = document.createElement('vaadin-text-field');
176
firstName.label = 'First Name';
177

178
const lastName = document.createElement('vaadin-text-field');
179
lastName.label = 'Last Name';
180

181
const email = document.createElement('vaadin-email-field');
182
email.label = 'Email';
183

184
formLayout.appendChild(firstName);
185
formLayout.appendChild(lastName);
186
formLayout.appendChild(email);
187
```
188

189
### Split Layout
190

191
Resizable split layout for dividing content areas with user-adjustable splitter.
192

193
```typescript { .api }
194
/**
195
 * Resizable split layout component
196
 * Divides content into two panes with adjustable splitter
197
 */
198
interface SplitLayout extends HTMLElement {
199
  /** Split orientation: horizontal or vertical */
200
  orientation: 'horizontal' | 'vertical';
201
  /** Splitter position as percentage (0-100) */
202
  splitterPosition: number;
203

204
  /** Set splitter position programmatically */
205
  setSplitterPosition(position: number, resize?: boolean): void;
206
}
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
import '@vaadin/split-layout';
213

214
const splitLayout = document.createElement('vaadin-split-layout');
215
splitLayout.orientation = 'horizontal';
216
splitLayout.splitterPosition = 30; // 30% for first pane
217

218
// Add content to split panes
219
const leftPanel = document.createElement('div');
220
leftPanel.innerHTML = '<h3>Navigation</h3><ul><li>Item 1</li></ul>';
221

222
const rightPanel = document.createElement('div');
223
rightPanel.innerHTML = '<h3>Content</h3><p>Main content area</p>';
224

225
splitLayout.appendChild(leftPanel);
226
splitLayout.appendChild(rightPanel);
227

228
// Listen for splitter changes
229
splitLayout.addEventListener('splitter-dragend', (e) => {
230
  console.log('New position:', splitLayout.splitterPosition);
231
});
232
```
233

234
### Scroller
235

236
Custom scrollable container with enhanced scroll behavior and virtual scrolling support.
237

238
```typescript { .api }
239
/**
240
 * Enhanced scrollable container
241
 * Provides custom scrolling behavior and virtual scrolling
242
 */
243
interface Scroller extends HTMLElement {
244
  /** Scroll direction restriction */
245
  scrollDirection: 'vertical' | 'horizontal' | 'both';
246

247
  /** Scroll to specific element or index */
248
  scrollToIndex(index: number): void;
249
  /** Scroll to specific element */
250
  scrollToElement(element: Element): void;
251
}
252
```
253

254
## Common Layout Patterns
255

256
### Application Shell
257

258
```typescript
259
// Complete app layout structure
260
const createAppShell = () => {
261
  const layout = document.createElement('vaadin-app-layout');
262

263
  // Header with navigation toggle
264
  const header = document.createElement('header');
265
  header.slot = 'navbar';
266

267
  const toggle = document.createElement('vaadin-drawer-toggle');
268
  toggle.setAttribute('aria-label', 'Menu toggle');
269
  header.appendChild(toggle);
270

271
  const title = document.createElement('h1');
272
  title.textContent = 'My Application';
273
  header.appendChild(title);
274

275
  layout.appendChild(header);
276

277
  // Navigation drawer
278
  const nav = document.createElement('nav');
279
  nav.slot = 'drawer';
280
  // Add navigation items...
281
  layout.appendChild(nav);
282

283
  return layout;
284
};
285
```
286

287
### Responsive Form
288

289
```typescript
290
// Form with responsive layout and validation
291
const createResponsiveForm = () => {
292
  const formLayout = document.createElement('vaadin-form-layout');
293

294
  formLayout.responsiveSteps = [
295
    { columns: 1 },
296
    { minWidth: '600px', columns: 2 },
297
    { minWidth: '900px', columns: 3 }
298
  ];
299

300
  // Add form fields with proper validation
301
  const fields = [
302
    { type: 'text-field', label: 'First Name', required: true },
303
    { type: 'text-field', label: 'Last Name', required: true },
304
    { type: 'email-field', label: 'Email', required: true },
305
    { type: 'tel-field', label: 'Phone' },
306
    { type: 'date-picker', label: 'Date of Birth' }
307
  ];
308

309
  fields.forEach(fieldConfig => {
310
    const field = document.createElement(`vaadin-${fieldConfig.type}`);
311
    field.label = fieldConfig.label;
312
    if (fieldConfig.required) field.required = true;
313
    formLayout.appendChild(field);
314
  });
315

316
  return formLayout;
317
};
318
```