---
title: "@customElement"
description: "Register custom elements with the browser."
group: Decorators
order: 1
---

import { RuiAlert, RuiAlertDescription, RuiAlertTitle } from '@ecopages/radiant-ui/alert';



# @customElement

The `@customElement` decorator provides a concise way to register custom elements with the browser's Custom Elements registry. It is a declarative wrapper around the standard `customElements.define()` API.

## Usage
```typescript
import { RadiantElement, customElement } from '@ecopages/radiant';

@customElement('my-component')
export class MyComponent extends RadiantElement {
	connectedCallback() {
		super.connectedCallback();
		this.textContent = 'Hello from my-component!';
	}
}
```
Usage in HTML:
```html
<my-component></my-component>
```

## Parameters

| Parameter | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `tagName` | `string` | Yes | The custom element tag name. |
| `options` | `ElementDefinitionOptions` | No | Options for element definition (e.g., `extends`). |

## Extending Built-in Elements

You can extend built-in HTML elements by providing the `options` parameter with the `extends` property. Note that you must also extend the corresponding HTML class.

```typescript
@customElement('fancy-button', { extends: 'button' })
export class FancyButton extends HTMLButtonElement {
	connectedCallback() {
		this.classList.add('fancy');
	}
}
```

Usage in HTML:

```html
<button is="fancy-button">Click me</button>
```

<RuiAlert variant="warning" layout="banner" class="unstyled">
  <RuiAlertTitle>WARNING</RuiAlertTitle>
  <RuiAlertDescription>
    <p>Customized built-in elements have limited browser support and are not supported in Safari. See <a href="/docs/getting-started/best-practices">Best Practices</a> for more information.</p>
  </RuiAlertDescription>
</RuiAlert>

## Learn More

- [Naming Rules & Best Practices](/docs/getting-started/best-practices)
- [RadiantElement](/docs/components/radiant-element)