Attributes
Attributes allow developers to configure the behavior of HTML elements. This is also true for Enhance Elements (and for HTML custom elements in general). Attributes can be used to pass basic units of data, which you can then leverage and respond to within your element.
Author attributes
To author an attribute on your Enhance Element, give it a name, and optionally a value, separated by an equals sign. An attribute without a value assigned to it becomes a boolean attribute (see below).
Note that, as per the HTML spec, attributes can only accept strings as values.
<my-message message="Howdy!"></my-message>
Access attrs
Attributes can be read via the attrs
property of the state
object.
export default function MyMessage({ html, state }) {
const { attrs } = state
const { message } = attrs
return html`<p>${message}</p>`
}
Attribute names
HTML attributes are written in all lowercase characters. Because all attribute names on HTML elements get lowercased by the HTML parser, we recommend not using casing methods such as camelCase
or PascalCase
when naming your attributes.
Of particular concern here is that the attributeChangedCallback
function will not fire for attributes with uppercase characters (because of the aforementioned parser behavior). Therefore, attributes named with multiple words should be delimited using kebab-casing
or snake_casing
(or not delimited at all).
case | attribute | JS access | attributeChangedCallback |
---|---|---|---|
lower | imagewidth |
attrs.imagewidth |
✅ |
kebab | image-width |
attrs['image-width'] |
✅ |
snake | image_width |
attrs.image_width |
✅ |
camel | imageWidth |
attrs.imageWidth |
❌ |
Handling booleans
Boolean attributes in HTML are a little different from what you may be used to if you’re coming to Enhance from a JavaScript centric framework. This is because, as per the HTML spec, a boolean attribute evaluates to true
when it’s present, and false when it’s absent.
For example, let’s take a look at the disabled
attribute, and when it evaluates to true
and false
:
<!-- TRUE -->
<button disabled>Disabled?</button>
<!-- TRUE -->
<button disabled="disabled">Disabled?</button>
<!-- TRUE -->
<button disabled="">Disabled?</button>
<!-- TRUE -->
<button disabled="false">Disabled?</button>
<!-- FALSE -->
<button>Disabled?</button>
In order to correctly check for (and conditionally apply) a boolean attribute on an Enhance Element, we recommend checking for the presence of that attribute on the element’s attrs
field, like so:
export default function MyButton({ html, state }) {
const { attrs } = state
const disabled = Object.keys(attrs).includes('disabled')
? 'disabled'
: ''
return html`<button ${disabled}>Disabled?</button>`
}