or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-vaadin--web-components

A comprehensive monorepo containing 70+ high-quality web components for business web applications built with modern web standards

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/vaadin-web-components@24.9.x

To install, run

npx @tessl/cli install tessl/npm-vaadin--web-components@24.9.0

Vaadin Web Components

Vaadin Web Components is a comprehensive monorepo containing 70+ high-quality web components for business web applications. Built with modern web standards including Lit and Polymer, these components provide a complete UI toolkit covering layout, input controls, data presentation, navigation, and specialized business functionality.

Package Information

Package Name: vaadin-web-components
Package Type: npm (monorepo)
Language: JavaScript/TypeScript
Installation: Components are installed individually, e.g., npm install @vaadin/grid
License: Apache-2.0 (Core), Commercial (Pro)

Core Imports

Components are imported individually from their respective packages:

// ES Modules
import '@vaadin/grid/vaadin-grid.js';
import '@vaadin/button/vaadin-button.js';
import '@vaadin/text-field/vaadin-text-field.js';

For TypeScript:

import '@vaadin/grid';
import '@vaadin/button';
import '@vaadin/text-field';

Basic Usage

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Vaadin Components Example</title>
  </head>
  <body>
    <!-- Use web components in HTML -->
    <vaadin-grid column-reordering-allowed multi-sort>
      <vaadin-grid-selection-column auto-select frozen></vaadin-grid-selection-column>
      <vaadin-grid-sort-column width="9rem" path="firstName"></vaadin-grid-sort-column>
      <vaadin-grid-sort-column width="9rem" path="lastName"></vaadin-grid-sort-column>
      <vaadin-grid-column width="9rem" path="address.city"></vaadin-grid-column>
    </vaadin-grid>

    <vaadin-button theme="primary">Click me</vaadin-button>
    <vaadin-text-field label="Enter text" placeholder="Type here..."></vaadin-text-field>

    <script type="module">
      // Import component modules to register custom elements
      import '@vaadin/grid/vaadin-grid.js';
      import '@vaadin/grid/vaadin-grid-selection-column.js';
      import '@vaadin/grid/vaadin-grid-sort-column.js';
      import '@vaadin/button/vaadin-button.js';
      import '@vaadin/text-field/vaadin-text-field.js';

      // Configure components programmatically
      const grid = document.querySelector('vaadin-grid');
      grid.items = [
        { firstName: 'John', lastName: 'Doe', address: { city: 'New York' }},
        { firstName: 'Jane', lastName: 'Smith', address: { city: 'London' }}
      ];
    </script>
  </body>
</html>

Architecture

The Vaadin Web Components monorepo is organized around several key architectural principles:

Individual Packages: Each component is published as a separate npm package under the @vaadin namespace
Shared Dependencies: Common utilities and base classes are shared across components through base packages
Theme System: Comprehensive theming through Lumo and Material design systems
Web Standards: Built on Web Components standards (Custom Elements, Shadow DOM, HTML Templates)
Framework Agnostic: Can be used with any frontend framework or vanilla JavaScript
Accessibility First: ARIA compliance and keyboard navigation built into all components
TypeScript Support: Full TypeScript definitions for all components

The repository uses Lerna for monorepo management and includes shared development tooling for building, testing, and documentation generation across all component packages.

Capabilities

Layout Components

Structural components for organizing application layouts and content.

// App Layout - Main application structure
import '@vaadin/app-layout/vaadin-app-layout.js';
import '@vaadin/app-layout/vaadin-drawer-toggle.js';

// Flexbox layouts
import '@vaadin/horizontal-layout/vaadin-horizontal-layout.js';
import '@vaadin/vertical-layout/vaadin-vertical-layout.js';

// Advanced layouts
import '@vaadin/split-layout/vaadin-split-layout.js';
import '@vaadin/form-layout/vaadin-form-layout.js';
import '@vaadin/master-detail-layout/vaadin-master-detail-layout.js';

Data Input Components

Form controls and input components for user interaction.

// Text inputs
import '@vaadin/text-field/vaadin-text-field.js';
import '@vaadin/text-area/vaadin-text-area.js';
import '@vaadin/password-field/vaadin-password-field.js';
import '@vaadin/email-field/vaadin-email-field.js';

// Numeric inputs
import '@vaadin/number-field/vaadin-number-field.js';
import '@vaadin/integer-field/vaadin-integer-field.js';

// Date and time
import '@vaadin/date-picker/vaadin-date-picker.js';
import '@vaadin/time-picker/vaadin-time-picker.js';
import '@vaadin/date-time-picker/vaadin-date-time-picker.js';

// Selection controls
import '@vaadin/checkbox/vaadin-checkbox.js';
import '@vaadin/checkbox-group/vaadin-checkbox-group.js';
import '@vaadin/radio-group/vaadin-radio-group.js';
import '@vaadin/combo-box/vaadin-combo-box.js';
import '@vaadin/multi-select-combo-box/vaadin-multi-select-combo-box.js';
import '@vaadin/select/vaadin-select.js';

// File upload
import '@vaadin/upload/vaadin-upload.js';

// Custom fields
import '@vaadin/custom-field/vaadin-custom-field.js';

Data Display Components

Components for presenting and organizing data.

// Data grid
import '@vaadin/grid/vaadin-grid.js';
import '@vaadin/grid/vaadin-grid-column.js';
import '@vaadin/grid/vaadin-grid-selection-column.js';
import '@vaadin/grid/vaadin-grid-sort-column.js';
import '@vaadin/grid/vaadin-grid-tree-column.js';

// Lists
import '@vaadin/virtual-list/vaadin-virtual-list.js';
import '@vaadin/list-box/vaadin-list-box.js';
import '@vaadin/item/vaadin-item.js';

// Cards and content
import '@vaadin/card/vaadin-card.js';
import '@vaadin/details/vaadin-details.js';
import '@vaadin/accordion/vaadin-accordion.js';
import '@vaadin/accordion/vaadin-accordion-panel.js';

// Progress indicators
import '@vaadin/progress-bar/vaadin-progress-bar.js';

// Markdown rendering
import '@vaadin/markdown/vaadin-markdown.js';

Navigation Components

Components for application navigation and user interface structure.

// Tab navigation
import '@vaadin/tabs/vaadin-tabs.js';
import '@vaadin/tabs/vaadin-tab.js';
import '@vaadin/tabsheet/vaadin-tabsheet.js';

// Side navigation
import '@vaadin/side-nav/vaadin-side-nav.js';
import '@vaadin/side-nav/vaadin-side-nav-item.js';

// Menus
import '@vaadin/menu-bar/vaadin-menu-bar.js';
import '@vaadin/context-menu/vaadin-context-menu.js';

// Buttons
import '@vaadin/button/vaadin-button.js';

Overlay Components

Modal dialogs, notifications, and overlay UI elements.

// Dialogs
import '@vaadin/dialog/vaadin-dialog.js';
import '@vaadin/confirm-dialog/vaadin-confirm-dialog.js';

// Notifications and feedback
import '@vaadin/notification/vaadin-notification.js';
import '@vaadin/tooltip/vaadin-tooltip.js';
import '@vaadin/popover/vaadin-popover.js';

Visual Components

Icons, avatars, and visual elements.

// Icons
import '@vaadin/icon/vaadin-icon.js';
import '@vaadin/icons/vaadin-iconset.js';

// User representation
import '@vaadin/avatar/vaadin-avatar.js';
import '@vaadin/avatar-group/vaadin-avatar-group.js';

Communication Components

Components for messaging and user communication interfaces.

// Chat and messaging
import '@vaadin/message-input/vaadin-message-input.js';
import '@vaadin/message-list/vaadin-message-list.js';

// Authentication
import '@vaadin/login/vaadin-login-form.js';
import '@vaadin/login/vaadin-login-overlay.js';

Utility Components

Scrolling, containers, and utility components.

// Containers
import '@vaadin/scroller/vaadin-scroller.js';

Pro Components

Advanced business components (require commercial license).

// Dashboard and layout
import '@vaadin/board/vaadin-board.js';
import '@vaadin/dashboard/vaadin-dashboard.js';

// Data visualization
import '@vaadin/charts/vaadin-chart.js';

// Advanced grid
import '@vaadin/grid-pro/vaadin-grid-pro.js';

// Content editing
import '@vaadin/rich-text-editor/vaadin-rich-text-editor.js';

// Maps
import '@vaadin/map/vaadin-map.js';

// CRUD operations
import '@vaadin/crud/vaadin-crud.js';

// Privacy and compliance
import '@vaadin/cookie-consent/vaadin-cookie-consent.js';

Base Packages and Utilities

Foundation packages for component development and theming.

// Component base classes
import '@vaadin/component-base/src/element-mixin.js';
import '@vaadin/field-base/src/field-mixin.js';
import '@vaadin/field-base/src/input-field-mixin.js';

// Accessibility utilities
import '@vaadin/a11y-base/src/focus-trap-mixin.js';
import '@vaadin/a11y-base/src/keyboard-mixin.js';

// Theming and styling
import '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
import '@vaadin/vaadin-lumo-styles/color.js';
import '@vaadin/vaadin-lumo-styles/typography.js';
import '@vaadin/vaadin-lumo-styles/sizing.js';
import '@vaadin/vaadin-lumo-styles/spacing.js';
import '@vaadin/vaadin-material-styles/color.js';
import '@vaadin/vaadin-material-styles/typography.js';

// Overlay and positioning
import '@vaadin/overlay/src/vaadin-overlay.js';
import '@vaadin/overlay/src/vaadin-overlay-mixin.js';

// Rendering utilities
import '@vaadin/lit-renderer/lit-renderer.js';

// Input utilities
import '@vaadin/input-container/src/vaadin-input-container.js';
import '@vaadin/field-highlighter/src/vaadin-field-highlighter.js';

// Legacy support
import '@vaadin/polymer-legacy-adapter/template-renderer.js';

Development and Build System

Package Management

// Root package.json scripts
"build:ts": "tsc --build tsconfig.build.json"
"lint": "npm-run-all --parallel lint:*"
"lint:css": "stylelint packages/**/src/*.js packages/**/theme/**/*-styles.js packages/**/*.css"
"lint:js": "eslint --ext .js,.ts *.js scripts packages test"
"lint:types": "tsc"
"test": "web-test-runner"
"analyze": "polymer analyze packages/**/vaadin-*.js > analysis.json"
"dist": "rimraf dist && yarn analyze && rollup -c rollup.config.js && cp analysis.json dist"

Testing Infrastructure

The monorepo includes comprehensive testing infrastructure:

Web Test Runner: Modern browser testing with Playwright
Cross-browser Support: Chrome, Firefox, Safari, Edge
Visual Regression Testing: Screenshot comparisons
Accessibility Testing: ARIA compliance verification
Unit Testing: Component behavior and API testing
Integration Testing: Component interaction testing

Theming System

// Lumo design system (default)
import '@vaadin/vaadin-lumo-styles/color.js';
import '@vaadin/vaadin-lumo-styles/typography.js';
import '@vaadin/vaadin-lumo-styles/sizing.js';
import '@vaadin/vaadin-lumo-styles/spacing.js';
import '@vaadin/vaadin-lumo-styles/style.js';
import '@vaadin/vaadin-lumo-styles/mixins/overlay.js';

// Material design system
import '@vaadin/vaadin-material-styles/color.js';
import '@vaadin/vaadin-material-styles/typography.js';
import '@vaadin/vaadin-material-styles/mixins/overlay.js';

// Custom theming
import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';

Types and Interfaces

// Common component interfaces
interface FieldMixin {
  value: string | number | boolean;
  name: string;
  label: string;
  placeholder: string;
  required: boolean;
  readonly: boolean;
  disabled: boolean;
  invalid: boolean;
  errorMessage: string;
}

interface InputFieldMixin extends FieldMixin {
  autocomplete: string;
  autocapitalize: string;
  spellcheck: boolean;
}

// Theme variants
type ThemeVariant =
  | 'primary' | 'secondary' | 'tertiary'
  | 'success' | 'error' | 'warning'
  | 'contrast' | 'small' | 'large'
  | 'icon' | 'contained' | 'outlined';

// Layout directions
type LayoutDirection = 'row' | 'column';

// Grid column configuration
interface GridColumn {
  path?: string;
  header?: string;
  width?: string;
  minWidth?: string;
  maxWidth?: string;
  flexGrow?: number;
  textAlign?: 'start' | 'center' | 'end';
  frozen?: boolean;
  sortable?: boolean;
  resizable?: boolean;
}

// Event types
interface CustomElementEvent<T = any> extends CustomEvent<T> {
  target: HTMLElement;
}

// Renderer function types
type GridColumnRenderer<T> = (
  root: HTMLElement,
  column: GridColumn,
  model: { item: T; index: number }
) => void;

type ComboBoxRenderer<T> = (
  root: HTMLElement,
  comboBox: HTMLElement,
  model: { item: T; index: number }
) => void;

Browser Support

Desktop Browsers:

Chrome (evergreen)
Firefox (evergreen)
Safari 15 or newer
Edge (Chromium, evergreen)

Mobile Browsers:

Chrome for Android (4.4 or newer)
Safari for iOS (15 or newer)

Installation Examples

Individual Component Installation

# Install specific components
npm install @vaadin/grid
npm install @vaadin/button
npm install @vaadin/text-field

# Install theme system
npm install @vaadin/vaadin-lumo-styles
npm install @vaadin/vaadin-material-styles

# Install pro components (requires license)
npm install @vaadin/charts
npm install @vaadin/grid-pro

Development Dependencies

# Development tooling
npm install @vaadin/testing-helpers
npm install @web/test-runner
npm install @web/dev-server

Error Handling

Common Component Errors

Invalid Property Values: Components validate input and set invalid property when constraints are violated.

const textField = document.querySelector('vaadin-text-field');
textField.required = true;
textField.value = ''; // Will set invalid=true and show error message

Missing Dependencies: Components require proper imports to register custom elements.

// This will fail - custom element not registered
document.createElement('vaadin-button');

// Correct - import registers the element
import '@vaadin/button/vaadin-button.js';
document.createElement('vaadin-button'); // Works

Theme Loading: Theme modules must be imported before component usage.

// Load theme first
import '@vaadin/vaadin-lumo-styles/color.js';
import '@vaadin/vaadin-lumo-styles/typography.js';

// Then import components
import '@vaadin/button/vaadin-button.js';