@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 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

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>;
	}
}
<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.

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

OptionTypeMeaning
sourcestringAttribute name to read and write. Defaults to the kebab-cased field name.
typeString | Number | Boolean | Object | ArrayBuilt-in attribute codec. Required for a field that is not a string unless converter.fromAttribute is given, and checked against the field.
defaultValueTValue 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.
bindboolean | stringCompanion 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.

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;
}
// 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