---
title: "@attr"
description: "Bind a reactive field to a host HTML attribute on a RadiantElement or RadiantController."
order: 2
---

# @attr

`@attr(...)` binds a reactive field to a host HTML attribute.

Use it when a value should come from authored host markup rather than from JSX property transport.

That makes it the right fit for:

- `data-*` configuration on `RadiantController`
- ordinary host attributes such as `title`, `lang`, `hidden`, or `aria-*`
- HTML-authored custom elements that should read plain host attributes reactively
- interoperable values that should stay visible on the host markup

Use [@prop](/docs/decorators/prop) when the field is part of a custom element's property API and should participate in JSX `prop:` transport.

Important: `@attr(...)` binds the decorated field to the host attribute channel. It is not the primary tool for setting attributes on child elements inside `render()`.

## Example

```ts
import { RadiantElement, attr, customElement } from '@ecopages/radiant';

@customElement('status-pill')
export class StatusPill extends RadiantElement {
	@attr({ source: 'data-status' }) status?: string;
	@attr({ source: 'aria-label' }) label?: string;

	override render() {
		return <span>{this.status ?? 'unknown'}</span>;
	}
}
```

```html
<status-pill data-status="ready" aria-label="Server status"></status-pill>
```

In this example:

- `status` reads from the host `data-status` attribute
- `label` reads from the host `aria-label` attribute
- assigning either field writes back through that same host attribute channel

The field type must agree with the options, and a field that is not a string needs `type` or a parser: see [Typing Decorated Fields](/docs/decorators#typing-decorated-fields).

When `type` is provided, `@attr(...)` uses the same built-in attribute codec family as `@prop(...)` for `String`, `Number`, `Boolean`, `Object`, and `Array`. Without it the field holds the raw attribute string.

## Options

| Option | Type | Meaning |
| --- | --- | --- |
| `source` | `string` | Attribute name to read and write. Defaults to the kebab-cased field name. |
| `type` | `String \| Number \| Boolean \| Object \| Array` | Built-in attribute codec. Required for a field that is not a string unless `converter.fromAttribute` is given, and checked against the field. |
| `defaultValue` | `T` | Value used when the attribute is absent. With `converter.fromAttribute`, only when the converter returns `undefined` for `null`. `null` is accepted. Without `converter.fromAttribute`, a default that does not match `type` throws when the host installs the attribute. |
| `bind` | `boolean \| string` | Companion JSX binding accessor to expose. |
| `converter` | `{ fromAttribute, toAttribute }` | Custom conversion hooks. `fromAttribute` parses the attribute and owns the field type, so `type` is no longer checked against it. `toAttribute` serializes written values, replacing the `type` codec. |

## Default Conversion

Use `type` for the common cases where the host attribute should behave like a typed `@prop(...)` value without becoming part of the custom element's public property API.

```ts
import { RadiantController, attr } from '@ecopages/radiant';

class SearchController extends RadiantController {
	@attr({ source: 'data-page', type: Number }) page = 1;
	@attr({ source: 'data-enabled', type: Boolean }) enabled = false;
	@attr({ source: 'title' }) title?: string;
}
```

```ts
// does not compile: without `type`, `count` would hold the string "5"
@attr({ source: 'data-count' }) count = 0;
// compiles: `type: Number` parses the attribute
@attr({ source: 'data-count', type: Number }) count = 0;
```

Use `converter` only when the built-in codecs are not enough.

## Element vs Controller Usage

- On `RadiantElement`, `@attr(...)` is useful for host markup-visible configuration.
- On `RadiantController`, it is the preferred way to read host-authored controller inputs, often through `data-*` but not limited to them.

## Important

`@attr(...)` is host-attribute-driven. It does not replace `@prop(...)` for JSX property APIs.

If a custom element needs both channels, keep them explicit:

- `@prop(...)` for JSX and property-driven composition
- `@attr(...)` for host-authored attributes

If you need to set attributes on child nodes produced by `render()`, use normal JSX attributes or the `data={{ ... }}` / `aria={{ ... }}` object forms instead of `@attr(...)`.

## See Also

- [@prop](/docs/decorators/prop)
- [RadiantController](/docs/components/radiant-controller)