Custom attribute converters

Web Components can receive data in many ways, but one of the most common ways is to use an attribute because attributes are declarative, static, and easy to read & write in HTML!

Every HTML element in the browser has attibutes and properties:

• Attributes are additional values that describe the state of an element in HTML. Attributes can only have string values.
• Properties are the instance properties of an element's JavaScript DOM object. Properties can take any kind of value, like numbers, booleans, and arrays.

Built-in elements often match a property with a similarly-named attribute. For example, the <input> element has both a value attribute and a value property.

<input value="This is setting the 'value' attribute">
<script>
  const inputElementReference = document.querySelector('input');
  inputElementReference.value = 'This is setting the "value" property';
</script>

Setting the value attribute also sets the value property, so you can set a default value for your input from static markup!

Since Lit elements are HTML elements, Lit elements have both attributes and properties. When you define a reactive property, you can set up an attribute that maps to your property, and specify how the attribute value is converted to a property value. Lit supplies built-in converters for common types like numbers and booleans. But if you want to convert to a type that Lit doesn't support out of the box, you may need to write some code.

An example would be the Date object – you can see an example of this in the playground preview. The Date object is being passed in as a JavaScript property in index.html instead of a readable, string attribute. You can see the desired behavior in the preview by clicking the Solve button.

Custom attribute converters address this problem.

• What is an attribute converter?
• How Lit's built-in attribute converters work.
• How to write your own attribute converter.

In this tutorial you will build a component that takes in a human-readable date-string, converts it to a JavaScript Date object, and displays the given date in a human-readable format.

You will do this with the default attribute converters and then upgrade your component with your own custom attribute converter that can convert a date-string attribute into a JavaScript Date object property and the other way around.

It's helpful if you understand the basics of reactive properties in Lit, as well as the willUpdate Lit lifecycle method. Both of these topics are covered in the tutorial on Reactivity.