# Component Implementation How a component is put together in code, in roughly the order you write it. For the package and file layout around it, see [Package Structure](package-structure.md). ## Element class A component is a `LitElement` subclass wrapped in the Vaadin mixin chain, registered at module scope and exported by name: ```js import { html, LitElement } from 'lit'; import { defineCustomElement } from '@vaadin/component-base/src/define.js'; import { buttonStyles } from './styles/vaadin-button-base-styles.js'; class Button extends ButtonMixin(ElementMixin(PolylitMixin(LumoInjectionMixin(LitElement)))) { static get is() { return 'vaadin-button'; } static get styles() { return buttonStyles; } static get properties() { return { disabled: { type: Boolean, value: false, reflectToAttribute: true, }, }; } /** @protected */ render() { return html` `; } } defineCustomElement(Button); export { Button }; ``` The static members: - **`static get is()`** — the custom element tag name. `defineCustomElement()` reads it to register the element. - **`static get styles()`** — the base styles imported from `./styles/vaadin-{name}-base-styles.js`. See [Theming](theming.md) for authoring them. - **`static get properties()`** — the reactive properties, see [Properties](#properties) below. - **`render()`** — the shadow DOM template, marked `/** @protected */`. See [DOM](dom.md) for parts, attributes, and slots. Register with `defineCustomElement(Class)` rather than `customElements.define()` directly: it stamps the package version onto the class, warns when the same element is loaded twice, and defers registration for components behind a feature flag (see [Ship new components as experimental](design.md#ship-new-components-as-experimental)). Most packages declare the class and export it at the bottom of the file (`export { Button };`) instead of using `export class`. ## Mixin chain Every component uses the same outer wrappers, in this order: ```js class MyComponent // Component-specific logic extends MyComponentMixin( // Vaadin element registration (public components only) ElementMixin( // Polymer-compat layer (required for all components) PolylitMixin( // Lumo style injection (required) LumoInjectionMixin(LitElement), ), ), ) {} ``` Field-like components add field mixins inside the component-specific layer (see [Common packages](common-packages.md)). `PolylitMixin` and `LumoInjectionMixin` are required for every component. `ElementMixin` is required for **public** components only — internal sub-elements (e.g. helper elements that aren't exported) skip it. Existing components also wrap `ThemableMixin`, which is the legacy shadow DOM style injection mechanism. New components don't use it — see [Theming](theming.md). ## Properties Declare reactive properties in the `static properties` block. Set defaults via the `value:` option, not class-field initializers. ```js static get properties() { return { /** * Whether the component is disabled. */ disabled: { type: Boolean, value: false, reflectToAttribute: true, }, /** * The value of the component. */ value: { type: String, value: '', notify: true, }, }; } ``` Why Polymer-style options instead of plain Lit: - **`value:` not field initializers.** PolylitMixin (in the canonical mixin chain) installs property accessors on the prototype. ES class-field initializers (`value = ''`) shadow those accessors with a same-named instance property, silently breaking reactivity — Lit's dev mode logs a `class-field-shadowing` warning. Set defaults with `value:` in the property declaration instead. - **`reflectToAttribute:` not `reflect:`.** PolylitMixin's `createProperty` recognises the Polymer-style option name, and every field-style component in the repo uses it. Match that. Other notes: - `attribute: false` for internal reactive properties (the codebase prefers this over Lit's `state: true`). - `notify: true` is provided by PolylitMixin and dispatches a `{property}-changed` `CustomEvent` — see [Events](events.md). - `readOnly: true` replaces the public setter with a no-op — even `host.toggleAttribute(...)` won't update the property because the reflected change still hits the no-op. PolylitMixin generates a protected `_set{Name}(value)` accessor; use it instead. For full Lit property options refer to the [Lit reactive properties guide](https://lit.dev/docs/components/properties/). ## Lit lifecycle — when to use what | Hook | Use it for | | ------------------------ | ------------------------------------------------------------- | | `constructor()` | Instantiate controllers; set non-reactive defaults. | | `connectedCallback()` | Add **global** event listeners (`window`, `document`). | | `disconnectedCallback()` | Remove the global listeners added in `connectedCallback()`. | | `firstUpdated()` | Set host attributes (`role`, `tabindex`); attach controllers. | | `willUpdate(props)` | Derive values that the template needs _before_ rendering. | | `updated(props)` | React to property changes (replaces Polymer-style observers). | ```js firstUpdated() { super.firstUpdated(); if (!this.hasAttribute('role')) { this.setAttribute('role', 'button'); } this.addController(new TooltipController(this)); } updated(props) { super.updated(props); if (props.has('disabled')) { this._disabledChanged(this.disabled, props.get('disabled')); } } ``` Always call `super.()` first — most Vaadin mixins rely on it. ## `firstUpdated()` vs `ready()` (PolylitMixin) `PolylitMixin` provides Polymer's `ready()` for backwards compatibility. The order is: 1. `firstUpdated()` 2. Initial property observers 3. `ready()` For new code, prefer `firstUpdated()`. Reach for `ready()` only when interoperating with Polymer-era mixins or observers that must have run first. ## `updated()` vs `static get observers()` Prefer `updated(changed)` with `changed.has('foo')` for new code: ```js updated(changed) { super.updated(changed); if (changed.has('disabled')) { this._disabledChanged(this.disabled, changed.get('disabled')); } } ``` Polymer-style `static get observers()` exists for legacy mixins; don't introduce new ones in component code. ## Dynamic observers PolylitMixin provides two helpers. Both register inside `ready()` and skip the initial property value (typical use: field validation): - **`_createPropertyObserver(prop, method)`** — single-property observer with access to the previous value (`this[method](newValue, oldValue)`). - **`_createMethodObserver(observer)`** — multi-property observer taking a Polymer-style observer string (e.g. `'_rangeChanged(min, max)'`). ## `willUpdate()` vs computed properties Use `willUpdate(changed)` to compute derived values before render: ```js willUpdate(changed) { if (changed.has('value') || changed.has('min') || changed.has('max')) { this._isOutOfRange = this.value < this.min || this.value > this.max; } } ``` Avoid PolylitMixin computed properties (`computed: '_compute(a, b)'`) in new code. ## `ifDefined()` for attribute bindings Use Lit's `ifDefined` directive to skip an attribute when the bound value is `null` or `undefined`. The most common case is forwarding `_theme` to a sub-element's `theme` attribute: ```js import { ifDefined } from 'lit/directives/if-defined.js'; render() { return html` `; } ``` ## Mixins vs reactive controllers Both extract reusable behavior. The rule of thumb: - **Mixin** — when the behavior needs to declare reactive properties on the host class, or a single component's logic is large enough that splitting it across files is useful (e.g. `vaadin-grid-*-mixin.js` files). Mixins can also override host lifecycle methods. - **Reactive controller** — when the behavior is self-contained and runs in step with Lit's update cycle. Controllers can be reused across components just like mixins, but they cannot add reactive properties to the host class — wire any external state through controller constructor arguments or methods instead. See [Common packages](common-packages.md) for the controllers shipped with the repo. Add a controller via `this.addController(controller)` in `firstUpdated()`.