What are Design Attributes in Lightning Web Components?

Posted by Vinay Vernekar 3rd November 2025

Introduction

Design attributes in Lightning Web Components (LWC) enable admins and builders to configure component behavior and appearance declaratively inside the Lightning App Builder, Experience Builder, and community pages. They expose component properties as editable fields in the builder UI so non-developers can customize components without changing code.

Why design attributes matter

Design attributes bridge the gap between developers and admins. By defining them, you make your LWC reusable, configurable, and easier to maintain. They improve adoption of custom components across multiple pages and apps while keeping customization safe and simple.

Where you define design attributes

Design attributes are declared in the component’s configuration file: the componentName.js-meta.xml file. These definitions tell the builder which properties to show, their types, labels, defaults, and where the component can be used (targets).

Basic example

Below is a minimal example that exposes two properties—title and showIcon—to the Lightning App Builder.

<?xml version="1.0" encoding="UTF-8"?>
<>LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>56.0</apiVersion>
<isExposed>true</isExposed>
<targets>
<target>lightning__AppPage</target>
<target>lightning__RecordPage</target>
</targets>
<targetConfigs>
<targetConfig targets="lightning__RecordPage">
<property name="title" type="String" label="Header Title" default="My Component"/>
<property name="showIcon" type="Boolean" label="Show Icon" default="true"/>
</targetConfig>
</targetConfigs>
</LightningComponentBundle>

Corresponding component code

In your LWC JavaScript, declare the properties with @api so the framework binds builder values to the component at runtime.

import { LightningElement, api } from 'lwc';

export default class MyComponent extends LightningElement {
@api title = 'My Component';
@api showIcon = true;
}

Supported property types

Common types you can use in .js-meta.xml include:

  • String — text input
  • Boolean — checkbox
  • Integer — numeric input
  • Double — decimal input
  • Picklist — dropdown with defined choices
  • Color — color picker
  • List — multi-value input (less common)

Picklist example

Define a picklist with choices in .js-meta.xml:

<property name="theme" type="Picklist" label="Theme" default="light">
<picklistValues>
<picklistValue>
<fullName>light</fullName>
<label>Light</label>
</picklistValue>
<picklistValue>
<fullName>dark</fullName>
<label>Dark</label>
</picklistValue>
</picklistValues>
</property>

Target configuration

Use <targets> to control where the component appears (App Page, Record Page, Home Page, Community). Use <targetConfigs> to scope specific properties per target if desired.

Best practices

  • Always mark properties with @api to make them accessible.
  • Provide sensible default values and labels to improve builder UX.
  • Group related settings and document expected values in the description attribute (where supported).
  • Limit the number of exposed properties — only surface what admins truly need to change.
  • Use picklists for constrained choices to prevent invalid configurations.

Troubleshooting

If a property doesn’t show in the App Builder:

  • Confirm isExposed is true in the .js-meta.xml.
  • Ensure the component target includes the page type where you expect to use it.
  • Check that property name matches the @api property in the JS file.
  • Clear cache or reload the Lightning App Builder if recent changes are not visible.

Conclusion

Design attributes make Lightning Web Components configurable and admin-friendly. By defining clear, well-labeled properties in the .js-meta.xml and exposing matching @api properties in your code, you empower builders to reuse and tailor components without code changes — improving maintainability and adoption across your org.

Tags: