0
# Vaadin Web Components
1

2
Vaadin Web Components is a comprehensive collection of enterprise-grade web components for building modern business applications. Built with Lit/LitElement, this ecosystem provides 70+ professionally designed, accessible, and themeable components following web standards.
3

4
## Package Information
5

6
- **Package Name**: @vaadin/vaadin
7
- **Package Type**: npm (meta-package)
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @vaadin/vaadin`
10

11
## Core Imports
12

13
The meta-package provides access to all Vaadin components. Import specific components as needed:
14

15
```typescript
16
// Individual component imports
17
import '@vaadin/button';
18
import '@vaadin/text-field';
19
import '@vaadin/grid';
20
import '@vaadin/date-picker';
21

22
// Web components are automatically registered and ready to use
23
```
24

25
For CommonJS:
26

27
```javascript
28
require('@vaadin/button');
29
require('@vaadin/text-field');
30
// Components auto-register when imported
31
```
32

33
## Basic Usage
34

35
```typescript
36
import '@vaadin/button';
37
import '@vaadin/text-field';
38
import '@vaadin/notification';
39

40
// Use components in HTML
41
const textField = document.createElement('vaadin-text-field');
42
textField.label = 'Name';
43
textField.placeholder = 'Enter your name';
44

45
const button = document.createElement('vaadin-button');
46
button.textContent = 'Submit';
47
button.addEventListener('click', () => {
48
  const notification = document.createElement('vaadin-notification');
49
  notification.textContent = `Hello ${textField.value}!`;
50
  notification.open();
51
  document.body.appendChild(notification);
52
});
53

54
document.body.appendChild(textField);
55
document.body.appendChild(button);
56
```
57

58
## Architecture
59

60
Vaadin Web Components follows consistent architectural patterns:
61

62
- **Mixin-based Architecture**: Core functionality provided through mixins (`ElementMixin`, `ThemableMixin`, `FocusMixin`)
63
- **Lit/LitElement Foundation**: All components built on modern Lit library for efficient rendering
64
- **Web Standards**: Native Custom Elements v1, Shadow DOM, and ES Modules
65
- **Accessibility First**: WCAG 2.1 AA compliant with comprehensive keyboard and screen reader support
66
- **Theming System**: Two complete design systems (Lumo and Material Design) with CSS custom properties
67
- **TypeScript Support**: Complete type definitions for all components and APIs
68
- **Event-driven**: Consistent event patterns with both native and custom events
69

70
## Capabilities
71

72
### Layout Components
73

74
Foundation layout components for organizing application structure and content flow.
75

76
```typescript { .api }
77
// App layout with drawer navigation
78
interface AppLayout extends HTMLElement {
79
  drawerOpened: boolean;
80
  overlay: boolean;
81
  primarySection: 'navbar' | 'drawer';
82
  openDrawer(): void;
83
  closeDrawer(): void;
84
}
85

86
// Flexbox layouts
87
interface HorizontalLayout extends HTMLElement {
88
  theme: string;
89
}
90

91
interface VerticalLayout extends HTMLElement {
92
  theme: string;
93
}
94

95
// Responsive form layout
96
interface FormLayout extends HTMLElement {
97
  responsiveSteps: FormLayoutResponsiveStep[];
98
}
99
```
100

101
[Layout Components](./layout.md)
102

103
### Input Components
104

105
Comprehensive form input controls with validation, accessibility, and consistent styling.
106

107
```typescript { .api }
108
// Base field properties shared by all inputs
109
interface FieldMixin {
110
  value: string;
111
  label: string;
112
  placeholder: string;
113
  required: boolean;
114
  readonly: boolean;
115
  disabled: boolean;
116
  invalid: boolean;
117
  errorMessage: string;
118
  helperText: string;
119
  validate(): boolean;
120
  checkValidity(): boolean;
121
  focus(): void;
122
}
123

124
// Text input fields
125
interface TextField extends HTMLElement, FieldMixin {
126
  type: string;
127
  pattern: string;
128
  minlength: number;
129
  maxlength: number;
130
  autocomplete: string;
131
  autocapitalize: string;
132
  autocorrect: string;
133
}
134

135
// Specialized input fields
136
interface EmailField extends TextField {}
137
interface PasswordField extends TextField {
138
  passwordVisible: boolean;
139
}
140
interface NumberField extends TextField {
141
  min: number;
142
  max: number;
143
  step: number;
144
  stepUp(increment?: number): void;
145
  stepDown(decrement?: number): void;
146
}
147
```
148

149
[Input Components](./input.md)
150

151
### Selection Components
152

153
Advanced selection controls including dropdowns, multi-select, and list components.
154

155
```typescript { .api }
156
// Dropdown select
157
interface Select extends HTMLElement {
158
  value: string;
159
  items: SelectItem[];
160
  placeholder: string;
161
  opened: boolean;
162
  open(): void;
163
  close(): void;
164
}
165

166
// Combo box with filtering
167
interface ComboBox extends HTMLElement {
168
  value: string;
169
  selectedItem: object | null;
170
  items: object[];
171
  itemLabelPath: string;
172
  itemValuePath: string;
173
  filteredItems: object[];
174
  loading: boolean;
175
  allowCustomValue: boolean;
176
  filter: string;
177
  open(): void;
178
  close(): void;
179
  clearFilter(): void;
180
}
181

182
// Radio group for exclusive selection
183
interface RadioGroup extends HTMLElement {
184
  value: string;
185
  label: string;
186
  required: boolean;
187
  disabled: boolean;
188
  validate(): boolean;
189
}
190
```
191

192
[Selection Components](./selection.md)
193

194
### Data Components
195

196
High-performance data display and manipulation components for handling large datasets.
197

198
```typescript { .api }
199
// Advanced data grid
200
interface Grid extends HTMLElement {
201
  items: object[];
202
  selectedItems: object[];
203
  activeItem: object | null;
204
  detailsOpenedItems: object[];
205
  columnReorderingAllowed: boolean;
206
  multiSort: boolean;
207
  selectItem(item: object): void;
208
  deselectItem(item: object): void;
209
  selectAll(): void;
210
  deselectAll(): void;
211
  expandItem(item: object): void;
212
  collapseItem(item: object): void;
213
  clearCache(): void;
214
}
215

216
// Virtualized list for performance
217
interface VirtualList extends HTMLElement {
218
  items: object[];
219
  renderer: (root: HTMLElement, list: VirtualList, index: number, item: object) => void;
220
  scrollToIndex(index: number): void;
221
}
222
```
223

224
[Data Components](./data.md)
225

226
### Navigation Components
227

228
Navigation and organizational components for structuring user interfaces.
229

230
```typescript { .api }
231
// Tab navigation
232
interface Tabs extends HTMLElement {
233
  selected: number;
234
  orientation: 'horizontal' | 'vertical';
235
  selectIndex(index: number): void;
236
}
237

238
// Accordion panels
239
interface Accordion extends HTMLElement {
240
  opened: number | null;
241
  items: AccordionPanel[];
242
  open(index: number): void;
243
  close(): void;
244
}
245

246
// Side navigation
247
interface SideNav extends HTMLElement {
248
  collapsible: boolean;
249
  collapsed: boolean;
250
}
251

252
// Menu bar with dropdowns
253
interface MenuBar extends HTMLElement {
254
  items: MenuBarItem[];
255
  opened: boolean;
256
  close(): void;
257
}
258
```
259

260
[Navigation Components](./navigation.md)
261

262
### Dialog Components
263

264
Modal dialogs, overlays, and notification components for user interactions.
265

266
```typescript { .api }
267
// Modal dialog
268
interface Dialog extends HTMLElement {
269
  opened: boolean;
270
  modeless: boolean;
271
  draggable: boolean;
272
  resizable: boolean;
273
  open(): void;
274
  close(): void;
275
}
276

277
// Toast notifications
278
interface Notification extends HTMLElement {
279
  opened: boolean;
280
  duration: number;
281
  position: NotificationPosition;
282
  open(): void;
283
  close(): void;
284
}
285

286
// Confirmation dialog
287
interface ConfirmDialog extends HTMLElement {
288
  opened: boolean;
289
  header: string;
290
  message: string;
291
  confirmText: string;
292
  cancelText: string;
293
  open(): void;
294
  close(): void;
295
}
296
```
297

298
[Dialog Components](./dialogs.md)
299

300
### Content Components
301

302
Display and presentation components for rich content and media.
303

304
```typescript { .api }
305
// Interactive button
306
interface Button extends HTMLElement {
307
  theme: string;
308
  disabled: boolean;
309
  click(): void;
310
  focus(): void;
311
}
312

313
// Content card
314
interface Card extends HTMLElement {
315
  theme: string;
316
}
317

318
// User avatar
319
interface Avatar extends HTMLElement {
320
  name: string;
321
  abbr: string;
322
  img: string;
323
  colorIndex: number;
324
}
325

326
// Progress indicator
327
interface ProgressBar extends HTMLElement {
328
  value: number;
329
  min: number;
330
  max: number;
331
  indeterminate: boolean;
332
}
333

334
// Message input for chat
335
interface MessageInput extends HTMLElement {
336
  value: string;
337
  disabled: boolean;
338
  focus(): void;
339
}
340

341
// Cookie consent banner
342
interface CookieConsent extends HTMLElement {
343
  position: string;
344
  message: string;
345
  show(): void;
346
  hide(): void;
347
}
348
```
349

350
[Content Components](./content.md)
351

352
### Date/Time Components
353

354
Specialized components for date and time selection with internationalization support.
355

356
```typescript { .api }
357
// Date picker
358
interface DatePicker extends HTMLElement {
359
  value: string; // ISO date format
360
  min: string;
361
  max: string;
362
  opened: boolean;
363
  i18n: DatePickerI18n;
364
  open(): void;
365
  close(): void;
366
  validate(): boolean;
367
}
368

369
// Time picker
370
interface TimePicker extends HTMLElement {
371
  value: string; // HH:mm format
372
  min: string;
373
  max: string;
374
  step: number; // seconds
375
  validate(): boolean;
376
}
377

378
// Combined date-time picker
379
interface DateTimePicker extends HTMLElement {
380
  value: string; // ISO datetime format
381
  datePlaceholder: string;
382
  timePlaceholder: string;
383
  validate(): boolean;
384
}
385
```
386

387
[Date/Time Components](./datetime.md)
388

389
### Professional Components
390

391
Advanced commercial components for enterprise applications (Pro subscription required).
392

393
```typescript { .api }
394
// Professional grid with inline editing
395
interface GridPro extends Grid {
396
  editOnClick: boolean;
397
  startEdit(item: object, column: GridProEditColumn): void;
398
  stopEdit(cancel?: boolean): void;
399
}
400

401
// Rich text editor
402
interface RichTextEditor extends HTMLElement {
403
  value: string; // Delta format
404
  htmlValue: string;
405
  readonly: boolean;
406
  focus(): void;
407
}
408

409
// Interactive charts
410
interface Chart extends HTMLElement {
411
  options: HighchartsOptions;
412
  type: string;
413
  categories: string[];
414
  update(): void;
415
}
416
```
417

418
[Professional Components](./pro.md)
419

420
## Type Definitions
421

422
```typescript { .api }
423
// Common event types
424
type CustomEventMap<T> = {
425
  [K in keyof T as `${string & K}-changed`]: CustomEvent<{ value: T[K] }>;
426
};
427

428
// Layout types
429
interface FormLayoutResponsiveStep {
430
  minWidth?: string;
431
  columns: number;
432
  labelsPosition?: 'aside' | 'top';
433
}
434

435
// Selection types
436
interface SelectItem {
437
  label: string;
438
  value: string;
439
  disabled?: boolean;
440
  component?: string;
441
}
442

443
// Validation types
444
interface ValidationResult {
445
  isValid: boolean;
446
  property: string;
447
  validator: string;
448
  message: string;
449
}
450

451
// Theme variants
452
type ThemeVariant =
453
  | 'small' | 'large'
454
  | 'primary' | 'secondary' | 'tertiary'
455
  | 'success' | 'error' | 'contrast'
456
  | 'icon' | 'contained' | 'outlined';
457

458
// Notification positions
459
type NotificationPosition =
460
  | 'top-start' | 'top-center' | 'top-end'
461
  | 'middle'
462
  | 'bottom-start' | 'bottom-center' | 'bottom-end';
463

464
// Date picker internationalization
465
interface DatePickerI18n {
466
  monthNames: string[];
467
  weekdays: string[];
468
  weekdaysShort: string[];
469
  firstDayOfWeek: number;
470
  today: string;
471
  cancel: string;
472
  formatTitle?: (monthName: string, fullYear: number) => string;
473
  formatDate?: (date: Date) => string;
474
  parseDate?: (text: string) => Date | undefined;
475
}
476
```