Web Components
The basics of the web-component plugin for Aurelia.
Introduction
Web Components are part of an ever-evolving web specification that aims to allow developers to create native self-contained components without the need for additional libraries or transpilation steps. This guide will teach you how to use Aurelia to create Web Components that can be used in any framework or vanilla JavaScript application.
Installing The Plugin
To use the web components functionality, you need to install the @aurelia/web-components
package:
npm install @aurelia/web-components
The package provides the IWcElementRegistry
interface which allows you to define web-component custom elements by calling the define
method.
Basic Setup
To use web components in your Aurelia application, import the IWcElementRegistry
interface from @aurelia/web-components
and register your web components:
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
// Define your web components here
registry.define('my-element', class MyElement {
static template = '<p>Hello from Web Component!</p>';
});
})
)
.app(class App {})
.start();
API Reference
The IWcElementRegistry.define
method has the following signatures:
interface IWcElementRegistry {
define(name: string, def: Constructable, options?: ElementDefinitionOptions): Constructable<HTMLElement>;
define(name: string, def: Omit<PartialCustomElementDefinition, 'name'>, options?: ElementDefinitionOptions): Constructable<HTMLElement>;
}
Parameters
name: The custom element name (must contain a hyphen
-
as per Web Components specification)def: Either a class constructor or an object with element definition properties
options: Optional configuration for extending built-in elements
How it works
Each web component custom element is backed by an Aurelia view model, like a normal Aurelia component.
For each
define
call, a corresponding native custom element class is created and registered with the browser'scustomElements
registry.Each bindable property on the backing Aurelia view model is converted to a reactive attribute (via
observedAttributes
) and reactive property on the custom element.The web component uses standard Web Components lifecycle callbacks (
connectedCallback
,disconnectedCallback
,attributeChangedCallback
,adoptedCallback
).Regular custom elements: Used as
<my-element></my-element>
in HTML.Extended built-in elements: Used as
<button is="my-button"></button>
in HTML with theis
attribute.
Important Notes
Web component custom elements work independently of Aurelia components. The same class can be both a web component and an Aurelia component, though this should be avoided to prevent double rendering.
containerless
mode is not supported. Use extend-built-in functionality instead if you want to avoid wrapper elements.Defined web components continue working even after the owning Aurelia application has stopped.
template
andbindables
information is retrieved and compiled only once perdefine
call. Changes after this call have no effect.Slot:
[au-slot]
is not supported when upgrading existing elements. Standard<slot>
elements work as normal web components.
Examples
1. Basic Web Component
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('hello-world', class HelloWorld {
static template = '<h1>Hello, Web Components!</h1>';
});
})
)
.app(class App {})
.start();
// Usage in HTML: <hello-world></hello-world>
2. Web Component with Bindable Properties
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('user-greeting', class UserGreeting {
static template = '<p>Hello, ${name}! You are ${age} years old.</p>';
static bindables = ['name', 'age'];
name: string = 'World';
age: number = 0;
});
})
)
.app(class App {})
.start();
// Usage in HTML:
// <user-greeting name="John" age="25"></user-greeting>
// Or programmatically:
// const element = document.createElement('user-greeting');
// element.name = 'Jane';
// element.age = 30;
3. Web Component with Shadow DOM
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('shadow-element', class ShadowElement {
static template = `
<style>
p { color: blue; font-weight: bold; }
</style>
<p>This is styled within Shadow DOM</p>
`;
static shadowOptions = { mode: 'open' };
});
})
)
.app(class App {})
.start();
4. Web Component with Lifecycle and Host Injection
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
import { INode } from 'aurelia';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('tick-clock', class TickClock {
static template = '${message}';
static inject = [INode];
private time: number;
private intervalId: number;
message: string = '';
constructor(private host: HTMLElement) {
this.time = Date.now();
}
attaching() {
this.intervalId = setInterval(() => {
this.message = `${Math.floor((Date.now() - this.time) / 1000)} seconds passed.`;
}, 1000);
}
detaching() {
clearInterval(this.intervalId);
}
});
})
)
.app(class App {})
.start();
5. Web Component with Object Definition
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('simple-card', {
template: `
<div class="card">
<h2>\${title}</h2>
<p>\${content}</p>
</div>
`,
bindables: ['title', 'content'],
shadowOptions: { mode: 'open' }
});
})
)
.app(class App {})
.start();
6. Extending Built-in Elements
When extending built-in elements, you use the { extends: 'element-name' }
option and reference them in HTML using the is
attribute:
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
// Extend a button element
registry.define('enhanced-button', class EnhancedButton {
static template = '<span>🚀</span> <slot></slot>';
static bindables = ['variant'];
variant: string = 'primary';
}, { extends: 'button' });
// Extend a paragraph element
registry.define('rich-paragraph', class RichParagraph {
static template = '<strong>${title}</strong>: ${content}';
static bindables = ['title', 'content'];
title: string = '';
content: string = '';
}, { extends: 'p' });
})
)
.app(class App {})
.start();
// Usage in HTML:
// <button is="enhanced-button" variant="secondary">Click Me</button>
// <p is="rich-paragraph" title="Note" content="This is enhanced content"></p>
7. Web Component with Advanced Features
import { Aurelia, AppTask } from 'aurelia';
import { IWcElementRegistry } from '@aurelia/web-components';
import { INode, ILogger } from 'aurelia';
Aurelia
.register(
AppTask.creating(IWcElementRegistry, registry => {
registry.define('data-display', class DataDisplay {
static template = `
<div class="loading" if.bind="loading">Loading...</div>
<div class="content" else>
<h3>\${title}</h3>
<div repeat.for="item of items">
<p>\${item.name}: \${item.value}</p>
</div>
</div>
`;
static bindables = ['url', 'title'];
static inject = [INode, ILogger];
url: string = '';
title: string = 'Data';
loading: boolean = false;
items: Array<{name: string, value: string}> = [];
constructor(
private host: HTMLElement,
private logger: ILogger
) {}
async urlChanged(newUrl: string) {
if (!newUrl) return;
this.loading = true;
try {
const response = await fetch(newUrl);
const data = await response.json();
this.items = data.items || [];
this.logger.info(`Loaded ${this.items.length} items`);
} catch (error) {
this.logger.error('Failed to load data', error);
this.items = [];
} finally {
this.loading = false;
}
}
});
})
)
.app(class App {})
.start();
Error Handling and Validation
The web components implementation includes built-in validation:
Invalid Element Names
// This will throw an error because element names must contain a hyphen
registry.define('myelement', class MyElement {}); // ❌ Error!
// This works
registry.define('my-element', class MyElement {}); // ✅ Correct!
Containerless Components
// This will throw an error because containerless is not supported
registry.define('my-element', class MyElement {
static containerless = true; // ❌ Error!
});
// Use extend-built-in instead if you need to avoid wrapper elements
registry.define('enhanced-span', class MyElement {
static template = '<span>Content</span>';
}, { extends: 'span' }); // ✅ Alternative approach
// Usage in HTML: <span is="enhanced-span">Content</span>
Usage Outside Aurelia Applications
Web components defined with Aurelia can be used in any context:
Vanilla JavaScript
<!DOCTYPE html>
<html>
<head>
<script src="./aurelia-web-components-bundle.js"></script>
</head>
<body>
<!-- Use regular web components -->
<user-greeting name="John" age="25"></user-greeting>
<!-- Use extended built-in elements -->
<button is="enhanced-button" variant="primary">Click Me</button>
<script>
// Create regular web components programmatically
const greeting = document.createElement('user-greeting');
greeting.name = 'Jane';
greeting.age = 30;
document.body.appendChild(greeting);
// Create extended built-in elements programmatically
const enhancedBtn = document.createElement('button', { is: 'enhanced-button' });
enhancedBtn.variant = 'secondary';
enhancedBtn.textContent = 'Dynamic Button';
document.body.appendChild(enhancedBtn);
</script>
</body>
</html>
React Integration
import React from 'react';
function App() {
return (
<div>
<h1>React App with Aurelia Web Components</h1>
<user-greeting name="React User" age="25" />
{/* For extended built-in elements: */}
<button is="enhanced-button" variant="primary">Enhanced Button</button>
</div>
);
}
Angular Integration
// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@NgModule({
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }
<!-- app.component.html -->
<user-greeting name="Angular User" [attr.age]="userAge"></user-greeting>
<!-- For extended built-in elements: -->
<button is="enhanced-button" variant="primary">Enhanced Button</button>
Best Practices
Element Naming: Always use kebab-case with at least one hyphen for element names.
Property Binding: Define bindable properties explicitly using the
bindables
array for reactive updates.Shadow DOM: Use Shadow DOM for style encapsulation when your component has its own styles.
Lifecycle Management: Implement
attaching
anddetaching
lifecycle methods for setup and cleanup.Error Handling: Always handle errors gracefully, especially in async operations.
Performance: Remember that web components are created for each instance, so avoid heavy operations in constructors.
Dependencies: Keep dependencies minimal since web components should be self-contained.
Extended Built-ins: When extending built-in elements, remember to use the
is
attribute in HTML (<button is="my-button">
) rather than creating new element names.
This enhanced documentation provides a complete guide to creating and using Aurelia-powered Web Components with accurate examples and proper error handling.
Last updated
Was this helpful?