Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Reactive Properties

Attributes, Reflection and Converters in Lit

Understand how Lit maps HTML attributes to properties, the Boolean, Number, Object and Array types, reflect, attribute names, and writing your own converter.

HTML authors configure elements with attributes: <img src="...">, <input disabled>. JavaScript code configures them with properties: img.src, input.disabled. A good custom element supports both, and Lit does most of the plumbing for you. This lesson explains how attribute values become typed properties, how to push property values back out to attributes, and how to write a converter when the built-in ones are not enough.

The main thing to remember: attributes are always strings (or absent), properties can be any JavaScript value. Everything in this lesson is about translating between the two.

Attribute to property: the type option

When you declare { type: Number }, Lit does two things: it adds count to observedAttributes so the browser reports changes of the count attribute, and it converts the attribute string to a number before storing it in the property.

Types in action

Here is the rule for each type:

type Attribute "x" becomes Missing attribute becomes
String (default) the string null
Number Number("x") null
Boolean true (any value, even "" or "false") false
Array, Object JSON.parse("x") null

Two details trip people up:

  • A Boolean attribute is true if it is present, whatever its value. sale="false" is still true, exactly like the built-in disabled attribute. To switch it off you remove the attribute.
  • Array and Object expect valid JSON. Single-quote the HTML attribute so the JSON can use double quotes. Invalid JSON throws a SyntaxError when the attribute is read.

Complex data is nicer as a property: el.sizes = ["A5", "A6"] from JavaScript, no JSON string needed. Reserve Array and Object attribute parsing for cases where markup authors really need it.

Attribute names

By default the attribute name is the lowercased property name. maxItems listens to maxitems, not max-items. Set attribute to choose a different name, or false to disable the attribute completely.

Naming attributes

Kebab-case attribute names such as max-stars match the HTML convention and are what most Lit components use. observedAttributes shows that secret is not in the list: setting an attribute of that name does nothing.

Property to attribute: reflect

By default data flows one way: attribute to property. When a property changes in JavaScript, the attribute in the DOM stays the same. Add reflect: true to write the property back to the attribute after each update.

Why bother? Two reasons. CSS can then select on state (my-chip[selected] { ... }), and tools such as the inspector or querySelector('[open]') see the true state.

Reflecting a property

For a Boolean, reflecting true adds an empty attribute and reflecting false removes it. For other types the property is converted to a string. Do not reflect large objects or rapidly changing values (such as scroll position): every reflection is a DOM write.

Attribute to property

HTML attribute Always a string
Converter type: Number, Boolean, JSON
Property A real JavaScript value

Default direction. Needs observedAttributes.

1 / 2

Writing a custom converter

The converter option takes an object with fromAttribute (string to value) and toAttribute (value to string). Use it for formats such as comma-separated lists, dates or colors.

A list converter

Passing a function instead of an object (converter: (value) => ...) defines only fromAttribute. Since Lit sets type to String when you do not specify one, a custom converter replaces that default completely.

Setting attributes and properties from a template

Inside another Lit template you pick the target with a prefix:

JavaScript
html`
  <status-chip active></status-chip>        <!-- static attribute -->
  <status-chip active=${flag}></status-chip> <!-- attribute binding (stringified) -->
  <status-chip .active=${flag}></status-chip> <!-- property binding: keeps the real value -->
  <status-chip ?active=${flag}></status-chip> <!-- boolean attribute: present when true -->
`

For custom elements, prefer the property binding (.): it passes arrays, objects and booleans untouched. The binding prefixes themselves are covered in the Templates and Directives chapter of this track.

Common mistakes

  • Expecting sale="false" to mean false for a Boolean. Remove the attribute instead.
  • Using camelCase attribute names in HTML: <my-el maxItems="3"> works only because HTML lowercases it to maxitems, which matches the default name. Prefer explicit attribute: "max-items".
  • Reflecting objects, which writes [object Object] unless you supply a converter.
  • Reflecting a property inside updated() yourself instead of using reflect: true.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A component declares open: { type: Boolean }. What is the value of open for <my-el open="false">?

    A Boolean attribute is true whenever it is present. Remove the attribute to make it false.
  2. 2. What does reflect: true do?

    Reflection writes the current property value to the attribute, so CSS selectors and the inspector see it.
  3. 3. Which attribute name does { type: Number } on a property called maxItems observe by default?

    The default attribute name is the lowercased property name. Use the attribute option for kebab-case.
  4. 4. What is the best way to pass a large array from JavaScript to a Lit component?

    Properties hold real values, so no serialization is needed.

Summary

  • Attributes are strings; Lit converts them with type (String, Number, Boolean, Array, Object).
  • A Boolean attribute is true when present, regardless of value.
  • attribute renames or disables the observed attribute; the default is the lowercase property name.
  • reflect: true writes properties back to attributes for CSS and tooling.
  • converter handles custom string formats in both directions.

Next: The Update Lifecycle