Public Properties

To expose a public property, decorate a field with @api. Public properties define the API for a component. When public properties are used in a template, they’re reactive. If the value of a public property used in a template changes, the component rerenders.

When a component rerenders, the expressions used in the template are reevaluated and the renderedCallback() lifecycle hook executes.

The @api Decorator

Decorators are a JavaScript language feature. The @api decorator is unique to Lightning Web Components. A field can have only one decorator.

Tip

A property can be your custom property or a property that’s inherited from the base HTMLElement interface.

Custom Properties

Import the @api decorator from lwc. This code exposes the itemName field as a public property.

1// todoItem.js
2import { LightningElement, api } from "lwc";
3export default class TodoItem extends LightningElement {
4  @api itemName = "New Item";
5}

The value of itemName displays in the template.

1<!-- todoItem.html -->
2<template>
3  <div class="view">
4    <label>{itemName}</label>
5  </div>
6</template>

This JavaScript class and HTML template define the c-todo-item component, where c is the namespace. A component that consumes the c-todo-item component can set the itemName property.

Property names in JavaScript are in camel case while HTML attribute names are in kebab case (dash-separated) to match HTML standards. In todoApp.html, the item-name attribute in markup maps to the itemName JavaScript property of c-todo-item.

Note

1<!-- todoApp.html -->
2<template>
3  <div class="listing">
4    <c-todo-item item-name="Milk"></c-todo-item>
5    <c-todo-item item-name="Bread"></c-todo-item>
6  </div>
7</template>

DOM Properties

An owner component that uses a component in its markup can access the component’s public properties via DOM properties. DOM properties are the public fields declared in a class. They’re accessible via the DOM element with dot notation. In this example, the component c-todo-item declares a public field as @api itemName, whose value is accessible via a DOM property on the instance of c-todo-item (the DOM element).

1// todoApp.js
2myItem = this.template.querySelector("c-todo-item").itemName;

See the CompositionBasics example in the lwc-recipes repository.

Tip

See Also

Render Lists

Release Preview

This release is in preview. Features described here don't become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can't guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.