# developer Lightning Web Components Developer Guide (lwc) - Full Documentation

<!-- document id=d82c471564e44ba223a3d173cd0e288405954430cbefd7714f245cea0457f05f url=/developer/current/en-us/lwc/lwc/guides/apex/apex-continuations-auraenabled.md -->

# `@AuraEnabled` Annotations for Continuations

Continuations use the `@AuraEnabled` annotation for Apex code. Here are the rules for usage.

- **`@AuraEnabled(continuation=true)`**

  An Apex controller method that returns a continuation must be annotated with `@AuraEnabled(continuation=true)`.

- **`@AuraEnabled(continuation=true cacheable=true)`**

  To cache the result of a continuation action, set `cacheable=true` on the annotation for the Apex callback method.

  **note:** There’s a space, **not a comma**, between `continuation=true cacheable=true`.

## Caching Considerations

It's best practice to set `cacheable=true` on all methods involved in the continuation chain, including the method that returns a `Continuation` object.

In this example, the Apex method that returns the continuation, `startRequest()`, and the callback, `processResponse()`, both contain `cacheable=true` in their `@AuraEnabled` annotation.

```apex
// Action method
@AuraEnabled(continuation=true cacheable=true)
public static Object startRequest() { }

// Callback method
@AuraEnabled(cacheable=true)
public static Object processResponse(List<String> labels,
  Object state) { }
```

## Cacheable Setting Behavior

Here's a table that summarizes the behavior with different settings of the `cacheable` attribute in `@AuraEnabled`.

| Method Returning Continuation Object Annotated with `cacheable=true` | Callback Method Annotated with `cacheable=true` | Valid?                   | Can be Called Using `@wire`?                | Is Action Response Cached on Client? |
| -------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ | ------------------------------------------- | ------------------------------------ |
| Yes                                                                  | Yes                                             | Yes                      | Yes                                         | Yes                                  |
| Yes                                                                  | No                                              | No (throws an exception) | N/A                                         | N/A                                  |
| No                                                                   | Yes                                             | Yes                      | No (all methods must have `cacheable=true`) | No                                   |
| No                                                                   | No                                              | Yes                      | No                                          | No                                   |

**See Also**

- [Make Long-Running Callouts with Continuations](https://developer.salesforce.com/docs/platform/lwc/guide/apex-continuations.md)
- [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)

<!-- document id=159f3b6311be3d44b04bed29985351737c85e406b4213a995f1f4957c29444ea url=/developer/current/en-us/lwc/lwc/guides/reference/reference-salesforce-modules.md -->

# `@salesforce` Modules

Modules scoped with `@salesforce` add functionality to Lightning web components at runtime.

Modules that are imported without `@salesforce`, like `lightning/uiRecordApi`, contain resources that don't change and are universal to all orgs.

Some modules have a fixed set of module identifiers. For example, the `@salesforce/i18n` module supports many identifiers including `@salesforce/i18n/dir` and `@salesforce/i18n/lang`.

Some modules have a dynamic set of module identifiers. The set is defined by the organization’s metadata. For example, `@salesforce/schema` accesses an organization’s objects and fields.

## `@salesforce/apex`

Import Apex methods from `@salesforce/apex`. The imported methods are functions that the component can call either via `@wire` or imperatively. See [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md).

```javascript
import apexMethodName from '@salesforce/apex/Namespace.Classname.apexMethodReference';
@wire(apexMethodName, { apexMethodParams })
propertyOrFunction;
```

- `apexMethodName`—A symbol that identifies the Apex method.
- `apexMethodReference`—The name of the Apex method to import.
- `Classname`—The name of the Apex class.
- `Namespace`—The namespace of the Salesforce organization. Specify a namespace unless the organization uses the default namespace (`c`), in which case don’t specify it.
- `apexMethodParams`—An object with properties that match the parameters of the `apexMethod`, if needed. If a parameter value is `null`, the method is called. If a parameter value is `undefined`, the method isn’t called. If the Apex method is overloaded, the choice of what method to call is non-deterministic (effectively random), and the parameters passed may cause errors now or in the future. Don't overload `@AuraEnabled` Apex methods.

**important:** `apexMethodParams` is an object. To pass parameter values to an Apex method, pass an object whose properties match the parameters of the Apex method. For example, if the Apex method takes a string parameter, don’t pass a string directly. Instead, pass an object that contains a property whose value is a string.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


**note:** The `data` property and the `error` property are hardcoded values in the API. You must use these values.

```javascript
// Example
import getAccounts from '@salesforce/apex/MyAccountController.getAccounts';

// Use the wire service to provision data to either a property or a function.
// This example provisions data to a property.
@wire(getAccounts)
accounts;

// This example provisions data to a function.
@wire(getAccounts)
wiredAccounts({ error, data }) {
  if (data) {
    this.accounts = data;
    this.error = undefined;
  } else if (error) {
    this.error = error;
    this.accounts = undefined;
  }
}
```

Import **`getSObjectValue`** from `@salesforce/apex`. Call this method to get a field value from an object retrieved from an Apex method.

```javascript
import { getSObjectValue } from "@salesforce/apex";
getSObjectValue(sObject, fieldApiName);
```

- `sObject`—The object returned by the Apex method.

- `fieldApiName`—The API name of the field. The value can be either a string or reference to a field imported from `@salesforce/schema`. You can specify up to three **relationship fields** to reference parent objects and fields using this format: `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`.

Import **`refreshApex`** from `@salesforce/apex`. Call this method to query the server for updated data returned by Apex, and refresh the cache of a wired property.

```javascript
import { refreshApex } from "@salesforce/apex";
refreshApex(valueProvisionedByApexWireService);
```

**note:** The use of `refreshApex` to refresh data from non-Apex wire adapters is deprecated. To refresh record data returned by a non-Apex wire adapter, use [`notifyRecordUpdateAvailable(recordIds)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-notify-record-update.md) instead.

- Where `{valueProvisionedByApexWireService}` is either a property annotated with an Apex `@wire`, or if you annotated a function, the argument that the wired function receives. See [Refresh the Cache When Using `@wire`](https://developer.salesforce.com/docs/platform/lwc/apex/apex-result-caching.md#refresh-the-cache-when-using-wire).

**note:** To update a record via imperative Apex, call the Apex method and then call `notifyRecordUpdateAvailable()` to update the cache. The `refreshApex()` function doesn’t refresh data that was fetched by calling an Apex method imperatively.

## `@salesforce/apexContinuation`

Import Apex methods from `@salesforce/apexContinuation`.

```javascript
// Syntax
import apexMethodName from "@salesforce/apexContinuation/Namespace.Classname.apexMethodName";
```

```javascript
// Example
import startRequest from "@salesforce/apexContinuation/SampleContinuationClass.startRequest";
```

- `apexMethodName`—A symbol that identifies the Apex method.
- `apexMethodReference`—The name of the Apex method to import.
- `Classname`—The name of the Apex class.
- `Namespace`—If the class is in the same namespace as the component, don’t specify a namespace. If the class is in a managed package, specify the namespace of the managed package.


See [Make Long-Running Callouts with Continuations](https://developer.salesforce.com/docs/platform/lwc/apex/apex-continuations.md).

## `@salesforce/client/formFactor`

```javascript
// Syntax
import formFactorPropertyName from @salesforce/client/formFactor
```

```javascript
// Example
import CLIENT_FORM_FACTOR from @salesforce/client/formFactor
```

- `formFactorPropertyName`—A name that refers to the form factor of the hardware running the browser. Possible values are:
  - `Large`—A desktop client.
  - `Medium`—A tablet client.
  - `Small`—A phone client.

[Pass the form factor](https://developer.salesforce.com/docs/platform/lwc/create/create-client-form-factor.md) to the `getRecordCreateDefaults` wire adapter to get the default layout information and object information for creating a record.

## `@salesforce/community`

Import the network ID of the current Experience Builder site from `@salesforce/community/Id`.

```javascript
// Syntax
import idName from "@salesforce/community/Id";
```

```javascript
// Example
import networkId from "@salesforce/community/Id";
```

Import the base URL of your Experience Builder site from `@salesforce/community/basePath`.

```javascript
// Syntax
import basepathname from "@salesforce/community/basePath";
```

```javascript
// Example
import sitePath from "@salesforce/community/basePath";
```

The base path is the section of the site’s URL that comes after the domain. So if your site domain name is `UniversalTelco.force.com` and `myPartnerSite` was the URL value added when you created the site, the community’s URL is `UniversalTelco.force.com/myPartnerSite/s`. In this case, `myPartnerSite/s` is the base path.

See [Get Information About the Current Experience Builder Site](https://developer.salesforce.com/docs/platform/lwc/create/create-community-info.md).

**important:** If a component imports `@salesforce/community`, it can target only an Experience Builder page. The component can’t be used in any other Salesforce container. See [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-community-builder.md).

## `@salesforce/contentAssetUrl`

Import content asset files from `@salesforce/contentAssetUrl`.

```javascript
// Syntax
import myContentAsset from "@salesforce/contentAssetUrl/contentAssetReference";
```

```javascript
// Syntax for assets in managed packages
import myContentAsset from "@salesforce/contentAssetUrl/namespace__contentAssetReference";
```

```javascript
// Example
import SALES_WAVE_LOGO from "@salesforce/contentAssetUrl/SalesWaveLogo";
```

- `myContentAsset`—A name that refers to the asset file.

- `contentAssetReference`—The name of the asset file.

  An asset file name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

- `namespace`—If the asset file is in a managed package, this value is the namespace of the managed package.

See [Access Content Asset Files](https://developer.salesforce.com/docs/platform/lwc/create/create-content-assets.md).

## `@salesforce/i18n`

Import internationalization properties from `@salesforce/i18n`.

```javascript
// Syntax
import internationalizationPropertyName from @salesforce/i18n/internationalizationProperty
```

```javascript
// Example
import LANG from "@salesforce/i18n/lang";
```

- `internationalizationPropertyName`—A symbol that identifies the internationalization property.

- `internationalizationProperty`—An internationalization property.

The internationalization properties are listed in [Access Internationalization Properties](https://developer.salesforce.com/docs/platform/lwc/create/create-i18n.md).

## `@salesforce/label`

Import labels in your Salesforce organization from `@salesforce/label`.

```javascript
// Syntax
import labelName from "@salesforce/label/labelReference";
```

```javascript
// Example
import greeting from "@salesforce/label/c.greeting";
```

- `labelName`—A name that refers to the label.
- `labelReference`—The name of the label in your org in the format `namespace.labelName`. We use this format because it’s the same format used in managed packages, in Visualforce, and in other Salesforce technologies. You can use the same format to access labels, `myns.labelName`, regardless of where you’re accessing them.

See [Access Labels](https://developer.salesforce.com/docs/platform/lwc/create/create-labels.md).

## `@salesforce/messageChannel`

Import a Lightning message channel that a component can use to communicate via the Lightning Message Service.

```javascript
// Syntax
import channelName from "@salesforce/messageChannel/channelReference";
```

```javascript
// Syntax for resources in a managed package
import channelName from "@salesforce/messageChannel/channelName__channelReference";
```

```javascript
// Example
import SAMPLEMC from "@salesforce/messageChannel/SampleMessageChannel__c";
```

- `channelName`—A symbol that identifies the message channel.

- `channelReference`—The API name of the message channel.
- `namespace`—If the message channel is in a managed package, this value is the namespace of the managed package. If the message channel is not in a managed package, do not include a namespace.

See [Create a Message Channel](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-intro.md)

## `@salesforce/resourceUrl`

Import static resources in your Salesforce organization from `@salesforce/resourceUrl`.

```javascript
// Syntax
import resourceName from "@salesforce/resourceUrl/resourceReference";
```

```javascript
// Syntax for resources in a managed package
import myResource from "@salesforce/resourceUrl/namespace__resourceReference";
```

```javascript
// Example
import TRAILHEAD_LOGO from "@salesforce/resourceUrl/trailhead_logo";
```

- `myResource`—A name that refers to the static resource.

- `resourceReference`—The name of the static resource.

  A static resource name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

- `namespace`—If the static resource is in a managed package, this value is the namespace of the managed package.

See [Access Static Resources](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md).

## `@salesforce/schema`

Import references to Salesforce objects and fields from `@salesforce/schema`.

```javascript
// Syntax
import objectName from "@salesforce/schema/objectReference";
import objectName from "@salesforce/schema/namespace__objectReference";
import fieldName from "@salesforce/schema/object.fieldReference";
```

```javascript
// Example
import POSITION_OBJECT from "@salesforce/schema/Position__c";
import POSITION_OBJECT from "@salesforce/schema/ns__Position__c";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import SPANNING_FIELD from "@salesforce/schema/Account.Owner.Name";
```

- `objectName`—A symbol that identifies the Salesforce object.
- `objectReference`—The name of a Salesforce object.
- `fieldName`—An imported symbol that identifies the Salesforce field.
- `fieldReference`—The name of a Salesforce field. You can specify up to three **relationship fields** to reference parent objects and fields using this format: `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`.
- `namespace`—If the object or field is in a managed package, this value is the namespace of the managed package.

See [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md).

## `@salesforce/site`

Import the site ID of the current Experience Builder site from `@salesforce/site/Id`.

```javascript
// Syntax
import idName from "@salesforce/site/Id";
```

```javascript
// Example
import siteId from "@salesforce/site/Id";
```

Import the list of active languages in your Experience Builder site from `@salesforce/site/activeLanguages`.

```javascript
// Syntax
import LANGUAGES from "@salesforce/site/activeLanguages";
```

```javascript
import siteLanguages from "@salesforce/site/activeLanguages";
```

The list of active languages in your Experience Builder site includes metadata on the default site language and all other active languages. You can configure a site’s languages in Experience Builder in **Settings** | **Languages**. Inactive languages are excluded from the list. The return value is an array of language objects, where each object includes the language’s label and the code, such as en-US. The array is sorted alphabetically by the label.

See [Get Information About the Current Experience Builder Site](https://developer.salesforce.com/docs/platform/lwc/create/create-community-info.md).

**important:** If a component imports `@salesforce/community` or `@salesforce/site`, it can target only an Experience Builder page. You can’t use the component in any other Salesforce container. See Configure a Component for Experience Builder.

## `@salesforce/user`

Import the current user’s ID from `@salesforce/user/Id`.

```javascript
// Syntax
import userId from "@salesforce/user/Id";
```

```javascript
// Example
import Id from "@salesforce/user/Id";
```

`userId`—An imported symbol that identifies the Salesforce user ID.

To determine whether the user is a guest user, import the current user’s status from `@salesforce/user/isGuest`.

```javascript
// Syntax
import isGuestUser from "@salesforce/user/isGuest";
```

```javascript
// Example
import isGuest from "@salesforce/user/isGuest";
```

`isGuestUser`—A symbol that identifies whether the user is a guest user (`true`) or not (`false`).

See [Get Information About the Current User](https://developer.salesforce.com/docs/platform/lwc/create/get-current-user.md).

## `@salesforce/userPermission`

Import a permission and check whether it’s assigned to the current user.

```javascript
// Syntax
import hasPermission from "@salesforce/userPermission/Permission";
```

```javascript
// Example
import { LightningElement } from 'lwc';
import hasViewSetup from '@salesforce/userPermission/ViewSetup';

export default class App extends LightingElement {
    get isSetupEnabled() {
        return hasViewSetup;
    }

    openSetup(e) {...}
}
```

- `hasPermission`—A boolean indicating whether the current user has the imported permission (`true`) or not (`undefined`).

- `Permission`—The name of a Salesforce user permission.

See [Check Permissions](https://developer.salesforce.com/docs/platform/lwc/create/create-get-permissions.md).

## `@salesforce/customPermission`

Import a custom permission and check whether it’s assigned to the current user.

```javascript
// Syntax
import hasPermission from '@salesforce/customPermission/Permission';
import hasPermission from '@salesforce/customPermission/namespace__Permission;
```

```javascript
// Example
import { LightningElement } from "lwc";
import hasViewReport from "@salesforce/customPermission/acme__ViewReport";

export default class App extends LightingElement {
  get isReportVisible() {
    return hasViewReport;
  }
}
```

- `hasPermission`—A boolean indicating whether the current user has the imported permission (`true`) or not (`undefined`).

- `Permission`—The name of a Salesforce custom permission.

See [Check Permissions](https://developer.salesforce.com/docs/platform/lwc/create/create-get-permissions.md).

<!-- document id=1abf6b7117116fcf238725327eadc6482c166510af8a36a33a9f3705a2725cfc url=/developer/current/en-us/lwc/lwc/guides/create/create-client-form-factor.md -->

# Access Client Form Factor

To access the form factor of the hardware the browser is running on, import the `@salesforce/client/formFactor` scoped module.

```javascript
import formFactorPropertyName from "@salesforce/client/formFactor";
```

- `formFactorPropertyName`—A name that refers to the form factor of the hardware running the browser. Possible values are:
  - `Large`—A desktop client.
  - `Medium`—A tablet client.
  - `Small`—A phone client.

Pass the form factor to the `getRecordCreateDefaults` wire adapter to get the default layout and object information for creating a record.

```javascript
import { getRecordCreateDefaults } from 'lightning/uiRecordApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import FORM_FACTOR from '@salesforce/client/formFactor';

@wire(getRecordCreateDefaults, { objectApiName: ACCOUNT_OBJECT, formFactor: FORM_FACTOR})
accountDefaults;
```

**note:** You can use `@salesforce/client/formFactor` in a [TypeScript file](https://developer.salesforce.com/docs/platform/lwc/guide/ts.md). This scoped module corresponds to the `client.d.ts` type definition in the [@salesforce/lightning-types](https://www.npmjs.com/package/@salesforce/lightning-types) npm package.

**See Also**

- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)
- [getRecordCreateDefaults](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-create-record-values.md)
- [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/lwc/use/use-config-form-factors.md)

<!-- document id=deac1472dc4267b182196a1ad8034c25a41fa74861423162f91bb4d801871ed9 url=/developer/current/en-us/lwc/lwc/guides/create/create-content-assets.md -->

# Access Content Asset Files

Import content asset files from the `@salesforce/contentAssetUrl` scoped module. Convert a Salesforce file into a content asset file to use the file in custom apps and Experience Builder templates.<!-- Reshma Dixit: A Salesforce File that is not yet assetized cannot be packaged, but one that has been assetized is packageable. That one characteristic of an asset file means that it opens it up to the use cases that have "metadata deploy" as one of their use cases: custom app (logos within), community templates (branding images), Insights (folder images [I think]) etc. I think when we say "setup and configuration" use cases, these above are the general categories we're referring to since the asset files used here are not pure data. -->

```javascript
import myContentAsset from "@salesforce/contentAssetUrl/contentAssetReference";
```

```javascript
import myContentAsset from "@salesforce/contentAssetUrl/namespace__contentAssetReference";
```

- `myContentAsset`—A name that refers to the asset file.
- `contentAssetReference`—The name of the asset file.

  An asset file name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

- `namespace`—If the asset file is in a managed package, this value is the namespace of the managed package.

Let’s look at some sample code.

The JavaScript code imports two content asset files.

```javascript
// assetFileExample.js
import { LightningElement } from "lwc";
import SALES_WAVE_LOGO from "@salesforce/contentAssetUrl/SalesWaveLogo";
import PARTNER_LOGOS from "@salesforce/contentAssetUrl/PartnerLogos";

export default class AssetFileExample extends LightningElement {
  // Expose the asset file URL for use in the template
  salesWaveLogoUrl = SALES_WAVE_LOGO;

  // Expose URL of assets included inside an archive file
  goldPartnerLogoUrl = PARTNER_LOGOS + "?pathinarchive=images/gold_partner.png";
}
```

A content asset file can be an archive file with a nested directory structure. To reference an item in an archive, concatenate a string to create the path to the item, as the example does to build `goldPartnerLogoUrl`. To specify the path to the content asset file in the archive, use the `pathinarchive` parameter.

To reference a resource in a template, use `{property}` syntax, which is the same syntax you use to reference any JavaScript property.

<!-- prettier-ignore -->
```html
<!-- assetFileExample.html -->
<template>
  <lightning-card title="Asset File Example" icon-name="custom:custom19">
    <div class="slds-m-around_medium">
      <img src={salesWaveLogoUrl} />
      <img src={goldPartnerLogoUrl} />
    </div>
  </lightning-card>
</template>
```

In a Salesforce DX project, asset files live in the `/force-app/main/default/contentassets` directory. You can’t create subdirectories of `contentassets`. Create an `.asset-meta` [metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_contentasset.htm) file that defines the asset file.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [miscContentAsset](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscContentAsset) component that demonstrates asset file usage.

**See Also**

- [_Lightning Aura Components Developer Guide_: \$ContentAsset](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/expr_contentasset_value_provider.htm)
- [_Salesforce Help_: Find and Create Asset Files in Experience Builder](https://help.salesforce.com/articleView?id=community_builder_find_create_assets.htm)
- [_Salesforce Help_: View and Edit Asset Files](https://help.salesforce.com/articleView?id=files_asset_files_edit_view.htm)
- [_Metadata API Developer Guide_: ContentAsset](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_contentasset.htm)
- [_Object Reference_: ContentAsset](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentasset.htm)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)

<!-- document id=70735b90b2382bd0cb9b55f2dd7fcf6ef380272248ec66f7b5ba582131315d75 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-dom-work.md -->

# Access Elements the Component Owns

To access elements rendered by a component with standard DOM APIs, use `querySelector()` with `this.template` or `this`. To locate elements in the DOM without a selector, use refs.

**important:** Don’t use the `window` or `document` global properties to query for DOM elements. See [DOM Access Containment](/docs/platform/lightning-components-security/guide/locker-dom.html). Also, we don’t recommend using JavaScript to manipulate the DOM unless you're working with a [third-party library via `lightning/platformResourceLoader`](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md). It's better to use the Lightning Web Components [HTML directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) to write declarative code.

## querySelector()

The standard way to access elements in the DOM is to use `querySelector()`. To locate shadow DOM nodes, use `querySelector()` or `querySelectorAll()` on `this.template`. For light DOM nodes, use one of those methods on `this`.

```javascript
// shadow DOM
this.template.querySelector("div");

// light DOM
this.querySelector("div");
```

**note:** You can also use `{element}.template.querySelector`.

Use these methods to look for the elements that your component rendered.

- The order of elements is not guaranteed.
- Elements not rendered to the DOM aren’t returned in the `querySelector` result.
- Don’t use ID selectors with `querySelector`. The IDs that you define in HTML templates may be transformed into globally unique values when the template is rendered. If you use an ID selector in JavaScript, it won’t match the transformed ID.
- For light DOM components, `this.querySelector()` searches through elements outside of the immediate template, such as light DOM children. Use a more specific selector to narrow the scope of the method.
- If the component runs in an org with Lightning Locker enabled, be aware of a [potential memory leak](/docs/platform/lightning-components-security/guide/locker-queryselector.html). If possible, the org should [enable Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-enable.html). Alternatively, consider using refs instead of `querySelector`.
- Place light DOM components within a shadow DOM component. Lightning Locker and LWS don’t support light DOM components outside shadow DOM.

```html
<!-- example.html -->
<template>
  <div>First <slot name="task1">Task 1</slot></div>
  <div>Second <slot name="task2">Task 2</slot></div>
</template>
```

```javascript
// example.js
import { LightningElement } from "lwc";

export default class Example extends LightningElement {
  renderedCallback() {
    this.template.querySelector("div"); // <div>First</div>
    this.template.querySelector("span"); // null
    this.template.querySelectorAll("div"); // [<div>First</div>, <div>Second</div>]
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [miscDomQuery](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscDomQuery) component that demonstrates DOM querying using `querySelectorAll`.

## Refs

Refs locate DOM elements without a selector and only query elements contained in a specified template. First, add the `lwc:ref` directive to your element and assign it a value. To call that reference, use `this.refs`. In this example, the `<div>` element has the directive `lwc:ref="myDiv"`, which `this.refs` references to access the `<div>` at runtime.

```html
<template>
  <div lwc:ref="myDiv"></div>
</template>
```

```javascript
export default class extends LightningElement {
  renderedCallback() {
    console.log(this.refs.myDiv);
  }
}
```

### Considerations

You must define the directive `lwc:ref` before calling `this.refs`. If you call `this.refs` for a nonexistent ref, it returns `undefined`. If the template contains duplicate `lwc:ref` directives, `this.refs` references the last `<div>`.

```html
<template>
  <div lwc:ref="myDiv"></div>
  <div lwc:ref="myDiv"></div>
</template>
```

`this.refs` is a plain, read-only object. Trying to add, modify, or delete properties from within its component causes a runtime error. Its key is a string, and its value is a DOM element. The syntax for `this.refs` is the same for referencing elements in light DOM and shadow DOM.

Refs are configurable and writable, so refs defined in a component overwrite those from `LightningElement.prototype`.

You can’t apply `lwc:ref` to `<template>` elements, or to `<slot>` elements in light DOM.

<!-- prettier-ignore -->
```html
<template lwc:render-mode="light">
  <template lwc:if={myTemplate} lwc:ref="myTemplate"></template>
  <!-- Not allowed -->
</template>
```

```html
<template lwc:render-mode="light">
  <slot lwc:ref="mySlot"></slot>
  <!-- Not allowed -->
</template>
```

If you place `lwc:ref` in a `for:each` or `iterator:*` loop, the template compiler throws an error.

<!-- prettier-ignore -->
```html
<template for:each={items} for:item="item">
  <div key={item} lwc:ref="foo"></div>
  <!-- Not allowed -->
</template>
```

### Multiple Templates

`this.refs` refers to the most recently rendered template in a multi-template component. When the template changes, the `this.refs` object will change too.

```javascript
import a from "./a.html";
import b from "./b.html";

export default class extends LightningElement {
  count = 0;

  render() {
    return this.count % 2 === 0 ? a : b;
  }

  renderedCallback() {
    console.log(this.refs);
  }

  increment() {
    this.count++;
  }
}

const cmp = createElement("c-component", { is: Component });
// Logs `this.refs` for a.html

cmp.increment();
// Logs `this.refs` for b.html

cmp.increment();
// Logs `this.refs` for a.html
```

To conditionally define an element based on `<template lwc:if={boolean}>`, create multiple child templates under one parent template. In this example, `this.refs.toggleDarkMode` refers to the element inside of whichever child template is rendered.

<!-- prettier-ignore -->
```html
<template>
  <template lwc:if={darkMode}>
    <button lwc:ref="toggleDarkMode">Enable Light Mode</button>
  </template>
  <template lwc:else>
    <button lwc:ref="toggleDarkMode">Enable Dark Mode</button>
  </template>
</template>
```

## Access the Parent Element

| AVAILABLE API VERSIONS               |
| ------------------------------------ |
| Available in LWC API v62.0 and later |

To access the [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) of a Lightning web component from within a [callback function](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.html), use `this.hostElement` in your component. The `hostElement` property lets you retrieve a property on the `HTMLElement` class. You can apply it to shadow DOM or light DOM components.

This example returns `this.hostElement` in a light DOM component.

```javascript
// c-light
import { LightningElement } from "lwc";

export default class extends LightningElement {
  static renderMode = "light"; // default is 'shadow'

  renderedCallback() {
    console.log(this.hostElement); // logs <c-light>
  }
}
```

In light DOM, `this.template.host` returns `undefined`. In shadow DOM, `this.hostElement` is interchangeable with `this.template.host`.

**See Also**

- [Light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md)
- [API Versioning](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-api-versioning.md)

<!-- document id=ede7e31471d2614de0a573fbd19d6638ea5ed6d0ca587892cee372a4c2cc8e67 url=/developer/current/en-us/lwc/lwc/guides/create/create-i18n.md -->

# Access Internationalization Properties

Import internationalization properties from the `@salesforce/i18n` scoped module. LWC provides internationalization properties that you can use to adapt your components for users worldwide, across languages, currencies, and timezones.

In a single currency organization, Salesforce administrators set the currency locale, default language, default locale, and default time zone for their organizations. Users can set their individual language, locale, and time zone on their personal settings pages.

We recommend that you use base components like `lightning-input` and `lightning-formatted-time` as they adapt automatically to the language, locale, and time zone settings of the Salesforce org they run in. For more information, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

To internationalize your own components so that they also adapt, use the internationalization properties.

```javascript
import internationalizationPropertyName from @salesforce/i18n/internationalizationProperty
```

- `internationalizationPropertyName`—A name that refers to the internationalization property.
- `internationalizationProperty`—An internationalization property.

The property values are returned for the current user.

| Internationalization Property    | Description                                                                                            | Sample Value                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `lang`                           | Language                                                                                               | `en-US`                                                                                     |
| `dir`                            | Direction of text                                                                                      | `ltr`                                                                                       |
| `locale`                         | Locale                                                                                                 | `en-CA`                                                                                     |
| `defaultCalendar`                | Default calendar format based on locale                                                                | `Gregorian`                                                                                 |
| `defaultNumberingSystem`         | Default numbering system based on locale                                                               | `latn`                                                                                      |
| `calendarData`                   | Calendar formats for the user’s locale                                                                 | `gregorian: {dayPeriods : {...}, days: {...}, eras: {...}, months: {...}, quarters: {...}}` |
| `currency`                       | Currency code                                                                                          | `CAD`                                                                                       |
| `firstDayOfWeek`                 | First day of the week                                                                                  | `1`                                                                                         |
| `isEasternNameStyle`             | Specifies if a name follows Eastern style, for example, `last name first name [middle] [suffix]`       | false                                                                                       |
| `common.calendarData`            | Supplementary calendar data for common calendar formats. The value is determined by `defaultCalendar`. | `gregorian:{calendarSystem:'solar',eras:{'0':{_end:'0-12-31'},'0':{_end:'1-01-01'}}}`       |
| `common.digits`                  | Unicode characters for numerical values                                                                | `0123456789`                                                                                |
| `dateTime.shortDateFormat`       | Short style date format                                                                                | `MM/dd/yyyy`                                                                                |
| `dateTime.mediumDateFormat`      | Medium style date format                                                                               | `MMM d, yyyy`                                                                               |
| `dateTime.longDateFormat`        | Long style date format                                                                                 | `MMMM d, yyyy`                                                                              |
| `dateTime.shortDateTimeFormat`   | Short style datetime format                                                                            | `MM/dd/yyyy h:mm a`                                                                         |
| `dateTime.mediumDateTimeFormat`  | Medium style datetime format                                                                           | `MMM d, yyyy h:mm:ss a`                                                                     |
| `dateTime.longDateTimeFormat`    | Long style datetime format                                                                             | `MMMM d, yyyy ‘at’ h:mm:ss a * z`                                                           |
| `dateTime.shortTimeFormat`       | Short style time format                                                                                | `h:mm a`                                                                                    |
| `dateTime.longTimeFormat`        | Long style time format                                                                                 | `h:mmss a`                                                                                  |
| `number.currencyFormat`          | Currency format                                                                                        | `#, ##0.00`                                                                                 |
| `number.currencySymbol`          | Currency symbol                                                                                        | `$`                                                                                         |
| `number.decimalSeparator`        | Decimal separator                                                                                      | `.`                                                                                         |
| `number.exponentialSign`         | Exponential symbol                                                                                     | `E`                                                                                         |
| `number.groupingSeparator`       | Grouping separator                                                                                     | `,`                                                                                         |
| `number.infinity`                | Infinity symbol                                                                                        | `∞`                                                                                         |
| `number.minusSign`               | Minus sign symbol                                                                                      | `-`                                                                                         |
| `number.nan`                     | String for “Not a number”                                                                              | `NaN`                                                                                       |
| `number.numberFormat`            | Number format                                                                                          | `#, ##0.###`                                                                                |
| `number.perMilleSign`            | Per mille symbol                                                                                       | `‰`                                                                                         |
| `number.percentFormat`           | Percent format                                                                                         | `#, ###0%`                                                                                  |
| `number.percentSign`             | Percent sign symbol                                                                                    | `%`                                                                                         |
| `number.plusSign`                | Plus sign symbol                                                                                       | `+`                                                                                         |
| `number.superscriptExponentSign` | Superscript exponent symbol                                                                            | `×`                                                                                         |
| `showJapaneseCalendar`           | Specifies whether to show dates in the Japanese Imperial calendar format                               | false                                                                                       |
| `timeZone`                       | Time zone                                                                                              | `America/Los_Angeles`                                                                       |

**note:** For LWR sites, the `lang` and `locale` are mapped to the language configured for the site, and `timeZone` is determined by the browser’s timezone rather than the user’s personal settings.
Additionally, `currency`, `number.currencySymbol`, and `number.currencyFormat` are unsupported.
If the site or org language configurations are updated, you must republish the site.

## Internationalization Value Formatting

Values returned by an internationalization property correspond to the formatting described by the [Unicode Locale Data Markup Language (LDML)](http://www.unicode.org/reports/tr35/). For example, `common.calendarData` follows the [Calendar Data LDML specification](https://unicode-org.github.io/cldr/ldml/tr35-dates.html#Calendar_Data).

## Example: Format a Date Into a Localized String

Dates are formatted differently in different languages. For example, the US uses Month, Day, Year, like 2/15/19. The United Kingdom uses Day, Month, Year, like 15/2/19.

To format a date according to the user’s language, import the user’s locale from the `@salesforce/i18n/locale` module. To format the date, use the JavaScript [Internationalization API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).

```javascript
// formatDate.js
import { LightningElement } from "lwc";
import LOCALE from "@salesforce/i18n/locale";

export default class FormatDate extends LightningElement {
  date = new Date(2020, 6, 7);
  formattedDate = new Intl.DateTimeFormat(LOCALE).format(this.date);
}
```

```html
<!-- formatDate.html -->
<template> {formattedDate} </template>
```

Alternatively, use the [`lightning-formatted-date-time`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time) base component for date and time formatting.

## Example: Format a Number Into a Localized Currency String

This example uses the `locale` and `currency` properties to format a number into a localized currency string.

```javascript
// formatNumber.js
import { LightningElement } from "lwc";
import LOCALE from "@salesforce/i18n/locale";
import CURRENCY from "@salesforce/i18n/currency";

export default class FormatNumber extends LightningElement {
  number = 123456.78;
  formattedNumber = new Intl.NumberFormat(LOCALE, {
    style: "currency",
    currency: CURRENCY,
    currencyDisplay: "symbol",
  }).format(this.number);
}
```

```html
<!-- formatNumber.html -->
<template> {formattedNumber} </template>
```

The `Intl.NumberFormat` object defines the currency output. For a user's given locale, display the numerical value as currency and provide the localized currency symbol.

Alternatively, use the [`lightning-formatted-number`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number/) base component for number, currency, and percentage formatting.

## Set HTML Attributes

To bind internationalization properties to HTML attributes, store them as private properties in your component's JavaScript file. Here, `lang` determines the user's language and `dir` specifies the direction that the text displays in HTML.

```javascript
// languageExample.js
import { LightningElement } from "lwc";
import LANG from "@salesforce/i18n/lang";
import DIR from "@salesforce/i18n/dir";

export default class LanguageExample extends LightningElement {
  lang = LANG;
  dir = DIR;
}
```

In your HTML template, reference the values with `{property}`.

<!-- prettier-ignore -->
```html
<!-- languageExample.html -->
<template>
  <p lang={lang} dir={dir}><!-- Localized text in a paragraph --></p>
</template>
```

**See Also**

- [_Salesforce Help_: Select Your Language, Locale, and Currency](https://help.salesforce.com/articleView?id=admin_language_locale_currency.htm)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)
- [Unicode Locale Data Markup Language (LDML)](https://unicode-org.github.io/cldr/ldml/tr35.html)
- [Translate Picklist Labels](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-picklist-values.md#translate-picklist-labels)

<!-- document id=e1d0cf309f65ca051ca4f9c99c3b4588562d481d98493f9fbf910a7b044ea71c url=/developer/current/en-us/lwc/lwc/guides/create/create-labels.md -->

# Access Labels

Import labels from the `@salesforce/label` scoped module. Custom labels are text values stored in Salesforce that can be translated into any language that Salesforce supports. Use custom labels to create multilingual applications that present information (for example, help text or error messages) in a user’s native language.

```javascript
import labelName from "@salesforce/label/labelReference";
```

- `labelName`—A name that refers to the label.
- `labelReference`—The name of the label in your org in the format `namespace.labelName`. We use this format because it’s the same format used in managed packages, in Visualforce, and in other Salesforce technologies. You can use the same format to access labels, `myns.labelName`, regardless of where you’re accessing them.

This sample code imports two labels.

```javascript
// labelExample.js
import { LightningElement } from "lwc";

// Import the URL for the static resource named 'salesforceLogo'
import SALESFORCE_LOGO from "@salesforce/resourceUrl/salesforceLogo";

// Import custom labels
import greeting from "@salesforce/label/c.greeting";
import salesforceLogoDescription from "@salesforce/label/c.salesforceLogoDescription";

export default class LabelExample extends LightningElement {
  // Expose the static resource URL to use in the template.
  logoUrl = SALESFORCE_LOGO;

  // Expose the labels to use in the template.
  label = {
    greeting,
    salesforceLogoDescription,
  };
}
```

To use the labels in the template, use the same `{property}` syntax that you use to reference any JavaScript property.

<!-- prettier-ignore -->
```html
<!-- labelExample.html -->
<template>
  <c-page-header
    header="Using static resources and custom labels"
    description="This sample shows how to reference external items like static resources and custom labels"
  ></c-page-header>

  <c-card>
    <img src={logoUrl} alt={label.salesforceLogoDescription} width="100" /><br />
    <br />
    {label.greeting}
  </c-card>
</template>
```

In a Salesforce DX project, label files can live in any subdirectory of `force-app/main/default`. For example, this file named `ExampleLabels.labels-meta.xml` lives in `force-app/main/default/mylabels`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
    <labels>
        <fullName>quoteManual</fullName>
        <value>This is a manual quote.</value>
        <language>en_US</language>
        <protected>false</protected>
        <shortDescription>Manual Quote</shortDescription>
    </labels>
    <labels>
        <fullName>quoteAuto</fullName>
        <value>This is an automatically generated quote.</value>
        <language>en_US</language>
        <protected>false</protected>
        <shortDescription>Automatic Quote</shortDescription>
    </labels>
</CustomLabels>
```

**See Also**

- [_Salesforce DX Developer Guide_: Salesforce DX Project Structure and Source Format](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm)
- [_Salesforce Help_: Custom Labels](https://help.salesforce.com/articleView?id=cl_about.htm)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)

<!-- document id=dbfdb87f946882ae7ac27e4a412f9dd1984e493d62365e660df7279561fed2b0 url=/developer/current/en-us/lwc/lwc/guides/create/create-resources.md -->

# Access Static Resources

Import static resources from the `@salesforce/resourceUrl` scoped module. Static resources can be archives (such as .zip and .jar files), images, stylesheets, JavaScript, and other files.

Before you can import a static resource, create and upload the file.

## Create and Upload a Static Resource

To create and upload a static resource:

1. From Setup, enter `Static Resources` in the Quick Find box, then select **Static Resources**.
2. Click **New**.
3. In the `Name` text box, enter the text that's used to identify the resource in your LWC code.

   **note:** A static resource name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.

4. In the `Description` text area, specify an optional description of the resource.
5. Click **Browse** to navigate to a local copy of the resource that you want to upload. The maximum file size is 5 MB. An org can have up to 250 MB of static resources.
6. Set the `Cache Control` for user sessions, including API and Experience Cloud user sessions:
   - `Private` specifies that the static resource data cached on the Salesforce server must not be shared with other users. The static resource is stored in cache only for the current user’s session.
   - `Public` specifies that the static resource data cached on the Salesforce server is shared with other users in your organization for faster load times. After it’s cached, the resource is accessible to all Internet traffic, including unauthenticated users.
7. Click **Save**.

For more information, see [_Salesforce Help_: Static Resources](https://help.salesforce.com/articleView?id=pages_static_resources.htm).

## Import a Static Resource

Import a static resource using this syntax.

```javascript
import myResource from "@salesforce/resourceUrl/resourceReference";
```

```javascript
import myResource from "@salesforce/resourceUrl/namespace__resourceReference";
```

- `myResource`—A name that refers to the static resource.
- `resourceReference`—The name of the static resource.
- `namespace`—If the static resource is in a managed package, this value is the namespace of the managed package.

Let’s look at some sample code.

The JavaScript code imports two resources: a Trailhead logo and an image of a Trailhead character.

```javascript
// miscStaticResource.js
import { LightningElement } from "lwc";
import TRAILHEAD_LOGO from "@salesforce/resourceUrl/trailhead_logo";
import TRAILHEAD_CHARACTERS from "@salesforce/resourceUrl/trailhead_characters";

export default class MiscStaticResource extends LightningElement {
  // Expose the static resource URL for use in the template
  trailheadLogoUrl = TRAILHEAD_LOGO;

  // Expose URL of assets included inside an archive file
  einsteinUrl = TRAILHEAD_CHARACTERS + "/images/einstein.png";
}
```

A static resource can be an archive file with a nested directory structure. To reference an item in an archive, concatenate a string to create the path to the item, as the example does to build `einsteinUrl`.

To reference a resource in a template, use `{property}` syntax, which is the same syntax you use to reference any JavaScript property.

<!-- prettier-ignore -->
```html
<!-- miscStaticResource.html -->
<template>
  <lightning-card title="MiscStaticResource" icon-name="custom:custom19">
    <div class="slds-m-around_medium">
      <img src={trailheadLogoUrl} />
      <img src={einsteinUrl} />
    </div>
  </lightning-card>
</template>
```

In a Salesforce DX project, static resources live in the `/force-app/main/default/staticresources` directory. You can’t create subdirectories of `staticresources`.

Create a `.resource-meta` metadata file for each resource. The metadata file defines the [content type](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_staticresource.htm) of the resource.

**tip:** This code sample is the `miscStaticResource` component in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/miscStaticResource) repo.

**See Also**

- [_Salesforce DX Developer Guide_: Salesforce DX Project Structure and Source Format](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm)
- [_Lightning Aura Components Developer Guide_: \$Resource](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/expr_resource_value_provider.htm)
- [_Metadata API Developer Guide_: StaticResource](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_staticresource.htm)
- [_Object Reference_: StaticResource](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_staticresource.htm)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)

<!-- document id=01ab95d0c0e0d5725dd7a50e6f4e39124b42417c0e29f60fa53cf9d33656f270 url=/developer/current/en-us/lwc/lwc/guides/create/create-global-value-providers.md -->

# Access Static Resources, Labels, Internationalization Properties, User IDs, and Form Factors

Lightning web components can access global Salesforce values, such as labels, resources, and users.

You can import these Salesforce resources from a component's JavaScript file.

- [Static Resources](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.md)
- [Content Asset Files](https://developer.salesforce.com/docs/platform/lwc/guide/create-content-assets.md)
- [SVG Resources](https://developer.salesforce.com/docs/platform/lwc/use/use-svg-in-component.md)
- [Labels](https://developer.salesforce.com/docs/platform/lwc/guide/create-labels.md)
- [Internationalization](https://developer.salesforce.com/docs/platform/lwc/guide/create-i18n.md)
- [Current User ID](https://developer.salesforce.com/docs/platform/lwc/guide/get-current-user.md)
- [Current Community](https://developer.salesforce.com/docs/platform/lwc/guide/create-community-info.md)
- [Permissions](https://developer.salesforce.com/docs/platform/lwc/guide/create-get-permissions.md)
- [Client Form Factor](https://developer.salesforce.com/docs/platform/lwc/guide/create-client-form-factor.md)

<!-- document id=92fe3323624b2f93f9e0247dd56c5431f11094f42c11e161b00f111073c2e5d6 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-iframes.md -->

# Access to iframe Content in Lightning Web Security

When Lightning Web Security (LWS) is enabled, Lightning components can access content in `iframe` elements when the content is from the same origin. [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md) prevents accessing `iframe` content even from the same origin.

Web browsers prevent access to content from a different origin.
Browsers follow the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) to block cross-origin content in `iframe` elements. Some properties such as `iframe.contentWindow.postMessage` are allowed. For more about cross-origin accessible window properties, see [CrossOriginProperties](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/%3Chttps://html.spec.whatwg.org/multipage/browsers.html#crossoriginproperties-(-o-)>) in the HTML spec.

LWS maintains the `iframe` identity across the sandbox boundary, so that checking the identity of `postMessage` event origin works normally.

LWS restricts the `src` attribute for `iframe` elements to values that use the `http://` and `https://` schemes. URL schemes like `javascript://` aren’t allowed.

LWS doesn’t allow iframe elements in Blob objects.

<!-- document id=d3a27e50c472a5539b3b8d1fcda08f6c5d349bd946e5389cbccf87a777ead160 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-js-api.md -->

# Access to Supported JavaScript API Framework Methods

When developing Aura components, you can only access published, [supported JavaScript API framework methods](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_jsapi_intro.htm). Previously, unsupported methods were accessible, which exposed your code to the risk of breaking when unsupported methods were changed or removed.

**See Also**

- [_Lightning Aura Components Developer Guide_: Using JavaScript](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_intro.htm)

<!-- document id=979e1e48bdcf1ebe1d7f73799b4f7db293974e8986d7f33dc8ca48c1da518d33 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-custom-tab-lex.md -->

# Add Components as Custom Tabs in a Lightning Experience App

Make a Lightning web component available in a custom tab, so that it’s accessible in Lightning Experience, both on desktop and in the Salesforce mobile app.

To configure a Lightning web component to be used as a custom tab, see [Configure Components for Custom Tabs](https://developer.salesforce.com/docs/platform/lwc/use/use-config-custom-tab.md).

To include your component in a Lightning Experience app and make it available to desktop and mobile users in your org, follow these steps.

1.  Create a custom tab for the component.

    1.  From Setup, enter `Tabs` in the Quick Find box, then select **Tabs**.

    2.  Click **New** in the Lightning Component Tabs related list.

    3.  Select the Lightning component that you want to make available to users.

    4.  Enter a label to display on the tab.

    5.  Select the tab style and click **Next**.

    6.  When prompted to add the tab to profiles, accept the default and click **Save**.

        Your Lightning component is now available from the All Items section of the App Launcher on desktop, and the All Items navigation menu item in the Salesforce mobile app.

2.  Add your Lightning component to a Lightning app’s navigation.

    1.  From Setup, enter `Apps` in the Quick Find box, then select **App Manager**.

    2.  Edit an existing app or create an app.

    3.  On the Navigation Items screen, select your Lightning component tab from the Available Items list and move it to the Selected Items list.

    4.  Save the app.

3.  Check your output.

    1.  Navigate to the App Launcher in Lightning Experience on desktop or in the Salesforce mobile app.

    2.  Search for the custom app name and click it.

    3.  See the component that you added.

**See Also**

- [Configure Components for Custom Tabs](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab.md)

<!-- document id=cf53be9e275ff11566293a2b4cc2963110466565b40f1b9b40f4dd9f37315d81 url=/developer/current/en-us/lwc/lwc/guides/use/use-packaging-add.md -->

# Add Components to Managed Packages

**important:** Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

A managed package ensures that your application and other resources are fully upgradeable.

To create and work with managed packages, use a Developer Edition organization and register a namespace prefix. A managed package includes your namespace prefix in the component names and prevents naming conflicts in an installer’s organization.

**note:** For a component to reference a Lightning web component installed from a managed package, [Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html) must be enabled in the subscriber's org. See [Component Namespaces](https://developer.salesforce.com/docs/platform/lwc/create/create-components-namespace.md).

AppExchange partners have two types of managed packages to choose from: second-generation managed packages (2GP) and first-generation managed packages (1GP). When working with managed packages, follow these guidelines.

- We recommend using 2GP for all new managed packages. To add components to your 2GP, include the components in your package directory and then [create a package version](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev_dev2gp_create_pkg_ver.htm).
- Add components to your 1GP by [adding them in your 1GP packaging org](https://developer.salesforce.com/docs/atlas.en-us.pkg1_dev.meta/pkg1_dev/uploading_packages.htm).

When you add a component to a package, other components referenced by the component and any resources imported with `@salesforce/*` are automatically included. For more information, see [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md).

After a package is released, the component name is locked, but the package developer can still edit these values in a component’s configuration file.

- `apiVersion`
- `description`
- `isExposed` (can only change from `false` to `true`)
- `masterLabel`
- `targetConfigs`
- `targets`

## Considerations When Using `isExposed`

Keep these considerations about the `isExposed` field in mind when working with 1GP, 2GP, and unlocked packages.

- If `isExposed` is `false`, the package developer can remove configuration targets and a public (@api) property from a component. The component isn't available to other namespaces or to Salesforce builders like Lightning App Builder and Experience Builder.
- If `isExposed` is `true` and the component is in a published managed package, the package developer can’t remove configuration targets or a public (`@api`) property from a component. This restriction is enforced even if the target or public property was added after the most recent publication of the package.
- When you delete a Lightning web component with an `isExposed` value of `true`, we recommend a two-stage process to ensure that the deleted component has no dependencies on the other items in the package. [See Remove Components from Second-Generation Managed Packages](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev_dev2gp_remove_md_components.htm).
- If `isExposed` is `true`, the component is available to other namespaces, including namespaces outside of a published managed package. The component is also available to Salesforce builders such as Lightning App Builder and Experience Builder.

## Licensing Considerations

By default, LWC doesn't automatically enforce managed package licensing. Users can see and use Lightning web components in a managed package even if they don’t have active licenses for that package. Users can also see and use Lightning web components in a managed package after a trial of that managed package expires. AppExchange partners are responsible for enforcing package licensing in their components.

We recommend that you use an Apex controller that calls either the [`UserInfo.isCurrentUserLicensed(namespace)`](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_userinfo.htm#apex_System_UserInfo_isCurrentUserLicensed) or [`UserInfo.isCurrentUserLicensedForPackage(packageID)`](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_userinfo.htm#apex_System_UserInfo_isCurrentUserLicensedForPackage) methods. If `false` is returned, don't render the component. Instead, show a message informing the user they aren't licensed for the managed package.

**See Also**

- [ISVforce Guide](https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/)
- [_Second-Generation Managed Packaging Developer Guide_: Components Available in Managed Packages](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/packaging_packageable_components.htm#mdc_lightning_component)

<!-- document id=b1f8b5d776696a77f33246662cdf37e352d20cc9fe7f43f1d758a690255c0a8a url=/developer/current/en-us/lwc/lwc/guides/use/use-email-builder-components-html.md -->

# Add Custom HTML To a Component

You can add custom HTML to your components for use in the email content builder.

Specify a special attribute and value in the template markup to the element to be in the innerHTML container: `ishtmlcontainer="true"`.

In your template, attach the attribute and value `ishtmlcontainer="true"` to where you want to specify an innerHTML container.

<!-- prettier-ignore -->
```html
<template>
  <div ishtmlcontainer="true" lwc:dom="manual"></div>
</template>
```

In your JavaScript file, create a setter and getter for your `htmlValue` attribute. Leave them empty for now.

```javascript
@api
set htmlValue(value) {

}

get htmlValue() {

}

```

Add a `renderedCallback()` method in which you create an instance variable to hold a reference to the elements holding the innerHTML property (referred to as `attachmentPoint`). On that element’s innerHTML property, assign it the value of the property you just created.

```javascript
renderedCallback() {
    this.attachmentPoint = this.template.querySelector('div[ishtmlcontainer=true]');
    this.attachmentPoint.innerHTML = this.htmlValue;
}

```

In the setter, add a check for the assignment of the instance variable you created. Assign the new value to the instance variable’s innerHTML attribute and assign the value to a non-public property. In the getter, return the value of the non-public property.

```javascript
import { LightningElement, api } from "lwc";

export default class CustomInner extends LightningElement {
  @api
  set htmlValue(value) {
    if (this.attachmentPoint) {
      this.attachmentPoint.innerHTML = value;
    }
    this._htmlValue = value;
  }

  get htmlValue() {
    return this._htmlValue;
  }

  renderedCallback() {
    this.attachmentPoint = this.template.querySelector("div[ishtmlcontainer=true]");
    this.attachmentPoint.innerHTML = this.htmlValue;
  }
}
```

Define default values and other properties of the property in the `.js-meta.xml` file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="CustomInner">
    <apiVersion>53.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Custom Inner HTML</masterLabel>
    <description>Display HTML-enhanced text</description>
    <targets>
        <target>lightningStatic__Email</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningStatic__Email">
            <property name="htmlValue" type="String" required="true" default="YOUR CUSTOM INNER HTML HERE"/>
            ...
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

```

**See Also**

- [renderedCallback()](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-rendered.md)
- [Configure a Component for the Email Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-email-builder-component-steps.md)

<!-- document id=74b7c8ca3531bb0bbc17d58636fc86fa004558ec3fba7709fc68de8503e7a687 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-spread-dynamic.md -->

# Add Event Listeners Dynamically on Children

To add an event listener dynamically to a child component, use the `lwc:on` directive.

Let's say you have a component `spreadOnEvent` with a child component `spreadOnEventChild`. You want to pass properties to the child component with an event handler.

<!-- prettier-ignore -->
```html
<!-- spreadOnEvent.html -->
<template>
  <c-spread-on-event-child
    lwc:spread={childProps}
    lwc:on={eventHandlers}
  ></c-spread-on-event-child>
  <p>Custom event received: {customEventDetail}</p>
</template>
```

The `spreadOnEvent` component uses `lwc:on` to attach a handler for a custom event on the child. The child component dispatches events both when it's inserted into the DOM and when a button is clicked, sending messages and updated properties back to the parent. The parent component updates its display based on the `detail` property that's received from the child component's events.

```javascript
// spreadOnEvent.js
import { LightningElement } from "lwc";

export default class SpreadOnEvent extends LightningElement {
  childProps = { name: "James Smith", age: "40" };
  customEventDetail = "";
  eventHandlers = {
    customEvent: this.handleCustomEvent,
  };

  handleCustomEvent(event) {
    this.customEventDetail = event.detail.message;
    this.childProps.name = event.detail.name;
    this.childProps.age = event.detail.age;
  }
}
```

The child component `spreadOnEventChild` displays the `name` and `age` property values, and a button to dispatch the custom event.

<!-- prettier-ignore -->
```html
<!-- spreadOnEventChild -->
<template>
  <div>Child Component</div>
  <p>Name: {name}</p>
  <p>Age: {age}</p>
  <lightning-button onclick={handleButtonClick} label="Get custom event"> </lightning-button>
</template>
```

On initial load, the `name` and `age` properties display "James Smith" and "40", which are values that are passed down from the parent component. When the button is clicked, the custom event dispatches and sets the values "LWC" and "8" on the child component.

```javascript
// spreadOnEventChild.js
import { LightningElement, api } from "lwc";

export default class SpreadOnEventChild extends LightningElement {
  @api name;
  @api age;

  connectedCallback() {
    // Dispatch a custom event when this component is connected
    this.dispatchEvent(
      new CustomEvent("customEvent", {
        detail: {
          message: "Hello from child component",
          name: this.name,
          age: this.age,
        },
      }),
    );
  }

  handleButtonClick() {
    this.dispatchEvent(
      new CustomEvent("customEvent", {
        detail: {
          message: "Button clicked in child component",
          name: "LWC",
          age: "8",
        },
      }),
    );
  }
}
```

<!-- document id=b4361e58885650e213db0649731be3137cdf384f0cb7a7230aa33b4ebf0fb67b url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-add-params-url.md -->

# Add Query Parameters

To add query parameters to the URL, update the `PageReference.state` property. The navigation service uses a `PageReference` to generate a URL. The key-value pairs of the `state` property are serialized to URL query parameters. The query parameters describe the page and form a more specific URL that the user can save or bookmark.

## Work With the `state` Property

Keep these behaviors in mind when working with the `state` property.

- The `PageReference` object is frozen, so you can’t change it directly. To navigate to the same page with a modified `state`, copy the current `PageReference` and modify the copy using `Object.assign({}, pageReference)`.
- `state` properties must use a namespace prefix followed by two underscores, `__`. If the component isn’t part of a managed package, use `c` for the namespace prefix. If the component is part of a managed package, use the package's namespace.
- Since the key-value pairs of `PageReference.state` are serialized to URL query parameters, all the values must be strings.
- Code that consumes a value from `state` must parse the value into its proper format.
- To delete a value from the `state` object, set it as `undefined`.
- Even when using HTTPS, including personal data for URL parameters isn’t safe. See [Storing Sensitive Data](https://developer.salesforce.com/docs/atlas.en-us.secure_coding_guide.meta/secure_coding_guide/secure_coding_storing_sensitive_data.htm) for details.
- In Lightning Experience and Experience Builder sites that are built with Aura or LWR templates, the view isn’t rerendered when only the URL query string changes. To react to a change in the URL query string, we recommend that components observe the `CurrentPageReference` object and compare against the page reference's `state`.

## Example: Update the Current Page State

The component in this example has a link labeled **Show Panel** that changes to **Hide Panel** when clicked. Clicking either link updates the current page's state. When the page state changes, the `this.currentPageReference` property, decorated with `@wire(CurrentPageReference)`, updates. The component rerenders to show or hide the panel and update the link label.

<!-- prettier-ignore -->
```html
<!-- pageStateChangeExample.html -->
<template>
  <div>
    <a href={showPanelUrl} onclick={handleShowPanelClick}>Show Panel</a>
  </div>
  <div lwc:if={showPanel}>
    <h1>This is the panel</h1>
    <a href={noPanelUrl} onclick={handleNoPanelClick}>Hide Panel</a>
  </div>
</template>
```

```javascript
// pageStateChangeExample.js
import { LightningElement, wire } from "lwc";
import { CurrentPageReference, NavigationMixin } from "lightning/navigation";

export default class PageStateChangeExample extends NavigationMixin(LightningElement) {
  // Declare the currentPageReference variable in order to track it
  currentPageReference;
  // Injects the page reference that describes the current page
  @wire(CurrentPageReference)
  setCurrentPageReference(currentPageReference) {
    this.currentPageReference = currentPageReference;

    if (this.connected) {
      // We need to have the currentPageReference, and to be connected before
      // we can use NavigationMixin
      this.generateUrls();
    } else {
      // NavigationMixin doesn't work before connectedCallback, so if we have
      // the currentPageReference, but haven't connected yet, queue it up
      this.generateUrlOnConnected = true;
    }
  }

  showPanelUrl;
  noPanelUrl;

  // Determines the display for the component's panel
  get showPanel() {
    // Derive this property's value from the current page state
    return this.currentPageReference && this.currentPageReference.state.c__showPanel == "true";
  }

  generateUrls() {
    this[NavigationMixin.GenerateUrl](this.showPanelPageReference).then(
      (url) => (this.showPanelUrl = url),
    );
    this[NavigationMixin.GenerateUrl](this.noPanelPageReference).then(
      (url) => (this.noPanelUrl = url),
    );
  }

  // Returns a page reference that matches the current page
  // but sets the 'c__showPanel' page state property to 'true'
  get showPanelPageReference() {
    return this.getUpdatedPageReference({
      c__showPanel: "true", // Value must be a string
    });
  }

  // Returns a page reference that matches the current page
  // but removes the 'c__showPanel' page state property
  get noPanelPageReference() {
    return this.getUpdatedPageReference({
      // Removes this property from the state
      c__showPanel: undefined,
    });
  }

  // Utility function that returns a copy of the current page reference
  // after applying the stateChanges to the state on the new copy
  getUpdatedPageReference(stateChanges) {
    // The currentPageReference property is read-only.
    // To navigate to the same page with a modified state,
    // copy the currentPageReference and modify the copy.
    return Object.assign({}, this.currentPageReference, {
      // Copy the existing page state to preserve other parameters
      // If any property on stateChanges is present but has an undefined
      // value, that property in the page state is removed.
      state: Object.assign({}, this.currentPageReference.state, stateChanges),
    });
  }

  connectedCallback() {
    this.connected = true;

    // If the CurrentPageReference returned before this component was connected,
    // we can use NavigationMixin to generate the URLs
    if (this.generateUrlOnConnected) {
      this.generateUrls();
    }
  }

  handleShowPanelClick(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    // This example passes true to the 'replace' argument on the navigate API
    // to change the page state without pushing a new history entry onto the
    // browser history stack. This prevents the user from having to press back
    // twice to return to the previous page.
    this[NavigationMixin.Navigate](this.showPanelPageReference, true);
  }

  handleNoPanelClick(evt) {
    evt.preventDefault();
    evt.stopPropagation();
    this[NavigationMixin.Navigate](this.noPanelPageReference, true);
  }
}
```

<!-- document id=54970e24ed9290928e0ce7e7d243c5a106d16c7f9ce4265afc1a6be1fdad68bf url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-addevent.md -->

# `addEvent(event, options)`

Adds an event to the device’s calendar.

## Syntax

```
import { getCalendarService } from 'lightning/mobileCapabilities';
addEvent(event: Event,
  options: CalendarServiceOptions
  ): Promise<Object>
```

## Parameters

- `event`—(Required) An `Event` object to be added to the device’s calendar.
- `options`—(Required) A [`CalendarServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-data-types.md) object to configure the CalendarService request.

## Returns

A Promise object that resolves as a coerced version of the `Event` parameter. If an error is encountered, an error message is returned.

## Usage

Use this function to add an event to a device’s calendar.

```javascript
myCalendarService
  .addEvent(event, options)
  .then((results) => {
    this.addedEvent = results;
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

For more information on when and why CalendarService coerces (changes) event data, see [Implicit Data Coercion](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice_in_a_lightning_component.htm#implicitdatacoercion).

**See Also**

- [Use the CalendarService API](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice_in_a_lightning_component.htm)

<!-- document id=8332e51f9865de56b8a0142b4fed0b1900e5e2cb7baefbd326edf646ab704b32 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-javascript-share.md -->

# Additional JavaScript Files

In addition to the JavaScript file that creates the HTML element, a component’s folder can contain other JavaScript files. Use these JavaScript files to structure code in UI components, and share code from API module components.

These additional JavaScript files must be ES6 modules and must have names that are unique within the component’s folder.

```javascript
myComponent
   ├──myComponent.html
   ├──myComponent.js
   ├──myComponent.js-meta.xml
   ├──myComponent.css
   ├──someUtils.js
   └──someMoreUtils.js
```

Export functions and variables in the JavaScript files so they can be imported by the component’s main JavaScript file.

**See Also**

- [Share JavaScript Code](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md)

<!-- document id=51d9df9f9315289b16cfad3cf95a04fd5304c9fd3235fc0a2d9e7545368fff56 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-examples.md -->

# Additional Usage Examples

Here are a wide range of examples you might find useful for your component development.

## Dynamic Class Names

Attach styles dynamically to user interface elements based on varying conditions.

```html
<template>
  <div class="{isActive && !isDisabled ? 'active' : 'inactive'}">
    <span class="{`status-${getStatus().toLowerCase()}`}">{getStatus()}</span>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class DynamicClassComponent extends LightningElement {
  isActive = true;
  isDisabled = false;
  status = "SUCCESS";

  getStatus() {
    return this.status;
  }
}
```

## Conditional Rendering

Show or don't show user interface elements, depending on whether they're relevant or not.

```html
<template>
  <div>
    {getUser() ? `Welcome, ${getUser().name}!` : 'Please log in'}
  </div>
  <div>
    {isLoggedIn && user ? `Hello, ${user.name.toUpperCase()}!` : 'Guest'}
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ConditionalRenderingComponent extends LightningElement {
  isLoggedIn = true;
  user = { name: "John Doe" };

  getUser() {
    return this.isLoggedIn ? this.user : null;
  }
}
```

## Data Formatting

Store values in canonical data types (for example, timestamps) in your records for ease of programming, while still showing them in easy to understand formats.

```html
<template>
  <div>
    <p>Price: {formatCurrency(getPrice())}</p>
    <p>Last updated: {formatDate(lastUpdated ?? Date.now())}</p>
    <p>Items: {getItems().length > 0 ? `Found ${getItems().length} items` : 'None'}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class DataFormattingComponent extends LightningElement {
  basePrice = 99.99;
  lastUpdated = Date.now();
  allItems = ["item1", "item2", "item3"];

  getPrice() {
    return this.basePrice * 1.1; // Add 10% tax
  }

  getItems() {
    return this.allItems.filter((item) => item);
  }

  formatCurrency(price) {
    return `$${price.toFixed(2)}`;
  }

  formatDate(timestamp) {
    return new Date(timestamp).toLocaleDateString();
  }
}
```

## Complex Calculations

```html
<template>
  <div>
    <p>Total: {calculateTotal()}</p>
    <p>Discount: {getDiscount() > 0 ? `-${formatCurrency(getDiscount())}` : 'None'}</p>
    <p>Final: {calculateTotal() - getDiscount()}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ComplexCalculationsComponent extends LightningElement {
  subtotal = 100;
  tax = 8.5;
  shipping = 5.99;
  discount = 10;

  calculateTotal() {
    return this.subtotal + this.tax + this.shipping;
  }

  getDiscount() {
    return this.discount;
  }

  formatCurrency(amount) {
    return `$${amount.toFixed(2)}`;
  }
}
```

## Numeric Operations

```html
<template>
  <div>
    <p>Binary: {0b1010}</p>
    <p>Hex: {0xFF}</p>
    <p>Octal: {0o777}</p>
    <p>Power: {2 ** 8}</p>
    <p>Bitwise: {flags & 0xFF}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class NumericOperationsComponent extends LightningElement {
  flags = 0b11111111;
}
```

## String Manipulation

```html
<template>
  <div>
    <p>Full name: {[getFirstName(), getLastName()].join(' ')}</p>
    <p>Uppercase: {getName().toUpperCase()}</p>
    <p>Template: {`Hello ${getName()}, you have ${getCount()} items`}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class StringManipulationComponent extends LightningElement {
  firstName = "John";
  lastName = "Doe";
  name = "world";
  count = 5;

  getFirstName() {
    return this.firstName;
  }

  getLastName() {
    return this.lastName;
  }

  getName() {
    return this.name;
  }

  getCount() {
    return this.count;
  }
}
```

## List Processing

```html
<template>
  <div>
    <p>Total items: {getAllItems().length}</p>
    <p>Active items: {getAllItems().filter(item => item.active).length}</p>
    <p>
      Average price: {getAllItems().reduce((sum, item) => sum + item.price, 0) /
      getAllItems().length}
    </p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ListProcessingComponent extends LightningElement {
  allItems = [
    { active: true, price: 10 },
    { active: false, price: 20 },
    { active: true, price: 30 },
    { active: true, price: 15 },
  ];

  getAllItems() {
    return this.allItems;
  }
}
```

## Object and Array Operations

```html
<template>
  <div>
    <p>Object: {({ name: 'John', age: 30 }).name}</p>
    <p>Array: {getNumbers().join(', ')}</p>
    <p>Computed: {getUser()['firstName']}</p>
    <p>Nested: {getData()?.items?.[0]?.name ?? 'No items'}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ObjectArrayOperationsComponent extends LightningElement {
  user = { firstName: "John" };
  data = {
    items: [{ name: "Item 1" }, { name: "Item 2" }],
  };

  getNumbers() {
    return [1, 2, 3, 4, 5];
  }

  getUser() {
    return this.user;
  }

  getData() {
    return this.data;
  }
}
```

## Event Handlers

```html
<template>
  <div>
    <button onclick="{() => handleClick(getCount())}">Click me</button>
    <button onclick="{() => incrementCount()}">Increment</button>
    <button onclick="{() => updateField(getFieldValue())}">Update</button>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class EventHandlersComponent extends LightningElement {
  count = 0;
  fieldValue = "value";

  getCount() {
    return this.count;
  }

  getFieldValue() {
    return this.fieldValue;
  }

  handleClick(count) {
    alert("Button clicked with count:" + count);
  }

  incrementCount() {
    this.count++;
  }

  updateField(value) {
    alert("Field updated with:" + value);
  }
}
```

## Type Checking

```html
<template>
  <div>
    <p>Type: {typeof getValue()}</p>
    <p>Is null: {getValue() === null}</p>
    <p>Is undefined: {typeof getValue() === 'undefined'}</p>
  </div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class TypeCheckingComponent extends LightningElement {
  value = "test";

  getValue() {
    return this.value;
  }
}
```

<!-- document id=a42fcfe6a73b9055e77f18845511379b8163e44b434c8a9e53aa563bebae7fae url=/developer/current/en-us/lwc/lwc/guides/use/use-dialog-alert.md -->

# Alert Modals

Use an alert modal to halt users and communicate an urgent error that’s affecting their system, feature, or page. The alert is displayed in a dialog on top of the page content using an overlay.

To display an alert modal in Lightning Experience, import `LightningAlert` from the `lightning/alert` module, and call `LightningAlert.open()` with your desired attributes.

`LightningAlert` is an alternative to the native `window.alert()` function, which isn’t supported for cross-origin iframes in Chrome and Safari. Unlike the native alert function, `LightningAlert.open()` doesn't halt execution on the page, it returns a promise. Use `async`/`await` or `.then()` for any code you want to execute after the alert window is closed.

![An alert modal with a red header over a darkened org.](https://developer.salesforce.com/media/dialog_alert_example.png '{"class": "image-full", "title": "An alert modal with a red header"}')

This example component creates a button that opens the alert modal that you see in the screenshot. Typically, an error condition would trigger display of the alert modal.

<!-- prettier-ignore -->
```html
<!-- c/myApp.html -->
<template>
  <lightning-button 
      onclick={handleAlertClick} 
      label="Open Alert Modal"> 
  </lightning-button>
</template>
```

Import `LightningAlert` from `lightning/alert` in the JavaScript file of the component that opens the alert modal. Create and dispatch a `LightningAlert` event with `message`, `theme`, and `label` attributes. The `.open()` function returns a promise that resolves when you click **OK**.

```javascript
// c/myApp.js
import { LightningElement } from "lwc";
import LightningAlert from "lightning/alert";

export default class MyApp extends LightningElement {
  async handleAlertClick() {
    await LightningAlert.open({
      message: "This is the alert message.",
      theme: "error", // a red theme intended for error states
      label: "Error!", // this is the header text
    });
    // alert notification has been closed
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [miscNotificationModules](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscNotificationModules) component that demonstrates alert notifications.

For information about the attributes for `LightningAlert`, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-alert?type=Specifications.

**See Also**

- [Component Reference: `lightning/alert`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-alert)

<!-- document id=2d7adcd7835ecf4757d99b875660faf38e77fbdc59ba755f281b96358b38e810 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-antipatterns.md -->

# Anti-Patterns for Styling Components

Here are some common mistakes developers make when styling Lightning web components. These techniques aren’t supported, and we hope it’s helpful to see some concrete examples so you can avoid them.

The most common anti-patterns are styling according to the rendered markup of Lightning base components and directly overriding SLDS classes and styles. Avoid querying elements using an exact class attribute string match.

## Anti-Pattern: Styling Rendered HTML of Base Components

When you check your browser console and see the rendered HTML of base components, it’s tempting to craft your CSS to target those elements and classes. However, Salesforce doesn’t support styling based on rendered output.

Salesforce needs the flexibility to redesign the internals of our components to improve performance, enhance functionality, and support accessibility. Therefore, you can’t assume that the component markup renders the same in each release. If you create styling based on such an assumption, the styling can break in the future. We document changes to the features and behavior of components, but don’t document changes to their internals.

**important:** Overriding base component styling isn't supported except when using [documented styling hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md).

Here’s a common mistake, replacing an SLDS class with one of your own.

```css
.myCustomClass .slds-class_name;
```

Let's say your company, Acme Widgets, uses the `lightning-combobox` base component in one of your custom components. You replace an SLDS class with one of Acme’s own because it's convenient, which is a common mistake. The component CSS targets the `.slds-combobox__input` selector.

```css
.acme-combobox_box .slds-combobox__input;
```

If Salesforce changes `lightning-combobox` to no longer use the `.slds-combobox__input` selector and it causes an adverse effect on Acme component styling, it’s up to you to fix your components’ styling.

See [Style Components with Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds.md) for the supported ways to style components.

## Anti-Pattern: Overriding SLDS Classes

It’s simple enough to take an SLDS selector name and tweak it a little, but it’s not supported.

When you override properties for SLDS selectors, a future change in SLDS can cause unexpected results for your component styling. Lightning Design System continually improves and documents all changes in the [SLDS release notes](https://www.lightningdesignsystem.com/release-notes/).

Here are some examples of unsupported overrides.

```css
/* myButton.css */
/* Anti-pattern - Don't do this */
.slds-button_brand {
  background-color: purple;
}
```

```css
/* Don’t do this */
.slds-button {
  padding: 16px;
}
```

```css
/* Don’t do this */
.slds-scoped-notification {
  padding: var(--scoped-spacing);
}
```

Instead, use the techniques discussed in [Style Components with Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds.md).

## Anti-Pattern: querySelector with Exact Attribute String Match

Extra whitespace in the `class` and `style` attributes isn't rendered. Update your JavaScript code that uses `class` or `style` attributes to ignore whitespace.

For example, if you have extra whitespace like this.

```html
<!-- myCmp.html -->
<div class="slds-var-m-around_medium  highlight   yellow">
  <div style=" color  :  red ! important  "></div>
</div>
```

The component is rendered without the extra whitespace.

```html
<!-- DOM rendering -->
<div class="slds-var-m-around_medium highlight yellow">
  <div style="color:  red !important"></div>
</div>
```

Revise your JavaScript code to use a selector that disregards whitespace.

```javascript
document.querySelector(".slds-var-m-around_medium.highlight.yellow");
```

Blank `class` and `style` attributes are also removed. For example:

```html
<!-- myCmp.html -->
<div class="">Content here</div>
<div style=" ">Content here</div>
```

The component is rendered without the blank attributes.

```html
<!-- DOM rendering -->
<div>Content here</div>
<div>Content here</div>
```

## Anti-Pattern: Relying On Generated CSS Scope Tokens

To scope CSS within a component, LWC automatically adds attributes and classes to DOM elements. These attributes and classes are internal implementation details that can change at any time.

```html
<c-cmp c-cmp_cmp-host>
  <span c-cmp_cmp></span>
</c-cmp>
```

While it can be easy to use generated CSS scope tokens that resemble the component names, your code can break if you rely on the internals of components you don't own. For performance reasons, LWC generates an obfuscated string for CSS scope tokens with the format `lwc-hashstring`, where `hashstring` is a unique alphanumerical string.

```html
<c-cmp lwc-2s44vctlls4-host>
  <span lwc-2s44vctlls4></span>
</c-cmp>
```

Obfuscated strings for CSS scope tokens affect _your_ custom components only when you use LWC API version 59.0 or later. However, this behavior affects all Salesforce-authored components in Lightning Experience and Experience Builder sites, such as the components that are rendered on record pages or list views, and base components.

Don't rely on internal attributes and classes in your code or tests using `this.template.querySelector()`, because internal implementation can change at any time. Instead of using `this.template.querySelector()`, you can also use [template refs (`lwc:ref`)](https://developer.salesforce.com/docs/platform/lwc/create-components-dom-work.md).

**See Also**

- [LWC API Versioning](https://developer.salesforce.com/docs/platform/get-started/get-started-api-versioning.md)
- [Synthetic Shadow](https://developer.salesforce.com/docs/platform/lwc/create-dom-synthetic.md)

<!-- document id=2ace19b64170cbc961f75fc0b59ea4dba6944e2cf67cf150c372b8920535fc01 url=/developer/current/en-us/lwc/lwc/guides/get-started/api-end-of-life.md -->

# API End-of-Life Policy

Salesforce is committed to supporting each API version for a minimum of 3 years from the date of first release. To mature and improve the quality and performance of the API, versions that are over 3 years old may be deprecated or retired.

Salesforce notifies customers who use an API version scheduled for deprecation at least 1 year before support for the version ends.

Lightning Web Components (LWC) was generally available in Spring '19 and is supported in Salesforce API version 45.0 and later.

Custom components can use [wire adapters](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md) to make calls to Salesforce APIs like Connect REST API and UI API. Review the API End-Of-Life Policy in the corresponding developer guides.

If you request any resource or use an operation from a retired API version, REST API returns the `410:GONE` error code.

To identify requests made from old or unsupported API versions, use the free [API Total Usage](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_eventlogfile_apitotalusage.htm) event type.

**See Also**

- [LWC API Versioning](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-api-versioning.md)

<!-- document id=3224e36c2d4c444d71dcbef18a254aacbf40986ff2db2aece351e63912a4f65c url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-api-versioning.md -->

# API Versioning

| AVAILABLE API VERSIONS               |
| ------------------------------------ |
| Available in LWC API v59.0 and later |

Beginning in Winter '24, LWC supports versioning for custom components. Beginning in Spring ’25, versioning is **required** for all custom components.

Components that were previously saved without setting an API version continue to run as before. However, the next time you modify the component, you'll need to set the API version, too. Attempting to save an unversioned component to Salesforce results in an error.

When a component specifies a version, the component then depends on that specific version of a Salesforce release. Every HTML, CSS, and JS file of a component corresponds to one API version. The API version tells the LWC framework to behave as it did for the Salesforce release corresponding to the specified API version for that component. This ensures a stable execution environment for your components.

**See Also**

- [Version Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/create/create-version-components.md)

<!-- document id=5b1b4a61a326f471c8db93207fd46134b01cb9448ae8ac9d74fd2eb11b17d0cf url=/developer/current/en-us/lwc/lwc/guides/create/create-use-third-party-styles.md -->

# Append Styles to a Custom Element

Third-party web components can contain custom elements that are created in shadow DOM or light DOM. For [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM#Basic_usage), open mode is more widely used than closed mode. To find out if the third-party web component you're working with is using a particular shadow mode, refer to the web component documentation. Alternatively, view the web component source and find the `attachShadow({mode: 'closed|open'})` method. A web component that uses light DOM doesn't use the `attachShadow()` method.

After you identify the DOM model for the third-party web component, you can decide how to style the custom element and its internals.

## Implement Custom Element Styling in Shadow DOM

Using shadow DOM, a custom element can't inherit styles from its container component. Similarly, styles that are defined within the custom element don't bleed out. You can't append styles to a custom element's shadow DOM in closed mode. For example, `this.refs.myEl.shadowRoot` returns null.

Many web component authors implement styles to the custom element by appending the `<style>` tag to the shadow root. View the web component source and find lines similar to these ones. These styles are scoped within the shadow root.

```javascript
const style = document.createElement("style");
style.textContent = `.someSelector { color: red }`;
this.shadow.appendChild(style);
```

To append styles in closed mode, you can use CSS variables (custom properties), classes, or shadow parts. We don't recommend using JavaScript to define CSS styles besides the shadow root styling implementation on third-party web components.

A web component author lets you override a style in the shadow root if they include a CSS custom property like this.

**tip:** Check the third-party web component source or documentation for available CSS custom properties and shadow parts that you can use to style the custom element in your component.

```javascript
style.textContent = `.someSelector { color: var(--my-title-color, 	#AA4A44)}`;
```

Since CSS custom properties bleed through the shadow DOM, you can override the styling in your host component.

Let's say the third-party web component provides the `border: var(--my-border, 1px solid black);` border styling with a CSS custom property `--my-border`. In your host component, use the CSS custom property with your own value.

```css
/* popupInfo.css */
:host {
  --my-border: 1px solid green;
}
```

If you want to style the host element of a third-party custom element, use a selector for the custom element in your `.css` file, for example, `c-custom-el { background-color: red; }`.

```html
<!--styleExample.html -->
<template>
  <c-custom-el lwc:external></c-custom-el>
</template>
```

The `c-custom-el` selector applies a red background to the content of the custom element.

```css
/* styleExample.css */
c-custom-el {
  background-color: red;
}
```

The custom element renders like this.

<!-- prettier-ignore -->
```html
<c-style-example>
  #shadow-root (open)
  |  <c-custom-el>
  |    #shadow-root (closed)
  |    |  <slot>your text here</slot>
  |   </c-custom-el>
</c-style-example>
```

## Implement Custom Element Styling in Light DOM

Unlike shadow DOM, light DOM enables styling from the root document to target a DOM node and style it. So the styles on a container component cascade into the nested custom element's light DOM. The styles on a custom element that's rendered in light DOM are also applied to its container components until a shadow boundary is encountered.

If the third-party web component uses light DOM, you can style the custom element's internals using a class in a `.css` file. To scope the style within the custom element, include your styles using a `.scoped.css` file in your component bundle.

```html
<!--styleExample.html-->
<template>
  <custom-element class="highlight" lwc:external></custom-element>
</template>
```

In your css file, provide the custom styling.

```css
.highlight {
  color: red;
}
```

**See Also**

- [Light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md)

<!-- document id=9c2e40e14802596b5aa6b14b6080895910b09eb793b065255aa56e88ec0d0418 url=/developer/current/en-us/lwc/lwc/guides/reference/appreviewservice/reference-lightning-appreviewservice.md -->

# AppReviewService API

Request an app review from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how AppReviewService works, see [Request an App Review on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_appreviewservice.htm).

<!-- document id=d944f7478d999f729762afe56cb914df62f8ff40422cc59c1a96f89665024aa9 url=/developer/current/en-us/lwc/lwc/guides/reference/appreviewservice/reference-lightning-appreviewservice-data-types.md -->

# AppReviewService Data Types

AppReviewService defines and uses several data types.

## `AppReviewServiceOptions`

An object representing configuration details for an AppReviewService session.

| Property Name                                  | Type    | Description                                                                                                                             |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ignoreIfAlreadyRequestedForCurrentAppVersion` | Boolean | Ignore the app review request if already asked for the current version of the app. Use `null` value if you're not passing in an option. |

## `AppReviewServiceFailure`

An object representing an error that occurred when accessing AppReviewService features.

| Property Name | Type                          | Description                                                                                                                                                                                                                                              |
| ------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `AppReviewServiceFailureCode` | A value representing the reason for an app review error. Possible failure codes include the following:<ul><li>`SERVICE_NOT_ENABLED`</li><li>`IN_APP_REVIEW_ERROR`</li><li>`ALREADY_REQUESTED_FOR_CURRENT_APP_VERSION`</li><li>`UNKNOWN_REASON`</li></ul> |
| `message`     | String                        | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.                                                                                 |

<!-- document id=c298a7f97c725a80ad983a472884f0d1658c088f1bf6dee5f205a98c4b83cdfc url=/developer/current/en-us/lwc/utam/references/arguments.md -->

# Arguments

Use arguments to pass data to methods.

## Argument Types

This table shows the syntax for declaring a non-literal argument with a name and type. Instead of using a combination of name and type, it's also possible to use a hardcoded (literal) value for an argument of these types.

|                           | Name/type (non literal)                         | Value/type (literal)                                      |
| ------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| **string primitive**      | `{ "name": "myArg", "type": "string" }`         | `{ "value": "myString" }`                                 |
| **integer primitive**     | `{ "name": "myArg", "type": "number" }`         | `{ "value": 1024 }`                                       |
| **boolean primitive**     | `{ "name": "myArg", "type": "boolean" }`        | `{ "value": false }`                                      |
| **locator**               | `{ "name": "myArg", "type": "locator" }`        | `{ "value": { "css": ".myClass" }, "type": "locator" }`   |
| **element reference**     | not supported                                   | `{ "type": "elementReference", "value": "myElement" }`    |
| **page object type**      | `{ "name": "myArg", "type": "pageObject" }`     | `{ "value": "my/page/object", "type": "pageObject" }`     |
| **root page object type** | `{ "name": "myArg", "type": "rootPageObject" }` | `{ "value": "my/page/object", "type": "rootPageObject" }` |
| **frame element**         | `{ "name": "myArg", "type": "frame" }`          | same as element reference                                 |
| **function**              | not supported                                   | `{ "type": "function", "predicate": [...] }`              |

## Argument Reference

To access an argument passed to a compose method in multiple statements, declare a reusable argument at the method level. The `args` property must be a sibling of the `name` property.
For example, we declare a reusable `passwordStr` argument at the method level:

```json
{
  "name": "passwordStr",
  "type": "string"
}
```

Then in each compose statement where you want to access the reusable argument, set the argument's `type` to `argumentReference`, the `name` of an argument with `"type": "argumentReference"` must match the name of one of the reusable arguments declared at the method level:

```json
{
  "name": "passwordStr",
  "type": "argumentReference"
}
```

Here's the full method declaration. The statements that apply actions to the `password` and `passwordConfirmation` elements both declare a reference to the reusable `passwordStr` argument. When test code invokes this method, the `passwordStr` argument is passed to both statements:

```json
{
  "name": "confirmPassword",
  "args": [
    {
      "name": "passwordStr",
      "type": "string"
    }
  ],
  "compose": [
    {
      "element": "password",
      "apply": "clearAndType",
      "args": [
        {
          "name": "passwordStr",
          "type": "argumentReference"
        }
      ]
    },
    {
      "element": "passwordConfirmation",
      "apply": "clearAndType",
      "args": [
        {
          "name": "passwordStr",
          "type": "argumentReference"
        }
      ]
    }
  ]
}
```

**note:** A reusable argument can't be an argument with a [hardcoded value](#argument-types), also known as a literal type.

For a working example of argument references, see [this tutorial](https://utam.dev/tutorial/compose-argument-references).

## Element Reference Argument Type

The `elementReference` type in an argument allows you to reference an existing element as a parameter value. This example uses an `elementReference` to a `targetElement` element.

```json
{
  "elements": [
    {
      "name": "sourceElement",
      "selector": {
        "css": ".source"
      },
      "type": ["draggable"]
    },
    {
      "name": "targetElement",
      "selector": {
        "css": ".source"
      }
    }
  ],
  "methods": [
    {
      "name": "composeDragAndDrop",
      "compose": [
        {
          "element": "sourceElement",
          "apply": "dragAndDrop",
          "args": [
            {
              "type": "elementReference",
              "value": "targetElement"
            }
          ]
        }
      ]
    }
  ]
}
```

Generated JavaScript code:

```js
// declaration
composeDragAndDrop(): Promise<void>;

// implementation
async composeDragAndDrop() {
    const _statement0 = await this.__getSourceElement();
    await _statement0.dragAndDrop(await this.__getTargetElement());
}
```

If a referenced element has a selector or filter arguments, those values are automatically inferred and added to the method declaration.

```json
{
  "name": "target",
  "selector": {
    "css": "foo:nth-child(%d)",
    "args": [
      {
        "name": "index",
        "type": "number"
      }
    ]
  }
}
```

When the element is referenced in a compose statement, this page object hard codes the value of 1 for an index.

```json
{
  "element": "source",
  "apply": "dragAndDrop",
  "args": [
    {
      "value": "target",
      "type": "elementReference",
      "args": [
        {
          "value": 1
        }
      ]
    }
  ]
}
```

<!-- document id=c8a48ba4a4e35b70e8b2809f11cbe5a9b982e954ea53f1f4a53f5355e3770e6d url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-array-proxy.md -->

# Arrays Proxied When Passed to Child Components

When you pass an array to a child component, Lightning Locker wraps the array in a proxy.

JavaScript `Proxy` is used on arrays that are passed to nested components. If you pass an array from a parent component to several layers of nested components, the array is proxied multiple times. When an array consists of many objects, multiple proxies cause a negative performance impact when running functions such as `JSON.stringify` on the array. A page that’s using a component that passes a large array of objects through layers of child components can become unresponsive.

To limit the negative performance impact of processing large arrays, refactor your code using one of these approaches.

- Avoid passing large arrays of objects more than one level down. For example, pass an array from parent to child but no further.
- Divide your data into multiple smaller arrays in the parent component.

[Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md) doesn’t have this limitation.

**See Also**

- [How Lightning Locker Uses the Proxy Object](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-proxy.md)

<!-- document id=38e1ad4903e1bfe4ea5fada871ad23d52d101603ec01e900943cd8bbd1ca1247 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-aura-endpoints.md -->

# Aura Endpoints Disallowed by Lightning Web Security

Lightning Web Security (LWS) disallows access to URL endpoints containing `/aura` and `/webruntime` because they’re part of the Lightning Component framework.

These JavaScript APIs are affected.

- `fetch`
- `Navigator.sendBeacon`
- `XMLHttpRequest.open`
- `HTMLObjectElement.prototype.data` setter

**See Also**

- [LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Window_fetch-value)

<!-- document id=dc50f13006f601f8cb1a8c8febdf1797e88898637efc6aa503358239d45ab160 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-authentication.md -->

# Authentication from Lightning Out (Beta)

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

To handle authentication, you must manually provide a Salesforce session ID or an OAuth access token when you initialize a Lightning Out (beta) app.

There are two supported ways to handle authentication for Lightning Out (beta).

- Use a Salesforce session ID. For example, on a Visualforce page, you can obtain the current Visualforce session ID with the expression `{! $Api.Session_ID }`. Sessions initiated with this session ID are intended for use only on Visualforce pages.
- Use an OAuth access token. Follow the same process that's used to authorize client applications that access Salesforce REST API resources. See [Authorization Through Connected Apps and OAuth 2.0](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_oauth_and_connected_apps.htm) in the _REST API Developer Guide_.

**note:** Lightning Out (beta) doesn't support JSON Web Tokens (JWT)-based access tokens. When implementing an OAuth authorization flow, use [opaque access tokens](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_access_tokens.htm&type=5) instead.

## Session Privileges

Lightning Out (beta) has the same privileges as the session from which you obtain the authentication token. If you use a Salesforce session ID, the session has the privileges of the current user. If you use an OAuth access token, the privilege is defined when you create the [connected app](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create.htm&type=5). Usually, Lightning Out (beta) requires you to grant **Full Access** scope to the connected app returning the OAuth access token.

## Session Persistence

A Lightning Out (beta) authenticated session persists access to any `lightning.force.com` domain running in the active browser session. After a user is authenticated, the session credentials are validated across all Salesforce applications running in the active browser session.

To prevent session persistence, Salesforce admins can lock the session to the originating IP address. From Setup, in the Quick Find box, enter `Session Settings`, and then select **Session Settings**. Then select **Lock sessions to the IP address from which they originated**.

**See Also**

- [Use Components in Visualforce Pages](https://developer.salesforce.com/docs/platform/lwc/use/use-visualforce.md)
- [Enable Browser Third-Party Cookies for Lightning Out (beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-third-party-cookies.md)
- [_Salesforce Help_: Enable OAuth Settings for API Integration](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create_api_integration.htm&type=5)

<!-- document id=56aa3b3ccb0adeb023074c93fcc4d98118bad49aca5f947a1320dc8a73a70176 url=/developer/current/en-us/lwc/slds_linter/guides/use/use-autofix-code.md -->

# Autofix Your Code

You’ve produced an SLDS Linter SARIF report, read through the report and identified the issues to fix and the components to update.
Fix validation issues automatically in bulk by running the `lint` command with the `--fix` option. The volume of issues that SLDS Linter can autofix depends on the extent of customizations done in your environment. After autofixing, generate a new SARIF report to see the remaining issues.

Here are a few different use cases for the `lint --fix` command.

Fix all files in current directory:

```
npx @salesforce-ux/slds-linter@latest lint --fix
```

Fix all files in a specific directory:

```
npx @salesforce-ux/slds-linter@latest lint "com/CORE/**" --fix
```

Fix issues by using custom configuration files. Send the configuration files to the `lint` command, and run the command with the `--fix` option:

```
npx @salesforce-ux/slds-linter@latest lint --config-eslint .eslintrc.yml --fix
```

Fix files with specific file types:

```
npx @salesforce-ux/slds-linter@latest lint "*/.{html,cmp}" --fix
```

<!-- document id=ea92ca0860a18c0b57a19e981389c25840ae544f33a24192bbd2883e1ff6eb3d url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-standard-objects.md -->

# Avoid Custom Properties on Standard JavaScript Objects

Adding custom properties directly to a [standard built-in JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects) can cause issues when the object is serialized. When an object is passed across namespaces or into the global scope, Lightning Web Security (LWS) doesn’t reflect this kind of mutation for security reasons.

If you must add custom data to a DOM element, use the [dataset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset) property of DOM elements instead of adding custom properties to the element object.

**See Also**

- [Avoid Mutating Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.md)

<!-- document id=b78a34f2052804f0c0855e4b3401413a2504975ca48949335ce270ac56711625 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-mutation-alternatives.md -->

# Avoid Mutating Objects

A common problematic coding practice is mutating objects that the namespace doesn’t own. When you mutate an object, you add or remove properties of the object or change values of properties. You change the "shape" of the object. When you mutate an object in a component that’s running in Lightning Web Security (LWS), that change isn’t propagated outside the namespace sandbox, which leads to errors.

Mutations can cause values to be `undefined`. For more information, see [Properties Evaluate as undefined in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-undefined.md).

This section discusses alternatives to mutations on these properties.

- Function arguments
- Class instance properties
- Objects received in events

## Mutation Alternative for Function Arguments

In this example, a function `foo()` mutates the argument `obj` by adding a property with value `foo`. Then `foo()` calls `otherFunction`, which expects that `prop = foo` is defined on `obj`.

```javascript
function foo(obj) {
  obj.prop = "foo"; // 'prop' did not exist on obj
  otherFunction(obj);
}
```

This mutation is problematic because `foo()` can receive `obj` from different callers. Then `foo()` can send `obj` to different consumers that expect `obj` to be differently shaped. Mutating `obj` introduces uncertainty and inconsistency. A change could unknowingly break other code, especially when the code base is large and complex.

Instead of adding a property to an object, create a [shallow clone](https://developer.mozilla.org/en-US/docs/Glossary/Shallow_copy) with relevant properties of the object. In the example code, refactor `foo()` to create a clone of the object and add `prop` to the clone.

Here’s a single-line change that removes the mutation by using a cloned object.

```javascript
function foo(obj) {
  const newObj = { ...obj, prop: "foo" };
  otherFunction(obj);
}
```

## Mutation Alternative for Class Instance Property

For classes, we recommend exposing getters and setters for properties that can be mutated. Avoid directly mutating class properties that are used for computations.

JavaScript now supports [private class fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields). A best practice in any object-oriented programming language is to define all internal state properties as private, and expose [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) and [setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) only for the properties that external code can mutate.

## Mutation Alternative for Objects Received in Events

For events, there’s no easy workaround because events propagate through the DOM.

Possible solutions are:

- Clone the event data, mutate it, and redispatch the same event but with the new data.
- Clone the event data, mutate it, and dispatch a new event with a different name.

**See Also**

- [Properties Evaluate as undefined in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-undefined.md)
- [_Lightning Web Components Developer Guide_: Objects Passed to Components Are Read-Only](/docs/platform/lwc/guide/create-components-data-flow.html#objects-passed-to-components-are-read-only)

<!-- document id=ef3e4e822616ed47f53cc588a3cf946f5de823ce26d5d7605f40500b1a885832 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-map.md -->

# Avoid Using Map Objects

Use of the [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object with Lightning Web Security (LWS) enabled can run into issues when the object is serialized. Instead of using a Map instance, you can use a plain JavaScript object in most cases.

If you must use maps, use the `set()` method to insert key-value pairs instead of adding custom properties. If the data passed in Map must be serialized, pass a custom [replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#replacer) function to `JSON.stringify(...)`.

Using maps in Lightning web components isn’t supported for both imperative and wired Apex calls.

**See Also**

- [_Lightning Web Components Developer Guide_: Pass Values to Apex](/docs/platform/lwc/guide/apex-call-imperative.html#pass-values-to-apex)

<!-- document id=262a519e5cc416b3908719133629af259c37126c62aa4994011854d313d48afd url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner.md -->

# BarcodeScanner API

Scan barcodes from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how BarcodeScanner works, see [Scan Barcodes on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner.htm).

<!-- document id=e65d1c52de6413467c46f8966c2eefce057127b37dcb6473709d1b17414413a6 url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-constants.md -->

# BarcodeScanner Constants

The `barcodeTypes` constant is available as a property on an instance of `BarcodeScanner`.

## `barcodeTypes`

An object enumerating the [barcode symbologies](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_compatibility.htm) supported by `BarcodeScanner`.

| Barcode Symbology Standard                                      | BarcodeScanner Type (`barcodeTypes`) |
| --------------------------------------------------------------- | ------------------------------------ |
| [Code 128](https://www.barcodefaq.com/1d/code-128/)             | `CODE_128`                           |
| [Code 39](https://www.barcodefaq.com/1d/code-39/)               | `CODE_39`                            |
| [Code 93](https://www.barcodefaq.com/barcode-match/)            | `CODE_93`                            |
| [Data Matrix](https://www.barcodefaq.com/2d/data-matrix/)       | `DATA_MATRIX`                        |
| [EAN-13 / GTIN-13](https://www.barcodefaq.com/1d/upc-ean/)      | `EAN_13`                             |
| [EAN-8 / GTIN-8](https://www.barcodefaq.com/1d/upc-ean/)        | `EAN_8`                              |
| [Interleaved 2 of 5](https://www.barcodefaq.com/barcode-match/) | `ITF`                                |
| [PDF417](https://www.barcodefaq.com/2d/pdf417/)                 | `PDF_417`                            |
| [QR-Code](https://www.barcodefaq.com/2d/qr-code/)               | `QR`                                 |
| [UPC-A / GTIN-12](https://www.barcodefaq.com/1d/upc-ean/)       | `UPC_A`                              |
| [UPC-E / GTIN-12](https://www.barcodefaq.com/1d/upc-ean/)       | `UPC_E`                              |

## Usage

Use the `barcodeTypes` constant when creating a [`BarcodeScannerOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) object. Call [`beginCapture(options) (Legacy)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-begincapture.md) with that object to start a scanning session.

```javascript
const myScanner = getBarcodeScanner();
const scanningOptions = {
  barcodeTypes: [
    // Add expected barcode types here
    // See Supported Barcode Types for list
    myScanner.barcodeTypes.QR,
  ],
};
```

<!-- document id=bf115d9481f96f9af270b6a9e7e769e962654dca1c961c960040a68b0e8425db url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-data-types.md -->

# BarcodeScanner Data Types

BarcodeScanner defines several data types.

## `Barcode`

An object representing a scanned barcode.

| Property Name | Type          | Description                                                                                                                                                   | Example                                                                                                                                        |
| ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | `BarcodeType` | The type of barcode that was recognized. Available values are enumerated in [`BarcodeScanner.barcodeTypes`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-constants.md). | <ul><li>"ean13" (the string value of `myScanner.barcodeTypes.EAN_13`)</li><li>"qr" (the string value of `myScanner.barcodeTypes.QR`)</li></ul> |
| `value`       | String        | The decoded value of the barcode.                                                                                                                             | <ul><li>"9781984825193"</li><li>"https://developer.salesforce.com/&quot;</li></ul>                                                             |

## `BarcodeScannerOptions`

An object representing configuration details for a barcode scanning session.

| Property Name           | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Example                                                                                          |
| ----------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `barcodeTypes`          | `BarcodeType[]` | Optional. Specifies the types of barcodes to scan for. Available values are enumerated in [`BarcodeScanner.barcodeTypes`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-constants.md). Defaults to all supported barcode types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `[myScanner.barcodeTypes.EAN_13, myScanner.barcodeTypes.QR, myScanner.barcodeTypes.DATA_MATRIX]` |
| `instructionText`       | String          | Optional. Provides instructions to display in the scanning interface. Defaults to no text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | "Scan the next item on the shelf"                                                                |
| `successText`           | String          | Optional. Provides a message to display in the scanning interface when a barcode is successfully scanned. Defaults to no text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | "Item scanned"                                                                                   |
| `showSuccessCheckMark`  | Boolean         | Optional. Indicates whether a check mark is displayed upon a successful scan. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false`                                                                                          |
| `supportInvertedColors` | Boolean         | Optional. Indicates whether the barcode scanner attempts to scan barcodes that are printed in inverted colors (for example, white-on-black instead of the standard black-on-white). Android only (ignored on iOS). Defaults to `false`. **Note**: By default, Android devices don't support scanning inverted color barcodes. The `supportInvertedColors` option enables most (not all) Android devices to scan inverted color barcodes. Results may vary when scanning inverted color barcodes.                                                                                                                                                                                                      | `false`                                                                                          |
| `vibrateOnSuccess`      | Boolean         | Optional. Determines whether the device vibrates when a scan is successful. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                          |
| `scannerSize`           | String          | Optional. Modifies the size of the scanner camera view. The available options represent a percentage of the user's device screen size. <ul><li>`SMALL`: 25%</li><li>`MEDIUM`: 33%</li><li>`LARGE`: 50%</li><li>`XLARGE`: 75%</li><li>`FULLSCREEN`: 100%</li></ul> Defaults to `XLARGE`.                                                                                                                                                                                                                                                                                                                                                                                                               | "MEDIUM"                                                                                         |
| `cameraFacing`          | String          | Optional. Specifies whether the front- or rear-facing camera is used. Defaults to "BACK". Available options include "FRONT" and "BACK". If the user's device doesn't support the specified camera facing, an error is returned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | "FRONT"                                                                                          |
| `backgroundViewHTML`    | String          | Optional. Defines a custom user interface for the scanner instead of using the standard UI. Defaults to null. If nothing is passed in for this parameter, the standard UI is used. If a custom UI is used, it completely replaces the standard UI, including the standard **Cancel** button used for dismissing the scanner. When defining a custom UI, it's the responsibility of the caller to handle dismissing the scanner. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                |                                                                                                  |
| `presentWithAnimation`  | Boolean         | Optional. Determines whether the scanner animates in and out when presented and dismissed. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`                                                                                          |
| `manualConfirmation`    | Boolean         | Optional. Determines whether the user has to manually confirm that a detected barcode should be scanned. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `true`                                                                                           |
| `previewBarcodeData`    | Boolean         | Optional. Determines whether the scanner displays the barcode data while scanning. Defaults to `true`. Previewing barcode is only supported when `backgroundViewHTML` is omitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false`                                                                                          |
| `enableBulkScan`        | Boolean         | Optional. Determines whether the scanner collects the results of scanned barcodes before sending them back to the caller. Defaults to `false`. When set to `true`, the scanner collects the results of scanned barcodes and displays them on the screen. When the user taps **done**, the scanned barcode data is sent back to the caller. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                                                                                                     | `true`                                                                                           |
| `enableMultiScan`       | Boolean         | Optional. Determines whether the scanner detects multiple barcodes simultaneously. Defaults to `false`. Setting this parameter to `true` automatically sets the `enableBulkScan` parameter to `true`. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                                                                                                                                                                                                                                          | `true`                                                                                           |
| `enableFlashlight`      | Boolean         | Optional. Determines whether the device flashlight should be turned on when scanning barcodes. This takes effect only if `cameraFacing` is set to back-facing camera. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `true`                                                                                           |
| `enableScanLine`        | Boolean         | Optional. When enabled, the scanner UI displays a scan line. Only barcodes touched by this line are detected; others within view are ignored. Defaults to `false`. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`                                                                                           |
| `enableActionButtons`   | Boolean         | Optional. Enables the scanner to show several action buttons that allow users to perform various functions at runtime. These actions include toggling the device’s flashlight, switching between the front and rear cameras, device vibration, and displaying a scan line. Defaults to `false`. **Note**: This option isn't supported in the Field Service Mobile App.                                                                                                                                                                                                                                                                                                                                | `true`                                                                                           |
| `initialZoomFactor`     | Number          | Optional. Determines the initial zoom factor setting for the device's camera. Defaults to 1.0 (1x or no magnification). For frequent scanning of small barcodes, increasing this value to 2.0 or 4.0 launches the scanner with 2x or 4x magnification, respectively, simplifying the process without requiring manual zooming. However, users retain the ability to further adjust the zoom using pinch-to-zoom. Note that if you provide a zoom factor that is outside the min or max range which the device camera supports, then your value is clamped to the min or max zoom factor that's supported by the device camera. **Note**: This option isn't supported in the Field Service Mobile App. | `2.0`                                                                                            |

## `BarcodeScannerFailure`

An object representing an error that occurred when attempting to scan a barcode.

| Property Name | Type                        | Description                                                                                                                                                                                                                                                                                                   |
| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `BarcodeScannerFailureCode` | A value representing the reason for the scanning failure. Possible codes include the following:<ul><li>`USER_DISMISSED_SCANNER`</li><li>`USER_DENIED_PERMISSION`</li><li>`USER_DISABLED_PERMISSION`</li><li>`INVALID_BARCODE_TYPE_REQUESTED`</li><li>`SERVICE_NOT_ENABLED`</li><li>`UNKNOWN_REASON`</li></ul> |
| `message`     | String                      | A string value explaining the reason for the scanning failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.                                                                                                                            |

**note:** `userDismissedScanner` is returned when the user clicks the **Cancel** button during scanning. This is the normal method of terminating a scanning session. Your error handling can check for and possibly treat `userDismissedScanner` differently from, for example, permissions errors.

<!-- document id=e98bfad87f608d3882cb3e5d86ea0fb4953b2e78734a50a68696fb56ceec8b59 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-compose.md -->

# Base Component Composition

As modular building blocks, base components follow several structures: _composition_ or _flat_ structure. Understanding the differences can be helpful as you work with base components or build your own custom components.

## Composition Structure

Many base components can compose other base components. We sometimes refer to this relationship as parent and child components. A common pattern for working with base components is to compose them declaratively like this.

<!-- prettier-ignore -->
```html
<lightning-breadcrumbs>
    <lightning-breadcrumb label="Parent Account" href="path/to/place/1">
    </lightning-breadcrumb>
    <lightning-breadcrumb label="Case" href="path/to/place/2">
    </lightning-breadcrumb>
</lightning-breadcrumbs>
```

You can create multiple instances of a nested base component via data from a JavaScript object. For example, if you have a large list to iterate through, you can use the `for:each` directive to display a list of menu items on the `lightning-button-menu` component.

<!-- prettier-ignore -->
```html
<lightning-button-menu alternative-text="Show menu">
<template for:each={menuItems} for:item="item" >  
    <lightning-menu-item 
        label={item.label}
        value={item.value}
        key={item.value}>
    </lightning-menu-item>
</template>
</lightning-button-menu>
```

In the component's JavaScript file, pass in the label and value pairs to `lightning-menu-item`.

```javascript
menuItems = [
  { label: "Not Started", value: "red" },
  { label: "In Progress", value: "yellow" },
  { label: "Done", value: "green" },
];
```

## Base Components That Use Composition

Here are some examples of base components that compose other base components.

| Parent                          | Child                                   | Description                                                     |
| ------------------------------- | --------------------------------------- | --------------------------------------------------------------- |
| `lightning-accordion`           | `lightning-accordion-section`           | Displays content in sections that can be expanded and collapsed |
| `lightning-breadcrumbs`         | `lightning-breadcrumb`                  | Displays a hierarchy path of the page you're visiting           |
| `lightning-button-group`        | `lightning-button`                      | Displays a group of buttons                                     |
| `lightning-button-menu`         | `lightning-menu-item`                   | Displays a dropdown menu with a list of action items            |
| `lightning-layout`              | `lightning-layout-item`                 | Displays content in a responsive grid system                    |
| `lightning-progress-indicator`  | `lightning-progress-step`               | Displays an indication on the progress of a process             |
| `lightning-record-edit-form`    | `lightning-input-field`                 | Displays a form for record editing                              |
| `lightning-record-view-form`    | `lightning-output-field`                | Displays record data                                            |
| `lightning-tabset`              | `lightning-tab`                         | Displays content in sections that can be shown one at a time    |
| `lightning-vertical-navigation` | `lightning-vertical-navigation-section` | Displays a list of links for navigation                         |

Base component composition is made possible by using slots in the parent components. For more information, see [Pass Markup to a Base Component Slot](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-slot.md).

## Flat Structure

Some base components, such as `lightning-combobox` and `lightning-select`, render child components internally. This presents a flatter component surface for you to work with.

<!-- prettier-ignore -->
```html
<lightning-select
    label="Quantity"
    value={value}
    options={options}
    onchange={handleChange}></lightning-select>
```

In this `lightning-select` example, you can use a getter to pass in the options. The component takes care of rendering the `<select>` and `<option>` tags.

```javascript
import { LightningElement } from "lwc";
export default class SelectExample extends LightningElement {
  value = "";
  get options() {
    return [
      { label: "choose one...", value: "" },
      { label: "one", value: "1" },
      { label: "two", value: "2" },
      { label: "three", value: "3" },
    ];
  }
  handleChange(event) {
    this.value = event.detail.value;
  }
}
```

When you compare composition and flat structures, the latter uses an attribute like `options` for you to pass in your configuration information.

## Base Components That Use A Flat Structure

Here are some examples of base components that use a flat structure.

| Base Component                                                                                                                            | Usage                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`lightning-checkbox-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-group) | Pass in the label and value that describe checkbox options to the `options` attribute.                          |
| [`lightning-combobox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox)             | Pass in the label and value that describe a menu item to the `options` attribute.                               |
| [`lightning-dual-listbox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-dual-listbox)     | Pass in the label and value that describe a menu item to the `options` attribute.                               |
| [`lightning-datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable)           | Pass in the label, fieldName, and type to the `columns` attribute. Pass in column data to the `data` attribute. |
| [`lightning-map`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-map)                       | Pass in the map markers to the `map-markers` attribute.                                                         |
| [`lightning-pill-container`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-pill-container) | Pass in the pill items to the `items` attribute.                                                                |
| [`lightning-radio-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-radio-group)       | Pass in the label and value that describe radio options to the `options` attribute.                             |
| [`lightning-select`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select)                 | Pass in the label and value that describe an option to the `options` attribute.                                 |
| [`lightning-tree`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree)                     | Pass in the tree items to the `items` attribute.                                                                |

The flatter structure in a base component is made possible by using an attribute to pass in configuration information and data. For more information, see [Pass Configuration and Data to a Base Component](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-attributes.md).

## Composition and Flat Structure Differences

As you build with base components and create your own components, it's helpful to understand the use cases for composition vs flat structures.

- Consider composition for general use cases, such as when you want to break down complexity of code and logic
- Consider a flat structure when you render large numbers of elements through composed components

If you end up with a heavily composed structure, consider moving the logic from child components back to a parent component. Doing so allows your parent component to inline as many of the elements, which improves performance by avoiding the rendering of more custom components where possible.

Keep in mind that the number of elements, functions, and event handlers increase component size and has performance implications especially when you are working with large numbers of such components on a page. If possible, move expensive operations higher up the component tree and reduce the number of operations a leaf component handles.

Additionally, consider these performance guidelines.

- Avoid or consolidate unnecessary DOM elements and event handlers.
- Reduce unnecessary rendering and rerendering.

For frequently reused components, expensive operations impact performance exponentially. Here are several ways to reduce performance overhead.

- Avoid making deep copies of large objects.
- Avoid processing collections of records or other data.
- Avoid forced rerendering and other DOM manipulations.

<!-- document id=60dbe70f4d0c24a1191ef4a7005ff310680d72b9340e672dcc321ee85dc5dbb9 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-accessibility.md -->

# Base Components Accessibility

Salesforce is committed to building performant and accessible base components. Base components that provide UI elements contain accessible HTML markup from Lightning Design System (SLDS). They follow W3C standard and best practices for interactive components, including keyboard behavior and management of ARIA roles and properties. Using base components provide a great starting point for building your own interactive and accessible components.

## ARIA Authoring Support

Base components implement SLDS blueprint markup that follow the [W3C ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) to provide standard accessibility requirements. By using ARIA attributes when necessary, base components ensure a consistent experience across devices. Following user interaction, these components also update their ARIA attributes automatically to reflect the new state. For example, the `lightning-accordion` base component toggles between `aria-hidden="true"` and `aria-hidden="false"` depending whether an accordion section is hidden or displayed. The `lightning-input` base component appends the `aria-describedby` attribute to the `input` element when a validation error is displayed.

Base components also use ARIA properties and roles to make content accessible to assisistive technologies. For example, the `lightning-breadcrumbs` base component uses `aria-label="Breadcrumbs"` and `role="navigation"` to provide semantic meaning to the content. Since this component doesn't use the `ul` and `li` HTML elements, the component uses `role="list"` and `role="listitem"` to ensure that the individual links are presented as an item within the larger list context.

With base components, you can also use ARIA attributes to build your own accessible user interfaces. For more information about the ARIA attributes available for each component, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

## Color Usage

Base components conform to SLDS color guidelines, which meet or exceed the [Web Content Accessibility Guidelines (WCAG) 2.1 AA standards](https://www.w3.org/TR/WCAG21/) for contrast. Based on SLDS blueprints, base components such as `lightning-button` provide variants that change the color of the component based on its purpose. For example, use the `success` variant for a green background color or the `error` variant for a red background color. In cases where a variant isn't available, you can also use [SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md) to customize the colors across base components consistently.

## Forms and Inputs

Base components provide an accessible implementation of input fields and forms. [Input components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md#input) include `lightning-input`, `lightning-combobox`, `lightning-select`, and more. These components follow the WCAG guidelines, such as for predictable input ([3.2.2](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.2&showtechniques=321%2C332%2C322&currentsidebar=%23col_customize#on-input)) and input assistance ([3.3](https://www.w3.org/WAI/WCAG22/quickref/#consistent-help)).

By using the [input components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md#input) and [form-based components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md#forms), you get these accessible requirements.

- Labeling controls with the `<label>` element and other mechanisms such as WAI-ARIA and `title` attribute to identify each form control
- Grouping controls with the `<fieldset>` and `<legend>` elements to group and associate related form controls.
- Form instructions guide users to complete the form and individual form controls.
- Input validation ensures users can undo changes and confirm data entry before submitting data.

## Images and Visuals

For images and icons, base components provide attributes for your text-based alternatives, which follow the [WCAG 1.1.1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.2&showtechniques=149%2C111#non-text-content) guideline for non-text content. For example, `lightning-avatar` and `lightning-icon` include an `alternative-text` attribute for your description. The `lightning-avatar` base component passes down this description to the `alt` and `title` attributes on the `img` element. To visually hide the description, the `lightning-icon` base component renders the description using the `slds-assistive-text` SLDS class.

**See Also**

- [SLDS: Accessibility Overview](https://www.lightningdesignsystem.com/accessibility/overview/)

<!-- document id=d20a9c52351374283263981831d0248bb6dc6f0561d5a3521da6f39d9c699c20 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-all.md -->

# Base Components Categories

Base components that are UI-based are built from Salesforce Lightning Design System (SLDS) design guidelines. While base components follow SLDS guidelines closely, they don't implement every guideline or every feature on a design. You can also find subtle differences in attribute or variant names across base components and their associated SLDS guidelines.

Base components support [SLDS 2](https://www.lightningdesignsystem.com/) for advanced theming and branding capabilities.

**note:** Use base components where possible instead of creating your own component from an SLDS guideline. Using base components, you get the latest SLDS design updates automatically.

Base components for LWC use the framework's capabilities for a seamless integration with Salesforce data, making it easy for you to build dynamic and interactive apps. If a base component doesn't support a feature that you see in an SLDS guideline, use the guideline to help you achieve your requirements.

Base components are not currently versioned. Most base components were first available in Spring ’19 (API version 45.0). To develop using LWC, set your custom component to use API version 45.0 or later in the component's `.js-meta.xml` file. See [Minimum API Version of Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-min-version.md).

Base components are in the `lightning` namespace and follow the format `lightning-component-name` in HTML markup, such as `lightning-button-group`, for example. Base components are grouped using these categories.

- Actions and Menus
- Containers
- Images (Visuals)
- Input
- Forms
- Navigation
- Notifications
- Output
- Progress
- Tables and Trees

Base components can [compose another base component](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-compose.md), such as `lightning-button` in `lightning-button-group`, or `lightning-accordion-section` in `lightning-accordion`. Base components also include [utility modules](#utility-modules) that provide additional functionalities and utility methods.

## Actions and Menus

Action and menu components trigger an action when clicked.

| Base Component                                                                                                                              | SLDS Design Guideline                                                                     | Base Component Usage Highlights                                                 | First Available in API Version |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------ |
| [`button`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button)                             | [Buttons](https://www.lightningdesignsystem.com/components/buttons)                       | Use variants to change the background color of the button.                      | 45.0                           |
| [`button-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-group)                 | [Button Groups](https://www.lightningdesignsystem.com/components/button-groups/)          | Compose other button components to create a group of buttons.                   | 45.0                           |
| [`button-icon`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-icon)                   | [Button Icons](https://www.lightningdesignsystem.com/components/button-icons/)            | The stateful variation type maps to `lightning-button-icon-stateful` component. | 45.0                           |
| [`button-icon-stateful`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-icon-stateful) | [Button Icons (Stateful)](https://www.lightningdesignsystem.com/components/button-icons/) | Toggle between two states using the `selected` and `onclick` attributes.        | 45.0                           |
| [`button-menu`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                   | [Menus](https://www.lightningdesignsystem.com/components/menus/)                          | Compose `lightning-menu-*` components to display a menu with a list of actions. | 45.0                           |
| [`menu-divider`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-menu-divider)                 | [Menus](https://www.lightningdesignsystem.com/components/menus/)                          | Group related `lightning-menu-item` components by using a divider.              | 45.0                           |
| [`menu-item`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-menu-item)                       | [Menus](https://www.lightningdesignsystem.com/components/menus/)                          | Compose a menu item within `lightning-button-menu`.                             | 45.0                           |
| [`menu-subheader`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-menu-subheader)             | [Menus](https://www.lightningdesignsystem.com/components/menus/)                          | Compose a subheader within `lightning-button-menu`.                             | 45.0                           |
| [`button-stateful`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-stateful)           | [Buttons (Stateful)](https://www.lightningdesignsystem.com/components/buttons)            | Toggle between two states using the `selected` and `onclick` attributes.        | 45.0                           |
| [`click-to-dial`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-click-to-dial)               | -                                                                                         | Display a phone number for Open CTI and Voice.                                  | 45.0                           |
| [`flow`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow)                                 | -                                                                                         | Display a flow interview.                                                       | 45.0                           |

## Containers

Container components group related content together.

| Base Component                                                                                                                          | SLDS Design Guideline                                                    | Base Component Usage Highlights                                                                                                                                             | First Available in API Version |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`accordion`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-accordion)                   | [Accordion](https://www.lightningdesignsystem.com/components/accordion/) | Display content that's collapsed or expanded in a `lightning-accordion-section` component.                                                                                  | 45.0                           |
| [`accordion-section`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-accordion-section)   | [Accordion](https://www.lightningdesignsystem.com/components/accordion/) | Compose multiple `lightning-accordion-section` components within `lightning-accordion`.                                                                                     | 45.0                           |
| [`card`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-card)                             | [Cards](https://www.lightningdesignsystem.com/components/cards/)         | When implementing a nested card, `lightning-card` must be nested directly within `lightning-card`. Placing a datatable or tiles in a card requires your own customization.  | 45.0                           |
| [`carousel`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-carousel)                     | [Carousel](https://www.lightningdesignsystem.com/components/carousel/)   | Display content that cycles through different views.                                                                                                                        | 45.0                           |
| [`carousel-image`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-carousel-image)         | [Carousel](https://www.lightningdesignsystem.com/components/carousel/)   | Compose a carousel image within the `lightning-carousel` component.                                                                                                         | 45.0                           |
| [`modal`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal)                           | [Modals](https://www.lightningdesignsystem.com/components/modals/)       | Display content that blocks interaction with everything else on the page until the modal is dismissed.                                                                      | 55.0                           |
| [`modal-body`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-body)                 | [Modals](https://www.lightningdesignsystem.com/components/modals/)       | Display content in the modal body. `lightning-modal-body` doesn't allow customizing of the styling on the white modal frame and background, close button, or gray backdrop. | 55.0                           |
| [`modal-footer`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-footer)             | [Modals](https://www.lightningdesignsystem.com/components/modals/)       | Display an optional footer on the `lightning-modal` component.                                                                                                              | 55.0                           |
| [`modal-header`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-header)             | [Modals](https://www.lightningdesignsystem.com/components/modals/)       | Display an optional header on the `lightning-modal` component.                                                                                                              | 55.0                           |
| [`quick-action-panel`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-quick-action-panel) | [Modals](https://www.lightningdesignsystem.com/components/modals/)       | Use `lightning-quick-action-panel` as a modal that's opened by a quick action.                                                                                              | 52.0                           |
| [`layout`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-layout)                         | [Grid](https://www.lightningdesignsystem.com/utilities/grid)             | Display content in `lightning-layout` to use the responsive grid system.                                                                                                    | 45.0                           |
| [`layout-item`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-layout-item)               | [Grid](https://www.lightningdesignsystem.com/utilities/grid)             | Compose multiple `lightning-layout-item` components within `lightning-layout`.                                                                                              | 45.0                           |
| [`tab`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tab)                               | [Tabs](https://www.lightningdesignsystem.com/components/tabs/)           | A single tab in a tabset.                                                                                                                                                   | 44.0                           |
| [`tabset`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tabset)                         | [Tabs](https://www.lightningdesignsystem.com/components/tabs/)           | Represents a list of tabs.                                                                                                                                                  | 44.0                           |
| [`tile`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tile)                             | [Tiles](https://www.lightningdesignsystem.com/components/tiles/)         | Use the media slot to insert an icon or avatar on `lightning-tile`. The `media` slot doesn't support inserting a checkbox.                                                  | 45.0                           |

## Images (Visuals)

Visual components display images, icons, and other visual elements.

| Base Component                                                                                                                  | SLDS Design Guideline                                                            | Base Component Usage Highlights                                                      | First Available in API Version |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------ |
| [`avatar`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-avatar)                 | [Avatars](https://www.lightningdesignsystem.com/components/avatar/)              | Display an image or icon. You can also use a static resource in your org.            | 45.0                           |
| [`badge`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-badge)                   | [Badge](https://www.lightningdesignsystem.com/components/badges/)                | Display a text-only badge or a badge with text and an icon.                          | 45.0                           |
| [`dynamic-icon`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-dynamic-icon)     | [Dynamic Icons](https://www.lightningdesignsystem.com/components/dynamic-icons/) | Display an animated icon that provides a visual cue for a specific action or state.  | 45.0                           |
| [`helptext`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-helptext)             | [Tooltips](https://www.lightningdesignsystem.com/components/tooltips/)           | Display contextual information, activated by hover, focus, or click.                 | 45.0                           |
| [`icon`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-icon)                     | [Icons](https://www.lightningdesignsystem.com/components/icons)                  | Display an SLDS icon or provide your own using SVG code.                             | 45.0                           |
| [`map`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-map)                       | [Map](https://www.lightningdesignsystem.com/components/map)                      | Display a map of one or more locations using Google Maps API.                        | 45.0                           |
| [`pill`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-pill)                     | [Pills](https://www.lightningdesignsystem.com/components/pills)                  | Display a compact label with text and an icon that a user can add and remove easily. | 45.0                           |
| [`pill-container`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-pill-container) |                                                                                  | Display pill items in a container.                                                   | 45.0                           |

## Input

Input components are for data entry with input validation support.

| Base Component                                                                                                                                                  | SLDS Design Guideline                                                                    | Base Component Usage Highlights                                                                                                                                  | First Available in API Version |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`checkbox-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-group)                                 | [Checkbox (Group)](https://www.lightningdesignsystem.com/components/checkbox)            | A group of checkboxes for single or multiple selection.                                                                                                          | 45.0                           |
| [`combobox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox)                                             | [Combobox](https://www.lightningdesignsystem.com/components/combobox)                    | A selector for single selection. Use `lightning-record-picker` for record lookup.                                                                                | 45.0                           |
| [`dual-listbox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-dual-listbox)                                     | [Dueling Picklist](https://www.lightningdesignsystem.com/components/dueling-picklist)    | Two side-by-side listboxes for selecting one or more options in the list on the left. Move selected options to the list on the right.                            | 45.0                           |
| [`file-upload`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-file-upload)                                       | [File Selector](https://www.lightningdesignsystem.com/components/file-selector)          | A file selector for uploading a file that's associated with a record ID. To upload a file without a record ID, use `lightning-input` with `type="file"` instead. | 45.0                           |
| [`input`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                   | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field based on the `type` attribute. Provides basic data validation and custom error message support.                                                   | 45.0                           |
| [`input type="checkbox"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                   | [Checkbox](https://www.lightningdesignsystem.com/components/checkbox)                    | A checkbox for single selection.                                                                                                                                 | 45.0                           |
| [`input type="checkbox-button"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                            | [Checkbox Button](https://www.lightningdesignsystem.com/components/checkbox-button)      | A styled checkbox to convey whether an option has been selected.                                                                                                 | 45.0                           |
| [`input type="date"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                       | [Datepickers](https://www.lightningdesignsystem.com/components/datepickers)              | An input field that provides date selection from a calendar.                                                                                                     | 45.0                           |
| [`input type="datetime"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                   | [Datetime Picker](https://www.lightningdesignsystem.com/components/datetime-picker)      | Input fields for selecting a date and time.                                                                                                                      | 45.0                           |
| [`input type="time"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                       | [Timepicker](https://www.lightningdesignsystem.com/components/timepicker)                | An input field that provides time selection from a list of predefined time.                                                                                      | 45.0                           |
| [`input type="email"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                      | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering an email address.                                                                                                                    | 45.0                           |
| [`input type="file"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                       | [File Selector](https://www.lightningdesignsystem.com/components/file-selector)          | A file selector. To upload a file and associate it with a record, use `lightning-file-upload` instead.                                                           | 45.0                           |
| [`input type="password"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                   | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering a password.                                                                                                                          | 45.0                           |
| [`input type="search"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                     | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering a search term.                                                                                                                       | 45.0                           |
| [`input type="tel"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                        | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering a telephone number.                                                                                                                  | 45.0                           |
| [`input type="url"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                        | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering a URL.                                                                                                                               | 45.0                           |
| [`input type="number"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                     | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering a number.                                                                                                                            | 45.0                           |
| [`input type="text"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                       | [Input](https://www.lightningdesignsystem.com/components/input)                          | An input field for entering text.                                                                                                                                | 45.0                           |
| [`input type="toggle"`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                     | [Checkbox Toggle](https://www.lightningdesignsystem.com/components/checkbox-toggle)      | A styled checkbox that's displayed as a toggle to convey if an option is selected.                                                                               | 45.0                           |
| [`input-address`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-address)                                   | [Form Element (Address)](https://www.lightningdesignsystem.com/components/form-element)  | A group of fields for entering an address.                                                                                                                       | 45.0                           |
| [`input-location`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-location)                                 | [Form Element (Compound)](https://www.lightningdesignsystem.com/components/form-element) | A pair of fields for entering a latitude and longitude.                                                                                                          | 45.0                           |
| [`input-name`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-name)                                         | [Form Element (Compound)](https://www.lightningdesignsystem.com/components/form-element) | A group of fields for entering a name, including a salutation, first, middle, and last name.                                                                     | 45.0                           |
| [`input-rich-text`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-rich-text)                               | [Rich Text Editor](https://www.lightningdesignsystem.com/components/rich-text-editor)    | An editor for entering rich text. To create a custom toolbar button, use the `lightning-rich-text-toolbar-button` component.                                     | 45.0                           |
| [`rich-text-toolbar-button`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button)             | [Button Icons](https://www.lightningdesignsystem.com/components/button-icons)            | A custom toolbar button for the rich text editor.                                                                                                                | 49.0                           |
| [`rich-text-toolbar-button-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button-group) | [Button Groups](https://www.lightningdesignsystem.com/components/button-groups)          | A group of custom toolbar buttons. Compose multiple `lightning-rich-text-toolbar-button` components within `lightning-rich-text-toolbar-button-group`.           | 49.0                           |
| [`radio-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-radio-group)                                       | [Radio Group](https://www.lightningdesignsystem.com/components/radio-group)              | A group of radio buttons for single selection.                                                                                                                   | 45.0                           |
| [`record-picker`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-picker)                                   | [Lookups](https://www.lightningdesignsystem.com/components/lookups)                      | Grouped and multi entity variants aren't available for `lightning-record-picker`.                                                                                | 59.0                           |
| [`select`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select)                                                 | [Select](https://www.lightningdesignsystem.com/components/select)                        | For multiple selection, use the `multiple` attribute or use `lightning-dual-listbox` instead.                                                                    | 59.0                           |
| [`slider`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-slider)                                                 | [Slider](https://www.lightningdesignsystem.com/components/slider)                        | An input field for searching Salesforce records.                                                                                                                 | 45.0                           |
| [`textarea`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-textarea)                                             | [Textarea](https://www.lightningdesignsystem.com/components/textarea)                    | A textarea field for entering multi-line text.                                                                                                                   | 45.0                           |

## Forms

Form components facilitate record creation, display, and editing.

| Base Component                                                                                                                      | SLDS Design Guideline                                                                       | Base Component Usage Highlights                                                           | First Available in API Version |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------ |
| [`input-field`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-field)           | [Form Element (Record Form)](https://www.lightningdesignsystem.com/components/form-element) | Compose multiple `lightning-input-field` components within `lightning-record-edit-form`.  | 45.0                           |
| [`output-field`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-output-field)         | [Form Element (Record Form)](https://www.lightningdesignsystem.com/components/form-element) | Compose multiple `lightning-output-field` components within `lightning-record-view-form`. | 45.0                           |
| [`record-edit-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-edit-form) | [Form Element (Record Form)](https://www.lightningdesignsystem.com/components/form-element) | A record edit layout that displays one or more fields using `lightning-input-field`.      | 45.0                           |
| [`record-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-form)           | [Form Element (Record Form)](https://www.lightningdesignsystem.com/components/form-element) | A form for record editing or record display.                                              | 45.0                           |
| [`record-view-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-view-form) | [Form Element (Record Form)](https://www.lightningdesignsystem.com/components/form-element) | A record view layout that displays one or more fields using `lightning-output-field`.     | 45.0                           |

## Navigation

Navigation components help users move between pages.

| Base Component                                                                                                                                                  | SLDS Design Guideline                                                                       | Base Component Usage Highlights                                                                                                     | First Available in API Version |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`breadcrumbs`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-breadcrumbs)                                       | [Breadcrumbs](https://www.lightningdesignsystem.com/components/breadcrumbs)                 | A hierarchy path of the page you're on. The SLDS overflow variant isn't available for `lightning-breadcrumbs`.                      | 45.0                           |
| [`breadcrumb`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-breadcrumb)                                         | [Breadcrumbs](https://www.lightningdesignsystem.com/components/breadcrumbs)                 | Compose multiple `lightning-breadcrumb` components within `lightning-breadcrumbs`.                                                  | 45.0                           |
| [`vertical-navigation`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-vertical-navigation)                       | [Vertical Navigation](https://www.lightningdesignsystem.com/components/vertical-navigation) | A list of links that can contain text with badges and text with icons.                                                              | 45.0                           |
| [`vertical-navigation-item`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-vertical-navigation-item)             | [Vertical Navigation](https://www.lightningdesignsystem.com/components/vertical-navigation) | A link within a list. Compose multiple `lightning-vertical-navigation-item` components within `lightning-vertical-navigation`.      | 45.0                           |
| [`vertical-navigation-item-badge`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-vertical-navigation-item-badge) | [Vertical Navigation](https://www.lightningdesignsystem.com/components/vertical-navigation) | A link with a badge. Compose multiple `lightning-vertical-navigation-item-badge` components within `lightning-vertical-navigation`. | 45.0                           |
| [`vertical-navigation-item-icon`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-vertical-navigation-item-icon)   | [Vertical Navigation](https://www.lightningdesignsystem.com/components/vertical-navigation) | A link with an icon. Compose multiple `lightning-vertical-navigation-item-icon` components within `lightning-vertical-navigation`.  | 45.0                           |

## Notifications

Status and notification components deliver information and insights.

| Base Component                                                                                                                                               | SLDS Design Guideline                                             | Base Component Usage Highlights                                                                                                | First Available in API Version |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| [`lightning/alert`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-alert)                                      | [Prompt](https://www.lightningdesignsystem.com/components/prompt) | Displays content in a modal to communicate a state that affects the system.                                                    | 54.0                           |
| [`lightning/confirm`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-confirm)                                  | [Prompt](https://www.lightningdesignsystem.com/components/prompt) | Displays content in a modal that asks the user to respond before they can continue.                                            | 54.0                           |
| [`lightning/platformShowToastEvent`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-show-toast-event) | [Toast](https://www.lightningdesignsystem.com/components/toast)   | Displays a toast notification using an event-based mechanism. `lightning/platformShowToastEvent` isn't supported in LWR sites. | 45.0                           |
| [`lightning/prompt`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-prompt)                                    | [Prompt](https://www.lightningdesignsystem.com/components/prompt) | Displays content in a modal to ask for user input.                                                                             | 54.0                           |
| [`lightning/toast`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast)                                      | [Toast](https://www.lightningdesignsystem.com/components/toast)   | Displays a toast notification. `lightning/toast` is also supported in LWR sites.                                               | 59.0                           |
| [`lightning/toastContainer`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast-container)                   | [Toast](https://www.lightningdesignsystem.com/components/toast)   | Manages toast components by specifying the position and the maximum number that can be displayed.                              | 58.0                           |

## Output

Output components display formatted data based on user locale and language. They don't correspond to an SLDS design and can be used wherever [data is displayed](https://www.lightningdesignsystem.com/guidelines/displaying-data/).

| Base Component                                                                                                                            | Base Component Usage Highlights                                                                                                | First Available in API Version |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| [`formatted-address`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-address)     | An address with a link to the given location on Google Maps. You can display a static map with the address for better context. | 45.0                           |
| [`formatted-date-time`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time) | A date and time that's formatted based on the user's locale.                                                                   | 45.0                           |
| [`formatted-email`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-email)         | An email address that's displayed with or without an email icon.                                                               | 45.0                           |
| [`formatted-location`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-location)   | A latitude and longitude value that represents a geolocation.                                                                  | 45.0                           |
| [`formatted-name`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-name)           | A name that's formatted based on the user's locale.                                                                            | 45.0                           |
| [`formatted-number`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number)       | A number that's formatted based on the user's locale.                                                                          | 45.0                           |
| [`formatted-phone`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-phone)         | A phone number that's formatted based on the user's locale.                                                                    | 45.0                           |
| [`formatted-rich-text`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-rich-text) | Text that's formatted by HTML, such as bold formatting and links.                                                              | 45.0                           |
| [`formatted-text`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-text)           | Text that can include links and newline characters for line breaks.                                                            | 45.0                           |
| [`formatted-time`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-time)           | Time that's formatted based on the user's locale.                                                                              | 45.0                           |
| [`formatted-url`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-url)             | Text that can include a URL.                                                                                                   | 45.0                           |
| [`relative-date-time`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-relative-date-time)   | The relative time difference between the source date-time and the provided date-time.                                          | 45.0                           |

## Progress

Progress components convey the progress of a process.

| Base Component                                                                                                                          | SLDS Design Guideline                                                                     | Base Component Usage Highlights                                                                                                                         | First Available in API Version |
| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`progress-bar`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-progress-bar)             | [Progress Bar](https://www.lightningdesignsystem.com/components/progress-bar)             | A horizontal progress bar that indicates the progress of an operation.                                                                                  | 45.0                           |
| [`progress-indicator`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-progress-indicator) | [Progress Indicator](https://www.lightningdesignsystem.com/components/progress-indicator) | A visual indication made up of steps that indicates the progress of a process. The vertical variant isn't available for `lightning-progress-indicator`. | 45.0                           |
| [`progress-step`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-progress-step)           |                                                                                           | Compose multiple `lightning-progress-step` components within `lightning-progress-indicator`.                                                            | 45.0                           |
| [`progress-ring`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-progress-ring)           | [Progress Ring](https://www.lightningdesignsystem.com/components/progress-ring)           | A circular progress indicator that provides feedback about an action or progress.                                                                       | 48.0                           |
| [`spinner`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-spinner)                       | [Spinners](https://www.lightningdesignsystem.com/components/spinners)                     | An animated spinner that indicates that a feature or page is loading.                                                                                   | 45.0                           |

## Tables and Trees

Table and tree components can display a large amount of data that can be expanded or collapsed.

| Base Component                                                                                                        | SLDS Design Guideline                                                       | Base Component Usage Highlights                                                                                                                                                                                                         | First Available in API Version |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable) | [Data Tables](https://www.lightningdesignsystem.com/components/data-tables) | A table that displays rows and columns of data. To create striped rows on `lightning-datatable`, use the `slds-table_striped` class. `lightning-datatable` highlights a row on hover and doesn't currently support `slds-no-row-hover`. | 45.0                           |
| [`tree`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree)           | [Trees](https://www.lightningdesignsystem.com/components/trees)             | A list of items that can nest other items, which can be expanded or collapsed.                                                                                                                                                          | 45.0                           |
| [`tree-grid`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree-grid) | [Tree Grid](https://www.lightningdesignsystem.com/components/tree-grid)     | A table with rows of data that can be expanded or collapsed. Removing the borders on rows isn't available for `lightning-tree-grid`.                                                                                                    | 45.0                           |

## Utility Modules

Utility modules provide additional functionalities and utility methods. They don't correspond to an SLDS design. To use a module in your JavaScript file, import its functions from the module.

| Base Component                                                                                                                                              | Description                                                                                       | First Available in API Version |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`lightning/flowSupport`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow-support)                        | Controls a flow navigation                                                                        | 45.0                           |
| [`lightning/logger`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-logger)                                   | Logs custom messages to Event Monitoring                                                          | 45.0                           |
| [`lightning/mediaUtils`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-media-utils)                          | Resizes and compresses image files                                                                | 45.0                           |
| [`lightning/messageService`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-message-service)                  | Communicates across the DOM between Visualforce pages, Aura components and LWC                    | 47.0                           |
| [`lightning/navigation`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation)                           | Navigates to another page in an app, such as in Lightning Experience and Experience Builder sites | 45.0                           |
| [`lightning/pageReferenceUtils`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-page-reference-utils)         | Encodes and decodes default field values                                                          | 48.0                           |
| [`lightning/platformResourceLoader`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-resource-loader) | Imports a third-party JavaScript or CSS library from a static resource                            | 45.0                           |
| [`lightning/refresh`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-refresh)                                 | Refreshes component data without reloading an entire page                                         | 55.0                           |
| [`lightning/userConsentCookie`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-user-consent-cookie)           | Sets cookie consent preferences                                                                   | 53.0                           |

For LWC API modules that provide access to record data and Salesforce APIs, see [LWC API Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-api-modules.md).

**See Also**

- [Version Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/create/create-version-components.md)

<!-- document id=5a1d01551a0051d81e87bb520f77ee04b7c73c942d4b346b563606f093826e5b url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-considerations.md -->

# Base Components Considerations

Consider these guidelines when working with base components.

## Name Format

The Component Reference and the LWC Dev Guide refer to base components using:

- A dash-separated name, `namespace-component-name`, for base components that are used in HTML template markup. For example, `lightning-button-group`.
- A forward-slash-separated name, `namespace/moduleName`, for base components that are used as an API module and must be imported in JavaScript code. For example, `lightning/toast`.

- Some base components make calls to Salesforce APIs like UI API, Connect REST API, GraphQL API, etc. and are subject to the corresponding API end-of-life policy.
- To work with a base component, use its public attributes. If an attribute is marked "Reserved for internal use", don't use the attribute as it can change in a future release. See the Specification tab for a component in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).
- To style a base component, first consider its available variants and utility classes before trying to override or applying a custom class. Don’t depend on the internal markup or CSS classes of a base component as they can change in future releases. See [Style Components with Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-slds.md).
- To locate a base component in your template, use `lwc:ref="uniqueId"`. Don't use the `id` global attribute as the ID value is transformed into a globally unique value when the template is rendered. Querying your element using `this.refs` instead of `this.querySelector` is more performant because the latter must scan through the DOM elements to find a match. See [Access Elements the Component Owns](https://developer.salesforce.com/docs/platform/lwc/create/create-components-dom-work.md).

## Namespaces

Base components are available in [the `lightning` namespace](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-accordion/). There are other components outside of these namespaces that are specific to a product area or app container, such as:

- `lightningsnapin` for [Embedded Service Chat](https://developer.salesforce.com/docs/atlas.en-us.snapins_web_dev.meta/snapins_web_dev/embedded_services_web_lightning_web_components.htm)
- `experience` for [Experience Builder sites](https://developer.salesforce.com/docs/platform/lwc/reference/reference-experience-cms-api.md)
- `wave` for [CRM Analytics](https://developer.salesforce.com/docs/analytics/dashboard-component/guide).

## API Modules

Some base components are used as an API module and must first be imported in the JavaScript file.

- Some UI-based components like `lightning/toast` and `lightning/prompt` require you to pass in your configuration information to a method on the module.
- API modules provide service or utility methods. For example, configure the navigation behavior for your components using `lightning/navigation`, or communicate across the DOM using `lightning/messageService`.
- Some API modules provide wire adapters and JavaScript functions for working with Salesforce data using Lightning Data Service. For example, get record data using `lightning/uiRecordApi`, or work with list views using `lightning/uiListsApi`.

- **See Also**

- [Base Components Categories: Utility Modules](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md#utility-modules)
- [Use a Base Component via a Module Import](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-patterns.md)
- [Supported App Containers for Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-containers.md)

<!-- document id=f1d41468c8f2d86201fb3e7e5d0610ae5050da162c5955debaaf6df5ffe04271 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-min-version.md -->

# Base Components Minimum API Version

Base components are not currently versioned. Changing your custom component’s API version in the `.js-meta.xml` configuration file to an earlier version does not impact the behavior of a base component you're using. So if you're using a base component in a custom component that's set to API version 60.0, its behavior does not change if you set your component to 59.0 or 61.0. The latest behavior is observed across all versions.

However, changing your component's API version tells the framework to behave as it did for that particular release.

Consider these guidelines when working with base components.

- When you use a base component in a custom component, you can specify an API version 45.0 and later for your custom component in the `.js-meta.xml` file. This API version you specify is the version of the framework that your custom component uses.
- As of Winter '24, custom components with API versions of 58.0 and earlier correspond to 58.0 (Summer '23). If you set the API version to a value lower than 58.0, LWC uses version 58.0 by default.

**tip:** We recommend that you update the API version of your components to take advantage of the latest features and bug fixes.

**See Also**

- [Version Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/create/create-version-components.md)

<!-- document id=c360b5fb9f6d133d2b898a16c6a1b266a19f4896c31487ff249930f8fe9d754c url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-patterns.md -->

# Base Components Usage Patterns

Base components provide a consistent and reusable way to add functionality to your apps.

You can use a base component in one of several ways:

- As markup in the component’s HTML template
- As a module import in the component’s JavaScript
- As a component class extension

This section covers common patterns for UI-based components only. For utility modules, see [Base Components Categories: Utility Modules](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md#utility-modules).

## Use a Base Component in Markup

As base components are built on LWC using W3C web standards, you can use them in a template like regular HTML. Create an instance of a base component within the `<template>` HTML element.

Most of the base components that are UI-based follow this pattern. Let's say you add a `lightning-button` base component to a template.

<!-- prettier-ignore -->
```html
<!-- c-custom-component -->
<template>
  <lightning-button
    variant="brand"
    label="Submit"
    title="Submit this form"
    onclick={handleClick}
    class="slds-m-left_x-small"
  ></lightning-button>
</template>
```

The component renders using the `<button>` element.

```html
<!-- c-custom-component renders like this -->
<lightning-button class="slds-m-left_x-small">
  <button title="Submit this form" type="button" class="slds-button slds-button_brand">
    Submit
  </button>
</lightning-button>
```

**note:** You can see how a base component renders in the DOM to understand its expected behavior. But don’t rely on any internal markup or CSS classes of a base component because they can change in future releases.

Base components encapsulate many functionalities while making it easy for you to customize the look-and-feel of the component. For example, while `variant` and `label` attributes are part of the `lightning-button` base component's [specification](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button?type=Specifications, `title`, `class`, and `onclick` are HTML global attributes.

In this example, the `variant` and `label` attributes and the HTML [global attributes](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-patterns-global.md) are exposed as a [public property](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md) so you can provide your own values in the custom component. The base component then passes your values down to the `<button>` element, implementing logic such as converting the `variant` value to a `class` on the `<button>` element.

## Use a Base Component via a Module Import

Some UI-based components are available via a module import, including notification and toast components.

### Import Notification Component Modules

These notification components require a module import.

- [`lightning/alert`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-alert)
- [`lightning/confirm`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-confirm)
- [`lightning/prompt`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-prompt)

For example, you use `lightning/prompt` by first importing the module, and then create an instance of the base component by calling a `.open()` method on the module.

```javascript
import { LightningElement } from "lwc";
import LightningPrompt from "lightning/prompt";
export default class MyComponent extends LightningElement {
  async handlePrompt() {
    // Returned value is input text if OK clicked
    // or null if cancel is clicked
    this.promptValue = await LightningPrompt.open({
      message: "This is the prompt message",
      label: "This is the header title",
      defaultValue: "initial input value",
      theme: "shade",
    });
  }
}
```

The usage of these components resemble the `window.*()` APIs. As
the HTML specification has [deprecated support](https://developer.salesforce.com/blogs/2022/01/preparing-your-components-for-the-removal-of-alert-confirm-prompt) for the `window.alert()`, `window.confirm()`, and `window.prompt()` methods when used in a third-party context, we recommend that you use these notification components instead.

Unlike the `window.*()` APIs, these modules' `.open()` method don't halt execution on the page, and they each return a promise. Use `async`/`await` or `.then()` for any code that you want to execute after the modal closes.

### Import Toast Component Modules

These toast components require a module import.

- [`lightning/toast`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast)
- [`lightning/platformShowToastEvent`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-show-toast-event)

Although both toast components require a module import, `lightning/platformShowToastEvent` uses an event-based mechanism to display a toast, and it's not supported in environments like LWR sites for Experience Cloud or standalone apps. We recommend that you use [lightning/toast](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast) instead.

## Use a Base Component by Extension

Unless stated otherwise, extending any class besides `LightningElement` to create a Lightning web component isn’t supported. Only several base components allow for class extension.

- `lightning/modal`
- `lightning/datatable`

Using `lightning/modal` by extension:

- Enables your custom modal component to appear as an overlay on the current app window.
- Provides the open and close mechanisms for your custom modal component.

To create the modal’s UI, use the `lightning-modal-header`, `lightning-modal-body`, and `lightning-modal-footer` components.

Similarly, using `lightning/datatable` by extension enables you to create a custom data type for the datatable component.

**See Also**

- [Modal Windows](https://developer.salesforce.com/docs/platform/lwc/use/use-dialog-modal.md)
- [Define Your Custom Type by Extending LightningDatatable](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md)

<!-- document id=decd4632548c9a9f8ea8063f1a67306a6f6e7a2bb49a7dd67f190b795e50c42e url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-map-aura-lwc-components.md -->

# Base Components: Aura Vs Lightning Web Components

Many of the base components for LWC provide the same functionality and attributes as their Aura counterparts. Some have subtle differences.

Lightning web components inherit global HTML attributes and events, making them more functional and better performing than their Aura counterparts. The [Component Reference](https://developer.salesforce.com/docs/component-library) doesn’t list the global HTML attributes and events for each component. See [Global Attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) and [Events](https://developer.mozilla.org/en-US/docs/Web/Events) at MDN.

For component styling, the base Aura components and Lightning web components both support design variations and SLDS utility classes. The base Aura components also support custom styling with your own classes. However, Lightning web components follow shadow DOM standards, which prevent custom styling with your own classes. Some base LWC components support SLDS styling hooks for custom styling. See [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md).

Beginning in Summer ’24, Aura components can also use styling hooks as described in [Replace Design Tokens with Styling Hooks](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/styling_hooks.htm).

The following table lists usage differences between Aura base components and their Lightning web component counterparts. Aura components follow the name format `namespace:componentName`, with a colon that separates the namespace and component name. Lightning web components follow the name format `namespace-component-name`, with a dash that separates the namespace and component name.

Table 1. Mapping of Aura Components to Lightning Web Components

| Namespace   | Aura Component                   | Lightning Web Component             | Differences                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------- | -------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lightning` | `accordion`                      | `accordion`                         | `lightning:accordion` supports the initialization of multiple open sections in simple markup. To initialize `lightning-accordion` with multiple open sections, pass the array of section names using JavaScript. For `lightning:accordion`, the `openSections` event parameter returns an array of strings even for a single open accordion section. For `lightning-accordion`, `openSections` returns a string only if you don't include the `allow-multiple-sections-open` attribute.                                                                 |
| `lightning` | `accordionSection`               | `accordion-section`                 | `lightning:accordionSection` supports custom menu `actions` through an actions attribute that passes in a `lightning:buttonMenu` component. The `title` attribute for the Aura component provides tooltip text when you hover over an accordion section. `lightning-accordion-section` supports custom menu actions through an `actions` slot for `lightning-button-menu`. The `title` attribute in the Lightning web component is currently reserved for internal use.                                                                                 |
| `lightning` | `avatar`                         | `avatar`                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `badge`                          | `badge`                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `breadcrumb`                     | `breadcrumb`                        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `breadcrumbs`                    | `breadcrumbs`                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `button`                         | `button`                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `buttonGroup`                    | `button-group`                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `buttonIcon`                     | `button-icon`                       | `lightning-button-icon` doesn’t support `iconClass`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lightning` | `buttonIconStateful`             | `button-icon-stateful`              | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `buttonMenu`                     | `button-menu`                       | `lightning:buttonMenu` doesn’t support the `onclick` and `onclose` event handlers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `lightning` | `buttonStateful`                 | `button-stateful`                   | In `lightning:buttonStateful`, use the `state` attribute to show when the button is selected. In `lightning-button-stateful`, use the `selected` attribute.                                                                                                                                                                                                                                                                                                                                                                                             |
| `lightning` | `card`                           | `card`                              | In `lightning:card`, you can set the `title` and `footer` attributes as strings or objects, which enables you to pass components. You can use the `actions` attribute to specify a `lightning:button` or `lightning:buttonIcon` to display in the card’s header. In `lightning-card`, you can set the `title` and `footer` attributes to text only. To include markup or other components, use named slots. You can specify actions only in an `action` named slot.                                                                                     |
| `lightning` | `carousel`                       | `carousel`                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `checkboxGroup`                  | `checkbox-group`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `clickToDial`                    | `click-to-dial`                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `combobox`                       | `combobox`                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `container`                      | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `datatable`                      | `datatable`                         | `lightning:datatable` doesn’t support custom data types in table cells. `lightning:datatable` supports custom CSS classes for styling a column of standard data types only. `lightning-datatable` supports custom data types in table cells. `lightning-datatable` supports custom CSS classes for styling a column for custom data types only.                                                                                                                                                                                                         |
| `lightning` | `dualListbox`                    | `dual-listbox`                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `dynamicIcon`                    | `dynamic-icon`                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `fileCard`                       | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `fileUpload`                     | `file-upload`                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `flexipageRegionInfo`            | -                                   | In Aura, use `flexipageRegionInfo` to make the containing component aware of the width it can occupy. In Lightning web components, use the `flexipageRegionWidth` public property for this purpose. See [Make a Component Width-Aware](https://developer.salesforce.com/docs/platform/lwc/use/use-width-aware.md).                                                                                                                                                                                                                                                                                      |
| `lightning` | `flow`                           | `flow`                              | See [Create and Start a Flow in a Custom LWC](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-embed-create-start.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `lightning` | `formattedAddress`               | `formatted-address`                 | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedDateTime`              | `formatted-date-time`               | In `lightning:formattedDateTime`, set the `hour12` attribute using true or false strings or a variable. In `lightning-formatted-number`, set the `hour12` attribute only by using a variable. Strings are always interpreted as true.                                                                                                                                                                                                                                                                                                                   |
| `lightning` | `formattedEmail`                 | `formatted-email`                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedLocation`              | `formatted-location`                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedName`                  | `formatted-name`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedNumber`                | `formatted-number`                  | In `lightning:formattedNumber`, use the `style` attribute to specify the type of number to display. In `lightning-formatted-number`, use the `format-style` attribute for this purpose.                                                                                                                                                                                                                                                                                                                                                                 |
| `lightning` | `formattedPhone`                 | `formatted-phone`                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedRichText`              | `formatted-rich-text`               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedText`                  | `formatted-text`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedTime`                  | `formatted-time`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `formattedUrl`                   | `formatted-url`                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `helptext`                       | `helptext`                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `icon`                           | `icon`                              | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `input`                          | `input`                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `inputAddress`                   | `input-address`                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `inputField`                     | `input-field`                       | `lightning:inputField` doesn’t provide a way to indicate that a field has been modified but not saved. `lightning-input-field` supports a `dirty` attribute to indicate that the field has been modified by the user but not saved or submitted. For more information, see the `recordEditForm` differences. `lightning:inputField` supports the `readonly` attribute but `lightning-input-field` supports both `readonly` and `read-only`.                                                                                                             |
| `lightning` | `inputLocation`                  | `input-location`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `inputName`                      | `input-name`                        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `inputRichText`                  | `input-rich-text`                   | `lightning:inputRichText` requires you to use the `lightning:insertImageButton` child component to add an insert image button. It doesn’t support an insert link button or custom buttons. `lightning-input-rich-text` provides buttons to insert images and links. `lightning-input-rich-text` supports adding custom buttons with the components `lightning-rich-text-toolbar-button-group` and `lightning-rich-text-toolbar-button` (beta).                                                                                                          |
| `lightning` | `insertImageButton`              | -                                   | An insert image button is supported in `lightning-input-rich-text` so you don’t need `lightning:insertImageButton`.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lightning` | `layout`                         | `layout`                            | `lightning:layout` allows HTML tags, text, expressions, and other components between `lightning:layoutItem` components. `lightning-layout` does not allow expressions or other components between `lightning-layout-item` components. However, you can place HTML tags and text between `lightning-layout-item` components.                                                                                                                                                                                                                             |
| `lightning` | `layoutItem`                     | `layout-item`                       | See the differences for `lightning-layout`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `lightning` | `listView`                       | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `map`                            | `map`                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `menuItem`                       | `menu-item`                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `navigation`                     | `navigation` module                 | In an Aura component, use the `lightning:navigation` component to access the navigation service. In a Lightning web component, import the `lightning/navigation` module in the component’s JavaScript. See [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                                                                                                                                             |
| `lightning` | `notificationsLibrary`           | `platformShowToastEvent` module     | In Aura components, add the `notificationsLibrary` component to create notices and toasts. The library provides `showToast` and `showNotice` events. In Lightning web components, import the `lightning/platformShowToastEvent` module in your component’s JavaScript. The module provides an event named `ShowToastEvent`. LWC doesn’t support notices yet. `ShowToastEvent` supports the same parameters, modes, and variants as Aura’s `showToast`. See [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/use/use-toast.md).                                                  |
| `lightning` | `outputField`                    | `output-field`                      | See `recordViewForm` differences.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `overlayLibrary`                 | -                                   | In Aura components, add the `overlayLibrary` component to create modal dialogs and popovers. The library provides `showCustomModal()`, `showCustomPopover()`, and `notifyClose()` methods.                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `path`                           | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `picklistPath`                   | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `pill`                           | `pill`                              | `lightning:pill` requires the `media` attribute to include an avatar or icon. The `variant` attribute is not available on `lightning:pill`. `lightning-pill` can accept avatars and icons as nested components.                                                                                                                                                                                                                                                                                                                                         |
| `lightning` | `pillContainer`                  | `pill-container`                    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `progressBar`                    | `progress-bar`                      | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `progressIndicator`              | `progress-indicator`                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `progressRing`                   | `progress-ring`                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `quipCard`                       | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `radioGroup`                     | `radio-group`                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `recordEditForm`                 | `record-edit-form`                  | `lightning:recordEditForm` doesn’t require you to nest `lightning:inputField` components directly in it. You can nest `lightning:inputField` components in HTML tags or other components such as `lightning:layout` to tailor the layout. `lightning-input-field` is intended to be used as a child of `lightning-record-edit-form`. You can nest `lightning-input-field` in HTML tags or another base component such as `lightning-layout` within `lightning-record-edit-form`. However, you can’t nest `lightning-input-field` in a custom component. |
| `lightning` | `recordForm`                     | `record-form`                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `recordViewForm`                 | `record-view-form`                  | `lightning:recordViewForm` doesn’t require you to nest `lightning:outputField` components directly in it, although this is the expected usage. `lightning-output-field` must be a child of `lightning-record-view-form`. Don’t nest `lightning-output-field` in another element like `lightning-layout`. You can place it in a container such as within `lightning-record-view-form`.                                                                                                                                                                   |
| `lightning` | `relativeDateTime`               | `relative-date-time`                | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `select`                         | -                                   | Lightning web component not yet available. In a mobile environment, use the native `<select>` element.In a desktop environment, consider using the `lightning-combobox` Lightning web component. To support multiple selection, use `lightning-dual-listbox`.                                                                                                                                                                                                                                                                                           |
| `lightning` | `slider`                         | `slider`                            | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `spinner`                        | `spinner`                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `tab`                            | `tab`                               | In `lightning:tab`, use the `id` attribute to assign a string to identify a tab. In `lightning-tab`, use the `value` attribute to assign the tab identifier. The `tabset` uses these strings to determine which tab was clicked.                                                                                                                                                                                                                                                                                                                        |
| `lightning` | `tabset`                         | `tabset`                            | `lightning:tabset` uses the `selectedTabId` attribute to specify the open tab. `lightning-tabset` uses the `active-tab-value attribute`.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `lightning` | `textarea`                       | `textarea`                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `tile`                           | `tile`                              | In `lightning:tile`, you can use `<aura:set\>` to add a `media` attribute that contains an avatar component or icon component. In `lightning-tile`, specify the avatar and icon components with `media` named slots.                                                                                                                                                                                                                                                                                                                                    |
| `lightning` | `tree`                           | `tree`                              | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `treeGrid`                       | `tree-grid`                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `unsavedChanges`                 | -                                   | Lightning web component not yet available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lightning` | `verticalNavigation`             | `vertical-navigation`               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `verticalNavigationItem`         | `vertical-navigation-item`          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `verticalNavigationItemBadge`    | `vertical-navigation-item-badge`    | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `verticalNavigationItemIcon`     | `vertical-navigation-item-icon`     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `verticalNavigationItemOverflow` | `vertical-navigation-item-overflow` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lightning` | `verticalNavigationSection`      | `vertical-navigation-section`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `aura`      | `expression`                     | Custom JavaScript                   | See [Migrate Expressions](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-expressions.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `aura`      | `html`                           | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `aura`      | `if`                             | `lwc:if / lwc:elseif / lwc:else`    | See [Migrate Conditionals](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-conditionals.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `aura`      | `iteration`                      | `for:each`                          | See [Migrate Iterations](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-iterations.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `aura`      | `renderIf`                       | `lwc:if / lwc:elseif / lwc:else`    | See [Migrate Conditionals](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-conditionals.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `aura`      | `template`                       | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `aura`      | `text`                           | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `aura`      | `token`                          | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `aura`      | `unescapedHTML`                  | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `force`     | `canvasApp`                      | -                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `force`     | `inputField`                     | `input-field`                       | `force:inputField` has been replaced by `lightning:inputField` in Aura. To create editable fields based on field types, use `lightning:inputField` with `lightning:recordEditForm` or their Lightning web component counterparts.                                                                                                                                                                                                                                                                                                                       |
| `force`     | `outputField`                    | `output-field`                      | `force:outputField` has been replaced by `lightning:outputField` in Aura. To create read-only fields based on field types, use `lightning:outputField` with `lightning:recordViewForm` or their Lightning web component counterparts.                                                                                                                                                                                                                                                                                                                   |
| `force`     | `recordData`                     | `@wire`                             | See [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `force`     | `recordEdit`                     | `record-edit-form`                  | `force:recordEdit` has been replaced by `lightning:recordEditForm`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `force`     | `recordView`                     | `record-view-form`                  | `force:recordView` has been replaced by `lightning:recordViewForm`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ltng`      | `require`                        | `platformResourceLoader` module     | In Aura components, add the `<ltng:require>` tag to your component markup to reference external static resources. In Lightning web components, import the `lightning/platformResourceLoader` module in your component’s JavaScript. See [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md).                                                                                                                                                                                                                                        |

**See Also**

- [Migrate Base Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-base-components.md)
- [Base Components: Migrate `ui` components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-ui-components.md)

<!-- document id=9456d7d7e1c8073d51ed55255ca444e6fe49a5f17cf09a2cf196c785ebe19097 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-map-ui-components.md -->

# Base Components: Migrate `ui` components

Aura components in the `ui` namespace are deprecated. Support for these deprecated components ended on May 1, 2021.

When you migrate Aura components from the `lightning` and `ui` namespaces, use its LWC equivalent. For example, replace `ui:button` and `lightning:button` with the LWC equivalent: `lightning-button`, `lightning-button-icon`, or `lightning-button-icon-stateful`.

Table 1. Mapping of Aura components in the `ui` namespace

| Aura Component                                                                                                                     | LWC                                                                                                                                                                                                                                                    | Usage                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ui\:actionMenuItem](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-action-menu-item)       | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:button](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-button)                         | lightning-button-\*                                                                                                                                                                                                                                    | Use `lightning-button`, `lightning-button-icon`, or `lightning-button-icon-stateful`. For button groups, use `lightning-button-group`.                                                                                                                                                                                                                      |
| [ui\:checkboxMenuItem](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-checkbox-menu-item)   | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:inputCheckbox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-checkbox)          | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `checkbox`, `toggle`, or `checkbox-button` type instead. For checkbox groups, use `lightning-checkbox-group`.                                                                                                                                                                                                                    |
| [ui\:inputCurrency](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-currency)          | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `number` type and `currency` formatter instead.                                                                                                                                                                                                                                                                                  |
| [ui\:inputDate](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-date)                  | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `date` type instead.                                                                                                                                                                                                                                                                                                             |
| [ui\:inputDateTime](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-date-time)         | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `datetime` type instead.                                                                                                                                                                                                                                                                                                         |
| [ui\:inputDefaultError](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-default-error) | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with built-in field validation instead.                                                                                                                                                                                                                                                                                               |
| [ui\:inputEmail](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-email)                | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `email` type instead.                                                                                                                                                                                                                                                                                                            |
| [ui\:inputNumber](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-number)              | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `number` type instead.                                                                                                                                                                                                                                                                                                           |
| [ui\:inputPhone](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-phone)                | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `phone` type instead.                                                                                                                                                                                                                                                                                                            |
| [ui\:inputRadio](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-radio)                | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `radio` type instead. For radio groups, use `lightning-radio-group`.                                                                                                                                                                                                                                                             |
| [ui\:inputRichText](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-rich-text)         | [lightning-input-rich-text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input-rich-text)                                                                                                              | Use `lightning-input-rich-text` instead. To create custom toolbar buttons, use `lightning-rich-text-toolbar-button-group`.                                                                                                                                                                                                                                  |
| [ui\:inputSecret](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-secret)              | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `password` type instead.                                                                                                                                                                                                                                                                                                         |
| [ui\:inputSelect](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-select)              | [lightning-combobox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox) or [lightning-select](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select) | To create a list of options for single selection, use `lightning-combobox`. To enable single and multiple selection on a menu of options, use `lightning-select`.                                                                                                                                                                                           |
| [ui\:inputSelectOption](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-select-option) | [lightning-combobox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox) or [lightning-select](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select) | To create a list of options for single selection, use `lightning-combobox`. To enable single and multiple selection on a menu of options, use `lightning-select`.                                                                                                                                                                                           |
| [ui\:inputText](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-text)                  | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `text` type instead.                                                                                                                                                                                                                                                                                                             |
| [ui\:inputTextArea](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-text-area)         | [lightning-textarea](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-textarea)                                                                                                                            | Use `lightning-textarea` instead.                                                                                                                                                                                                                                                                                                                           |
| [ui\:inputURL](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-input-url)                    | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `url` type instead.                                                                                                                                                                                                                                                                                                              |
| [ui\:menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu)                             | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:menuItem](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu-item)                    | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:menuItemSeparator](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu-item-separator) | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-divider` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                          |
| [ui\:menuList](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu-list)                    | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:menuTrigger](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu-trigger)              | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:menuTriggerLink](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-menu-trigger-link)     | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:message](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-message)                       | [lightning/platformShowToastEvent](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-show-toast-event)                                                                                             | Use `lightning/toast` with `lightning/toastContainer` in LWR sites.                                                                                                                                                                                                                                                                                         |
| [ui\:outputCheckbox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-checkbox)        | [lightning-input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)                                                                                                                                  | Use `lightning-input` with `checkbox` type and set `readonly` to `true`.                                                                                                                                                                                                                                                                                    |
| [ui\:outputCurrency](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-currency)        | [lightning-formatted-number](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number)                                                                                                            | Use `lightning-formatted-number` with `style` set to `currency`.                                                                                                                                                                                                                                                                                            |
| [ui\:outputDate](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-date)                | [lightning-formatted-date-time](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time)                                                                                                      | Use `lightning-formatted-date-time` instead.                                                                                                                                                                                                                                                                                                                |
| [ui\:outputDateTime](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-date-time)       | [lightning-formatted-date-time](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time)                                                                                                      | To include the date in the output, use `lightning-formatted-date-time`. Otherwise, use `lightning-formatted-time`.                                                                                                                                                                                                                                          |
| [ui\:outputEmail](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-email)              | [lightning-formatted-email](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-email)                                                                                                              | Use `lightning-formatted-email` instead.                                                                                                                                                                                                                                                                                                                    |
| [ui\:outputNumber](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-number)            | [lightning-formatted-number](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number)                                                                                                            | Use `lightning-formatted-number` instead.                                                                                                                                                                                                                                                                                                                   |
| [ui\:outputPhone](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-phone)              | [lightning-formatted-phone](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-phone)                                                                                                              | Use `lightning-formatted-phone` instead.                                                                                                                                                                                                                                                                                                                    |
| [ui\:outputRichText](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-rich-text)       | [lightning-formatted-rich-text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-rich-text)                                                                                                      | Use `lightning-formatted-rich-text` instead.                                                                                                                                                                                                                                                                                                                |
| [ui\:outputText](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-text)                | [lightning-formatted-text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-text)                                                                                                                | Use `lightning-formatted-text` instead.                                                                                                                                                                                                                                                                                                                     |
| [ui\:outputTextArea](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-text-area)       | [lightning-formatted-text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-text)                                                                                                                | Use `lightning-formatted-text` instead.                                                                                                                                                                                                                                                                                                                     |
| [ui\:outputURL](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-output-url)                  | [lightning-formatted-url](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-url)                                                                                                                  | There are several ways to work with links. <ul><li>Custom onclick event handler: Use the HTML anchor tag `<a>`</li><li>Navigate in Lightning Experience: Use `lightning-navigation`</li><li>Email address with `mailto:` protocol: Use `lightning-formatted-email`</li><li>Phone number with the `tel:` protocol: Use `lightning-formatted-phone`</li></ul> |
| [ui\:radioMenuItem](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-radio-menu-item)         | [lightning-button-menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu)                                                                                                                      | Use `lightning-menu-item` with `lightning-button-menu` instead.                                                                                                                                                                                                                                                                                             |
| [ui\:spinner](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ui-spinner)                       | [lightning-spinner](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-spinner)                                                                                                                              | Use `lightning-spinner` instead.                                                                                                                                                                                                                                                                                                                            |

**See Also**

[Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components.md)

<!-- document id=0a1d2187fc7f771d1c42be58ed456df79a07ba3f28f14784bce95faa6943156f url=/developer/current/en-us/lwc/utam/references/basic-actions.md -->

# Basic Actions

[Basic elements](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#basic-elements) support different public methods depending on the array of `type` options set for the element.

The following sections list the methods available for each type.

## Base Element Actions

These methods are available by default for all elements.

| Action                | Summary                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `containsElement`     | Returns `true` if the current element contains an element with the selector provided as a parameter. The second optional parameter is a boolean to expand the element's shadowRoot when looking for the element.                                                                                                                                  |
| `getAttribute`        | Returns the string value of a given attribute.                                                                                                                                                                                                                                                                                                    |
| `getClassAttribute`   | Shortcut for `getAttribute("class")`, in Java actual method is called getClassAttribute().                                                                                                                                                                                                                                                        |
| `getCssPropertyValue` | Returns the string value of a given CSS property.                                                                                                                                                                                                                                                                                                 |
| `getRect`             | Returns an `ElementRectangle` object with coordinates (`x` and `y` properties in JavaScript, `getX()` and `getY()` public methods in Java) and the size of the element (`width` and `height` properties in JavaScript, `getWidth()` and `getHeight()` public methods in Java). **This method returns void if you use it in a compose statement.** |
| `getText`             | Returns a string with the `innerText` of an element.                                                                                                                                                                                                                                                                                              |
| `getTitle`            | Shortcut for `getAttribute("title")`.                                                                                                                                                                                                                                                                                                             |
| `getValue`            | Returns the value of an `input` element's `value` property.                                                                                                                                                                                                                                                                                       |
| `isEnabled`           | Returns `true` if the element is enabled.                                                                                                                                                                                                                                                                                                         |
| `isFocused`           | Returns `true` if the element has focus at the moment.                                                                                                                                                                                                                                                                                            |
| `isPresent`           | Returns `true` if the element is found in the DOM.                                                                                                                                                                                                                                                                                                |
| `isVisible`           | Returns `true` if the element is visible.                                                                                                                                                                                                                                                                                                         |
| `waitFor`             | Waits for a function that's provided as a parameter to return a truthy value. This method is the UTAM version of [Selenium `wait`](https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/node/selenium-webdriver/lib/webdriver.js).                                                                                                        |
| `waitForAbsence`      | Polling wait action&mdash;waits for an element to be absent (not-attached to the DOM) within a timeout. Throws an exception after the timeout.                                                                                                                                                                                                    |
| `waitForInvisible`    | Polling wait action&mdash;waits for the element to become not displayed within the timeout. Expects the element to be present while checking its visibility.                                                                                                                                                                                      |
| `waitForVisible`      | Polling wait action&mdash;waits for the element to be visible within a timeout. Throws an error if the element isn’t present.                                                                                                                                                                                                                     |

## Actionable Type Actions

These methods are available if the element's `type` array includes `actionable`.

| Action           | Summary                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `blur`           | Applies a blur action to the element.                                                                                           |
| `focus`          | Applies a focus action to the element. The focused element is the default element to receive keyboard or similar events.        |
| `moveTo`         | Moves the mouse to the middle of the element&mdash;also known as mouseover.                                                     |
| `scrollToCenter` | Scrolls the current element to the center of the screen by executing JavaScript `arguments[0].scrollIntoView({block:'center'})` |
| `scrollToTop`    | Scroll to the element by executing JavaScript `return arguments[0].scrollIntoView(true);`                                       |

## Clickable Type Actions

These methods are available if the element's `type` array includes `clickable` type.

| Action         | Summary                                                                                 |
| -------------- | --------------------------------------------------------------------------------------- |
| `click`        | Applies click action to the element.                                                    |
| `doubleClick`  | Applies double click action to the element.                                             |
| `rightClick`   | Applies right click action to the element.                                              |
| `clickAndHold` | Click on the element and holds `holdDurationSec` seconds before releasing mouse button. |

## Editable Type Actions

These methods are available if the element's `type` array includes `editable`.

| Action         | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clear`        | If this element is a text entry element, the method clears the value. Otherwise it throws an exception.                                                                                                                                                                                                                                                                                                                                    |
| `clearAndType` | Combines `clear` and `setText`: clears an element's value and replaces it with a provided string.                                                                                                                                                                                                                                                                                                                                          |
| `press`        | Presses a key. Pass a [key name](https://w3c.github.io/webdriver/#keyboard-actions): `press('Enter')`. This method has an optional second `options` object `{text: string}` parameter that allows you to specify key combinations. This example copies the text of the currently focused editable textarea element to the clipboard.<br/>`await textarea.press('Meta', { text: 'A' });`<br/>`await textarea.press('Meta', { text: 'C' });` |
| `setText`      | Simulate typing text inside an element, which may set its value.                                                                                                                                                                                                                                                                                                                                                                           |

## Draggable Type Actions

These methods are available if the element's `type` array includes `draggable`.

| Action                | Summary                                                                                                                                                                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dragAndDrop`         | Clicks on an element, and holds and drops it at the target location. The target location is defined by another basic element. If the second optional `durationSec` parameter is set, pause during the hold. Example: `dragAndDrop(myElement, 10)`.                                                   |
| `dragAndDropByOffset` | Clicks on an element, and holds and drops it at the target location. The target location is determined by `x` and `y` offset coordinates relative to the current element. If the third optional `durationSec` parameter is set, pause during the hold. Example: `dragAndDropByOffset(400, 300, 10)`. |

## Touchable Type Actions

**important:** Touchable type actions are only supported for Mobile platform.

These methods are available if the element's `type` array includes `touchable`.

| Action  | Summary                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flick` | Flicks on the touch screen using finger motion events. The start point is the middle of the element. The end point is determined by `x` and `y` offset coordinates relative to the current element. Example: `flick(100, 100)`. |

<!-- document id=53a4f3e6f29c8a11872e60c3fbb1c7121c29e692fcfa7f902cc2d23bd17827db url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-basic.md -->

# Basic Navigation

In Lightning Experience and the Salesforce mobile app, each page corresponds to a `PageReference` JavaScript object. A [`PageReference`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md) is a JavaScript object that describes the page type, its attributes, and the state of the page. Using a `PageReference` insulates your component from future changes to URL formats. It also allows your component to be used in multiple applications, each of which can use different URL formats.

Use the following resources to simplify navigation across your apps. URLs for components using these resources are case-sensitive.

- The `lightning/navigation` module

  - : Use the navigation service, `lightning/navigation`, to navigate to many different page types, like records, list views, and objects. Also use the navigation service to open files.

- The `lightning__UrlAddressable` target

  - : To generate a URL for a component so you can navigate directly to it, add the [`lightning__UrlAddressable` target](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-url-addressable.md) to the component's `.js-meta.xml` configuration file. You can navigate to the component using `lightning/navigation` with the `standard__component` page reference type.

## `PageReference` Properties

`PageReference` supports the following properties.

| `PageReference` Property | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`                   | String | To navigate in Lightning Experience, Experience Builder sites, or the Salesforce mobile app, define a `PageReference` object. The `PageReference` type generates a unique URL format and defines attributes that apply to all pages of that type. For Experience Builder sites, depending on the page type, the `PageReference` property requirements can differ between LWR sites and Aura sites. See [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md). | Yes      |
| `attributes`             | Object | Map of name-value pairs that determine the target page. The page type defines the set of possible attribute names and their respective value types.                                                                                                                                                                                                                                                                                                                          | Yes      |
| `state`                  | Object | Set of key-value pairs with string keys and string values. These parameters conditionally customize content within a given page. Some page reference types support a standard set of `state` properties. You can also pass non-standard properties into `state` as long as they are namespaced.                                                                                                                                                                              | No       |

The navigation service adds two APIs to your component's class. Since these APIs are methods on the class, invoke them from `this`.

- `[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference, [replace])`

  A component calls `this[NavigationMixin.Navigate]` to navigate to another page in the application.

- `[NavigationMixin.GenerateUrl](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference)`

  A component calls `this[NavigationMixin.GenerateUrl]` to get a `promise` that resolves to the resulting URL. The component can use the URL in the `href` attribute of an anchor. It can also use the URL to open a new window using the `window.open({url})` browser API.

## Use the Navigation Service

1.  In the component’s JavaScript class, import the `NavigationMixin` function from the [`lightning/navigation`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation) module.

    ```javascript
    import { NavigationMixin } from "lightning/navigation";
    ```

2.  Apply the `NavigationMixin` function to your component’s base class.

    ```javascript
    export default class MyCustomElement extends NavigationMixin(LightningElement) {}
    ```

3.  Create a plain JavaScript [`PageReference`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md) object that defines the page.
4.  To dispatch the navigation request, call the navigation service’s `[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference, [replace])` function. If `replace` is set to `true`, the `pageReference` replaces the existing entry in the browser history so the user doesn’t have to press the back button twice. The default value is `false`.

    ```javascript
    navigateNext() {
           this[NavigationMixin.Navigate]({
               type: 'standard__navItemPage',
               attributes: {
                   apiName: this.tabName,
               },
           });
       }
    ```

## Example: Navigate to Account Home

This example shows a link to the account home page. When a user clicks the link, the `click` event handler, `handleClick`, calls the navigation service’s `Navigate` method, which loads the account home page. The account home URL is also available in the anchor tag, which allows users to copy the link or open it in a new window.

<!-- prettier-ignore -->
```html
<!-- navigationLinkExample.html -->
<template>
  <div>
    <a href={url} onclick={handleClick}>Account Home</a>
  </div>
</template>
```

In the component’s JavaScript file, import the navigation service.

To navigate to the account home page and to generate its URL, the navigation service uses a `PageReference` object. The `PageReference` object, `accountHomePageRef`, is defined in the `connectedCallback()` lifecycle hook when the component is inserted into the DOM. The navigation service stores the account home URL in the `url` property, which is used in the template.

The `handleClick` event handler is also defined in the component’s JavaScript class, and navigates to the page reference, `accountHomePageRef`.

```javascript
// navigationLinkExample.js
import { LightningElement, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class NavigationLinkExample extends NavigationMixin(LightningElement) {
  url;

  connectedCallback() {
    // Store the PageReference in a variable to use in handleClick.
    // This is a plain Javascript object that conforms to the
    // PageReference type by including 'type' and 'attributes' properties.
    // The 'state' property is optional.
    this.accountHomePageRef = {
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Account",
        actionName: "home",
      },
    };
    this[NavigationMixin.GenerateUrl](this.accountHomePageRef).then((url) => (this.url = url));
  }

  handleClick(evt) {
    // Stop the event's default behavior.
    // Stop the event from bubbling up in the DOM.
    evt.preventDefault();
    evt.stopPropagation();
    // Navigate to the Account Home page.
    this[NavigationMixin.Navigate](this.accountHomePageRef);
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has navigation service examples. Look for components that start with `navTo`, such as [navToHome](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/navToHome).

**See Also**

- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md)
- [Navigate to a URL-Addressable Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-url-addressable.md)
- [Quick Action Navigation](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-quick-action.md)
- [Test the Navigation Service](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md#test-the-navigation-service)

<!-- document id=03be882a315d757e4a731c403b8cbfef99fa40550facfd3e37e7a0c33e92e9b6 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-batched-actions.md -->

# Batching of Apex Actions

The framework queues up Apex actions before sending them to the server. This mechanism is largely transparent to you when you’re writing code but it enables the framework to minimize network traffic by batching multiple actions into one request (XHR).

The batching of actions is also known as boxcar’ing, similar to a train that couples boxcars together.

The framework uses a stack to track the Apex actions to send to the server. When the browser finishes processing events and JavaScript on the client, the enqueued actions on the stack are sent to the server in a batch.

**note:** The framework returns a 413 HTTP response status code if there are more than 2,500 actions in a boxcar request. If a user sees this rare error, consider redesigning your custom component to follow best practices and reduce the number of actions in a request.

<!-- document id=de6e3ad23bc50598fd52acbf1d3d9117695a933ff096cd9365ad68b442367f9d url=/developer/current/en-us/lwc/utam/references/beforeload.md -->

# beforeLoad

The `beforeLoad` array sets the criteria to be satisfied before the `load` method completes. If you don't specify a `beforeLoad` array, the `load` method finds a root element for a regular page object, or waits for the root element to be present for a root page object, by default.

**note:** Statements inside the `beforeLoad` array can reference only `root` or `document` elements because other elements are not loaded yet.

This `ApplicationHome` page object waits for the DOM to finish rendering before loading is complete and then waits for the root and indicator elements:

```json
{
  "selector": {
    "css": "application-home"
  },
  "root": true,
  "beforeLoad": [
    {
      "element": "document",
      "apply": "waitForDocumentReady"
    },
    {
      "apply": "waitFor",
      "args": [
        {
          "type": "function",
          "predicate": [
            {
              "element": "root",
              "apply": "isPresent"
            },
            {
              "element": "root",
              "apply": "containsElement",
              "args": [
                {
                  "type": "locator",
                  "value": {
                    "css": ".indicator"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Load an element

When `load` is set to true for an element.A [waitFor method for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#load-an-element) is generated and it is automatically invoked in the `beforeLoad` method.

## Invoke beforeLoad from compose

Sometimes page can be partially reloaded, then to avoid stale elements we might need to invoke `beforeLoad` from compose method. Note that invocation should be of the method `load` which is part of public API, here is an example:

```json
{
  "name": "reloadAndClick",
  "compose": [
    {
      "element": "increment",
      "apply": "click"
    },
    {
      "apply": "load"
    }
  ]
}
```

<!-- document id=09c71f921d259db8c73f0096742b323d00d56681a17d3f72bf912a2d7a0d11f2 url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-begincapture.md -->

# `beginCapture(options)` (Legacy)

Use this function to start a new scanning session.

**note:** We recommend using the modern [`scan()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-scan.md) and [`dismiss()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-dismiss.md) APIs in your LWC’s scanning code to streamline your development experience. The legacy APIs `beginCapture()`, `resumeCapture()`, and `endCapture()` are still available, but will be retired in a future release.

## Syntax

```
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
beginCapture(options: BarcodeScannerOptions): Promise<Object>
```

## Parameters

- `options`—(Required) A [`BarcodeScannerOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) object to configure the scanning session.

## Returns

A Promise object that resolves as a [`Barcode`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) with the scanned barcode details.

A rejected promise returns a [`BarcodeScannerFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md).

## Usage

This function allocates scanner resources. To release the resources when scanning is complete, pair it with `endCapture()`.

```javascript
myScanner
  .beginCapture(scanningOptions)
  .then((result) => {
    // Do something with the result of the scan
    console.log(result);
    this.scannedBarcode = result.value;
  })
  .catch((error) => {
    // Handle cancellation and scanning errors here
    console.error(error);
  })
  .finally(() => {
    myScanner.endCapture();
  });
```

When this function is called, a mobile OS scanning user interface is displayed on the mobile device. The user can point their camera at a barcode and wait for the barcode to be recognized.

- When a barcode is successfully scanned, the result is returned via a fulfilled promise. Handle successful results in a `then` clause.
- When a barcode scan fails, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user clicks the **Cancel** button during a scan, the promise is rejected with a [`BarcodeScannerFailure.code`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) value of `userDismissedScanner`.
- The mobile OS scanner interface remains displayed after a successful scan or an error. To close the scanner interface and return to your component’s interface, call `endCapture()`.
- Handle any final cleanup, such as calling `endCapture()`, in a `finally` clause.

**See Also**

- [BarcodeScanner Example—Single Scan (Legacy)](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_example.htm)
- [endCapture() (Legacy)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-endcapture.md)

<!-- document id=afc395785967b11c623136408c544c39e8e555ccc751fb420ca2033f256e7b94 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-console-benchmark.md -->

# Benchmark Lightning Locker Effect on JavaScript Code

Benchmark your JavaScript code with and without Lightning Locker and view relative performance metrics.

Benchmarking enables you to see the performance difference with Lightning Locker enabled and disabled, without requiring you to create an app to test your component.

## Example

Let’s look at an example where you study the performance of a series of nested loops.

1. Paste this code into the code console.

   ```javascript
   function build(count) {
     var table = document.createElement("table");
     for (var contact = 0; contact < count; contact++) {
       for (var day = 0; day < 7; day++) {
         var tr = document.createElement("tr");
         var td = document.createElement("td");
         td.textContent = contact;
         tr.appendChild(td);
         for (var hour = 6; hour < 22; hour++) {
           td = document.createElement("td");
           td.className = "officeDivider";
           tr.appendChild(td);

           td = document.createElement("td");
           td.className = "officeHourIn";
           tr.appendChild(td);

           td = document.createElement("td");
           td.className = "officeHourIn";
           tr.appendChild(td);

           td = document.createElement("td");
           td.className = "officeHourIn";
           tr.appendChild(td);

           td = document.createElement("td");
           td.className = "officeHourIn";
           tr.appendChild(td);
         }
         table.appendChild(tr);
       }
     }
     return table;
   }
   build(10);
   ```

2. Click **Benchmark**.

   The FASTEST column in the results window shows that the code runs 16.11 times faster when Lightning Locker is disabled. This difference in speed is the cost of security, and whether the performance loss is acceptable depends on each specific case.

   ![Locker Console benchmark results for JavaScript code with DOM API calls inside nested loops](https://developer.salesforce.com/media/locker_console_benchmark_nested_loop.png '{"class": "image-framed"}')

The benchmark action allows you to tweak your code and see how the change affects running time. This rapid iterative process is useful when you're optimizing computationally intensive sections of the code.

## Example with Improved Performance

To show how to reduce the overhead of Lightning Locker, let's build the same table using a string of HTML and benchmark to evaluate the difference.

1. Paste this code into the code console.

   ```javascript
   function build(count) {
     var html = "<body>";
     for (var contact = 0; contact < count; contact++) {
       for (var day = 0; day < 7; day++) {
         html += "<td>" + contact + "</td>";
         for (var hour = 6; hour < 22; hour++) {
           html += "<td class='officeDivider'></td>";
           html += "<td class='officeHourIn'></td>";
           html += "<td class='officeHourIn'></td>";
           html += "<td class='officeHourIn'></td>";
           html += "<td class='officeHourIn'></td>";
         }
       }
     }
     html += "</body>";
     return html;
   }

   var div = document.createElement("div");
   div.innerHTML = build(10);
   ```

2. Click **Benchmark**.

   ![Locker Console benchmark results for JavaScript code without DOM API calls inside loops](https://developer.salesforce.com/media/locker_console_benchmark_improved_performance.png '{"class": "image-framed"}')

Because there are no DOM API calls, such as `document.createElement()`, inside the loops in this example, the performance of the `build()` function is similar whether Locker is on or off. The code runs 1.15 times faster when Lightning Locker is disabled, as opposed to 16.11 times faster in the previous example that had multiple DOM API calls.

Plain JavaScript is generally much faster than the DOM API, and the more often a section of code connects to the DOM, the slower the code runs. The DOM API causes most of the Locker overhead. Here, we accelerate the code by reducing the number of times we touch the DOM, which also greatly reduces the overall Locker overhead.

**See Also**

- [Locker Console Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console.md)

<!-- document id=ee1666c543f8c1ae68c0b146e465bfa7a467cc0064a4345c78660cdb295a994a url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-best-practices.md -->

# Best Practices

When using complex template expressions in LWC, follow these best practices to ensure maintainable, performant, and reliable code.

## Keep Expressions Simple and Readable

While complex expressions enable powerful inline computations, prioritize readability and maintainability:

```html
<!-- ✅ Good - simple and clear -->
<div>{user?.name ?? 'Guest'}</div>
<div>{items.length > 0 ? `Found ${items.length} items` : 'No items'}</div>

<!-- ❌ Avoid - too complex for inline -->
<div>
  {items.filter(i => i.active).map(i => i.price).reduce((a, b) => a + b, 0) / items.filter(i =>
  i.active).length}
</div>
```

**Best Practice:** If an expression spans multiple lines or requires significant mental parsing, it might be too complicated.

## Use Getters for Complex Logic

When logic becomes complex, extract complex calculations, formatting, or transformations to getters for better testability and reusability.

```html
<!-- ✅ Good - complex logic in getter -->
<div>{totalPrice}</div>
<div>{formattedDate}</div>

<!-- ❌ Avoid - complex logic inline -->
<div>{(subtotal + tax + shipping - discount).toFixed(2)}</div>
<div>
  {new Date(timestamp).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric'
  })}
</div>
```

## Prefer Component Methods for Reusable Logic

For logic that needs to be reused across multiple expressions or components, use component methods.

```html
<!-- ✅ Good - reusable method -->
<div>{formatCurrency(price)}</div>
<div>{formatCurrency(discount)}</div>
<div>{formatCurrency(total)}</div>
```

**tip:** Component methods are easier to test, debug, and reuse than inline expressions. Put your methods and functions in a separate [API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md) that you can easily import into any component that uses them.

## Test Thoroughly

Since complex template expressions are experimental, thorough testing is essential. Write comprehensive tests for any component using complex template expressions.

- **Unit Tests**: Test the JavaScript methods and getters used in expressions
- **Integration Tests**: Verify that expressions render correctly in components
- **Edge Cases**: Test with `null`, `undefined`, empty arrays, and boundary values
- **HTML Compliance**: Verify that expressions work correctly in both text nodes and attributes
- **Browser Compatibility**: Test across different browsers and versions

## Avoid Deeply Nested Expressions

Deeply nested expressions are difficult to read and maintain:

```html
<!-- ✅ Good - clear and readable -->
<div>{user?.profile?.name ?? 'Anonymous'}</div>

<!-- ❌ Avoid - too deeply nested -->
<div>{user?.profile?.settings?.theme?.colors?.primary ?? 'default'}</div>
```

**Best Practice:** Flatten nested structures or use intermediate variables or getters when nesting exceeds 2-3 levels.

## Use Meaningful Variable Names in Arrow Functions

When using arrow functions in expressions, use descriptive parameter names that clearly indicate what the variable represents.

```html
<!-- ✅ Good - clear variable names -->
<div>{items.map(item => item.name)}</div>
<div>{users.filter(user => user.isActive)}</div>

<!-- ❌ Avoid - unclear single-letter names -->
<div>{items.map(x => x.name)}</div>
<div>{users.filter(u => u.isActive)}</div>
```

## Quote Expressions in Attributes

Always quote complex expressions when used in attributes:

```html
<!-- ✅ Good - quoted complex expressions -->
<div class="{isActive ? 'active' : 'inactive'}"></div>
<button onclick="{() => handleClick()}">Click</button>

<!-- ❌ Error - unquoted complex expressions -->
<div class={isActive ? 'active' : 'inactive'}></div>
<button onclick={() => handleClick()}>Click</button>
```

**Best Practice**: Quote any expression that contains operators, function calls, or anything beyond simple property access.

## Consider HTML Compliance

Always ensure expressions are HTML compliant, especially when using comparison operators:

```html
<!-- ✅ Good - HTML compliant -->
<div>{age >= 18 ? 'Adult' : 'Minor'}</div>
<div class="{bar > foo ? 'high' : 'low'}"></div>

<!-- ❌ Avoid - not HTML compliant in text nodes -->
<div>{age < 18 ? 'Minor' : 'Adult'}</div>
```

**Best Practice**: Use `>=` and `>` instead of `<` and `<=` in text node expressions, or use quoted attributes for `<` comparisons. See [HTML Syntax Compatibility](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-expressions-compatibility.md) for additional details.

## Monitor Performance

While complex expressions are performant, be mindful of:

- **Repeated Calculations**: If an expression is used multiple times, consider caching the result in a getter
- **Large Arrays**: Operations on large arrays (filter, map, reduce) can impact performance
- **Frequent Re-renders**: Expressions are re-evaluated on every render; complex expressions can have a larger-than-expected impact

**Best Practice**: Profile your components and optimize expressions that are called frequently or operate on large datasets.

<!-- document id=1cbef6c6c060e5ecc9b94ec00a07cdb1f684379b7ef07314bb872fa53bcafa02 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-best-practices.md -->

# Best Practices for Development with Lightning Web Components

To create secure and efficient Lightning web components, follow our list of best practices for developers at the Salesforce Developer’s Blog:

- [Drive Consistency and Grow Developer Skills with a Developer Best Practices Checklist](https://developer.salesforce.com/blogs/2022/01/drive-consistency-and-grow-developer-skills-with-a-developer-best-practices-checklist)
- [Lightning Web Components Performance Best Practices](https://developer.salesforce.com/blogs/2020/06/lightning-web-components-performance-best-practices)
- [Step Up Your LWC Skills – Part 1](https://developer.salesforce.com/blogs/2020/10/step-up-your-lwc-skills-part-1)
- [Step Up Your LWC Skills – Part 2](https://developer.salesforce.com/blogs/2020/10/step-up-your-lwc-skills-part-2)

You can also explore these best practices videos:

::video{src="https://youtube.com/embed/_8LUnYDtUlU" title="Lightning Web Components Best Practices | TrailblazerDX 2023" type="youtube" }

::video{src="https://youtube.com/embed/9I7kTPVtrkI" title="Design Patterns and Best Practices to build reusable Lightning Web Components" type="youtube" }

::video{src="https://youtube.com/embed/_sdRQJuAeys" title="LWC Error Handling Best Practices" type="youtube" }

**See Also**

- [Explore Trailhead and Sample Code](https://developer.salesforce.com/docs/platform/lwc/install/install-sample-code-repo.md)

<!-- document id=20ba2e7727fc18cda5a06cf7c4c8eac9847928108394b56ffc194cbc9e8ccffe url=/developer/current/en-us/lwc/lwc/guides/use/use-best-practices-reactivity.md -->

# Best Practices for Reactivity in Screen Flows

Ensure your Lightning web components integrate well within the Flow runtime engine and work as expected for screen flow reactivity.

## State Management and Reactivity

These sections describe state management with reactivity in screen flows, including:

- How LWC state management differs from Aura
- How state management works in the new LWC Flow Runtime
- State management and event best practices to follow when building LWCs for your screen flows

## State Management in Aura vs LWC

State management for Aura components and LWCs follow different paradigms. In Aura components, `<aura:attributes />` are viewed and modified by the component to which they belong, including external components. LWCs are designed to have a clear separation between internal and external states. Variables declared with `@api` are intended to be modified only by the LWC’s parents. Variables without the `@api` annotation and variables with `@track` are considered internal states and can be changed within the LWC that defines them.

## LWC State Management in Screen Flows

The Flow runtime adheres to LWC state management design principles. It works best when the LWC components that it renders do not modify their own `@api` attributes. Instead, components request a change by firing `FlowAttributeChangeEvent`, which is essential for several reasons.

- Components that allow their parents to control their `@api` properties are more easily reused because they allow the application to control the state rather than the component’s own internal business logic.
- By firing attribute change events, the Flow runtime maintains an accurate picture of the component state. The Flow runtime can control inter-component interactions such as conditional field visibility, which is part of reactivity.

Using [LWC linter rules](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md) is an excellent way to ensure that your component does not modify `@api` properties. Set up a linter that uses LWC’s linter rules in your development environment, specifically ensuring that the setting is enforced.

## State Management When the Flow Navigates

To maintain consistent behavior between Flow Runtime versions, when a user clicks the **Next** or **Finish** button, the Flow Runtime collects values by extracting each custom LWC component’s current `@api` attribute state before moving to the next screen or finishing the flow. This mechanism ensures that components that do not adhere to the prescribed design pattern continue to work in the latest Flow Runtime version. It is strongly recommended to avoid relying on this behavior.

Here is an example of a simple text input component that demonstrates firing `FlowAttributeChangeEvent` instead of updating the LWC’s `@api` property:

```javascript
@api textValue;

handleTextInputChange(event) {
  const event = new FlowAttributeChangeEvent('textValue', event.target.value);
  this.dispatchEvent(event);
}
```

The following example isn’t recommended.

```javascript
//Don’t do this
@api textValue;

handleTextInputChange(event) {
  this.textValue = event.target.value;
}
```

## Create a `FlowAttributeChangeEvent` Instance

The `FlowAttributeChangeEvent` event provides LWCs the ability to inform the runtime of their current state. It is part of Flow Runtime’s state management mechanism. These events are meant to be fired whenever user interaction results in a modification that requires an update to an `@api` property.

Import `FlowAttributeChangeEvent` from the `lightning/flowSupport` module.

```javascript
import { FlowAttributeChangeEvent } from "lightning/flowSupport";
```

Next, you can create an instance of the event.

```javascript
const attributeChangeEvent = new FlowAttributeChangeEvent(apiParameterName, updatedValue);
```

`FlowAttributeChangeEvent` includes two arguments.

- `apiParameterName`—The name of the API property to modify.
- `updatedValue`—The updated value for the Flow attribute.

Pass a string to `apiParameterName` that matches the API property as it appears in the JavaScript and `.js-meta.xml` files.

For example, notice how `exampleApiParameterName` is consistent in all 3 places:

- Declare the attribute in the LWC’s `.js-meta.xml` file:

  ```xml
  <property name="exampleApiParameterName" label="Example Api Parameter" .../>
  ```

- Declare the API property in the LWC’s `.js` file:

  ```javascript
  @api exampleApiParameterName;
  ```

- Construct the `FlowAttributeChangeEvent` instance:

  ```javascript
  const changeEvent = new FlowAttributeChangeEvent("exampleApiParameterName", "newValue");
  ```

Pass the `updatedValue` to match the declared datatype in the `.js-meta.xml` file.

- Declare the property as a Record:

  ```javascript
  const changeEvent = new FlowAttributeChangeEvent("exampleApiParameterName", {
    StringFieldName: "stringValue",
    BooleanFieldName: false,
    NumberFieldName: 42,
    DateTimeFieldName: "2022-12-15T23:35:24.000Z",
  });
  ```

- Declare the property as a string:

  ```javascript
  const changeEvent = new FlowAttributeChangeEvent("exampleApiParameterName", "newValue");
  ```

- Declare the property as a number:

  ```javascript
  const changeEvent = new FlowAttributeChangeEvent("exampleApiParameterName", 6);
  ```

- Declare the property as a boolean:

  ```javascript
  const changeEvent = new FlowAttributeChangeEvent("exampleApiParameterName", true);
  ```

## Fire the `FlowAttributeChangeEvent` Event

After constructing a `FlowAttributeChangeEvent` instance, you can fire the event using the `this.dispatchEvent(eventToFire)` method.

```javascript
const attributeChangeEvent = new FlowAttributeChangeEvent("apiPropertyName", 10);
this.dispatchEvent(attributeChangeEvent);
```

## `FlowAttributeChangeEvent` Best Practices

Follow these `FlowAttributeChangeEvent` examples and steer clear of problematic usages to reduce unexpected behaviors after a flow version upgrade. These best practices enable you to maintain your components more easily.

- Fire events in event handlers or in methods invoked within event handlers.
- Limit an event’s value parameter to the following datatypes: String, number, boolean, JSON (for record types).
- Ensure that the Flow datatype of the event’s value parameter matches the datatype of the LWC’s `@api` property.
- React to changes to `@api` properties by using a get/set pattern where appropriate.

This example demonstrates using a getter and setter to count the updates with an `@api` property vs. incrementing a counter before firing an attribute change event. Both patterns are valid, but they achieve slightly different results.

```javascript
@api textValue;
textValueToRender;
changeCounter = 0;

get textValue() {
  return this.textValueToRender;
}

// Due to the nature of the Flow Runtime, this setter method
// is called after the FlowAttributeChangeEvent fired below. It also
// is invoked when reactivity leads to a change to the textValue property.
set textValue(newTextValue) {
  this.changeCounter++;
  this.textValueToRender = newTextValue;
}

handleTextInputChange(event) {
  const event = new FlowAttributeChangeEvent('textValue', event.target.value);
  this.dispatchEvent(event);
}
```

In this case, `this.changeCounter` is incremented whenever the user enters a change in the text input and whenever the Flow Runtime determines that the `textValue` property has changed. This approach accounts for component initialization and cross-component interactions via reactivity. Use an intermediate variable to render updates from the set method. In this example, `textValueToRender` fills this role.

The following code example increments a counter before firing an attribute change event. This scenario doesn’t use the get/set pattern.

```javascript
@api textValue;
changeCounter = 0;

handleTextInputChange(event) {
  this.changeCounter++;
  const event = new FlowAttributeChangeEvent('textValue', event.target.value);
  this.dispatchEvent(event);
}
```

In this case, `this.changeCounter` is incremented whenever the user inputs a change in the text input. The counter does not update when reactivity changes the value of this field.

Use annotationless or `@track` properties to maintain a modifiable local component state.

The following example shows a color picker that presents the user with an input text box and some swatches. The color picker component returns `color` to the flow, so only `color` needs the `@api` annotation. The `selectedSwatchId` and `inputValue` members are internal only and do not need any decorator.

```javascript
//colorPicker.js

@api color;

inputValue;
selectedSwatchId;


ALL_SWATCHES =[{
  'id': 1,
  'color': 'red'
}, {
  'id': 2,
  'color': 'blue'
}, {
  'id': 3,
  'color': 'green'
}, {
  'id': 4,
  'color': 'yellow'
}];

set color(newColor) {
  // Set the content of the input text to the color value:
  this.inputValue = newColor;

  // If the color matches a swatch, highlight it in the UI:
  const foundSwatch = this.ALL_SWATCHES.find(swatch => swatch.color === newColor);
  this.selectedSwatchId = foundSwatch && foundSwatch.id;
}

get color() {
  return this.inputValue;
}

handleSwatchSelected(event) {
  // Select get the swatch data for the clicked swatch:
  const selectedSwatch = this.ALL_SWATCHES.find(swatch => swatch.id === event.target.dataset.id);
  const changeEvent = new FlowAttributeChangeEvent('color', selectedSwatch.color);
  this.dispatchEvent(changeEvent);
}

handleInputValueChange(event) {
  this.inputValue = event.target.value;
  const changeEvent = new FlowAttributeChangeEvent('color', this.inputValue);
  this.dispatchEvent(changeEvent);
}
```

Use a get method to combine multiple `@api` properties together to construct a derived variable for the view.

```javascript
//Salutation.js
@api firstName;
@api lastName;
@api ageName;

get salutation() {
  return `Hello ${this.firstName} ${this.lastName}, you are ${this.age} years old.`;
}
```

<!-- prettier-ignore -->
```html
<!-- Salutation.html -->
<template>
  <div>{salutation}</div>
</template>
```

Apply the same logic in the set method of every `@api` property that contributes to a derived member variable needed for internal component state management, as in more complex scenarios than the previous example. This logic ensures that a change made to any contributing attribute causes the value to render correctly regardless of the order of the set attributes.

```javascript
//Dropdown.js
set optionLabels(newOptionLabels) {
  this.internalOptionLabels = newOptionLabels;
  this.options = this.computeOptions();
}

set optionValues(newOptionValues) {
  this.internalOptionValues = newOptionValues;
  this.options = this.computeOptions();
}

set value(newValue) {
  this.internalValue = newValue;
  this.options = this.computeOptions();
}

handleSelect(event) {
  const selectedValue = event.srcElement.value;
  const isAlreadySelected = this.options.some(option => {
    return option.isSelected && option.value === selectedValue;
  });

  if (!isAlreadySelected) {
    const attributeChange = new FlowAttributeChangeEvent('value', selectedValue);
    this.dispatchEvent(attributeChange);
  }
}

computeOptions() {
  if (this.internalOptionLabels.length !== this.internalOptionValues.length) {
    return [];
  }

  return this.internalOptionLabels.map((label, index) ==> {
    const value = this.internalOptionValues[index];
    const isSelected = this.internalValue === value;
    return {
      label,
      value,
      isSelected
    };
  });
}
```

Don’t modify `@api` properties. Fire `FlowAttributeChangeEvents` instead.

Don’t modify `FlowAttributeChangeEvent` parameters after construction. By default, `FlowAttributeChangeEvent` instances are composed and bubble.

```javascript
const changeEvent = new FlowAttributeChangeEvent("prop", "value");
changeEvent.bubbles = false; // Don’t do this
changeEvent.composed = false; // Don’t do this
```

Avoid firing `FlowAttributeChangeEvents` and `FlowNavigationXxx` events at the same time as it can lead to race conditions. There's never a guarantee that your Lightning web component has had time to render the updated values by the time the navigation process is started.

## Derived Attribute Best Practices

In a flow component, a _derived_ attribute is an attribute whose value is determined by other attributes of the same component. The value may be tied to one or more other attributes. For example, the `firstSelectedRow` parameter of the Data Table component is a derived attribute because its value is determined by the value of the `selectedRows` attribute. Specifically, the value of the `firstSelectedRow` parameter is the value of the first element of the `selectedRows` attribute.

When you create a flow screen component that includes a derived attribute, follow the best practices outlined here to ensure that the component functions properly within the reactivity framework. With these best practices, you can avoid issues related to:

### Reactivity Chaining

A reactivity chain occurs when a change to an attribute of one component results in a cascade of changes to attributes of other components. For example, a user selects a row in a Data Table component, which changes the value of the `firstSelectedRow` attribute of the component, which changes the `firstName` attribute of a Name component. The change to the Name component changes the `value` attribute of a Text component.

### Preserving Values on Revisited Screens

When an admin configures a screen, you choose whether the flow preserves user-specified values when the user leaves and then returns to the screen using the Previous or Next button.

To ensure that derived attributes behave as expected in flow screens with reactive components, follow these guidelines:

1. **Do** fire a `FlowAttributeChangeEvent` event for the derived attribute in the `set` method of the attribute that drives the change. Also fire a `FlowAttributeChangeEvent` event for the derived attribute in the `connectedCallback` method of the component, for example:

   ```java

      // 'Driving' attribute set method
      set stringToCount(newStringToCount) {
          this._stringToCount = newStringToCount;
          // Fire an event for 'derived' attribute
          const lengthChangeEvent = new FlowAttributeChangeEvent('stringLength', this._stringToCount.length);
          this.dispatchEvent(lengthChangeEvent);
      }
      connectedCallback() {
      // Fire an event for 'derived' attribute here as well
      const lengthChangeEvent = new FlowAttributeChangeEvent('stringLength', this._stringToCount.length);
      this.dispatchEvent(lengthChangeEvent);
      }
   ```

2. **Don't** omit the `FlowAttributeChangeEvent` event in the `connectedCallback` method.
   You must include the `FlowAttributeChangeEvent` event in two locations. When the flow executes the `FlowAttributeChangeEvent` in the `set` method of the attribute that drives the change, the component isn't in the DOM and the event essentially goes nowhere. Adding the event in the `connectedCallback` method ensures that when the flow adds the component to the DOM, the flow runtime can consume the event.

3. **Don't** omit the `FlowAttributeChangeEvent` event in the `set` method.
   Firing the `FlowAttributeChangeEvent` in the `set` method of the attribute that drives the change ensures that changes are applied to both the attribute that drives the change and the derived attribute. Consequently, reactivity chains that include a custom component function properly.

4. **Don't** omit the `connectedCallback` method by using `Promise.resolve().then(...)` to delay firing the `FlowAttributeChangeEvent` inside the `set` method.
   Delaying the `FlowAttributeChangeEvent` ensures that the component is in the DOM when the flow first calls the `set` method. However, the delay also means that the component fires the event after the flow initializes the screen. Consequently, the flow runtime always overrides preserved values and overrules the setting for revisited value.

   ```java

    set stringToCount(newStringToCount) {
    this._stringToCount = newStringToCount;
    const lengthChangeEvent = new FlowAttributeChangeEvent('stringLength', this._stringToCount.length);
    // This code overwrites preserved values. Don't do this.
    Promise.resolve().then(() => {
        this.dispatchEvent(lengthChangeEvent);
    });
    }
   ```

## Navigation Events

To control navigation programmatically from a screen component, including checking which navigation actions are available, see [Control Navigation in Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-screen-navigate.md).

<!-- document id=e04b9ab749a264d805b44f3f1825a3474154961aa7979e006644a374afa2f798 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-managers-design.md -->

# Best Practices for State Manager Design

State managers introduce a new approach for pro-code developers to interact with data. State manager composition provides an ideal abstraction for accessing platform data and metadata. The optimal use of state managers, both built-in and your own, is to compose a page- or app-level system of data access. That is, build an [API module component](https://developer.salesforce.com/docs/platform/js/js-share-code.md) that can retrieve and update all of the data needed by the app or page. This abstracts data access into the module, so that your app's components can concentrate on showing the data, user interaction, and other presentation-level concerns.

**note:** These design guidelines are brief. More documentation is in the works.

An example of building a complex state manager for use on a record home-style page is available in [Nested State Manager Example](https://developer.salesforce.com/docs/platform/state-management/state-management-example-nested.md). This state manager is designed to be used at the page level, consolidating the data retrieval and metadata parsing required.

If you're building a standalone component for use in many contexts, [`@wire` adapters](https://developer.salesforce.com/docs/platform/data/data-wire-service.md) are often simpler.

**See Also**

- [Nested State Manager Example](https://developer.salesforce.com/docs/platform/state-management/state-management-example-nested.md)
- [Example: Use a Built-in State Manager](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use-example.md)
- _LWC Recipes:_ [Opportunities State Manager](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/opportunitiesStateManager)
- [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/platform/data/data-wire-service.md)
- [Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-ui-api.md)

<!-- document id=22ad99da1836232af02e5a783e25eef9a105ee96679ea6f2d765856b90123a8f url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-getter.md -->

# Bind Data in a Template

Bind data using a property in a component’s template to a property in the component’s JavaScript class.

In the template, surround the property with curly braces without spaces: `{property}`. To compute a value for the property, use a JavaScript getter in the JavaScript class, `get` _`property`_`(){}`. In the template, the _`property`_ can be a JavaScript identifier (for example, `person`) or dot notation that accesses a property from an object (`person.firstName`). LWC doesn’t allow computed expressions like `person[2].name['John']`.

A property used in a template should contain a primitive value, except when used in a [`for:each`](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md) or [`iterator`](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md) directive.

## Example: Bind Component Template Properties to JavaScript Properties

To follow along in a code editor, open the `hello`, `helloBinding`, and `helloExpressions` components from the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. You can also copy the code to [a StackBlitz LWC playground](https://playground.lwc.dev).

Here’s the simplest example of data binding. The `greeting` property in the template is bound to the `greeting` property in the JavaScript class.

```html
<!-- hello.html -->
<template> Hello, {greeting}! </template>
```

```javascript
// hello.js
import { LightningElement } from "lwc";

export default class Hello extends LightningElement {
  greeting = "World";
}
```

The property in `{ }` must be a valid JavaScript identifier or member expression. For example, `{data}` and `{data.name}` are both valid. Don’t add spaces around the property, for example, `{ data }` is not valid HTML.

Instead of a hard-coded string, this component has an input field that asks for a name to greet.

The `lightning-input` field uses the `onchange` attribute to listen for a change to its value. When the value changes, the `handleChange` function in the JavaScript file executes. Notice that to bind the `handleChange` function to the template, we use the same syntax, `{handleChange}`

<!-- prettier-ignore -->
```html
<!-- helloBinding.html -->
<template>
  <p>Hello, {greeting}!</p>
  <lightning-input label="Name" value={greeting} onchange={handleChange}></lightning-input>
</template>
```

We talk about event handling in-depth in another [topic](https://developer.salesforce.com/docs/platform/lwc/events/events.md), but notice in the JavaScript class that `handleChange` is passed an `event` object. The `event` object contains information about the change event. The component uses the `event` object to get the value that the user entered into the input field.

```javascript
// helloBinding.js
import { LightningElement } from "lwc";

export default class HelloBinding extends LightningElement {
  greeting = "World";

  handleChange(event) {
    this.greeting = event.target.value;
  }
}
```

Most of this code is standard HTML and JavaScript.

**note:** When a component rerenders, the expressions used in the template are reevaluated.

## Use Getters Instead of Expressions

To compute a value for a property, use a [JavaScript getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get). For example, to convert the name to all uppercase letters, use a getter function in the JavaScript class, not an expression in the template.

Getters are much more powerful than expressions because they’re JavaScript functions. Getters also enable unit testing, which reduces bugs and increases fun.

Define a getter that computes the value in your JavaScript class.

```javascript
get propertyName() { ... }
```

Access the getter from the template.

<!-- prettier-ignore -->
```javascript
{ propertyName }
```

In this example, a user enters their first and last name. A JavaScript getter computes a new value, `uppercasedFullName`, and the template renders it: **DEANNA LI**.

The `uppercasedFullName` property in the template is bound to the `get uppercasedFullName()` getter in the JavaScript class.

<!-- prettier-ignore -->
```html
<!-- helloExpressions.html -->
<template>
  <div class="slds-m-around_medium">
    <lightning-input
      name="firstName"
      label="First Name"
      onchange={handleChange}
    ></lightning-input>
    <lightning-input name="lastName" label="Last Name" onchange={handleChange}></lightning-input>
    <p class="slds-m-top_medium">Uppercased Full Name: {uppercasedFullName}</p>
  </div>
</template>
```

The `handleChange` function sets the `firstName` and `lastName` properties to the values that the user enters. The `uppercasedFullName()` getter combines and uppercases the names.

```javascript
// helloExpressions.js
import { LightningElement } from "lwc";

export default class HelloExpressions extends LightningElement {
  firstName = "";
  lastName = "";

  handleChange(event) {
    const field = event.target.name;
    if (field === "firstName") {
      this.firstName = event.target.value;
    } else if (field === "lastName") {
      this.lastName = event.target.value;
    }
  }

  get uppercasedFullName() {
    return `${this.firstName} ${this.lastName}`.toUpperCase();
  }
}
```

**tip:** All fields are reactive. If the field is used in a template, or indirectly in a getter of a property that’s used in a template, the component rerenders when the property's value changes. In this example, when `firstName` and `lastName` change, the template rerenders because they’re used in the `uppercasedFullName` getter, and that property is used in a template. See [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md).

**See Also**

- [Set Properties on Child Components](https://developer.salesforce.com/docs/platform/lwc/create/create-components-data-binding.md)
- [Fields, Properties, and Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-intro.md)
- [Reactivity](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md)

<!-- document id=d0ee38deb24b0f454e77b39af209bf93beb00b96fdec9137cec5592ea1b4c376 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-class-binding.md -->

# Bind HTML Classes

| AVAILABLE API VERSIONS               |
| ------------------------------------ |
| Available in LWC API v62.0 and later |

Manipulate a component or an element's class list easily using its `class` attribute. You can use class object binding instead of string concatenation to generate complex class names.

Here's an example that evaluates multiple classes on an element.

<!-- prettier-ignore -->
```html
<template>
  <h1>Class Object Binding Demo</h1>
  <div class={computedClassNames}>Evaluate some classes here</div>
</template>
```

Pass in your class object to the getter.

```javascript
import { LightningElement } from "lwc";

export default class extends LightningElement {
  position = "left";
  fullWidth = true;
  hidden = false;

  get computedClassNames() {
    return [
      "div__block",
      this.position && `div_${this.position}`,
      {
        "div_full-width": this.fullWidth,
        hidden: this.hidden,
      },
    ];
  }
}
```

Your element renders like this.

```html
<div class="div__block div_left div_full-width">Evaluate some classes here</div>
```

## Class Binding Considerations

In LWC API v62.0 and later, use an array or an object to bind multiple styles to an element's `class` attribute.

- An array is evaluated based on its individual items based on class object binding semantics. For example, if you pass in `["highlight", "yellow"]`, the element renders `class="highlight yellow"`.
- An object is evaluated based on class object binding semantics. LWC iterates over the enumerable string properties on the object, excluding symbols and properties on the proto-chain. It applies the classes with the keys associated with a truthy value. For example, if you pass in `{ highlight: true, hidden: false }`, the element renders `class="highlight"`.

In LWC API v62.0 and later, booleans, numbers, and functions are removed instead of converted to a string. For example, if you pass in `true`, `false`, or `10`, the element renders `class=""`. LWC ignores all other values, like primitive and complex objects.

To render a boolean or numerical value as a string, such as `class="false"` or `class="1"`, convert the value to a string using `String(value)`.

**note:** Before LWC API v62.0（equivalent to LWC OSS v7.0.0), the `class` attribute rendered booleans, numbers, functions, arrays, and objects differently. See [_LWC v7.0.0_: Class object binding](https://github.com/salesforce/lwc/releases/tag/v7.0.0#class-object-binding).

## Class Binding Examples

These examples show the differences between LWC API v62.0 and previous versions.

| Type     | Example                                                 | Output in LWC API v62.0        | Output in LWC API v61.0                   |
| -------- | ------------------------------------------------------- | ------------------------------ | ----------------------------------------- |
| String   | `"note highlight"`                                      | `class="note highlight"`       | `class="note highlight"`                  |
| Boolean  | false                                                   | `class=""`                     | `class="false"`                           |
| Number   | 10                                                      | `class=""`                     | `class="10"`                              |
| Function | `() => {}`                                              | `class=""`                     | `class="() => {}"`                        |
| Array    | `["note", "highlight"]`                                 | `class="note highlight"`       | `class="note,highlight"`                  |
|          | `[false, 'note', null]`                                 | `class="note"`                 | `class="false,note,"`                     |
|          | `['block', { note: true }, ['highlight']]`              | `class="block note highlight"` | `class="block,[object Object],highlight"` |
| Object   | `{block: true, hidden: false, 'note highlight': true }` | `class="block note highlight"` | `class="[object Object]"`                 |

**See Also**

- [Bind Inline Styles](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-style-binding.md)
- [Anti-Patterns for Component Styling](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-antipatterns.md)

<!-- document id=c8a5d23be29c4f7afd40e6d598afb3d6ca1cf9427faf2502d843e8ce70147224 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-style-binding.md -->

# Bind Inline Styles

Append a class or multiple classes on an element or component using its [`style` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style).

<!-- prettier-ignore -->
```html
<div class="block" style={inlineStyles}></div>
```

This example uses a [getter](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getters-setters.md) to set inline styles on an element. To provide multiple styles, separate the styles using a semi-colon. Also, use standard kebab-cased CSS property keys like `font-size`.

```javascript
import { LightningElement } from "lwc";

export default class extends LightningElement {
  percentage = 80;

  get inlineStyles() {
    return `width: ${this.percentage}%; font-size: 20px`;
  }
}
```

When binding inline styles, follow the [`style` global attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style) guidelines. Consider using the `class` attribute with a stylesheet in your component bundle for reusability first. Using inline styles can be helpful when you need to compute properties to generate different styles based on a condition. For example, this function appends a background color that depends on the value `this.iconName`.

```javascript
get computedStyles() {
    if (this.iconName) {
        const color = getIconColor(this.iconName);
        if (color) {
            return `background-color: ${color}`;
        }
    }
    const fallbackColor = '#eee';
    return `background-color: ${fallbackColor}`;
}
```

Here's an example that uses an input field to change the size of a chart bar with an inline style. The `c-input` parent component assigns the `percentage` property based on user input. It uses the property to pass a value down to the child `c-chart` component. The child component evaluates the inline style based on the value that's passed down.

<!-- prettier-ignore -->
```html
<!-- c-input -->
<template>
    <div>
        Percentage:
        <input
            type="number"
            min="0"
            max="100"
            value={percentage}
            onchange={handlePercentageChange}
        ></input>
        <c-chart percentage={percentage}></c-chart>
    </div>
</template>
```

When the number in the input field changes, the `handlePercentageChange` event handler assigns the new value to `this.percentage`.

```javascript
// c-input
import { LightningElement } from "lwc";

export default class Input extends LightningElement {
  percentage = 50;

  handlePercentageChange(event) {
    const percentage = event.target.value;
    this.percentage = percentage <= 100 ? percentage : 100;
  }
}
```

The `c-chart` child component displays the `percentage` value, which is passed down from `c-input`.

<!-- prettier-ignore -->
```html
<!-- c-chart -->
<template>
    <div class="container">
        <div class="text">{percentage}%</div>
        <div class="bar" style={style}></div>
    </div>
</template>
```

`c-chart` evaluates the inline styles based on the `percentage` property.

```javascript
// c-chart
import { LightningElement, api } from "lwc";

export default class ChartBar extends LightningElement {
  @api percentage;

  get style() {
    return `width: ${this.percentage}%`;
  }
}
```

**See Also**

- [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css.md)
- [Share CSS Style Rules](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-share.md)
- [Anti-Patterns for Component Styling](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-antipatterns.md)

<!-- document id=5ac953c830923bb39230b48d609334b7183986b3b55e829eaf547db702589e04 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice.md -->

# BiometricsService API

Access a device’s biometrics capabilities from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how BiometricsService works, see [Access a Mobile Device’s Biometrics Capabilities](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice.htm).

<!-- document id=628c9f1e6644886e7a29a9c0caaf5c9fc65260a06085d593fad44cafe61bb125 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-constants.md -->

# BiometricsService Constants

BiometricsService defines and uses several constants. Each of the following constants enumerate the accepted string values for the associated properties.

## Constant Values

All of the following constants are available as properties on an instance of `BiometricsService`.

| Constant Name             | Accepted Value | Description                                                                                                       |
| ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `BiometricsServicePolicy` | "PIN_CODE”     | PIN_CODE instructs BiometricsService to fallback using pin code if biometrics is not available or not configured. |

## `BiometricsServiceFailureCode`

Correlates with the `code` property on the `BiometricsServiceFailure` object.

| Accepted Value           | Description                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| "HARDWARE_NOT_AVAILABLE" | There is no fingerprint scanner or face recognition hardware found.                                                                                                |
| "NOT_CONFIGURED"         | Biometrics hardware was found but has not been set up yet.                                                                                                         |
| "SERVICE_NOT_ENABLED"    | BiometricsService is not enabled and cannot be used.                                                                                                               |
| "UNKNOWN_REASON"         | An error occurred in the native code that isn’t related to permissions or hardware issues. More information is provided in the `BiometricsServiceFailure` message. |

<!-- document id=94e7cee4ad265901faadca97cb5567fbe44f236cd5e67ac399c93607d9708955 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-data-types.md -->

# BiometricsService Data Types

BiometricsService defines and uses several data types.

## `BiometricsServiceOptions`

An object for specifying which instances of a recurring event are affected by an update to or deletion of one instance of the event.

| Property Name                 | Type                               | Description                                                                                                |
| ----------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `permissionRequestBody`       | String                             | Reason to use biometrics scanner.                                                                          |
| `permissionRequestTitle`      | String                             | Title used in the dialog when the reason text is displayed. Allowed on iOS, but effective only on Android. |
| `additionalSupportedPolicies` | Array of `BiometricsServicePolicy` | Policies specified in the array allows customization of the biometrics scan behavior.                      |

## `BiometricsServiceFailure`

An object representing an error that occurred when accessing BiometricsService features.

| Property Name | Type                           | Description                                                                                                                                                                             |
| ------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `BiometricsServiceFailureCode` | A value representing the reason for a biometrics service error. See [BiometricsServiceFailureCode](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-biometricsservice-constants.md) for the list of possible values. |
| `message`     | String                         | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.                |

<!-- document id=dc61a872a3593f419595c17f64adc2445a2692d92c6b009c314cd37416581e85 url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-boolean.md -->

# Boolean Properties

Boolean attributes on standard HTML Elements are set to `true` by adding the attribute to the element. The absence of the attribute defaults the attribute to `false`. Therefore, the default value of an attribute is always `false`. Lightning web components use the same principle for boolean properties.

## Set a Property Statically

Always set the default value for a boolean public property to `false`. If you set the default value to `true` instead in `bool.js`, there’s no way to statically toggle the value to `false` in markup.

```javascript
// bool.js
import { LightningElement, api } from "lwc";

export default class Bool extends LightningElement {
  @api show = false;
}
```

Here’s the HTML file.

```html
<!-- bool.html -->
<template>
  <p>show value: {show}</p>
</template>
```

The parent component includes `c-bool`, which displays the default value of `false` because the `show` attribute isn’t added to `<c-bool>`.

**important:** The only way to specify `false` in markup is to omit the boolean attribute. Setting `show="false"` in markup evaluates to `true`.

```html
<!-- parent.html -->
<template>
  <c-bool></c-bool>
</template>
```

To set the `show` property to `true`, add a `show` attribute with an empty value to the markup. This version of `c-parent` displays a value for `true` for the `show` property.

```html
<!-- parent.html -->
<template>
  <c-bool show></c-bool>
</template>
```

The value of `show` is `true`, but a `show` attribute isn’t reflected in the rendered HTML unless you explicitly reflect it by calling `setAttribute`. See [Reflect JavaScript Properties to HTML Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-html-attributes.md).

**note:** When a boolean attribute’s value is `true`, the rendered HTML is `<my-component my-attribute>`.

## Set a Property Dynamically

To toggle the value dynamically, pass down a dynamic computed value from the parent component. For example:

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <c-bool show={computedValue}></c-bool>
</template>
```

Use a JavaScript getter in `parent.js` to return the value of `{computedValue}`.

**See Also**

- [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md)

<!-- document id=a9f751bb6bffa04b247b59bf682fa36843e687e55b5d0b513172e51b732ff5dd url=/developer/current/en-us/lwc/utam/guide/browser-extension.md -->

# Browser Extension

When you write a test for a Salesforce application page, it's often confusing to know which page objects (POs) to use. To make this page object selection process easier, use UTAM's browser extension for Google Chrome. It presents you with the appropriate set of POs for the page that you're currently browsing, and identifies which page elements are affected by the methods in a selected PO.

Here's a quick introduction to the browser extension.

::video{src="https://developer.salesforce.com/docs/platform/utam/guide/zwsMXEU8Lv6ytiKhatYcKk" title="UTAM Browser Extension Video Intro" type="vidyard"}

## Workflow for Browser Extension

This section shows you how to use the browser extension.

### Step 1: Install Browser Extension

Install the [UTAM Browser Extension](https://chrome.google.com/webstore/detail/utam/llgodnekeleaidcljgfljjechnjdgnli "Chrome Web Store") from the Chrome Web Store.

After installation, you can see the extension in your browser's toolbar.

![UTAM browser extension in the toolbar](https://developer.salesforce.com/docs/media/utam/browser_extension.png)

### Step 2: Download Page Object Artifact

The browser extension reads UTAM POs contained in an artifact downloaded from an artifact repository. An artifact is either a zip file (`.zip`, `.jar`) or a gzipped tar file (`.tar.gz`, `.tgz`).

**important:** The browser extension doesn't automatically download these artifacts. Before you can use the browser extension, you must obtain an artifact as a prerequisite step.

Get UTAM POs from an artifact published to [Maven Central Repository](https://mvnrepository.com/repos/central) or [NPM](https://www.npmjs.com/).

To get the artifact for JavaScript page objects, run this command from the command line:

```bash
npm pack salesforce-pageobjects
```

This command downloads a gzipped tar file of the artifact to the current directory.

For more information about the PO artifacts for Java and JavaScript, see [Downloads](https://developer.salesforce.com/docs/platform/utam/guide/downloads.md#downloads).

### Step 3: Load Page Objects into the Browser Extension

After you install the browser extension, load the page objects that you previously downloaded in the artifact.

1. Navigate to a Salesforce page.
2. In Chrome, click **View > Developer > Developer Tools** and click the **UTAM** subtab in the Developer Tools pane.
3. To import the POs from the downloaded artifact, click the **Import** button.
   ![Import POs from the artifact](https://developer.salesforce.com/docs/media/utam/browser_extension_import.png)

Navigate to the PO artifact that you downloaded earlier and click **Open**.

### Step 4: Identify Page Objects for a Web Page

To use the browser extension on a page to be tested, you must identify a root page object:

1. In the UTAM tab, click **Find**.
   ![Find root page object](https://developer.salesforce.com/docs/media/utam/browser_extension_find_root.png)

2. You see a tree list of POs that you can navigate to find methods of interest for your test.
   ![Tree list of page objects](https://developer.salesforce.com/docs/media/utam/browser_extension_po_tree.png)

3. Hover over a PO in the list to see an outline in the browser window for the element represented by the PO.

4. Click the `>` icon at the beginning of a PO name to see the methods available for the PO.

5. If a method takes an argument, you can use the **Add arguments** input on the right side of the panel to enter an argument value. In this example, we select `getActionRendererWithTitle(text)`.
   ![Select a PO method](https://developer.salesforce.com/docs/media/utam/browser_extension_po_method.png)

6. Enter _New Contact_ in the **Add Arguments** input and click **Apply** to highlight the **New Contact** button in the Account header.
   ![Hover over a method](https://developer.salesforce.com/docs/media/utam/browser_extension_po_method_arg.png)

7. After you've selected all the methods of interest, select Java or JavaScript in the Code Output dropdown and click the **Copy Generated Code** button. The code to access the selected PO methods is copied to the clipboard.
   ![Copy the selected code](https://developer.salesforce.com/docs/media/utam/browser_extension_copy_code.png)

8. Paste the code into a UTAM test in your IDE of choice. In this example, the copied Java code is:

```java
loader.load(RecordHomeTemplateDesktop.class)
    .getHighlights()
    .getActions()
    .getActionRendererWithTitle("New Contact");
```

## Import a New Page Object Artifact

The **Settings** subtab in the UTAM panel shows you the current version of the page object artifacts that you're using.

![Hover over a method](https://developer.salesforce.com/docs/media/utam/browser_extension.png)

You can import one or more page object artifacts, which means that you can import your own custom page object artifacts as well as the page object artifact provided by Salesforce.

To import a new page object artifact, click **Import new artifact**. To remove a page object artifact, click the `X` button in the upper
right-hand corner of the artifact tile. To remove all page object artifacts, click **Clear all imported artifacts**.

On the Settings page, you can also choose Java or JavaScript as the default code output to use when you **Copy Generated Code** to the clipboard.
Also on the Settings page, you can customize the format of the highlighter used to highlight elements when selecting page objects in the tree of
the Actions page.

## Terms of Use

These Terms of Use are a binding agreement between you and Salesforce, Inc. (“Salesforce”). Please read them carefully. We may make changes at any time, so be sure to check back regularly. By continuing to use the browser extension after these Terms have changed, you indicate your agreement to the revised Terms. If you do not agree to the changes, you should stop using the browser extension.

**Proprietary Rights.** Salesforce grants to you a revocable, non-exclusive, non-transferable, limited, and personal right (without the right to authorize any third party) to use the browser extension, solely in accordance with any applicable documentation and any additional terms made available by Salesforce. You may not, without Salesforce’s prior written consent, access or use the browser extension to commercially distribute your product or service to third parties unless you are authorized to do so pursuant to a separate agreement with Salesforce.

**Relationship to Salesforce Services.** Any main services agreement you or your organization may have with Salesforce does not apply to use of the browser extension, and the browser extension is not licensed or otherwise provided under such agreement. In addition, any use of the browser extension in connection with any Salesforce services provided under a main services agreement is subject to the restrictions of such main services agreement.

In the event the browser extension includes free or open source software projects that are subject to license terms incompatible with each other, and/or incompatible with your obligations under a main services agreement or another agreement, you are responsible for complying with (a) any main services agreement governing Salesforce services to which you subscribe, and (b) any terms applicable to code or applications you use in connection with such Salesforce services.

**Privacy.** Salesforce may collect, process, and store device, system, and other information related to your use of the browser extension. Such information may contain Personal Data, which is handled as described in our Privacy Statement at https://www.salesforce.com/company/privacy/.

**Disclaimer.** SALESFORCE MAKES NO REPRESENTATIONS, WARRANTIES, OR CONDITIONS OF ANY KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SALESFORCE SPECIFICALLY DISCLAIMS ALL REPRESENTATIONS, WARRANTIES, AND CONDITIONS, WHETHER EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, TO THE MAXIMUM EXTENT PERMITTED UNDER APPLICABLE LAW. THE BROWSER EXTENSION IS MADE AVAILABLE ON AN “AS IS,” “WHERE IS,” AND “WHERE AVAILABLE” BASIS, EXCLUSIVE OF ANY WARRANTY WHATSOEVER. SALESFORCE HAS NO OBLIGATION TO PROVIDE ANY SUPPORT OR MAINTENANCE SERVICES FOR THE BROWSER EXTENSION.

**Limitation of Liability.** SALESFORCE WILL NOT HAVE ANY LIABILITY ARISING OUT OF OR RELATED TO USE OF THE BROWSER EXTENSION, WHETHER AN ACTION IS IN CONTRACT OR TORT, REGARDLESS OF THE THEORY OF LIABILITY, AND EVEN IF SALESFORCE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR IF A REMEDY OTHERWISE FAILS OF ITS ESSENTIAL PURPOSE. THE FOREGOING DISCLAIMER WILL NOT APPLY TO THE EXTENT PROHIBITED BY LAW.

**Governing Law and Jurisdiction.** These Terms will be governed by and construed in accordance with the laws of the state of California and controlling United States federal law, without regard to choice or conflicts of law rules or the United Nations Convention on the International Sale of Goods. You agree to the exclusive jurisdiction of the state and federal courts located in San Francisco, California, submit to the personal jurisdiction of such courts, and waive any defense based on venue or inconvenient forum.

**Last Updated**: March 30, 2023

<!-- document id=d3b76170e61a8709801e760418ddfe60a3c260de5594b7f1fe03e24051ca52e8 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-screen-generic-types.md -->

# Build a Flow Screen Component for Multiple Objects

You can build a single flow screen component that works with any sObject, instead of building one component per object. For example, you can build one data table component and reuse it in flows that operate on accounts, contacts, cases, or any other object. With Flow Builder, admins can pick the object type when they add the component to a screen.

To enable multiple objects on a component, declare a generic type in the component's configuration file using the `propertyType` subtag. Properties that reference the generic type then accept the concrete object type the admin selects at flow design time.

## Declare a Generic Type

In the component's `.js-meta.xml` file, add a `propertyType` subtag inside the `targetConfig` for `lightning__FlowScreen`. The `propertyType` tag declares the named type that `property` tags can reference.

| Attribute     | Required | Description                                                                                                                                        |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Yes      | The identifier for the generic type. Use this name, wrapped in curly braces, as the `type` value of any property that should use the generic type. |
| `extends`     | Yes      | The base type the generic type extends. Must be `SObject`. Generic Object is not supported.                                                        |
| `label`       | No       | The label for the type in the Flow Builder **Object Type** field. Defaults to the `name` value if omitted.                                         |
| `description` | No       | The description shown in the Flow Builder **Object Type** field for this type. Use it to help admins understand what kind of object to select.     |

```xml
<!-- dataTable.js-meta.xml -->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>68.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__FlowScreen</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__FlowScreen">
      <propertyType
        name="T"
        extends="SObject"
        label="Object"
        description="Select the object whose records you want to display in this table."
      />
      <property name="records" type="{T[]}" label="Records" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

## Reference the Generic Type in Properties

In the same `targetConfig`, reference the generic type by name in curly braces as the `type` value of any `property` subtag. Use `{T}` for a single sObject and `{T[]}` for a collection.

```xml
<!-- Single record -->
<property name="selectedRecord" type="{T}" label="Selected Record" />

<!-- Collection of records -->
<property name="records" type="{T[]}" label="Records" />
```

In the component's JavaScript file, declare matching `@api` properties.

```javascript
// dataTable.js
import { LightningElement, api } from "lwc";

export default class DataTable extends LightningElement {
  @api records = [];
}
```

## Share a Generic Type Across Multiple Properties

If you declare multiple properties that all use the same `propertyType`, the admin maps the type once and all properties share the same concrete object. For example, a component that accepts both an input record and produces an output record can use the same type for both.

```xml
<!-- dataTable.js-meta.xml (excerpt) -->
<propertyType
  name="T"
  extends="SObject"
  label="Object"
  description="Select the object for this component."
/>
<property name="inputRecord"  type="{T}" role="inputOnly"  label="Input Record" />
<property name="outputRecord" type="{T}" role="outputOnly" label="Output Record" />
```

Because both properties reference the same `propertyType`, the admin selects the object only once. All properties that reference `{T}` remain in sync. This is an advantage over using Apex generic sObjects in flows, where each parameter must be mapped to a concrete object independently.

## Add the Component to a Flow Screen in Flow Builder

1. Open your screen flow in Flow Builder.
2. On a screen element, add the generic-type component.
3. In the component's property panel, locate the **Object Type** control. Select the sObject that this instance of the component should work with.
4. After you select the object, the component's properties that reference the generic type update to accept values of the selected type. Map each property to the appropriate flow variable.

## Custom Property Editors for Advanced Type Mapping

For most use cases, Flow Builder's built-in **Object Type** control is sufficient. For a more customized type-mapping experience, build a custom property editor and register it using the `configurationEditor` attribute on the `targetConfig` tag. For example, you can restrict which objects the admin can select, or show additional context alongside the picker.

For a complete example, see [Generic SObject Input for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-sobject-lwc-example.md).

**See Also**

- [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens.md)
- [Control Navigation in Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-screen-navigate.md)
- [Display Flow Stages in a Flow Screen Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-screen-stages.md)
- [Generic SObject Input for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-sobject-lwc-example.md)
- [Runtime Considerations for Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-runtime-considerations.md)

<!-- document id=f243d4b2d628191a87805742129686a880ccdebfee5d180c09bf4d78586e1b4a url=/developer/current/en-us/lwc/lwc/guides/create/create-mixed-shadow.md -->

# Build Components in Mixed Shadow Mode (Beta)

Mixed shadow mode enables a component to use native shadow DOM, even when the synthetic shadow polyfill is applied.

**note:** This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at [Agreements and Terms](https://www.salesforce.com/company/legal/agreements/).

All major browsers now support [shadow DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom.md). Salesforce maintains the [synthetic shadow polyfill](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md) for legacy browsers and is committed to migrating to native shadow DOM via mixed shadow mode. With mixed shadow mode, you gain the speed and efficiency of using native shadow as much as possible in your app. And you can more readily migrate to use native shadow fully in the future.

Our benchmarks have shown that native shadow components are up to 50% faster than their synthetic counterparts in some scenarios. In the future, removing the synthetic shadow polyfill can reduce LWC's overall JavaScript size by half. Mixed shadow mode takes us closer to being able to fully migrate to native shadow, then enabling us to remove the polyfill from LWC completely.

Native and [synthetic shadow](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom-synthetic.md) have several differences, such as how they achieve encapsulation through slots versus styling. While apps rely on global stylesheets to apply styles in synthetic shadow DOM, a component's styles are added to the component bundle in native shadow. Most importantly, native shadow components are faster and more performant than synthetic shadow ones.

Here's an example of an app with mixed mode components. It has a parent `c-app` component with `c-native` and `c-synthetic` children components. When you inspect native shadow components in the web console, they appear within a `#shadow-root` tag.

```html
<!-- c-app -->
<c-app>
    <c-native>
     #shadow-root
     |  <div>This is a component in native shadow</div>
    </c-native>
    <c-synthetic>
        <div>This is a component in synthetic shadow</div>
    </c-synthetic>
</template>
```

For the purpose of this article, parent and children components are also known as ancestor and descendant components. In contrast, a component that extends another component is referred to as a subclass and its superclass.

**note:** LWC allows inheritance, but it isn’t recommended because composition is usually more effective. Inheritance doesn’t work across namespaces, and you can’t extend the `lightning` namespace.

A synthetic shadow component can contain native shadow components, but the inverse isn't supported.

```html
<!-- c-app -->
<c-app>
  #shadow-root (synthetic)
  <c-synthetic>
    #shadow-root (synthetic)
    <c-native>
      #shadow-root (native)
      <p>Content inside a native shadow root</p>
    </c-native>
  </c-synthetic>
</c-app>
```

## Enable Mixed Shadow Mode

To enable mixed shadow mode on a component, set the static `shadowSupportMode` property to `native`.

```javascript
// native.js
import { LightningElement } from "lwc";
export default class MixedModeApp extends LightningElement {
  static shadowSupportMode = "native";
}
```

Valid values for `shadowSupportMode` include:

- `any`—(Deprecated) Renders the whole component subtree in native shadow DOM where possible. If the browser doesn't support shadow DOM, the subtree renders in synthetic shadow.
- `native`- Renders the whole component subtree in native shadow DOM regardless of the `shadowSupportMode` value on the subtree components.
- `reset`—Enables a subclass to opt out of receiving the `shadowSupportMode` value from its superclass. `reset` applies only if the component's superclass is using `native` and no parent components are using `native`.

Before setting `shadowSupportMode` to `native` to enable mixed shadow mode, we recommend checking that all components in the subtree are compatible with native shadow DOM. For example, you can't use the attribute selector `[dir=""]` in a native shadow DOM subtree because the selector only works in synthetic shadow DOM. Instead, see if your browser supports the `:dir()` pseudo-class in native shadow DOM. Alternatively, you can start at the leaf components and work your way up the component tree to make sure that mixed shadow mode is working as expected.

## Work with Mixed Shadow Mode

If a parent component uses `native`, then all components in the subtree operate in native shadow regardless of its `shadowSupportMode` value. Native shadow mode components can contain native shadow mode children components only.

Slots don't count as a parent-child relationship. The slotted content is owned by the slotter, not the slottee. In this example, the slotter is `my-component` and the slottee is `c-native`.

<!-- prettier-ignore -->
```html
<!-- my-component.html -->
<template>
  <c-native> <!-- owned by my-component -->
    <c-synthetic></c-synthetic> <!-- owned by my-component, slotted into c-native -->
  </c-native>
</template>
```

The slot renders in the same shadow mode that its parent renders in. In other words, for the purposes of determining the shadow mode, the slot is considered a "child" of the slotter, not the slottee.

Slotted content isn’t descended from the component it’s nested in, so you can slot synthetic shadow content into a native shadow component. This also means that slotted content isn’t affected by how your browser renders the `#shadow-root` of the component containing the slot. For example, if your browser renders a native shadow component in synthetic shadow, native content slotted into that component is still rendered in native shadow.

In the next example, `<c-parent>` has a native shadow subtree with the child component, `<c-child>` and slotted content `<c-slotted>`. `<c-child>` operates in native shadow because it’s descended from `<c-parent>`, but `<c-slotted>` can be in synthetic shadow because it’s not a descendant of `<c-parent>`.

<!-- prettier-ignore -->
```html
<!-- c-app -->
<c-app>
  #shadow-root (synthetic)
  |  <c-parent>
  |  #shadow-root (native)
  |  |  <p>Parent component</p>
  |  |  <slot>
  |  |    <c-slotted>
  |  |    #shadow-root (synthetic)
  |  |    |  <p>Slotted content</p>
  |  |    </c-slotted>
  |  |  </slot>
  |  |  <c-child>
  |  |  #shadow-root (native)
  |  |  |  <p>Child component</p>
  |  |  </c-child>
  |  </c-parent>
</c-app>

```

On a browser that supports shadow DOM, here's how a parent and child component render in synthetic shadow when you set `shadowSupportMode` to `native` or `reset`.

```html
<!-- c-parent -->
<template>
  <c-child></c-child>
</template>
```

| Parent | Child  | Shadow Mode                      |
| ------ | ------ | -------------------------------- |
| -      | -      | synthetic                        |
| reset  | reset  | synthetic                        |
| native | native | native                           |
| native | reset  | native                           |
| reset  | native | Parent: synthetic, Child: native |
| -      | native | Parent: synthetic, Child: native |
| -      | reset  | synthetic                        |

In Lightning Experience or when the `@lwc/synthetic-shadow` polyfill is present, reset the shadow mode to the default behavior by setting `shadowSupportMode` to `reset`.

- If the polyfill is present, `reset` sets the shadow mode to synthetic shadow.
- If the polyfill isn't present, `shadowSupportMode` has no impact and components render in native shadow.

## Check if a Component is Native or Synthetic

To determine if an element has a synthetic shadow root, use `this.template.synthetic`.

```javascript
export default class extends LightningElement {
  renderedCallback() {
    console.log("Synthetic?", this.template.synthetic);
  }
}
```

In synthetic shadow, `this.template.synthetic` returns `true`. In native shadow, `this.template.synthetic` evaluates to `undefined`.

## Example: Use Native and Synthetic Shadow Components

An app can include both native and synthetic shadow components. This example assumes that the app is running in Lightning Experience or the `@lwc/synthetic-shadow` polyfill is present. The app renders in the DOM like this.

<!-- prettier-ignore-start -->
```html
<!-- c-app -->
<c-app>
  <c-native>
    #shadow-root 
    |  <div>Your content for the native shadow component</div>
  </c-native>
  <c-synthetic>
    <div>Your content for the synthetic shadow component</div>
  </c-synthetic>
</c-app>
```
<!-- prettier-ignore-end -->

Let's take a look at the app markup, which includes two components running in different modes.

```html
<!-- c-app -->
<template>
  <c-native></c-native>
  <c-synthetic></c-synthetic>
</template>
```

Here's the native shadow component.

```html
<!-- c-native -->
<template>
  <div>Your content for the native shadow component</div>
</template>
```

```javascript
// native.js
import { LightningElement } from "lwc";
export default class Native extends LightningElement {
  static shadowSupportMode = "native";
}
```

Here's the synthetic shadow component.

```html
<!-- c-synthetic -->
<template>
  <div>This is a component in synthetic shadow</div>
</template>
```

```javascript
// synthetic.js
import { LightningElement } from "lwc";
export default class Synthetic extends LightningElement {}
```

**note:** In Lightning Experience, synhetic shadow components render with CSS scope tokens like `c-child_child` or `lwc-66unc5l95ad-host`, depending on your custom component's `apiVersion`. Don't rely on these scope tokens as they are an internal implementation that can change anytime. See [Synthetic Shadow](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom-synthetic.md).

## Compare Native Shadow with Synthetic Shadow

Synthetic shadow DOM doesn't support these features that are available with native shadow.

- [Server-side rendering](https://lwc.dev/guide/ssr)
- The CSS [`::part` pseudo-element](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)
- Form-Associated Custom Elements
- Imperative slots

Also, the CSS [`:dir()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir) uses a partial polyfill in synthetic shadow DOM that only works for `dir` attributes explicitly on the host element.

Here are additional differences between native and synthetic shadow.

### Elements and Slots

In native shadow, elements are rendered in a component's light DOM and assigned to slots in a child component's shadow DOM. Slots are created in the order that's defined in the component invoking the slotting. In synthetic shadow, LWC doesn't render elements that are passed down to child components unless they are assigned to a slot. Slots are also created in the order that's defined in the target slottable component.

For a component `c-parent` that contains `c-child`, `c-child` has a span that's not assigned to a slot. In native shadow, this span is rendered in the DOM. However, in synthetic shadow, the span doesn't exist in the DOM.

```html
<!-- c-parent -->
<template>
  <c-child>
    <span>This is some text in a span tag</span>
  </c-child>
</template>
```

```html
<!-- c-child -->
<template>
  <p>child</p>
</template>
```

To determine which slot an element is assigned to, call the `assignedSlot` API. Previously, when the synthetic shadow polyfill is loaded, [`assignedSlot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/assignedSlot) returned `null` on elements assigned to slots in native shadow components. Now, the API returns the `<slot>` element for slotted elements in native shadow components.

To return an array of all elements at the specified coordinates, use the [`elementsFromPoint` API](https://developer.mozilla.org/en-US/docs/Web/API/Document/elementsFromPoint), including for synthetic shadow DOM elements that aren’t visible in the DOM. In the following example, `<c-inner>` is invisible (zero width and height), but the `<div>` that it contains is visible.

```html
<c-outer>
  #shadow-root
  <c-inner>
    #shadow-root
    <div></div>
  </c-inner>
</c-outer>
```

In synthetic shadow, calling `outer.shadowRoot.elementsFromPoint()` returns `[<div>, <c-outer>, <html>]`. In native shadow, it returns `[<c-inner>, <c-outer>, <html>]`.

### Styling

With synthetic shadow, apps rely on global stylesheets to apply styles throughout the DOM. The same isn't possible in native shadow, where a component's styles have to be added to the component bundle.

However, with synthetic shadow, a shared stylesheet at the top level of your document can style all components on a page. To allow global or shared styles to apply to child components, [use `@import` to include the shared stylesheet](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-share.md) in a component that requires it.

**note:** Importing the same stylesheet in multiple components does not impact performance as LWC handles the deduplication of CSS for you.

While the CSS module import works for most shared CSS libraries, it doesn't work if the CSS contains selectors that traverse shadow boundaries. Let’s say you have a parent and child component with this CSS.

```css
.parent .child {
  color: red;
}
```

This CSS doesn't work if the `.parent` and `.child` selectors are in separate components. In this case, use [CSS custom properties](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-custom-properties.md) or another technique to conditionally render children based on their parent.

For example, you can pass the `color` property to the child component.

```javascript
class Parent extends LightningElement {
  myColor = "red";
}

class Child extends LightningElement {
  @api color;
  get myStyle() {
    return `color: ${this.color}`;
  }
}
```

The color that displays in the child component is determined by the parent component.

<!-- prettier-ignore -->
```html
<!-- c-parent -->
<template>
  <c-child color={myColor}></c-child>
</template>

<!-- c-child -->
<template>
  <h1 style={myStyle}>My color is determined by my parent</h1>
</template>
```

Alternatively, consider migrating your components to use [light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md) instead if you don't require encapsulation on your components.

### Accessibility

With synthetic shadow, you can create references across shadow boundaries by dynamically setting attributes in both the parent and child components. With native shadow, you can't do the same as element IDs are scoped to a specific component.

We recommend the following options.

- If an element references another element's ID, place both in the same component.
- If you use `aria-labelledby`, duplicate the strings across elements using `aria-label`.

Alternatively, if you're working with components that don't require encapsulation, consider using [light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md). For example, you have two light DOM components as siblings within the same shadow DOM parent component, and the IDs are shared between the siblings.

### Lightning Base Components

Base components are currently not supported for mixed shadow mode. Salesforce is preparing the base components for native shadow DOM following Web Components standards. The internal structure of base components continue to change as we work on enabling future support of mixed shadow mode and native shadow DOM. Currently, styling on base components can break when they are placed within a native shadow component; native shadow renders all child components without synthetic shadow.

### Events

With synthetic shadow, listeners can handle non-composed events outside of the root LWC node if the event originates from a non-LWC component in the subtree. However, shadow DOM doesn't support this behavior.

Also, `blur` and `focus` events don't bubble or compose correctly in synthetic shadow. Let's say you have a focusable element in a component.

```html
<template>
  <input type="text" />
</template>
```

In synthetic shadow, `blur` and `focus` events don't bubble up.

<!-- prettier-ignore -->
```html
<lightning-component 
  onfocus={NotExecuted} 
  onblur={NotExecuted}
></lightning-component>
```

The same works as expected in native shadow.

<!-- prettier-ignore -->
```html
<lightning-component 
  onfocus={executedWhenInputIsFocused} 
  onblur={executedWhenInputIsFocused}
></lightning-component>
```

### Forms

In synthetic shadow, form elements like `<input>` and `<button>` are associated with the enclosing `<form>` tag, maintaining form behavior like validity states and form submission. However, the same isn't true for native shadow. [Form-Associated Custom Elements](https://web.dev/articles/more-capable-form-controls#form-associated_custom_elements) isn't currently supported.

### Lifecycle Hooks

With synthetic shadow, slotted elements are rendered if they are assigned to a slot only. For slotted elements that are never assigned to a slot, their lifecycle hooks are never invoked.

Furthermore, lifecycle hooks in synthetic shadow are invoked in the order of appearance after they are assigned. Contrastingly, in native shadow, they are invoked in the order of appearance in the template.

### Tests

In WebDriver-based tests, XPath selectors ignore synthetic shadow DOM, but respect native shadow DOM. This means that your XPath selectors may not work in native shadow DOM. You should use [UTAM](https://utam.dev/) or [kagekiri](https://github.com/salesforce/kagekiri) instead of XPath selectors.

### Web APIs

In synthetic shadow where light DOM nodes surround a shadow node, the `innerText` property doesn't hide shadow content, but it hides shadow content in native shadow. Other Web APIs like `innerHTML`, `outerHTML`, and `textContent` also display similar behavior.

Let's look at a `c-light` light DOM component that contains a `c-shadow` shadow DOM component.

<!-- prettier-ignore -->
```html
<c-light>
  <c-shadow>
    #shadow-root 
    |  <h1>Hello Shadow DOM</h1>
  </c-shadow>
  <c-light></c-light
></c-light>
```

In synthetic shadow, calling `innerHTML` from `c-light` returns `<c-shadow><h1>Hello Shadow DOM</h1></c-shadow>`. In native shadow, calling `innerHTML` from `c-light` light DOM component returns `<c-shadow></c-shadow>`.

<!-- document id=24757f8e0645b6880d6d03a1a5fb256e3f334be87ab70b46cfdfeb7badda2aa9 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-build-components.md -->

# Build Components to Work with Lightning Web Security

When you develop Lightning components that are compatible with Lightning Web Security (LWS), follow these coding guidelines.

- [Avoid Mutating Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.md)
  - : When you mutate an object in a component that’s running in LWS, that change isn’t propagated outside the namespace sandbox. Consider mutation alternatives, such as creating a shallow clone.
- [Avoid Using Map Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-map.md)
  - : Use of the Map object with LWS enabled can run into issues when the object is serialized. Instead of using a Map instance, you can use a plain JavaScript object in most cases.
- [Avoid Custom Properties on Standard JavaScript Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-standard-objects.md)
  - : Adding custom properties directly to a standard built-in JavaScript object can cause issues when the object is serialized. If you must add custom data to a DOM element, use the `dataset` property of DOM elements instead.
- [Specify a MIME Type for Blob Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mime.md)
  - : LWS requires you to set the MIME type when you create Blob objects. LWS permits some MIME types, sanitizes some MIME types, and blocks the rest.
- [Script Tags Transformed to Fetch Calls](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-script-tags.md)
  - : LWS transforms `<script>` tags into fetch calls. LWS downloads the script to evaluate it in the sandbox.
- [Access to iframe Content in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-iframes.md)
  - : When LWS is enabled, Lightning components can access content in `iframe` elements when the content is from the same origin.
- [URL Protocol Schemes Allowed](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-url-schemes.md)
  - : LWS restricts the `HTMLObjectElement.data` attribute and the src attribute for `iframe` elements to values that use the `http://` and `https://` schemes. URL schemes such as `javascript://` aren’t allowed.
- [Aura Endpoints Disallowed by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-aura-endpoints.md)
  - : LWS blocks access to URL endpoints containing `/aura` and `/webruntime` because they’re part of the Lightning Component framework.
- [Analytics Libraries Blocked by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-analytics.md)
  - : LWS prevents the third-party analytics scripts from accessing code running in the browser outside the JavaScript sandboxes.
- [Salesforce Global Variables Blocked by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-restricted-globals.md)
  - : For Lightning web components, LWS blocks access to some global JavaScript objects that are available to other Salesforce features, such as `$A`, `Aura`, `Sfdc`, and `sforce`.
- [Third-Party Library Considerations for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-js.md)
  - : Third-party scripts can encounter issues when running with LWS enabled if they have certain behaviors, such as adding themselves to the global `window` object or explicitly setting `"use strict"`.
- [Local Storage Limitations](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-local-storage.md)
  - : LWS creates synthetic storage for each sandbox. The synthetic storage prevents code in one sandbox from retrieving data that belongs to another namespace or that was set in the global scope outside LWS sandboxes, which impacts the usage of the `localStorage` and `sessionStorage` APIs.
- [Objects Passed Between Components Are Proxied](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-proxies.md)
  - : To maintain namespace isolation and reduce incompatibility, LWS proxies objects that are passed between components. To avoid issues related to proxies, pass values as JSON strings and parse them later.
- [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.md)
  - : LWS uses proxy objects, which can have a performance cost. To optimize performance, reduce heavy DOM usage where possible. When creating large collections of objects, minimize the use of global objects and use plain JavaScript objects instead.

<!-- document id=bdea0c4723a5b3e66becefc4046dc41fd37a7a8b75543fb8f898d419afd59e7b url=/developer/current/en-us/lwc/lwc/guides/data/data-salesforce-write.md -->

# Build Custom UI to Create and Edit Records

If the `lightning-record*form` components don’t provide enough flexibility for your use case, use the imperative JavaScript functions in the `lightning/uiRecordApi` module to build UI that creates and edits records.

**tip:** Before you use the `lightning/uiRecordApi` module, see whether the `lightning-record*form` components meet your needs. See [Compare Base Components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md).

This document explains the `ldsCreateRecord` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. The component asks for a name and creates an account with that name. When the account is created, it renders the account Id.

![Form that asks for an Account name and creates an account.](https://developer.salesforce.com/media/lds_create_record.png)

To create a record via JavaScript, call the `createRecord()` function. This component calls the function in the `createAccount` handler.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="LdsCreateRecord" icon-name="standard:record">
    <div class="slds-m-around_medium">
      <lightning-input label="Id" disabled value={accountId}></lightning-input>
      <lightning-input
        label="Name"
        onchange={handleNameChange}
        class="slds-m-bottom_x-small"
      ></lightning-input>
      <lightning-button
        label="Create Account"
        variant="brand"
        onclick={createAccount}
      ></lightning-button>
    </div>
  </lightning-card>
</template>
```

The component’s JavaScript imports `createRecord` from the `lightning/uiRecordApi` module. To display notifications for error handling, it imports `ShowToastEvent` from `lightning/platformShowToastEvent`. It also imports references to the Account object and Account name field.

Specify the `apiName` and `fields` values for your `recordInput` object. In the example, we pass in `fields` on the `recordInput` object using a shorthand syntax, instead of passing in `fields: fields`. Then, pass the account name to `createRecord(recordInput)`, which creates an account record based on the name you provide.

Next, provide a handler that creates an account record using `createRecord(recordInput)`. In this example, the `handleNameChange(event)` method handles a `change` event from the component HTML file when a user enters an account name.

```
import { LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import { createRecord } from 'lightning/uiRecordApi';
import { reduceErrors } from 'c/ldsUtils';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import NAME_FIELD from '@salesforce/schema/Account.Name';

export default class LdsCreateRecord extends LightningElement {
    accountId;

    name = '';

    handleNameChange(event) {
        this.accountId = undefined;
        this.name = event.target.value;
    }

    async createAccount() {
        const fields = {};
        fields[NAME_FIELD.fieldApiName] = this.name;
        const recordInput = { apiName: ACCOUNT_OBJECT.objectApiName, fields };
        try {
            const account = await createRecord(recordInput);
            this.accountId = account.id;
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Success',
                    message: 'Account created',
                    variant: 'success'
                })
            );
        } catch (error) {
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Error creating record',
                    message: reduceErrors(error).join(', '),
                    variant: 'error'
                })
            );
        }
    }
}

```

The `createRecord(recordInput)` function returns a Promise object that resolves when the record is created. This component returns the `account.id` and sets it to the `accountId` property. If an error is returned in the async function, the promise is rejected. You can handle the error using the try/catch block.

**tip:** To update a record, see [updateRecord(recordInput, clientOptions)](https://developer.salesforce.com/docs/platform/lwc/reference/reference-update-record.md). To update multiple records using Apex, see [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/data/data-table-inline-edit.md).

**See Also**

- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)
- [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/use/use-toast.md)
- [Write Jest Tests: Test Imperative Apex Methods](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md#test-imperative-apex-methods)

<!-- document id=0dcc0d480eab5961bfca738eda3fbe9c08e326d09c680c94e747b1f132c64261 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-build-html-css.md -->

# Build the UI for a Custom Property Editor

Unlike the component class, which requires you to follow the property editor contract, the HTML markup and CSS for a custom property editor don't require you to follow a contract. You can make the editor look and feel however you like. For example, assign the font, type size, and text color.

In the Custom Article component example, you want to create a custom property editor for `textAlignment` so that your Experience Builder users can select alignment from a button group. Here's how the HTML for this custom property editor can look.

<!--prettier-ignore-->
```html
<template>
  <div>
    <lightning-button-group onclick={handleAlignmentClick}>
      <template for:each={buttons} for:item="button">
        <lightning-button-icon-stateful
          key={button.value}
          value={button.value}
          selected={button.selected}
          icon-name={button.icon}
        ></lightning-button-icon-stateful>
      </template>
    </lightning-button-group>
  </div>
</template>
```

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)
- [The Property Editor Contract and Property Sheet](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-property-editor-contract.md)
- [General Guidelines for Creating a Custom Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-general-guidelines.md)

<!-- document id=2e7a8fbaf732f69349974f6d6af3395950085ebdae703fbc1a62f5b4296b1c83 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice.md -->

# CalendarService API

Manage calendar events from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how CalendarService works, see [Manage Calendar Events on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice.htm).

<!-- document id=39903d47a19f0a758a0540a05b8ebbc6217c1a5f0a47020187a3bbc2e49c68d1 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-constants.md -->

# CalendarService Constants

CalendarService defines and uses several constants. Each of the following constants enumerates the accepted string values for the associated properties.

## Constant Names and Values

All of the following constants are available as properties on an instance of CalendarService.

| Constant Names        | Accepted Values                                                              | Description                                                                      |
| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `EventAvailability`   | "Busy", "Free", "Tentative"                                                  | Correlates with the `availability` property on the `Event` object.               |
| `EventStatus`         | "Cancelled", "Confirmed", "Tentative"                                        | Correlates with the `status` property on the `Event` object.                     |
| `ParticipantRole`     | "Required", "Optional", "Unknown"                                            | Correlates with the `role` property on the `Participant` object.                 |
| `ParticipantStatus`   | "Accepted", "Declined", "Pending", "Tentative", "Unknown"                    | Correlates with the `status` property on the `Participant` object.               |
| `RecurrenceFrequency` | "Daily", "Weekly", "Monthly", "Yearly"                                       | Correlates with the `frequency` property on the `RecurrenceRule` object.         |
| `Weekday`             | "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" | Correlates with the `dayOfTheWeek` property on the `RecurrenceDayOfWeek` object. |
| `Span`                | "ThisEvent", "ThisAndFollowingEvents"                                        | Correlates with the `span` property on the `CalendarServiceOptions` object.      |

## CalendarServiceFailureCode

Correlates with the `code` property on the `CalendarServiceFailure` object.

| Accepted Value           | Description                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| "USER_DENIED_PERMISSION" | A user denied permission to calendar access when prompted.                                                                                   |
| "NOT_FOUND"              | A specified item (either a calendar or an event) wasn’t found.                                                                               |
| "SERVICE_NOT_ENABLED"    | CalendarService isn’t enabled and can’t be used.                                                                                             |
| "UNKNOWN_REASON"         | An error has occurred in the native code that isn’t permission-based. More information is available in the `CalendarServiceFailure` message. |

<!-- document id=b4b879acbb3cc80d37be61578cd22baf62cfe33cd33fcba33f844a24538142b7 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-data-types.md -->

# CalendarService Data Types

CalendarService defines and uses several data types.

## `Calendar`

An object representing a calendar.

| Property Name                | Type    | Description                                                                                                                                                             | Example              |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `id`                         | String  | A stringified number unique to each calendar. Generated by the native device at the time of calendar creation.                                                          | "6544287"            |
| `title`                      | String  | The name of the calendar.                                                                                                                                               | "Awanasa's Calendar" |
| `allowsContentModifications` | Boolean | Indicates whether the calendar is editable (`true`) or read-only (`false`).                                                                                             | `false`              |
| `hexColor`                   | String  | Specifies the accent color shown for this calendar’s events on the device UI. Valid entries must contain a number sign (#) followed by a six-character hex color value. | "#009EDB"            |
| `type`                       | String  | Metadata about the calendar’s type.                                                                                                                                     | "exchange"           |
| `isPrimary`                  | Boolean | Indicates whether the selected calendar is the default calendar for the device.                                                                                         | `true`               |

## `Event`

An object representing an event.

| Property Name         | Type                | Description                                                                                              | Example                                                                                             |
| --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `id`                  | String              | A stringified number unique to each event. Generated by the native device at the time of event creation. | "7824456"                                                                                           |
| `isAllDay`            | Boolean             | Indicates whether the event is all-day. Defaults to false.                                               | `true`                                                                                              |
| `startDateSecondsUTC` | Number              | Denotes the starting date and time for a given display range.                                            | 1667692800                                                                                          |
| `endDateSecondsUTC`   | Number              | Denotes the ending date and time for a given display range.                                              | 1668211200                                                                                          |
| `availability`        | `EventAvailability` | Indicates a participant’s availability during an event. Defaults to “Busy”.                              | "Busy"                                                                                              |
| `status`              | `EventStatus`       | This parameter is read-only; any value specified by the user is ignored by the plugin.                   | "Tentative"                                                                                         |
| `calendarId`          | String              | Matches the id value from the associated calendar.                                                       | "6544287"                                                                                           |
| `title`               | String              | The name of the event.                                                                                   | "Chan's Birthday Party"                                                                             |
| `location`            | String              | The location of the event.                                                                               | "415 Mission St, San Francisco, CA, 94105"                                                          |
| `notes`               | String              | Miscellaneous notes associated with the event.                                                           | "Don't forget to bring the cake!"                                                                   |
| `alarms`              | `Alarm[]`           | Indicates when a reminder is generated before the start of an event.                                     | `{relativeOffsetSeconds: 3600}`                                                                     |
| `attendees`           | `Participant[]`     | Lists the attendees for an event.                                                                        | `{name: "Alex Driskall", email: "alex_driskall@example.com", role: "Required", status: "Accepted"}` |
| `recurrenceRules`     | `RecurrenceRule[]`  | Specifies any recurrence rules for an event.                                                             | `{frequency: "Monthly"}`                                                                            |

## `Alarm`

An object representing when a notification is generated before an event.

| Property Name           | Type   | Description                                                                                | Example |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------ | ------- |
| `relativeOffsetSeconds` | Number | The amount of time, in seconds, before an event when a reminder notification is generated. | 1800    |

## `Participant`

An object representing an invitee to a particular calendar event.

| Property Name | Type                | Description                                                  | Example                                    |
| ------------- | ------------------- | ------------------------------------------------------------ | ------------------------------------------ |
| `name`        | String              | The name of the participant.                                 | "Chan Ming Lewis"                          |
| `email`       | String              | The email address of the participant.                        | "chan_ming_lewis_fake_email\@employer.com" |
| `role`        | `ParticipantRole`   | Indicates the level of necessity of an invitee’s attendance. | "Optional"                                 |
| `status`      | `ParticipantStatus` | Indicates whether an invitee will attend an event.           | "Attending"                                |

## `RecurrenceRule`

An object representing the recurrence cadence of a calendar event.

| Property Name     | Type                    | Description                                                                                                                                                                                                                                                                | Example                                                                                                                               |
| ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `frequency`       | `RecurrenceFrequency`   | Indicates the frequency of the event’s recurrence.                                                                                                                                                                                                                         | "Weekly"                                                                                                                              |
| `interval`        | Number                  | Indicates the interval at which the event’s recurrence takes place. Defaults to 1. For example, if the value of the `frequencyparameter` is "Weekly" and the value of the `interval` is 3, the event recurs every three weeks.                                             | 3                                                                                                                                     |
| `daysOfTheWeek`   | `RecurrenceDayOfWeek[]` | Indicates which days of the week the events occurs on.                                                                                                                                                                                                                     | `{dayOfTheWeek: "Thursday"}`                                                                                                          |
| `daysOfTheMonth`  | `Number[]`              | Indicates which days of the month the event occurs on. Acceptable values include positive integers from 1 through 31 (inclusive).                                                                                                                                          | 5                                                                                                                                     |
| `monthsOfTheYear` | `Number[]`              | Indicates which months of the year the event occurs on. Acceptable values include positive integers from 1 through 12 (inclusive).                                                                                                                                         | 6                                                                                                                                     |
| `weeksOfTheYear`  | `Number[]`              | Indicates which weeks of the year the event occurs on. Acceptable values include positive integers from 1 through 53 (inclusive).                                                                                                                                          | 17                                                                                                                                    |
| `daysOfTheYear`   | `Number[]`              | Indicates which days of the year the event occurs on. Acceptable values include positive integers from 1 through 366 (inclusive).                                                                                                                                          | 200                                                                                                                                   |
| `setPositions`    | `Number[]`              | Specifies a comma-separated list of values that correspond to the nth occurrence within the set of recurrence instance specified by the rule. The example provided shows a possible `RecurrenceRule` object representation of "the third and fifth weekdays of the month". | `{ frequency: "Monthly", daysOfTheWeek: {dayOfTheWeek: "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"}, setPositions, 3, 5 }` |
| `end`             | `RecurrenceEnd`         | Indicates when the event recurrence ends.                                                                                                                                                                                                                                  | `{occurrenceCount: 8}`                                                                                                                |

**note:** Recurrence rule properties are defined in accordance with the standardized iCalendar data format. For more information of the specifics of the iCalendar format, see [Internet Calendaring and Scheduling Core Object Specification](https://datatracker.ietf.org/doc/html/rfc5545).

## `RecurrenceDayOfWeek`

An object for specifying the weekly recurrence cadence of a calendar event.

| Property Name  | Type       | Description                                                                                                                    | Example  |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `dayOfTheWeek` | `Weekday`  | Indicates the day of the week.                                                                                                 | "Monday" |
| `weekNumber`   | `Number[]` | Indicates the week number within the calendar year. Acceptable values include positive integers from 1 through 53 (inclusive). | 25       |

## `RecurrenceEnd`

An object for specifying the end of a recurrence cadence of a calendar event.

| Property Name       | Type   | Description                                                   | Example    |
| ------------------- | ------ | ------------------------------------------------------------- | ---------- |
| `endDateSecondsUTC` | Number | Denotes the ending date and time for a given recurring event. | 1668211200 |
| `occurrenceCount`   | Number | Denotes the number of times an event recurs.                  | 12         |

## `CalendarServiceOptions`

An object for specifying which instances of a recurring event are affected by an update to or deletion of one instance of an event.

| Property Name | Type   | Description                                                                                                                                                               | Example                  |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `span`        | `Span` | Indicates whether an update to or deletion of a recurring event applies to the specified event instance only, or the specified event instance and all future recurrences. | "ThisAndFollowingEvents" |

## `CalendarServiceFailure`

An object representing an error that occurred when accessing CalendarService features.

| Property Name | Type                         | Description                                                                                                                                                                                              |
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `CalendarServiceFailureCode` | A value representing the reason for a calendar error. See `CalendarServiceFailureCode` in [CalendarService Constants](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-constants.md) for the list of possible values. |
| `message`     | String                       | A string value describing the reason for the failure. This value is suitable for use in user error messages. The message is provided in English and isn’t localized.                                     |

<!-- document id=450171255dae8d57b2ccb92f462289b004660560f15514bf1982626acb460b6a url=/developer/current/en-us/lwc/lwc/guides/apex/apex.md -->

# Call Apex Methods

Lightning web components can import methods from Apex classes. The imported methods are functions that the component can call either via `@wire` or imperatively.

Before you use an Apex method, make sure that there isn’t an easier way to get the data, for example, using a base component such as `lightning-record-form`. See [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/data/data-guidelines.md).

**important:** Assume that Apex methods provision immutable data, even if it's possible to mutate the data today. It's a best practice to treat all data that a component receives as immutable. To mutate the data, make a shallow copy of the objects you want to mutate. It’s important to understand this concept when working with data. See [Data Flow](https://developer.salesforce.com/docs/platform/lwc/create/create-components-data-flow.md).

To call an Apex method:

- [Import the Apex method](https://developer.salesforce.com/docs/platform/lwc/guide/apex-import-method.md)
- [Expose the Apex method to a component](https://developer.salesforce.com/docs/platform/lwc/guide/apex-expose-method.md)

Consider several ways to call an Apex method:

- [Wire an Apex method to a component](https://developer.salesforce.com/docs/platform/lwc/guide/apex-wire-method.md)
- [Call an Apex method imperatively](https://developer.salesforce.com/docs/platform/lwc/guide/apex-call-imperative.md)

When calling an Apex method, it's helpful to [cache the Apex method results on the client-side](https://developer.salesforce.com/docs/platform/lwc/guide/apex-result-caching.md). We also recommend [importing references to objects and fields](https://developer.salesforce.com/docs/platform/lwc/guide/apex-schema.md).

## Example

The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has several components that call Apex methods. Look for components whose names start with `apex`.

## Apex Limits

Apex limits are applied per invocation of an Apex method. If your JavaScript code invokes multiple Apex methods via `@wire` or imperatively, the Apex limits are applied separately to each method call.

The framework queues up Apex actions before sending them to the server. If there are more than 2,500 actions in a batched request, you may get a 413 HTTP error code. See [Batching of Apex Actions](https://developer.salesforce.com/docs/platform/lwc/guide/apex-batched-actions.md).

**See Also**

- [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input-intro.md)
- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)
- [Handle Errors from Apex](https://developer.salesforce.com/docs/platform/lwc/guide/apex-error-handling.md)

<!-- document id=fa4845d1e8430d23b48cf9a361fc0b91fb9f49441275203cc6648344a3dd196a url=/developer/current/en-us/lwc/lwc/guides/apex/apex-call-imperative.md -->

# Call Apex Methods Imperatively

To control when the method invocation occurs (for example, in response to clicking a button), call the method imperatively. When you call a method imperatively, you receive only a single response. Compare this behavior with `@wire`, which delegates control to the framework and results in a stream of values being provisioned.

In the following scenarios, you must call an Apex method imperatively as opposed to using `@wire`.

- To call a method that isn’t annotated with `cacheable=true`, which includes any method that inserts, updates, or deletes data.
- To control when the invocation occurs.
- To work with objects that aren’t [supported by User Interface API](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm), like Task and Event.
- To call a method from an ES6 module that doesn’t extend `LightningElement`

If an Apex method is marked with `@AuraEnabled(cacheable=true)`, a client-side Lightning Data Service cache is checked before issuing the network call to invoke the Apex method on the server. However, Lightning Data Service doesn’t manage data provisioned by Apex. Therefore, to refresh stale data, invoke the Apex method and then call [notifyRecordUpdateAvailable(recordIds)](https://developer.salesforce.com/docs/platform/lwc/reference/reference-notify-record-update.md) to update the Lightning Data Service cache.

## Call an Apex Method

Let’s look at the [apexImperativeMethod component](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/apexImperativeMethod) from the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo that uses the same `getContactList` class as our previous examples. Instead of wiring it, when a user clicks a button, the component calls `getContactList()`.

![A Load Contacts button with a list of contacts underneath.](https://developer.salesforce.com/media/apex_imperative.png)

The imported function returns a promise. This code provides a one-time resolution given a set of parameters, whereas [`@wire(apexMethod)`](https://developer.salesforce.com/docs/platform/lwc/guide/apex-wire-method.md) provides a stream of values and supports dynamic parameters.

```
import { LightningElement } from 'lwc';
import getContactList from '@salesforce/apex/ContactController.getContactList';

export default class ApexImperativeMethod extends LightningElement {
    contacts;
    error;

    async handleLoad() {
        try {
            this.contacts = await getContactList();
            this.error = undefined;
        } catch (error) {
            this.contacts = undefined;
            this.error = error;
        }
    }
}

```

```
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Picture__c != NULL
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

The template uses `lwc:if` to render the list of contacts. It also uses `for:each` to iterate over the contacts.

```
<template>
  <lightning-card title="ApexImperativeMethod" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <p class="slds-m-bottom_small">
        <lightning-button label="Load Contacts" onclick={handleLoad}></lightning-button>
      </p>
      <template lwc:if={contacts}>
        <template for:each={contacts} for:item="contact">
          <p key={contact.Id}>{contact.Name}</p>
        </template>
      </template>
      <template lwc:elseif={error}>
        <c-error-panel errors={error}></c-error-panel>
      </template>
    </div>
  </lightning-card>
</template>
```

## Call an Apex Method with Parameters

Pass parameters values to an Apex method in an object whose properties match the parameters of the Apex method. For example, if the Apex method takes a string parameter, don’t pass a string directly. Instead, pass an object that contains a property whose value is a string.

![Enter characters in a seach field and click Search to return a list of contacts.](https://developer.salesforce.com/media/apexImperativeWithParams.png)

```
import { LightningElement } from 'lwc';
import findContacts from '@salesforce/apex/ContactController.findContacts';

export default class ApexImperativeMethodWithParams extends LightningElement {
    searchKey = '';
    contacts;
    error;

    handleKeyChange(event) {
        this.searchKey = event.target.value;
    }

    async handleSearch() {
        try {
            this.contacts = await findContacts({ searchKey: this.searchKey });
            this.error = undefined;
        } catch (error) {
            this.error = error;
            this.contacts = undefined;
        }
    }
}

```

```
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> findContacts(String searchKey) {
        String key = '%' + searchKey + '%';
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Name LIKE :key AND Picture__c != NULL
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

**tip:** To call a method with an object parameter, check out [the `apexImperativeMethodWithComplexParams` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/apexImperativeMethodWithComplexParams) in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc) repo.

## Pass Values to Apex

When you pass values such as record data from LWC to Apex, use JavaScript objects or arrays. Map values are not serialized when passed to Apex methods.

Using maps isn’t supported for both imperative and wired Apex calls. The improper use of maps, such as with `map[key] = val`, allowed the data to be passed with Lightning Web Security (LWS) disabled. However, this usage no longer works when LWS is enabled. Furthermore, `map.set(key, val)` isn’t supported for passing values to Apex.

```javascript
//Don’t do this
Map map = new Map();
map.set(key, val);
apexMethod({map});
```

You can use a JavaScript object like this.

```javascript
import { LightningElement, wire } from "lwc";
import apexMethod from "@salesforce/apex/ReadValues.apexMethod";

export default class ApexValueExample extends LightningElement {
  objVal = {};

  val;

  connectedCallback() {
    this.objVal["one"] = "two";
    this.loadValue();
  }

  async loadValue() {
    this.val = await apexMethod({ theValues: this.objVal });
  }

  @wire(apexMethod, { theValues: "$objVal" })
  propertyOrFunction;
}
```

## Handle Errors in Imperative Apex Calls

When you call [Apex imperatively](https://developer.salesforce.com/docs/platform/lwc/apex/apex-call-imperative.md), use the try/catch block to handle errors.

```javascript
async handleApexMethod() {
  try {
    this.records = await getApexMethod();
    this.error = undefined;
  } catch (error) {
    this.records = undefined;
    this.error = error;
  }
}
```

Alternatively, you can also use the syntax of a promise like this.

```javascript
getContactList()
  .then((result) => {
    // handle result
  })
  .catch((error) => {
    // handle errors
  });
```

The Apex method calls the `then` or `catch` block depending if there's an error. Calling the `then` and `catch` blocks happens asynchronously, so you can't put the whole `getContactList()` method within a try-catch block.

In this case, the `catch` block handle errors from both the Apex method and the `then` block. If the `getContactList()` Apex method throws an exception, you can handle it in the `catch` block. If the Apex method runs successfully, your code in the `then` runs next. And if there's an error in the `then` block, you can also handle it in the `catch` block. See [Handle Errors from Apex](https://developer.salesforce.com/docs/platform/lwc/guide/apex-error-handling.md).

**See Also**

- [Wire Apex Methods to Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/apex-wire-method.md)
- [getRecordNotifyChange(recordIds) (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-record-notify.md)
- [_Security for Lightning Components_: Avoid Mutating Objects](/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.html)
- [_MDN Web Docs_: Rewriting a Promise chain with an async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function#rewriting_a_promise_chain_with_an_async_function)
- [Write Jest Tests: Test Imperative Apex Methods](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md#test-imperative-apex-methods)

<!-- document id=f7659c6bb96015eb6c3d17f56765a5fec0a15865beb5beae377e3e0eef003826 url=/developer/current/en-us/lwc/lwc/guides/data/data-api-calls-apex.md -->

# Call APIs from Apex

To call an API from Apex, use a named credential, which specifies the URL of a callout endpoint and its required authentication parameters.

**note:** By security policy, sessions created by Lightning components aren’t enabled for API access. This restriction prevents even your Apex code from making API calls to Salesforce. Using a named credential for specific API calls allows you to carefully and selectively bypass this security restriction.

The restrictions on API-enabled sessions aren’t accidental. Carefully review any code that uses a named credential to ensure you’re not creating a vulnerability.

Before using Apex to make an API call, see if you can make the API call from JavaScript. You can use Lightning Data Service (LDS) in JavaScript to work with data and metadata for Salesforce records. Lightning Data Service is built on top of the public User Interface API, but it only supports a subset of the API. That subset covers many of the typical use cases for working with data. You can’t make calls to Salesforce APIs other than LDS from JavaScript code.

If Lightning Data Service doesn’t support the entity you are looking to use, or if you want to use another Salesforce API, call the API from an Apex class.

**See Also**

- [Call APIs from JavaScript](https://developer.salesforce.com/docs/platform/lwc/js/js-api-calls.md)
- [_Apex Developer Guide_: Named Credentials as Callout Endpoints](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_named_credentials.htm)
- [_Apex Developer Guide_: Invoking Callouts Using Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts.htm)

<!-- document id=d1b5fb623fd258cc01af16b5df4d5a65beb6edb318c2782957712fa3cbedff2e url=/developer/current/en-us/lwc/lwc/guides/js/js-api-calls.md -->

# Call APIs from JavaScript

Make calls to Salesforce APIs and third-party APIs from a Lightning web component. By default, you can’t make WebSocket connections or calls to third-party APIs from JavaScript code. To do so, add a remote site as a trusted URL (previously CSP Trusted Site).

The Lightning Component framework uses
[Content Security Policy (CSP)](/docs/platform/lightning-components-security/guide/content-security-policy-intro.html), which is a W3C standard, to control the source of content that can be loaded on a page. The default CSP policy doesn’t allow API calls from JavaScript code. You change the policy, and the content of the CSP header, by adding the trusted URLs.

## Salesforce APIs

Use [Lightning Data Service (LDS)](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md) to work with data and metadata for Salesforce records. Lightning Data Service is built on top of the public User Interface API, but it only supports a subset of the API. That subset covers many of the typical use cases for working with data. You can’t make calls to Salesforce APIs other than LDS from JavaScript code.

If LDS doesn’t support the object you are looking to use, or if you want to use another Salesforce API, [write an Apex class](https://developer.salesforce.com/docs/platform/lwc/data/data-api-calls-apex.md).

## Third-Party APIs

Calling a Salesforce API or a third-party API typically requires authentication and authorization using OAuth 2.0. Some APIs also make their data available without authentication and authorization for demonstration purposes, such as with the [Google APIs Explorer](https://developers.google.com/apis-explorer). We recommend that you check the third-party API documentation for usage details.

**note:** If you need to include authentication headers in your calls, use the Apex [`HttpRequest` class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_restful_http_httprequest.htm) to send the request. Providing your keys in JavaScript isn't secure.

To make a call to a third-party API, you must first add the third-party URL to the Trusted URLs page in Setup. If you're fetching data from `https://www.example.com/items/v1/brands`, add the base URL `https://www.example.com/` as a trusted URL.

Use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make third-party API calls. For example, you can make HTTP requests from your Lightning web component with the Fetch API and then parse JSON responses with the `.json()` method.

```javascript
async getItems() {
  const response = await fetch("http://example.com/items.json");
  const items = await response.json();
}
```

**tip:** The [miscRestApiCall](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/miscRestApiCall) component in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/) sends a request to the Google Books API to perform a book search.

The Fetch API returns a promise, which is useful when you're working with async requests. Use the `fetch()` method to make a request and fetch a resource. The `catch()` method is called only when the request fails entirely, such as when the user is offline, or when the request times out. To handle a 4XX or 5XX error, check the [`response.status`](https://developer.mozilla.org/en-US/docs/Web/API/Response/status) property using `then()` or within the `try` block.

```javascript
async getItems() {
  try {
    const response = await fetch("http://example.com/items.json");
    if (!response.ok) {
      throw Error(response);
    }
    const myItems = await response.json();
  } catch (error) {
    console.error("There's a problem with your fetch operation:", error);
  } finally {
    // do something regardless of whether the operation was successful
  }
}
```

For more information, see [_MDN Web Docs_: Using the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). Alternatively, you might also find [third-party web components](https://developer.salesforce.com/docs/platform/lwc/create/create-use-third-party-components.md) or [third-party JavaScript libraries](https://developer.salesforce.com/docs/platform/lwc/guide/js-third-party-library.md) that match your requirements.

**important:** Although you can call a third-party API through a trusted URL, you can’t load JavaScript resources from a third-party site, even from a trusted URL. To use a JavaScript library from a third-party site, add it to a static resource, and then add the static resource to your component. After the library is loaded from the static resource, you can use it as normal.

**See Also**

- [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/guide/js-third-party-library.md)
- [_Salesforce Help_: Manage Trusted URLs](https://help.salesforce.com/s/articleView?id=xcloud.security_trusted_urls_manage.htm)
- [_Salesforce Developers' Blog_: Working with CORS and CSP to Call APIs from LWC](https://developer.salesforce.com/blogs/2022/03/working-with-cors-and-csp-to-call-apis-from-lwc)
- [_Mozilla Developer Network_: The WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)

<!-- document id=db244ffa9ce24c8ef904d6d74c34cff552a495c526a8bd5191215bbd1c2da958 url=/developer/current/en-us/lwc/lwc/guides/create/create-javascript-methods.md -->

# Call Methods on Child Components

To expose a public method, decorate it with `@api`. Public methods are part of a component’s API. To communicate down the containment hierarchy, owner and parent components can call JavaScript methods on child components.

**note:** To communicate up the containment hierarchy, fire an event in a child component and handle it in an owner or container component. See [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md).

Check out the `apiMethod` component (previously named `apiFunction`) in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo, which calls a method on its `clock` child component.

## Define a Method

This example exposes a getter for an `isPlaying` property, and `play()`, and `pause()` methods in a `c-video-player` component by adding the `@api` decorator to them. A parent component that contains `c-video-player` can read the property and call the methods. Here’s the JavaScript file.

```javascript
// videoPlayer.js
import { LightningElement, api } from "lwc";

export default class VideoPlayer extends LightningElement {
  @api videoUrl;

  @api
  get isPlaying() {
    const player = this.template.querySelector("video");
    return player !== null && player.paused === false;
  }

  @api
  play() {
    const player = this.template.querySelector("video");
    // the player might not be in the DOM just yet
    if (player) {
      player.play();
    }
  }

  @api
  pause() {
    const player = this.template.querySelector("video");
    if (player) {
      // the player might not be in the DOM just yet
      player.pause();
    }
  }

  // private getter for computed value
  get videoType() {
    return "video/" + this.videoUrl.split(".").pop();
  }
}
```

`videoUrl` is a public property. The `@api` decorator can be used to define a public property, and a public JavaScript method, on a component. Public properties are another part of the component’s public API.

**note:** To access elements that the template owns, the code uses the [`template`](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md) property.

Now, let’s look at the HTML file where the video element is defined.

<!-- prettier-ignore -->
```html
<!-- videoPlayer.html -->
<template>
  <div class="fancy-border">
    <video autoplay>
      <source src={videoUrl} type={videoType} />
    </video>
  </div>
</template>
```

In a real-world component, `c-video-player` would typically have controls to play or pause the video itself. For this example to illustrate the design of a public API, the controls are in the parent component that calls the public methods.

## Call a Method

The `c-method-caller` component contains `c-video-player` and has buttons to call the `play()` and `pause()` methods in `c-video-player`. Here’s the HTML.

<!-- prettier-ignore -->
```html
<!-- methodCaller.html -->
<template>
  <div>
    <c-video-player video-url={video}></c-video-player>
    <button onclick={handlePlay}>Play</button>
    <button onclick={handlePause}>Pause</button>
  </div>
</template>
```

Clicking the buttons in `c-method-caller` will play or pause the video in `c-video-player` after we wire up the `handlePlay` and `handlePause` methods in `c-method-caller`.

Here’s the JavaScript file for `c-method-caller`.

```javascript
// methodCaller.js
import { LightningElement } from "lwc";

export default class MethodCaller extends LightningElement {
  video = "https://www.w3schools.com/tags/movie.mp4";

  handlePlay() {
    this.template.querySelector("c-video-player").play();
  }

  handlePause() {
    this.template.querySelector("c-video-player").pause();
  }
}
```

The `handlePlay()` function in `c-method-caller` calls the `play()` method in the `c-video-player` element. `this.template.querySelector('c-video-player')` returns the `c-video-player` element in `methodCaller.html`. The `this.template.querySelector()` call is useful to get access to a child component so that you can call a method on the component.

The `handlePause()` function in `c-method-caller` calls the `pause()` method in the `c-video-player` element.

## Return Values

To return a value from a JavaScript method, use the `return` statement. For example, see the `isPlaying()` method in `c-video-player`.

```javascript
@api get isPlaying() {
    const player = this.template.querySelector('video');
    return player !== null && player.paused === false;
}
```

## Method Parameters

To pass data to a JavaScript method, define one or more parameters for the method. For example, you could define the `play()` method to take a `speed` parameter that controls the video playback speed.

```javascript
@api play(speed) { … }
```

## Query Selectors

The `querySelector()` method is a standard DOM API that returns the first element that matches the selector.

If you’re iterating over an array, consider adding some other attribute to the element, like a `class` or `data-*` value, and using it to select the desired element.

The `querySelectorAll()` method returns an array of DOM Elements.

**note:** Don’t pass an `id` to a query method like `querySelector`. When an HTML template is rendered, `id` values can be transformed into globally unique values. If you use an `id` selector in JavaScript, it doesn’t match the transformed `id`.

For more information, see [developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll) and [developer.mozilla.org/en-US/docs/Web/API/Element/querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector).

**See Also**

- [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md)
- [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)
- [Decorators](https://developer.salesforce.com/docs/platform/lwc/reference/reference-decorators.md)

<!-- document id=5e67bdeb18d468812bb52a0e16141527eedb68a9ce71977d0622993d028bc310 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-cancel-async-request.md -->

# Cancel an Asynchronous Request in a Flow Local Action

If an asynchronous request times out, the flow executes the local action's fault connector and sets the error message to `$Flow.FaultMessage`. However, the original request isn't automatically canceled. To abort an asynchronous request, use the `cancelToken` parameter available in the `invoke()` method.

**note:** By default, requests time out after 120 seconds.

## Example

In this local action component class, the `invoke()` method returns a Promise. When the method has done all it needs to do, it fulfills the Promise and control returns to the flow.

- If the request is successful, the method uses `resolve()` to execute the next element in the flow after this action.
- If the request isn't successful, it uses `reject()` to execute the local action’s fault connector and sets `$Flow.FaultMessage`.
- If the request takes too long, it uses `cancelToken.promise.then` to abort the request.

```
import { api, LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';


export default class ShowToastExampleComponent extends LightningElement {
   @api toastTitle;
   @api toastMessage;


   @api invoke(cancelToken) {
       return new Promise((resolve, reject) => {


           // If the Promise times out, abort the request and
           // pass set $Flow.FaultMessage to "Request timed out"
           cancelToken.promise.then(error => {
// Here is where you can clean up ongoing async requests and customize the fault message in the event of a timeout
               reject(new Error("Request timed out."));
           });

           // Do your asynchronous work and call resolve() or reject("Custom error message") when finished.
           resolve();
       });
   }
```

**See Also**

- [Component Reference: `lightning:availableForFlowActions` Interface](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-available-for-flow-actions)
- [Lightning Aura Components Dev Guide: Configure the Client-Side Controller for a Flow Local Action](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_flow_actions_controller.htm)

<!-- document id=2d5d6ab92f35a1133223c87519295b6fd93f6df5497621d537fa031d5e415f00 url=/developer/current/en-us/lwc/lwc/guides/data/data-display-density.md -->

# Change the Form Display Density

In Lightning Experience, the display density setting determines how densely content is displayed and where field labels are located. Display density is controlled for the org in Setup, and users can also set display density to their liking from their profile menu.

An org’s comfy setting places the labels on the top of fields and adds more space between page elements. Contrastingly, compact is a denser view with labels on the same line as the fields and less space between lines. The cozy setting resembles compact, but with more space between lines.

You can design your form to respect the display density setting, or set the form density to override the display density setting. Overriding display density gives you more control over the label location, but doesn’t affect spacing. In addition, you can set individual fields in your form to use variants that change the label location for the field.

## Use the Org’s Default Display Density in a Form

`lightning-record-edit-form`, `lightning-record-view-form`, and `lightning-record-form` adapt to your org's display density by default or when you set `density="auto"`.

```xml
<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the record-id with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="auto">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName"></lightning-input-field>
            <lightning-input-field field-name="LastName"></lightning-input-field>
            <lightning-input-field field-name="Email"></lightning-input-field>
            <lightning-input-field field-name="Phone"></lightning-input-field>
        </lightning-record-edit-form>
    </div>
</lightning-card>
```

## Override the Org’s Display Density

To override the org's display density, specify `density="compact"` or `density="comfy"`. The `cozy` value isn’t supported on the `density` attribute. If an org's display density is set to cozy, labels and fields are on the same line by default.

The following table lists the org’s display density settings and how they relate to the form density on `lightning-record-edit-form`, `lightning-record-view-form`, and `lightning-record-form`.

| Org Display Density | Form Density                  | Field Label Alignment                  |
| ------------------- | ----------------------------- | -------------------------------------- |
| Comfy               | `auto` (default) or `comfy`   | Labels are above fields                |
|                     | `compact`                     | Labels and fields are on the same line |
| Cozy                | `auto` (default) or `compact` | Labels and fields are on the same line |
|                     | `comfy`                       | Labels are above fields                |
| Compact             | `auto` (default) or `compact` | Labels and fields are on the same line |
|                     | `comfy`                       | Labels are above fields                |

## Reduce Space Between the Label and Field

When the form density is `compact`, the labels and fields can appear too far apart for a single column form in a larger region. To reduce the space between the label and field when the form uses compact density, use the `slds-form-element_1-col` class on `lightning-input-field` or `lightning-output-field`.

```xml
<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the record-id with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="compact">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="LastName" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="Email" class="slds-form-element_1-col"></lightning-input-field>
            <lightning-input-field field-name="Phone" class="slds-form-element_1-col"></lightning-input-field>

        </lightning-record-edit-form>
    </div>
</lightning-card>
```

## Set Label Variants on Form Fields

You can set a variant on `lightning-input-field` if you want specific fields to have a label and field alignment that’s different than that used by the form. A variant overrides the display density for that field.

`lightning-input-field` supports these variants: `standard` (default), `label-hidden`, `label-inline`, and `label-stacked`.

This example displays two input fields with inline labels, while the rest of the fields have labels displayed on top of fields due to the comfy form density.

```xml
<lightning-card icon-name="standard:contact" title="record-edit-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the recordId with your own -->
        <lightning-record-edit-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="comfy">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="FirstName" variant="label-inline"></lightning-input-field>
            <lightning-input-field field-name="LastName" variant="label-inline"></lightning-input-field>
            <lightning-input-field field-name="Email"></lightning-input-field>
            <lightning-input-field field-name="Phone"></lightning-input-field>
        </lightning-record-edit-form>
    </div>
</lightning-card>
```

`lightning-output-field` supports these variants: `standard` (default) and `label-hidden`.

This example displays output field values without labels when the form density is `comfy`. Hidden labels are available to assistive technology.

```xml
<lightning-card icon-name="standard:contact" title="record-view-form">
    <div class="slds-p-horizontal_small">
        <!-- Replace the recordId with your own -->
        <lightning-record-view-form record-id="003RM0000066Y82YAE"
                                  object-api-name="Contact"
                                  density="comfy">
            <lightning-messages></lightning-messages>
            <lightning-output-field field-name="FirstName" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="LastName" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="Email" variant="label-hidden"></lightning-output-field>
            <lightning-output-field field-name="Phone" variant="label-hidden"></lightning-output-field>
        </lightning-record-view-form>
    </div>
</lightning-card>
```

Additionally, to reduce the space between the label and field when the label variant is `label-inline`, use the `slds-form-element_1-col` class on `lightning-input-field`.

## Usage Considerations

Admins can set the default display density for the org on the Density Settings setup page. Users can choose their own display density at any time. Admins can’t override a user’s display density setting. The org’s default display setting depends on the Salesforce edition. Density changes don’t apply to Salesforce Classic, Experience Cloud sites, or the Salesforce mobile app. For more information, see [Configure User Interface Settings](https://help.salesforce.com/articleView?id=customize_ui_settings.htm).

**See Also**

- [_Component Reference_: `lightning-record-edit-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-edit-form)
- [_Component Reference_: `lightning-record-view-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-view-form)

<!-- document id=672600541f79ebb0136b339397da2f8f6a00aa00fbd0d8f569cfe3f99a6188a3 url=/developer/current/en-us/lwc/lwc/guides/create/create-version-changes.md -->

# Changes in LWC Framework that Affect Component Behavior

Every Salesforce release increments the API version of the LWC framework. Versioning your components insulates you from unexpected changes, but also limits access to new features. Keep yourself in the loop on LWC changes over time.

## Component-Level Features

To see what's changed in LWC in the latest Salesforce release, see the [release notes](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc.htm). Changes that apply to a specific `apiVersion` are described separately from changes that affect all versions of LWC.

## Component-Level Breaking Changes

Component-level breaking changes apply to custom components for Lightning Experience, Experience Builder sites, and the Salesforce mobile app.

- [v63.0](https://help.salesforce.com/s/articleView?id=release-notes.rn_lwc_versioning.htm&release=254)
- [v62.0](https://help.salesforce.com/s/articleView?id=release-notes.rn_lwc_versioning.htm&release=252)
- [v61.0](https://help.salesforce.com/s/articleView?id=release-notes.rn_lwc_versioning.htm&release=250)
- [v60.0](https://help.salesforce.com/s/articleView?id=release-notes.rn_lwc_versioning.htm&release=248)
- [v59.0](https://help.salesforce.com/s/articleView?id=release-notes.rn_lwc_versioning.htm&release=246)

LWC developers who use LWC outside of the Salesforce platform are impacted by additional breaking changes. For more information, see [LWC OSS v8.0.0](https://github.com/salesforce/lwc/releases/tag/v8.0.0).

<!-- document id=cdaffd126e86c5248ed485e9d1ce4f25e9590fb7b16739621b293f15b03bc490 url=/developer/current/en-us/lwc/lwc/guides/create/create-get-permissions.md -->

# Check Permissions

Import Salesforce permissions from the `@salesforce/userPermission` and `@salesforce/customPermission` scoped modules. Customize a component’s behavior based on the permissions of the context user.

**tip:** See the `miscPermissionBasedUI` recipe in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/miscPermissionBasedUI).

To check whether a user has a permission, import a static reference to the permission and evaluate whether it’s `true` or `undefined`.

```javascript
import hasPermission from "@salesforce/userPermission/PermissionName";
```

Checking for a custom permission has a similar syntax. Don't use a namespace with the permission name if you reference a custom permission from a component in the same namespace as the permission, including the default namespace.

```javascript
import hasPermission from "@salesforce/customPermission/PermissionName";
```

If the custom permission was installed from a managed package, prepend the namespace followed by `__` to the permission name.

```javascript
// For a custom permission installed from a managed package only
import hasPermission from "@salesforce/customPermission/namespace__PermissionName";
```

The name of the static reference is your choice. We chose the format `has{Permission}` to indicate that the reference contains a boolean.

This sample checks whether the current user has the ViewSetup standard permission.

```javascript
// app.js
import { LightningElement } from 'lwc';
import hasViewSetup from '@salesforce/userPermission/ViewSetup';

export default class App extends LightingElement {
    get isSetupEnabled() {
        return !hasViewSetup;
    }

    openSetup(e) {...}
}
```

If the user has the permission, `!hasViewSetup` results in the `disabled` attribute evaluating to `false`, so the button is not disabled.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <setup-panel-group>
    <setup-button disabled={isSetupEnabled} onclick={openSetup}></setup-button>
  </setup-panel-group>
</template>
```

This sample checks whether the current user has the ViewReport custom permission installed from a managed package with the `acme` namespace.

```javascript
// app.js
import { LightningElement } from "lwc";
import hasViewReport from "@salesforce/customPermission/acme__ViewReport";

export default class App extends LightingElement {
  get isReportVisible() {
    return hasViewReport;
  }
}
```

If the user has the permission, the component displays the `expense-report` component .

<!-- prettier-ignore -->
```html
<!--– app.html -->
<template>
  <common-view></common-view>

  <template lwc:if={isReportVisible}>
    <c-expense-report></c-expense-report>
  </template>
</template>
```

**tip:** Replace any cases where a parent Aura component references permissions dynamically with a static reference in the Lightning web component. The static reference is more efficient because it does not require a network call.

**See Also**

- [_Second-Generation Managed Packaging Developer Guide_: Create and Register Your Namespace](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev_dev2gp_create_namespace.htm)
- [_Salesforce Help_: Custom Permissions](https://help.salesforce.com/articleView?id=custom_perms_overview.htm)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)

<!-- document id=68875dd8643575a2d631ba48bc7c8a9f3a2d8f3887806f6ad39e0af86cae6565 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-checkuserisdeviceowner.md -->

# `checkUserIsDeviceOwner(options)`

Verify if the user is the device owner using the device’s biometrics hardware or pin code.

## Syntax

```javascript
import { getBiometricsService } from 'lightning/mobileCapabilities';
checkUserIsDeviceOwner(options: BiometricsServiceOptions): Promise<Object>;
```

## Parameters

- `options`—(Required) A [`BiometricsServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-biometricsservice-data-types.md) object to configure the BiometricsService request.

## Returns

A Promise object that resolves as a Boolean value. `true` if the user is the registered device owner and `false` otherwise. If an error is encountered, the error is returned via a rejected promise.

## Usage

```javascript
myBiometricsService
  .checkUserIsDeviceOwner(options)
  .then((results) => {
    if (result === true) {
      console.log("✔ Current user is device owner.");
    } else {
      console.log("𐄂 Current user is NOT device owner.");
    }
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

**See Also**

- [BiometricsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice_example.htm)
- [BiometricsService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-biometricsservice-data-types.md)

<!-- document id=d3abde292294368e67d9e2b87268541d6a33eb0c3a4be8a10735061e2ea732f6 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-relationships.md -->

# Children and Parent Relationships

You can specify a parent or child relationship in your query for the GraphQL wire adapter.

## Children Relationships

Objects can have children relationships to the same object. For example, a parent account can have a child account. Some objects also have children relationships to other objects. For example, accounts have child relationships to assets, cases, and contacts among other objects.

To query a child relationship, pass in the child relationship name and fields to the parent `node`. The GraphQL wire adapter only supports one level of child relationships. For example, you can request contacts on an account record, but not any child relationships of those contacts.

The child relationships records in the response are paginated and include [cursor and pagination information](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-pagination.md).

To create a query with children relationships, use the [`query` parameter of the GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md).

```javascript
query operationName {
  uiapi {
    query {
      Account (where: { Name: { eq: "United Oil" }}) {
        edges {
          node {
            Id
            Name {
              value
            }
            Contacts ( first: 5 ) {
              edges {
                node {
                  Name { value }
                }
              }
              totalCount
              pageInfo {
                hasNextPage
              }
            }
          }
        }
      }
    }
  }
}
```

The response looks like this.

```nolang
{
  "data": {
    "uiapi": {
      "query": {
        "Account": {
          "edges": [
            {
              "node": {
                "Id": "001RM000005Zcl6YAC",
                "Name": {
                  "value": "United Oil"
                },
                "Contacts": {
                  "edges": [
                    {
                      "node": {
                        "Name": {
                          "value": "Pat Stumuller"
                        }
                      }
                    },
                    {
                      "node": {
                        "Name": {
                          "value": "Stella Pavlova"
                        }
                      }
                    },
                    {
                      "node": {
                        "Name": {
                          "value": "Lauren Boyle"
                        }
                      }
                    },
                    {
                      "node": {
                        "Name": {
                          "value": "Jane Grey"
                        }
                      }
                    },
                    {
                      "node": {
                        "Name": {
                          "value": "Arthur Song"
                        }
                      }
                    }
                  ],
                  "totalCount": 11,
                  "pageInfo": {
                    "hasNextPage": true
                  }
                }
              }
            }
          ]
        }
      }
    }
  },
  "errors": []
}
```

## Parent Relationships

To query a parent relationship, pass in the parent relationship name and fields to the child `node`. The GraphQL wire adapter returns one level of parent relationship. Unlike child relationships, you can request multiple levels of parent relationships. For example, request the name of the account owner associated with an opportunity.

To create a query with parent relationships, use the [`query` parameter of the GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md).

```nolang
query operationName {
  uiapi {
    query {
      Opportunity {
        edges {
          node {
            Id
            Name {
              value
            }
            Account {
              Name {
                value
              }
            }
          }
        }
      }
    }
  }
}
```

The response looks like this.

```nolang
{
  "data": {
    "uiapi": {
      "query": {
        "Opportunity": {
          "edges": [
            {
              "node": {
                "Name": {
                  "value": "Edge SLA"
                },
                "Account": {
                  "Name": {
                    "value": "Edge Communications"
                  }
                }
              }
            },
            {
              "node": {
                "Name": {
                  "value": "Edge Emergency Generator"
                },
                "Account": {
                  "Name": {
                    "value": "Edge Communications"
                  }
                }
              }
            },
            {
              "node": {
                "Name": {
                  "value": "Edge Emergency Generator"
                },
                "Account": {
                  "Name": {
                    "value": "Edge Communications"
                  }
                }
              }
            },
            {
              "node": {
                "Name": {
                  "value": "Edge Installation"
                },
                "Account": {
                  "Name": {
                    "value": "Edge Communications"
                  }
                }
              }
            },
            {
              "node": {
                "Name": {
                  "value": "Burlington Textiles Weaving Plant Generator"
                },
                "Account": {
                  "Name": {
                    "value": "Burlington Textiles Corp of America"
                  }
                }
              }
            }
          ]
        }
      }
    }
  },
  "errors": []
}
```

## Polymorphic Relationships

Some relationships fields, like `Account.OwnerId`, are [polymorphic fields](https://developer.salesforce.com/docs/platform/graphql/guide/filter-parent.html). To create a query with polymorphic relationships, use the [`query` parameter of the GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md) and annotate the object using the `polymorphicParentRelationship` field.

In this example, the `OwnerId` polymorphic field is mapped to the User object.

```nolang
query AccountCasesDetail {
  uiapi {
      query {
          Account(where: { Name: { like: "Acme%" } }) {
              edges {
                  node {
                      Id
                      Name {
                          value
                          displayValue
                      }
                      Cases(
                          where: { IsClosed: { ne: true } }
                          orderBy: { LastModifiedDate: { order: ASC } }
                      ) {
                          edges {
                              node {
                                  Id
                                  Subject {
                                      value
                                      displayValue
                                  }
                                  Owner  {
                                      ... on User {
                                          Name {
                                              value
                                          }
                                      }
                                  }
                                  CreatedDate {
                                      displayValue
                                  }
                                  Id
                                  IsEscalated {
                                      value
                                  }
                              }
                          }
                      }
                  }
              }
          }
      }
  }
}
```

The response looks like this.

```nolang
{
  "data": {
    "uiapi": {
      "query": {
        "Account": {
          "edges": [
            {
              "node": {
                "Name": {
                  "value": "Acme Corp.",
                  "displayValue": null
                },
                "Cases": {
                  "edges": [
                    {
                      "node": {
                        "Subject": {
                          "value": "Starting generator after electrical failure"
                        },
                        "Owner": {
                          "Name": {
                            "value": "Amy Taylor"
                          }
                        },
                        "CreatedDate": {
                          "displayValue": "10/28/2022, 3:44 PM"
                        },
                        "IsEscalated": {
                          "value": false
                        }
                      }
                    },
                    {
                      "node": {
                        "Subject": {
                          "value": "Cannot start generator after electrical failure"
                        },
                        "Owner": {
                          "Name": {
                            "value": "John Kingsley"
                          }
                        },
                        "CreatedDate": {
                          "displayValue": "10/28/2022, 3:44 PM"
                        },
                        "IsEscalated": {
                          "value": false
                        }
                      }
                    },
                  ]
                }
              }
            }
          ]
        }
      }
    }
  },
  "errors": []
}
```

**tip:** For more information, see [Use GraphQL API with Lightning Web Components](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html).

**See Also**

- [_GraphQL API Developer Guide_: Paginate Results](https://developer.salesforce.com/docs/platform/graphql/guide/paginate.html)

<!-- document id=0c204d9344ac0d4ffec23df89f76dca2efa746a5bef7327c363271c89902adbf url=/developer/current/en-us/lwc/lwc/guides/apex/apex-result-caching.md -->

# Client-Side Caching of Apex Method Results

To improve runtime performance, annotate the Apex method with `@AuraEnabled(cacheable=true)`, which caches the method results on the client. To set `cacheable=true`, a method must only get data, it can’t mutate (change) data.

Marking a method as cacheable improves your component’s performance by quickly showing cached data from client-side storage without waiting for a server trip. If the cached data is stale, the framework retrieves the latest data from the server. Caching is especially beneficial for users on high latency, slow, or unreliable connections. Cacheable methods perform better, so use them when possible.

To use `@wire` to call an Apex method, you must set `cacheable=true`.

To call an Apex method imperatively, you can choose to set `cacheable=true`.

The caching refresh time is the duration in seconds before an entry is refreshed in storage. The refresh time is automatically configured in Lightning Experience and the Salesforce mobile app.

The default cache duration can change as we optimize the platform. When you design your Lightning web components, don't assume a cache duration. If a component knows that a cached value is invalid, for example when underlying data changes, it can query the server for updated data and refresh the cache with `refreshApex()` from `@salesforce/apex`.

**tip:** The `ldsDeleteRecord` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo calls `refreshApex()`.

## Refresh the Cache When Calling a Method Imperatively

To refresh stale Apex data, invoke the Apex method and then call [notifyRecordUpdateAvailable(recordIds)](https://developer.salesforce.com/docs/platform/lwc/reference/reference-notify-record-update.md) to update the Lightning Data Service (LDS) cache. Lightning Data Service doesn’t manage data provisioned by imperative Apex calls. After you invoke the Apex method, call `notifyRecordUpdateAvailable(recordIds)` to signal to Lightning Data Service that some records are stale and refresh those records in the cache.

```javascript
import { LightningElement, wire } from 'lwc';
import { getRecord, notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
import apexUpdateRecord from '@salesforce/apex/Controller.apexUpdateRecord';

export default class Example extends LightningElement {
    @api recordId;

    // Wire a record
    @wire(getRecord, { recordId: '$recordId', fields: ... })
    record;

    async handler() {
      // Do something before the record is updated

      // Update the record via Apex
      await apexUpdateRecord(this.recordId);

      // Notify LDS that you've changed the record outside its mechanisms
      // Await the Promise object returned by notifyRecordUpdateAvailable()
      await notifyRecordUpdateAvailable([{recordId: this.recordId}]);
    }
}
```


To indicate that the refresh process is underway, you can use a component like `lightning-spinner` on the page. For more information about showing and hiding a spinner, see [Component Reference: Spinner](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-spinner).

## Refresh the Cache When Using `@wire`

To refresh Apex data provisioned via an Apex `@wire`, call `refreshApex()`. The function provisions the data using the configuration bound to the `@wire` and updates the cache.

**note:** The parameter you refresh with `refreshApex()` must be an object that was previously emitted by an Apex `@wire`.

Sometimes, you know that the cache is stale. If the cache is stale, the component needs fresh data. To query the server for updated data and refresh the cache, import and call the `refreshApex()` function. Invoke `refreshApex()` only when necessary because it incurs a network trip to query the server.

The `refreshApex()` function returns a Promise. When the Promise is resolved, the data in the wire is fresh. The return value from the Apex method is only available on the `@wire`. The `@wire` has fresh data when the Promise resolves, but the actual value to which the Promise resolves is meaningless. Use a `then()` block to work with the refreshed data, such as setting a property on the page.

```javascript
import { refreshApex } from "@salesforce/apex";
refreshApex(valueProvisionedByApexWireService);
```

- Where `valueProvisionedByApexWireService` is either a property annotated with an Apex `@wire`, or if you annotated a function, the argument that the wired function receives.

  ```javascript
  // Example of refreshing data for a wired property
  // after you update data via an LDS-managed module (lightning/uiRecordApi).
  import { LightningElement, wire } from 'lwc';
  import { updateRecord } from 'lightning/uiRecordApi';
  import { refreshApex } from '@salesforce/apex';
  import getOpptyOverAmount from '@salesforce/apex/OpptyController.getOpptyOverAmount;

  export default class RefreshDataWiredPropertyExample extends LightningElement {
    @wire(getOpptyOverAmount, { amount: '$amount' })
    opptiesOverAmount;

    // Update the record using updateRecord(recordInput)
    // Refresh Apex data that the wire service provisioned
    async handler() {
      try {
        await updateRecord(recordInput);
        await refreshApex(this.opptiesOverAmount);
      } catch (error) {
        // handle error
      }
    }
  }
  ```

  ```javascript
  // Example of refreshing data for a wired property
  // after you update data via imperative Apex.
  import { LightningElement, wire } from 'lwc';
  import { refreshApex } from '@salesforce/apex';
  import { notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
  import getOpptyOverAmount from '@salesforce/apex/OpptyController.getOpptyOverAmount;
  import apexUpdateRecord from '@salesforce/apex/Controller.apexUpdateRecord';

  export default class RefreshDataImperativeExample extends LightningElement {
    @wire(getOpptyOverAmount, { amount: '$amount' })
    opptiesOverAmount;

    // Update the record in Apex, such as via a button click
    // Refresh Apex data that the wire service provisioned
    async handler() {
        try {
            await apexUpdateRecord(recordIds);
            refreshApex(this.opptiesOverAmount);
            notifyRecordUpdateAvailable(recordIds); // Refresh the Lightning Data Service cache
        } catch (error) {
            this.error = error;
        }
      }
  }
  ```

  ```javascript
  //Example of refreshing data for a wired function
  import { LightningElement, wire } from 'lwc';
  import { refreshApex } from '@salesforce/apex';
  import getActivityHistory from '@salesforce/apex/ActivityController.getActivityHistory;

  export default class RefreshDataWiredExample extends LightningElement {
    @wire(getActivityHistory, { accountId: '$recordId', max: '500' })
    wiredGetActivityHistory(value) {
        // Hold on to the provisioned value so we can refresh it later.
        this.wiredActivities = value;
        // Destructure the provisioned value
        const { data, error } = value;
        if (data) { ... }
        else if (error) { ... }
        ...
    }
    handler() {
      refreshApex(this.wiredActivities);
    }
  }
  ```

## Example: Refresh the Cache for a Wired Property

Let’s look at an example. This component displays a list of opportunities over a specified amount. A user can click to mark all the opportunities as Won. When the opportunities are updated, the cache data becomes stale. So after the code updates the opportunities, it calls `refreshApex()` to query the server for updated data and refresh the cache.

![Shows a list of opportunities over a specified amount.](https://developer.salesforce.com/media/apex_refresh.png)

<!-- prettier-ignore -->
```html
<!-- opportunitiesOverAmount.html -->
<template>
  <!-- Display a list of opportunities -->
  <p>
    List of opportunities over
    <lightning-formatted-number
      value={amount}
      format-style="currency"
    ></lightning-formatted-number>
  </p>
  <template lwc:if={opptiesOverAmount.data}>
    <template for:each={opptiesOverAmount.data} for:item="oppty" for:index="idx">
      <div key={oppty.Id} class="slds-m-bottom_medium">
        <p>{idx}. {oppty.Name}</p>
        <p>
          <lightning-formatted-number
            value={oppty.Amount}
            format-style="currency"
          ></lightning-formatted-number>
        </p>
        <p>
          <lightning-formatted-date-time value={oppty.CloseDate}></lightning-formatted-date-time>
        </p>
        <p><lightning-badge label={oppty.StageName}></lightning-badge></p>
      </div>
    </template>
    <!-- Click the button to change the opportunities. Requires the data to be refetched
             and rerendered -->
    <lightning-button label="Mark all as Closed Won" onclick={handleClick}></lightning-button>
  </template>
</template>
```

Let’s look at the JavaScript code for the `<c-opportunities-over-amount>` component. First it imports `refreshApex` and the Apex methods from `@salesforce/apex`.

Then it calls the Apex method `getOpptyOverAmount` with a dynamic value, `amount`. The data is rerequested whenever `this.amount` changes. The system provides the data from the client-side cache or from the server.

```javascript
// opportunitiesOverAmount.js
import { LightningElement, api, wire } from "lwc";
import { refreshApex } from "@salesforce/apex";
import getOpptyOverAmount from "@salesforce/apex/OpptiesOverAmount.getOpptyOverAmount";
import updateOpptyStage from "@salesforce/apex/OpptiesOverAmount.updateOpptyStage";

export default class OpportunitiesOverAmount extends LightningElement {
  @api amount = 500000;

  @wire(getOpptyOverAmount, { amount: "$amount" })
  opptiesOverAmount;

  async handleClick(e) {
    try {
      await updateOpptyStage({
        amount: this.amount,
        stage: "Closed Won",
      });
      await refreshApex(this.opptiesOverAmount);
    } catch (error) {
      this.message =
        "Error received: code" + error.errorCode + ", " + "message " + error.body.message;
    }
  }
}
```

The code calls `refreshApex()` in the `handleClick` method. Changing the `stage` to Closed Won impacts the `CloseDate` field, which means that the `@wire` data is stale. The Close Date field changes to today's date when you have a close date in the future.

To tell the system that the data is stale, call `refreshApex()`. The wire adapter marks its cache as stale, requeries the server for updated data, updates its cache, then notifies its subscribers. When that happens, the component's `this.opptiesOverAmount` property updates, which triggers a rerender with the new data. The close date is now `July 18, 2019` (today’s date) and the opportunity stage is now “Closed Won”.

![Shows a list of opportunities that are marked as Closed Won.](https://developer.salesforce.com/media/apex_refresh_result.png)

The `OpptiesOverAmount` class contains the `getOpptyOverAmount` method, which retrieves a list of opportunities over the specified amount. It also contains the `updateOpptyStage` method, which updates the opportunity stage for opportunities over the specified amount to “Closed Won” using the `update` DML operation.

```apex
public with sharing class OpptiesOverAmount {
    @AuraEnabled(cacheable=true)
    public static List<Opportunity> getOpptyOverAmount(Decimal amount) {
        return [SELECT Id, Name, Amount, StageName, CloseDate FROM Opportunity WHERE Amount > :amount];
    }

    @AuraEnabled
    public static void updateOpptyStage(Decimal amount, String stage) {
        for (List<Opportunity> oppts:
            [SELECT Id, Name, Amount, StageName, CloseDate FROM Opportunity WHERE Amount > :amount]) {
                for(Opportunity o : oppts) {
                    o.StageName = stage;
                }
                update oppts;
            }
            return;
    }
}

```

## Example: Refresh the Cache for a Wired Function

To refresh a wired function, pass the argument the wired function receives (which is the wired value) to `refreshApex()`. In this sample code, the wired function is `wiredGetActivityHistory(value)`. Hold on to the value provisioned by the wire service and pass it to `refreshApex()`.

Call `refreshApex()` imperatively using a new function. To track the provisioned value, define a new property, `wiredActivities`, and use it in `wiredGetActivityHistory(value)`. Destructure the provisioned value to extract the `data` and `error` objects easily.

```javascript
import { LightningElement, api, wire } from 'lwc';
import { refreshApex } from '@salesforce/apex';
import getActivityHistory from '@salesforce/apex/GalleryApexController.getActivityHistory';

export default class GalleryApexMaster extends LightningElement {
    @api recordId;
    wiredActivities;

    @wire(getActivityHistory, { accountId: '$recordId', max: '500' })
    wiredGetActivityHistory(value) {
        // Hold on to the provisioned value so we can refresh it later.
        this.wiredActivities = value; // track the provisioned value
        const { data, error } = value; // destructure the provisioned value
        if (data) { ... }
        else if (error) { ... }
        ...
    }

    handleLogACall() {
        // Use the value to refresh wiredGetActivityHistory().
        return refreshApex(this.wiredActivities);
    }
}
```

**See Also**

- [_Apex Developer Guide_: How DML Works](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/langCon_apex_dml_examples.htm)

<!-- document id=a0b563cb3c87c3849668b2bbdae18879cd60638089839e63872d148b5c148908 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-clone-objects.md -->

# Cloned Objects Behavior Differently in LWS Compared to Lightning Locker

If you clone objects using `JSON.stringify(o)`, the behavior in Lightning Web Security (LWS) is different compared to Lightning Locker. Your code might rely on a non-standard behavior of Lightning Locker that doesn’t occur with LWS.

In Lightning Locker, platform objects are replaced with a secure wrapper. To illustrate the behavior, let’s look at the `Event` object. `Event` objects are exposed as `SecureEvent` objects. `SecureEvent` objects are new objects in which all the [inherited and direct properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty#direct_vs._inherited_properties) of the original `Event` object become direct properties in the new object. Direct properties are called "own properties". The conversion to own properties means that the inherited property `Event.prototype.detail` becomes an own property of the `SecureEvent` instance.

`JSON.stringify(o)` only operates on own properties, but if you use it on an `Event` object when Lightning Locker is enabled, all the properties are included because `SecureEvent` converts them to own properties. Under Lightning Locker, you can “clone” received objects by using `JSON.parse(JSON.stringify(o))`.

LWS doesn’t use secure wrappers, and objects typically behave as they would on the browser platform. For the `Event` object under LWS, `Event.prototype.detail` isn’t included in the properties serialized by `JSON.stringify(o)`, because that property is inherited and is not an own property. Therefore, techniques that rely on all properties being serialized won’t work the same in LWS.

`CustomEvent` object cloning through `JSON.parse(JSON.stringify(o))` is one area where developers have run into issues while transitioning to LWS. `CustomEvent.detail` is not an own property so it’s stripped away when cloning.

For example, this code works in Lightning Locker only because wrapping by `SecureEvent` converts the `detail` property to an own property that `JSON.parse(JSON.stringify(event))` can parse.

```javascript
// This cloning technique works in Lightning Locker, but not in LWS.
// Inherited properties aren't included in JSON.stringify serialization,
// and therefore will not be in the cloned object in LWS.

const div = document.createElement("div");

function passItAlong(payload) {
  console.log(payload);
}

div.addEventListener("foo", (event) => {
  passItAlong(JSON.parse(JSON.stringify(event)));
});

const event = new CustomEvent("foo", {
  detail: {
    a: 1,
    b: 2,
  },
});

div.dispatchEvent(event);
```

To pass the value of the `detail` property of an `Event` object, we recommend destructuring the property from the object and reassigning into a new object.

```javascript
// This cloning technique works in LWS.

const div = document.createElement("div");

function passItAlong(payload) {
  console.log(payload);
}

div.addEventListener("foo", (event) => {
  const { detail, type, ...ownProperties } = event;
  passItAlong({ detail, type, ...ownProperties });
});

const event = new CustomEvent("foo", {
  detail: {
    a: 1,
    b: 2,
  },
});

div.dispatchEvent(event);
```

<!-- document id=2f6c28475e6a6f4a2144fb1141694ce8454dc4f18fdf876802df4bf4254e60d1 url=/developer/current/en-us/lwc/lwc/guides/reference/paymentsservice/reference-lightning-paymentsservice-collectpayment.md -->

# collectPayment()

Collect a payment using the selected payment method.

## Syntax

```js
import { getPaymentsService } from 'lightning/mobileCapabilities';
collectPayment(options: CollectPaymentOptions): Promise<[CollectPaymentResult]>
```

## Parameters

- `CollectPaymentOptions`-An object described by these attributes.
  - `amount`-(Required) A text field that shows the amount intended to be collected in a decimal format (for example, 150.00).
  - `paymentMethod`-(Required) A text field that shows the requested payment method (for example, TAP_TO_PAY).
  - `currencyIsoCode`-(Required) A text field that represents the currency ISO code.
  - `merchantAccountId`-(Required) A text field that represents the ID of the Merchant Account object.
  - `merchantName`-(Required) A text field that shows the text that’s presented as the product/service name being paid for (for example, “Power Connector”).
  - `payerAccountId`-(Required) A text field that represents the ID of the Account object requesting to collect the payment.
  - `sourceObjectIds`-(Optional) A text field that represents the ID of the originating object for the payment (for example, ServiceAppointment ID, WorkOrder ID).
  - `permissionRationaleText`-(Optional) A text field that’s presented to the user if permission is missing (for example, location permission) and must be requested from the user. Defaults to a predefined text if it’s empty.

## Returns

A Promise object that resolves as a CollectPaymentResult object. If there’s an error, a rejected promise returns the error type of `PaymentsServiceFailure`.

## Usage

```js
myPaymentsService.collectPayments(options).then((results) => {
  const collectPaymentResult = JSON
  .parse(JSON.stringify(collectPaymentResult, undefined, 2));
  var msg = "Confirmation Status: " + confirmationStatus + ",
  Confirmation ID: " + confirmationId; console.log(msg);
  }
  )
  .catch((error) => {
    const msg = `Failed to collect payment: ${JSON.stringify(error)}`;
    console.log(msg);
    }
    );
```

<!-- document id=f5f90906ca0319f8986c4b9e9ef3c7003113c421e744c14fe23c1953725a0883 url=/developer/current/en-us/lwc/slds_linter/guides/reference/reference-commands.md -->

# Commands

Use these commands to work with SLDS Linter. To uplift your code to SLDS 2 best practices, review and fix the issues that are captured in the generated report.

## lint

Performs style and component linting on your files.

### Description

This command runs SLDS Linter on your code and identifies all the instances where the code doesn’t meet the SLDS 2 rules. It runs ESLint rules on HTML, CMP, and CSS files.

### Examples

See the lint output in the Terminal:

```
npx @salesforce-ux/slds-linter@latest lint
```

Recursively lint all style and markup files in a single directory:

```
npx @salesforce-ux/slds-linter@latest lint aura
```

Recursively lint all style and markup files in multiple directories:

```
npx @salesforce-ux/slds-linter@latest lint "**/{aura,lwc}/**"
```

Recursively lint all CSS files in a single directory:

```
npx @salesforce-ux/slds-linter@latest lint "aura/**/*.css"
```

Lint multiple types of style files:

```
npx @salesforce-ux/slds-linter@latest lint "**/*.{css,scss,sass}"
```

Recursively lint all HTML files in a single directory:

```
npx @salesforce-ux/slds-linter@latest lint "aura/**/*.html"
```

Lint multiple types of markup files:

```
npx @salesforce-ux/slds-linter@latest lint "**/*.{html,cmp}"
```

### Flags

`--fix`  
Optional

Automatically fix problems.

Type: Boolean

`–config-eslint <path>`  
Optional

Path to ESLint configuration file.

Type: Option/String

`--editor <editor>`  
Optional

Editor to open files. For example, VS Code, Atom, Sublime.

Type: Option/String

Default value: `VS Code`

## report

Generates a SARIF or CSV report for analyzing the issues identified by SLDS Linter. The default format is SARIF.

### Description

This command generates a report containing all the instances in your code that don’t align with SLDS 2 guidelines. The report is generated in .csv or .sarif format.

### Examples

Generate a SARIF report:

```
npx @salesforce-ux/slds-linter@latest report --format sarif
```

Generate a CSV report:

```
npx @salesforce-ux/slds-linter@latest report --format csv
```

Generate a CSV report to a specific directory:

```
npx @salesforce-ux/slds-linter@latest report --format csv /mydirectory
```

### Flags

`-o, --output <path>`  
Optional

Output directory for reports. Defaults to the current directory.

Type: Option/String

`--config-eslint <path>`  
Optional

Path to ESLint configuration file.

Type: Option/String

`–format <type>`  
Optional

Output format for the report. Allowed values are `sarif` and `csv`.

Type: Option/String

Default value: `sarif`

## emit

Generates the custom configuration files used by SLDS Linter. By default, the files are placed in the current directory.

### Description

This command generates the `.eslintrc.yml` configuration file used by the SLDS Linter CLI. In this file, you can add new rules and enable or disable existing rules.

### Examples

```
npx @salesforce-ux/slds-linter@latest emit
```

### Flags

`-d, –directory <path>`  
Optional

Target directory to scan. Defaults to the current directory. Supports glob patterns.

Type: Option/String

## help

Displays help for the various commands.

### Description

To view help, add `--help` to each command.

### Examples

See which options you can use with the `lint` command:

```
npx @salesforce-ux/slds-linter@latest lint --help
```

### Flags

`-V, --version`  
Optional

Displays the version number.

Type: Option/String

`-h, –help`  
Optional

Displays help for the various commands.

Type: Option/String

<!-- document id=4f73127011c25d8032bbf70f3016a7d2dfced795a62f3621451e85b9e208f247 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-cart/reference-commerce-cloud.md -->

# Commerce Cloud for LWC

Build custom shopping experiences from LWC with these Commerce Cloud modules.

- [Commerce Cart API (`lightning/commerceCartApi`)](https://developer.salesforce.com/docs/platform/lwc/commerce-cart/reference-lightning-commerce-cart-api.md)
- [Commerce Register Guest Buyer API (`lightning/commerceRegisterGuestBuyerApi`)](https://developer.salesforce.com/docs/platform/lwc/commerce-register-guest-buyer/reference-lightning-commerce-register-guest-buyer-api.md)
- [Commerce Repricing API (`lightning/commerceRepricingApi`)](https://developer.salesforce.com/docs/platform/lwc/commerce-repricing/reference-lightning-commerce-repricing-api.md)

**See Also**

- [Commerce API Developer Guide](https://developer.salesforce.com/docs/commerce/commerce-api/overview)

<!-- document id=ab4197eb1a277e7b59c9d1eb2e1b8a70b5f6ec10ca5d129868fdeeb88307e760 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-errors.md -->

# Common Error Messages

Here are some common error messages you may encounter when using complex template expressions:

- **"Template syntax error: Expected quoted attribute value"** — Complex expression in attribute without quotes
- **"Template syntax error: Unexpected token"** — HTML non-compliant character (like `<`) in text node, or malformed expression
- **"'this' is not allowed in template expressions"** — Using `this` keyword
- **"'new' operator is not allowed in template expressions"** — Using `new` operator
- **"Function declarations are not allowed in template expressions"** — Using function declaration instead of arrow function
- **"Arrow functions with block bodies are not allowed"** — Using block body in arrow function
- **"Assignment operators are not allowed outside arrow functions"** — Assignment outside arrow function
- **"Update operators are not allowed outside arrow functions"** — Update operator (`++`, `--`) outside arrow function

## HTML Compliance Errors in Text Nodes

Using HTML non-compliant characters like `<` in text node expressions will cause parsing errors.

```html
<!-- ❌ Error: < character in text node -->
<div>{age < 18 ? 'Minor' : 'Adult'}</div>
<!-- Error: Template syntax error: Unexpected token -->

<!-- ❌ Error: <= operator in text node -->
<div>{count <= 10 ? 'Low' : 'High'}</div>
<!-- Error: Template syntax error: Unexpected token -->

<!-- ✅ Valid - use HTML-compliant alternatives -->
<div>{age >= 18 ? 'Adult' : 'Minor'}</div>
<div>{count > 10 ? 'High' : 'Low'}</div>
```

## Syntax Errors in Expressions

Malformed expressions will result in syntax errors.

```html
<!-- ❌ Error: Missing closing parenthesis -->
<div>{formatCurrency(price}</div>
<!-- Error: Expected closing parenthesis -->

<!-- ❌ Error: Missing closing brace in template literal -->
<div>{`Hello ${name`}</div>
<!-- Error: Expected closing brace in template literal -->

<!-- ❌ Error: Invalid operator usage -->
<div>{foo && && bar}</div>
<!-- Error: Unexpected token -->

<!-- ✅ Valid expressions -->
<div>{formatCurrency(price)}</div>
<div>{`Hello ${name}`}</div>
<div>{foo && bar}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class SyntaxErrorsComponent extends LightningElement {
  price = 99.99;
  name = "World";
  foo = true;
  bar = "value";

  formatCurrency(price) {
    return `$${price.toFixed(2)}`;
  }
}
```

<!-- document id=7964e53eeee29e117d6f5bbb5ac281a51b3579c0e6ae394c12fee04df9bfc6c0 url=/developer/current/en-us/lwc/lwc/guides/events/events-pubsub.md -->

# Communicate Across the DOM

The easiest way to communicate between components that aren’t in the same DOM tree is to use Lightning message service (`lightning/messageService`). Consider using the publish-subscribe mechanism with the `pubsub` module only if you're working in containers that don't support Lightning Message Service. The `pubsub` module is no longer officially supported or actively maintained.

## Use Lightning Message Service

To communicate between components in a single Lightning page or across multiple pages, set up a Lightning message channel. The advantage over the publish-subscribe mechanism is that message channels aren’t restricted to a single page. Any component in a Lightning Experience application that listens for events on a message channel updates when it receives a message. It works between Lightning web components, Aura components, and Visualforce pages in any tab or in any pop-out window in Lightning Experience. It also works across namespaces.

To use Lightning Message Service:

1. [Declare a message channel using the LightningMessageChannel metadata type.](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-intro.md)
2. [Publish a message using the publish() function from the @salesforce/messageChannel module.](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-publish.md)
3. [Subscribe and unsubscribe to a message using the subscribe() and unsubscribe() functions from the @salesforce/messageChannel module.](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-subscribe.md)

## Use the `pubsub` Module

In containers that [don’t support](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-considerations.md) Lightning Messaging Service, use the `pubsub` module. Download the module from [github.com/developerforce/pubsub](https://github.com/developerforce/pubsub).

In a publish-subscribe pattern, one component publishes an event. Other components subscribe to receive and handle the event. Every component that subscribes to the event receives the event. The `pubsub` module restricts events to a single page. You must also manually unregister all components that are registered to `pubsub`.

**note:** The `pubsub` module is not officially supported or actively maintained.

**See Also**

- [_Salesforce Developers Blog_: Inter-Component Communication Patterns for Lightning Web Components](https://developer.salesforce.com/blogs/2021/05/inter-component-communication-patterns-for-lightning-web-components)
- [_Salesforce Developers Blog_: Step Up Your LWC Skills](https://developer.salesforce.com/blogs/2020/10/step-up-your-lwc-skills-part-1)

<!-- document id=7d8799c72125a42d7356eef36d3517dab626f2c23e2ab53bfd6b2730fb7a1e58 url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel.md -->

# Communicate Across the DOM with Lightning Message Service

Use Lightning message service to communicate across the DOM within a Lightning page. Communicate between Visualforce pages embedded in the same Lightning page, Aura components, and Lightning web components, including components in a utility bar and pop-out utilities. Choose whether a component subscribes to messages from the entire application, or from only the active area.

If you're switching from Salesforce Classic to Lightning Experience, you can build Lightning web components that communicate with existing Visualforce pages or Aura components. You can also use Lightning message service to communicate with softphones via Open CTI.

**important:** Lightning message service is available in Lightning Experience and for Lightning components used in Experience Builder sites.

**See Also**

- [Component Reference: lightning/messageService](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-message-service)
- [Blog: Lightning Message Service](https://developer.salesforce.com/blogs/2019/10/lightning-message-service-developer-preview.html)
- [Lightning Aura Components Developer Guide: Communicating Across the DOM with Lightning Message Service](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/message_channel_intro.htm)
- [Visualforce Developer Guide: Communicating Across the DOM with Lightning Message Service](https://developer.salesforce.com/docs/atlas.en-us.pages.meta/pages/message_channel_intro.htm)
- [Open CTI Developer Guide: Lightning Message Service Methods for Lightning Experience](https://developer.salesforce.com/docs/atlas.en-us.api_cti.meta/api_cti/sforce_api_cti_methods_lms.htm)

<!-- document id=c2dc584db39bc519b5ce4c556ccc1513cd5036fe9a396ad5759dffe54b0d935c url=/developer/current/en-us/lwc/lwc/guides/events/events.md -->

# Communicate with Events

Lightning web components dispatch standard DOM events. Components can also create and dispatch custom events. Use events to communicate up the component containment hierarchy. For example, a child component, `c-todo-item`, dispatches an event to tell its parent, `c-todo-app`, that a user selected it.

Events in Lightning web components are built on [DOM Events](https://dom.spec.whatwg.org/#events), a collection of APIs and objects available in every browser.

The DOM events system is a programming design pattern that includes these elements.

- An event name, called a type
- A configuration to initialize the event
- A JavaScript object that emits the event

To create events, we strongly recommend using the `CustomEvent` interface. In Lightning web components, `CustomEvent` provides a more consistent experience across browsers. It requires no setup or boilerplate, and it allows you to pass any kind of data via the `detail` property, which makes it flexible.

Lightning web components implement the `EventTarget` interface, which allows them to dispatch events, listen for events, and handle events. Learn more about events in this section:

- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/guide/events-create-dispatch.md)
- [Handle Events](https://developer.salesforce.com/docs/platform/lwc/guide/events-handling.md)
- [Configure Event Propagation](https://developer.salesforce.com/docs/platform/lwc/guide/events-propagation.md)
- [Communicate Across the DOM](https://developer.salesforce.com/docs/platform/lwc/guide/events-pubsub.md)
- [Events Best Practices](https://developer.salesforce.com/docs/platform/lwc/guide/events-best-practices.md)
- [Dynamic Event Listeners Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/events-dynamic-considerations.md)

**tip:** To communicate down the component containment hierarchy, pass properties to the child via HTML attributes, or call its public methods. To communicate between components, use [Lightning message service](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel.md) or a [publish-subcribe](https://developer.salesforce.com/docs/platform/lwc/events/events-pubsub.md) utility.

**See Also**

- [Send Events to an Enclosing Aura Component](https://developer.salesforce.com/docs/platform/lwc/events/events-sending-to-aura-components.md)
- [_Salesforce Developers Blog_: How Events Bubble in Lightning Web Components](https://developer.salesforce.com/blogs/2021/08/how-events-bubble-in-lightning-web-components)

<!-- document id=bb41151b04c4203088a70a2971fd290245f8ed16a1ed8abe49d4bd438e2ba9db url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-intro.md -->

# Compare a Custom Property Editor to a Standard Property Editor

Without a custom property editor, when an admin configures a custom flow screen component or invocable action in Flow Builder, the UI is composed of text boxes or combo boxes for the component’s input values. The UI of a custom property editor can be composed of any input component and can use custom styling. This example shows a custom flow screen component with no custom property editor. The component shows text boxes and combo boxes for input attributes that pass data into the flow.

![Flow screen component without a custom property editor](https://developer.salesforce.com/media/flow_custom_property_editor_none.png)

Instead, create a custom property editor that provides a simplified experience for an admin. This example shows a custom flow screen component with a custom property editor that uses custom labels and a slider component for the input values.

![Flow screen component with a custom property editor that includes a slider component to set an input value](https://developer.salesforce.com/media/flow_custom_property_editor_volume.png)

<!-- document id=3ea305cd2e0ee757a3d62eedce177c2421b03d4da8c419b98b34f9e3cfeed07e url=/developer/current/en-us/lwc/lwc/guides/data/data-get-user-input.md -->

# Compare Base Components

Compare `lightning-record*form` components to find the one that meets your use case.

These components provide a form layout. Field labels use values that are based on the default values in your org. The components handle record create, read, and update changes without requiring Apex code. They use [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md) to cache and share record updates across components.

- [`lightning-record-edit-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-edit-form)—Displays an editable form.
- [`lightning-record-view-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-view-form)—Displays a read-only form.
- [`lightning-record-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-form)—Supports edit, view, and read-only modes.

**note:** The components support the objects that User Interface API supports. See [Supported Objects](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm).

| Feature                         | `lightning-record-form`                 | `lightning-record-view-form`            | `lightning-record-edit-form`            |
| ------------------------------- | --------------------------------------- | --------------------------------------- | --------------------------------------- |
| Create Records                  | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Edit Records                    | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| View Records                    | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                         |
| Read-Only Mode                  | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                         |
| Layout Types                    | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                         |                                         |
| Multi Column Layout             | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Custom Layout for Fields        |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Custom Rendering of Record Data |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

For most use cases, `lightning-record-form` provides a great starting point. It combines and simplifies the functionality of `lightning-record-view-form` and `lightning-record-edit-form`. All three components support a multi column layout. For example, you can use `<div class="slds-grid">` to create a column.

Specify either a layout type or the fields and the mode, and the component takes care of layout, validation, CRUD changes, and error handling. The `lightning-record-form` component also switches from edit mode to view mode after changes are submitted successfully.

**note:** To improve performance, specify fields instead of a layout whenever possible. Specify a layout only when you want the administrator, not the component, to control the fields that are provisioned. The component must handle receiving every field that is assigned to the layout for the context user.

For more advanced use cases that require custom field layouts and custom rendering of record data, use `lightning-record-view-form` and `lightning-record-edit-form`.

If you need more customization than the base components allow, such as a custom user interface, see [Build Custom UI to Create and Edit Records](https://developer.salesforce.com/docs/platform/lwc/data/data-salesforce-write.md) and [Get Record Data](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-example.md).

**See Also**

- [Lightning Web Components Video Gallery: Using Metadata-Aware Base Components](https://developer.salesforce.com/tv/lwc-video-gallery)

<!-- document id=3a99f7d55e3170c51c1c43a2642388c5172713072f99a309747d284012c89b9e url=/developer/current/en-us/lwc/lwc/guides/data/data-table-vs-tree-grid.md -->

# Compare `lightning-datatable` and `lightning-tree-grid` for Data Display

These components are similar, but `lightning-tree-grid` has a chevron button that expands and collapses rows that have child records.

`lightning-datatable` uses the [Data Tables blueprint](https://www.lightningdesignsystem.com/components/data-tables/) from Salesforce Lightning Design System (SLDS) and provides an easy way to display your record data on desktop.

`lightning-tree-grid` uses the [Tree Grid blueprint](https://www.lightningdesignsystem.com/components/tree-grid/) from SLDS and enables you to display hierarchical data, grouping records into parent-child relationships.

**tip:** The Lightning Design System docs have examples of each component in different states.

Here’s a list of features supported by `lightning-datatable` and `lightning-tree-grid`.

| Feature                     | `lightning-datatable`                   | `lightning-tree-grid`                   |
| --------------------------- | --------------------------------------- | --------------------------------------- |
| Format columns by data type | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Custom data types           | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Header Actions              | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Row Actions                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Resize Columns              | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Select Rows                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Wrap or Clip Column Content | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Row Numbers                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Column Sorting              | ![Yes](https://developer.salesforce.com/media/checkmark.png) | -                                       |
| Inline Editing              | ![Yes](https://developer.salesforce.com/media/checkmark.png) | -                                       |
| Infinite Scrolling          | ![Yes](https://developer.salesforce.com/media/checkmark.png) | -                                       |
| Expandable Rows             | -                                       | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

**note:** `lightning-datatable` and `lightning-tree-grid` aren’t supported on mobile devices.

**See Also**

- [_Salesforce Lightning Design System_: Displaying Data](https://www.lightningdesignsystem.com/guidelines/displaying-data/)
- [_Component Reference_: `lightning-datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable)
- [_Component Reference_: `lightning-tree-grid`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree-grid)

<!-- document id=b80c9e86808af0003c05f855401154c9bf52664fc27382376d35352a49bd46f9 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-slds1-slds2.md -->

# Compare Salesforce Lightning Design System Versions

Salesforce Lightning Design System (SLDS) now has two versions. Salesforce Lightning Design System 2 (SLDS 2) was [introduced in Spring ’25](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds_slds2.htm&release=254&type=5). The original SLDS is now called SLDS 1.

SLDS 2 is built with a new CSS framework that separates the structure from the visual design using styling hooks. Styling hooks are CSS custom properties that enable deeper customization and theming, allowing you to create unique experiences faster.

You can opt in to using SLDS 2 by choosing the Salesforce Cosmos theme in your org. See [Salesforce Cosmos Theme and SLDS 2 Availability](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&language=en_US&type=5) in Salesforce Help.

This table lists key differences between SLDS 1 and SLDS 2 for developers, with links to more information.

|                         | SLDS 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | SLDS 2                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web site                | [v1.lightningdesignsystem.com](http://v1.lightningdesignsystem.com)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | [lightningdesignsystem.com](http://lightningdesignsystem.com)                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Default theme           | Lightning Blue                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Salesforce Cosmos                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Component Blueprints    | The blueprints are in the SLDS 1 site: [Blueprint Overview](https://v1.lightningdesignsystem.com/components/overview/)                                                                                                                                                                                                                                                                                                                                                                                                                                                        | SLDS 2 uses the same blueprints as SLDS 1. The blueprints aren't republished in the lightningdesignsystem.com site.                                                                                                                                                                                                                                                                                                                                                               |
| Design tokens           | Design tokens are supported in SLDS 1 themes. Design tokens are documented in the [v1 site](https://v1.lightningdesignsystem.com/design-tokens/#site-main-content).                                                                                                                                                                                                                                                                                                                                                                                                           | Design tokens are not supported in SLDS 2 themes. Design tokens are not documented in the new site.                                                                                                                                                                                                                                                                                                                                                                               |
|                         | Global styling hooks can replace design tokens to enable a component’s styling to work in SLDS 1 and SLDS 2\.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Use [SLDS Linter](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds_linter.htm&release=254&type=5) and [SLDS Validator](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds_validator.htm&release=254&type=5) for help finding design tokens and replacing with global styling hooks in your components.                                                                                                                                          |
|                         | Use [SLDS Linter](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds_linter.htm&release=254&type=5) and [SLDS Validator](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds_validator.htm&release=254&type=5) for help finding design tokens and replacing with global styling hooks in your components.                                                                                                                                                                                                                                      | See [Styling Hooks \> Developer Best Practices](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks/b/607020) for more information about updating component styling to transition to SLDS 2\.                                                                                                                                                                                                                                                                  |
| Global styling hooks    | SLDS 1 provides global styling hooks for accessible system colors and accessible color palettes. These styling hooks are listed at [**Global Color Styling Hooks**](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks) in the SLDS 1 site and also included in the [Global Styling Hooks Index](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks/b/768d36) on the SLDS 2 site. Read [Styling Hooks](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks) on the SLDS 2 site for more information. | The global styling hooks provided in SLDS 1 are also available in SLDS 2, plus semantic UI color global styling hooks. Read [Styling Hooks](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks) and view the [Global Styling Hooks Index](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks/b/768d36) on the SLDS 2 site. We recommend replacing the original global color hooks with the semantic UI color global styling hooks. |
| Component styling hooks | Component styling hooks are documented in [component blueprints in the v1 site](https://v1.lightningdesignsystem.com/components/overview/). See [Component Styling Hooks Versus Global Color Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.html?q=component-level#component-level-versus-global-color-styling-hooks).                                                                                                                                                                                       | Component styling hooks aren't currently supported in SLDS 2\. If your components use styling hooks that are named `--slds-c-*` we recommend that you stay on SLDS 1 for now. We're working to enable component level styling hooks in SLDS 2\.                                                                                                                                                                                                                                   |

**See Also**

[SLDS 2 Get Started | Developers](https://www.lightningdesignsystem.com/2e1ef8501/p/547b38-developers)

[SLDS 2 Developer FAQ](https://www.lightningdesignsystem.com/2e1ef8501/p/313db3-faqs/b/70dcc7)

[SLDS Linter Developer Guide](https://developer.salesforce.com/docs/platform/slds-linter/guide/get-started-intro.html)

[SLDS Validator Developer Guide](https://developer.salesforce.com/docs/platform/slds-validator/guide/get-started.html)

<!-- document id=390d3b12d88567b96a92c7ae5ffcbcd8268fd5173f11586625fbf1e10a44e4d6 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-accessibility.md -->

# Component Accessibility

Accessible software and assistive technologies enable users with disabilities to use the products you build. Develop your components so that all users can perceive, understand, navigate, and interact with them.

To create accessible components:

- [Use accessibility attributes](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-accessibility-attributes.md)
- [Handle focus](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-focus.md)

We recommend that you follow the [WCAG Guidelines](https://www.w3.org/TR/WCAG/) for accessibility. Alternatively, consider using a [Lightning base component](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-slds.md), which provides built-in Lightning Design System styling and accessibility. If you can't find a base component that meets your requirement, consider [creating a component from an SLDS Blueprint](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-slds-blueprint.md).

**See Also**

- [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)
- [Follow Accessible Mobile Design Guidelines](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/ux_a11y.htm)
- [Lightning Design System: Accessibility Overview](https://www.lightningdesignsystem.com/accessibility/overview/)

<!-- document id=1455f3143824ad551a9419c5986c0c7e95ccaee6603876f9e558d2cd2495adb0 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-accessibility-attributes.md -->

# Component Accessibility Attributes

To make your components available to screen readers and other assistive technologies, use HTML attributes on your components. HTML attributes describe the UI elements that they contain. Accessibility software interprets UI elements by reading the attributes aloud.

One critical piece of accessibility is the use of the `label` attribute. By associating labels with a control, you allow assistive technology to present it to the user and let the user identify the purpose of the control. See [WCAG label techniques](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html#techniques).

Lightning base components provide built-in accessibility. When you use a base component like `lightning-input` and `lightning-record-form`, the label you provide is automatically associated with the input field.

```html
<lightning-input type="text" label="Enter some text"></lightning-input>
```

The input field is rendered with an associated label.

```html
<!-- Generated HTML -->
<lightning-input class="slds-form-element">
  <label for="input-2" class="slds-form-element__label slds-no-flex">Enter some text</label>
  <div class="slds-form-element__control slds-grow">
    <input type="text" id="input-2" class="slds-input" />
  </div>
</lightning-input>
```

When the `label` element cannot be used, use the `aria-label` attribute to identify form controls like buttons and input fields for screen reader users. Screen readers read `aria-label` attribute values to a user.

**note:** The `aria-label` attribute doesn't display visibly for all users, and it only communicates the label to screen readers. If you're including important information for users and want your content to be accessible, we recommend making the text visible.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <lightning-button aria-label="Log In" label="Log In" 
</template>
```

That template creates HTML output like the following for the screen reader to read out “Log In” to the user.

```html
<!-- Generated HTML -->
<lightning-button>
  <button aria-label="Log In">Log In</button>
</lightning-button>
```

Note that the sample code above doesn't need to use `aria-label` because the `label="Log In"` attribute is sufficient to label the component for all users. Use the `aria-label` attribute to create a label only when one isn't visually present or to provide additional text for a screen reader user beyond what's already visible.

**note:** The base component examples are for demonstration purposes only. Base component internals are subject to change. We document changes to the features and behavior of components, but don’t document changes to their internals. See the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) for the public attributes and methods on a base component.

## Use an Accessibility Attribute as a Public Property

When you’re creating a Lightning web component, use `@api` to expose a public `aria-label` attribute if you want a screen reader to read a value aloud to the user.

**note:** When you take control of an attribute by exposing it as a public property, the attribute no longer appears in the HTML output by default.

To pass the value through to the rendered HTML as an attribute (to reflect the property), define a getter and setter for the property and call the `setAttribute()` method.

You can also perform operations in the setter. Use a private property to hold the computed value.

```javascript
// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  privateAriaLabel;
  @api
  get ariaLabel() {
    return this.privateAriaLabel;
  }

  set ariaLabel(value) {
    this.privateAriaLabel = value.toUpperCase();
    this.setAttribute("aria-label", this.privateAriaLabel);
  }
}
```

```html
<!-- parent.html -->
<template>
  <c-my-component aria-label="Custom Input"></c-my-component>
</template>
```

```html
/* Generated HTML */
<c-my-component aria-label="Custom Input">
  <input type="text" class="slds-input" placeholder="Custom Input" />
</c-my-component>
```

For more information on using `setAttribute()`, see [Reflect JavaScript Properties to HTML Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-html-attributes.md).

## ARIA Attributes

To provide more advanced accessibility, such as a screen reader reading out a button’s current state, use [ARIA](https://www.w3.org/TR/wai-aria-1.1/#usage) attributes. These attributes give more detailed information to the screen readers that support the ARIA standard.

You can associate ARIA attributes with `id` attributes in your HTML template. In a component’s template file, `id` values must be unique so that screen readers can associate ARIA attributes such as `aria-describedby`, `aria-details`, and `aria-owns` with specific elements.

**note:** When a template is rendered, `id` values may be transformed into globally unique values. Don’t use an `id` selector in CSS or JavaScript because it won’t match the transformed `id`. Instead, use the element's `class` attribute or a `data-*` attribute like `data-id`.

Let’s look at some code. The `aria-pressed` attribute tells screen readers to say when a button is pressed. When using a `lightning-button` component, you write:

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <lightning-button
    label="Liked"
    onclick={login}
    aria-label="Like"
    aria-pressed="true"
  ></lightning-button>
</template>
```

The component defines the ARIA attributes as public properties, and uses fields to get and set the public properties.

<!-- prettier-ignore -->
```html
<!-- lightning-button.html -->
<template>
  <button
    label="Liked"
    onclick={login}
    aria-label={innerLabel}
    aria-pressed={pressed}
  ></button>
</template>
```

The component JavaScript uses the camel-case attribute mappings to get and set the values in `lightning-button.js`.

```javascript
// lightning-button.js
import { LightningElement, api } from "lwc";
export default class LightningButton extends LightningElement {
  innerLabel;

  @api
  get ariaLabel() {
    return this.innerLabel;
  }

  set ariaLabel(newValue) {
    this.innerLabel = newValue;
  }

  pressed;

  @api
  get ariaPressed() {
    return this.pressed;
  }

  set ariaPressed(newValue) {
    this.pressed = newValue;
  }
}
```

The generated HTML is:

<!-- prettier-ignore -->
```html
<lightning-button>
  <button
    label="Liked"
    onclick={login}
    aria-label="Like"
    aria-pressed="true">
  </button>
</lightning-button>
```

A screen reader that supports ARIA reads the label and indicates that the button is pressed.

**note:** ARIA attributes use camel-case in accessor functions. For example, `aria-label` becomes `ariaLabel`. The complete mapping list is defined in the [LWC GitHub repo](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/aria-reflection/README.md#implementation).

## Default ARIA Values

A component author may want to define default ARIA attributes on a custom component, and still allow component consumers to specify attribute values. In this case, a component author defines default ARIA values on the component’s element.

```javascript
// lightning-button.js sets "Submit Form" as the default label
import { LightningElement } from "lwc";
export default class LightningButton extends LightningElement {
  connectedCallback() {
    this.template.querySelector("lightning-button").ariaLabel = "Submit Form";
  }
}
```

**note:** Define attributes in `connectedCallback()`. Don’t define attributes in `constructor()`. See [Constructor Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-created.md).

When you use the component and supply an `aria-label` value, the supplied value appears.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <lightning-button
    label="Submit"
    onclick={submit}
    aria-label="Submit This Form"
    aria-pressed
  ></lightning-button>
</template>
```

The generated HTML is:

```html
<lightning-button>
  <button label="Submit" aria-label="Submit This Form" aria-pressed="true"></button>
</lightning-button>
```

And, when you don’t supply an `aria-label` value, the default value appears.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <lightning-button label="Submit" onclick={submit}></lightning-button>
</template>
```

The generated HTML is:

<!-- prettier-ignore -->
```html
<lightning-button>
  <button label="Submit" onclick={submit} aria-label="Submit Form"></button>
</lightning-button>
```

## Static Values

What if you create a custom component and don't want the value of an attribute to change? A good example is the `role` attribute. You don't want a component consumer to change `button` to `tab`. A button is a button.

You always want the generated HTML to have the `role` be `button`, like in this example.

<!-- prettier-ignore -->
```html
<lightning-button>
  <div label="Log In" onclick={login} role="button"></div>
</lightning-button>
```

To prevent a consumer from changing an attribute’s value, simply return a string. This example always returns `"button"` for the `role` value.

```javascript
// lightning-button.js
import { LightningElement, api } from "lwc";
export default class LightningButton extends LightningElement {
  set role(value) {}

  @api
  get role() {
    return "button";
  }
}
```

## Link IDs and ARIA Attributes from Different Templates

IDs and ARIA attributes in the same template are linked automatically. If attributes are in different templates, you must link them manually.

In native shadow DOM, you can’t link IDs and ARIA attributes between elements in separate templates.

To link together two elements using IDs and ARIA attributes, use light DOM to place them in the same shadow root. See the **Accessibility** section in [Light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md).

<!-- document id=8fadeb7978de792529340d8a2dbf7c3bdeceb307ab676e4c5504acf16f572c17 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-meta-file.md -->

# Component Configuration File

Every component must have a configuration file. The configuration file defines the metadata values for the component, including supported targets and the design configuration for Lightning App Builder and Experience Builder.

The configuration file follows the naming convention `componentName.js-meta.xml`, such as `myComponent.js-meta.xml`.

Include the configuration file in your component’s project folder, and push it to your org along with the other component files.

Here’s the simplest configuration file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>false</isExposed>
</LightningComponentBundle>
```

For the complete list of elements in the configuration file, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

**tip:** If you don’t include a configuration file for your component, you get an error similar to the following when you push your changes.

```
Cannot find Lightning Component Bundle <component_name>
```

**See Also**

- [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder.md)
- [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-community-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=b8ee80ea6edbb455848a27d9ea18b38ae4dcd08a4f372f36afcb4761eb01ff8c url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-file.md -->

# Component CSS File

A component can include a CSS file. Use standard CSS syntax to style Lightning web components.

To style a component, create a stylesheet in the component bundle with the same name as the component. If the component name is `myComponent`, the style sheet is `myComponent.css`. The stylesheet is applied automatically.

A component’s CSS file can have a maximum file size of 128 KB (131,072 bytes).

To share CSS style rules among components, create a module that contains only a CSS file and a configuration file. Import the module into the CSS files of Lightning web components.

**See Also**

- [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css.md)
- [Share CSS Style Rules](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-share.md)

<!-- document id=835555e614321feabfddd1995d3407e1fa3d3b900df0c2d91b42ce7aa3102582 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-folder.md -->

# Component Folder

To define a component, create a folder that bundles your component’s files directly under the `lwc` folder. If you use [Salesforce DX Tools](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-cli.md), the folders are automatically created for you when you [create a project](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx-hello-world.md). The Salesforce DX project structure looks like this.

```ascii
force-app
    ├──main
        ├──default
            ├──aura
            ├──...
            ├──lwc
                ├──myComponent
```

A project includes a `force-app/main/default` folder that contains folders like `aura` and `lwc`. For more information, see [Salesforce DX Project Structure and Source Format](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm).

## Component Files

The folder and its files must have the same name, including capitalization and underscores. However, a utility file that exports JavaScript code can have a different name, for example, `utils.js`.

```ascii
myComponent
   ├──myComponent.html
   ├──myComponent.js
   ├──myComponent.js-meta.xml
   ├──myComponent.css
   ├──myComponent.svg
   ├──utils.js
   └──__tests__
       ├──data
       └──myComponent.test.js
```

A component folder can include these files.

| File          | Required?                               | Created automatically using Salesforce DX Tools? | Description                                                                                                                                        |
| ------------- | --------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTML          |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png)          | Provides a UI for the component. See [Component HTML File](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-file.md).                                                        |
| JavaScript    | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png)          | Defines the logic for a component. See [Component JavaScript File](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript.md).                                               |
| Configuration | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png)          | Defines the metadata values for the component. See [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-meta-file.md).                                 |
| CSS           |                                         |                                                  | Provides styling for the component. See [Component CSS File](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-file.md).                                                   |
| SVG           |                                         |                                                  | Enables a component to use a custom icon in Lightning App Builder and Experience Builder. See [Component SVG Icon](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-svg-icon.md). |
| Utilities     |                                         |                                                  | Shares code between components. See [Share JavaScript Code](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md).                                                               |
| Test          |                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png)          | Provides Jest tests for a component. See [Write Jest Tests for Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md).      |

## Component Names

The folder and its files must follow these naming rules.

- Must begin with a lowercase letter
- Must contain only alphanumeric or underscore characters
- Must be unique in the namespace
- Can’t include whitespace
- Can’t end with an underscore
- Can’t contain two consecutive underscores
- Can’t contain a hyphen (dash)

**note:** Save each Lightning web component directly under the `force-app/main/default/lwc` root folder. You can't nest a component in another component folder.

Lightning web components match web standards wherever possible. The [HTML standard](https://html.spec.whatwg.org/multipage/custom-elements.html) requires that custom element names contain a hyphen.

Since all Lightning web components have a namespace that’s separated from the folder name by a hyphen, component names meet the HTML standard. For example, the markup for the Lightning web component with the folder name `widget` in the default namespace `c` is `<c-widget>`.

However, the Salesforce platform doesn’t allow hyphens in the component folder or file names. What if a component’s name has more than one word, like “mycomponent”? You can’t name the folder and files `my-component`, but we do have a handy solution.

Use camel case to name your component `myComponent`. Camel case component folder names map to kebab-case in markup. In markup, to reference a component with the folder name `myComponent`, use `<c-my-component>`.

```html
<!-- parent.html -->
<template>
  <c-my-component></c-my-component>
</template>
```

You can use underscores in component folder names, but they don’t map to kebab case in markup. The names are legal because the namespace is separated with a hyphen, but most users expect hyphens instead of underscores in a web component name. For example, this component’s markup references the `my_component` component. It’s legal, it just looks a little odd.

```html
<!-- parent.html -->
<template>
  <c-my_component></c-my_component>
</template>
```

**See Also**

- [Component Namespaces](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-namespace.md)

<!-- document id=2145637924354b73d696894ead157f3c3929261a3f4c17cf394538eb3c807f7f url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-file.md -->

# Component HTML File

Every UI component must have an HTML file with the root tag `<template>`. API module components (libraries) don’t require an HTML file.

The HTML file follows the naming convention `componentName.html`, such as `myComponent.html`.

A component’s HTML file can have a maximum file size of 128 KB (131,072 bytes).

Create the HTML for a Lightning web component declaratively, within the `<template>` tag. The HTML template element contains your component’s HTML.

```html
<!-- myComponent.html -->
<template>
  <!-- Replace comment with component HTML -->
</template>
```

When a component renders, the `<template>` tag is replaced with the name of the component, `<namespace-component-name>`. For example, in the browser console, `myComponent` renders as `<c-my-component>`, where `c` is the default namespace.

The HTML spec mandates that tags for custom elements (components) aren’t self-closing. In other words, custom elements must include separate closing tags. For example, the `c-todo-item` component nested in this component includes a separate closing `</c-todo-item>` tag.

```html
<!-- myComponent.html -->
<template>
  <c-todo-item></c-todo-item>
</template>
```

Write markup that you may not want to display when the page loads, but that can be rendered at runtime. See [Render DOM Elements Conditionally](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.md).

Use simple HTML template syntax to render lists. See [Render Lists](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.md).

Create placeholders in the template that component consumers can replace with content. See [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md).

<!-- document id=2858effdb2d0ff8c19bc3c38e7dfc07651386132e1819d9b32419178ee3b914e url=/developer/current/en-us/lwc/lwc/guides/create/create-components-javascript.md -->

# Component JavaScript File

Every component must have a JavaScript file. If the component renders UI, the JavaScript file defines the HTML element. If the component is an API module (library), the JavaScript file exports functionality for other components to use.

JavaScript files in Lightning web components are ES6 modules. By default, everything declared in a module is local—it’s scoped to the module.

To import a class, function, or variable declared in a module, use the `import` statement. To allow other code to use a class, function, or variable declared in a module, use the `export` statement.

**note:** A component’s JavaScript file can have a maximum file size of 1 MB (1,000,000 bytes). If your JavaScript file size exceeds the size limit, refactor the code into multiple files. For more information, see [Share JavaScript Code](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md).

## UI Component

The JavaScript file follows the naming convention `componentName.js`, such as `myComponent.js`.

Every UI component must include a JavaScript file with at least this code.

```javascript
import { LightningElement } from "lwc";
export default class MyComponent extends LightningElement {}
```

The core module in Lightning Web Components is `lwc`. The `import` statement imports `LightningElement` from the `lwc` module.

```javascript
import { LightningElement } from "lwc";
```

`LightningElement` is a custom wrapper of the standard HTML element.

Extend `LightningElement` to create a JavaScript class for a Lightning web component. _You can’t extend any other **Salesforce base component** class to create a Lightning web component, unless otherwise stated._

```javascript
export default class MyComponent extends LightningElement {
  // Your code here
}
```

The `export default` keywords export a `MyComponent` class for other components to use. The class must be the default export for UI components. _Exporting other variables or functions in a UI component isn’t currently supported._

The convention is for the class name to be Pascal Case, where the first letter of each word is capitalized. For `myComponent.js`, the class name is `MyComponent`.

The JavaScript file can contain:

- The component’s public API via public properties and methods annotated with `@api`.
- Fields
- Event handlers

UI component folders can include other JavaScript files in addition to the main `myComponent.js` file. However, the code in these files is for the component’s own use and can’t be shared.

## API Module Component

A Lightning web component without a UI can be used as an API module component for sharing code. API module components are sometimes known as service components.

To share code between components, create an ES6 module and export the variables or functions that you want to expose.

An ES6 module is a file that explicitly exports functionality that other modules can use. Modules make it easier to structure your code without polluting the global scope.

An API module component follows the same [folder structure](https://developer.salesforce.com/docs/platform/lwc/create/create-components-folder.md) and naming convention as the UI components. The difference is that there's no HTML file. See [Share JavaScript Code](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md).

These export statements for the `lwc` module aren't allowed.

```javascript
// These exports are invalid
export {} from "lwc";
export * from "lwc";
export { registerTemplate } from "lwc";
```

## LWC Import Declarations

An LWC module can use named imports and default imports. You can't save an LWC module that contains namespace imports and re-export bindings. You can use only these named imports for the `lwc` module.

- [`LightningElement`](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-lwc.md)
- [`api`](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)
- [`track`](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md)
- [`wire`](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md)

You can import multiple names from the `lwc` module.

```javascript
import { LightningElement, api, wire } from "lwc";
```

These import statements for the `lwc` module aren't allowed.

```javascript
// These imports are invalid
import lwc from "lwc";
import \* as lwc from "lwc";
import { registerTemplate } from "lwc";
import "lwc";
```

In addition to importing from the `lwc` module, there are several ways to use named imports in a Lightning web component.

- [Import a wire adapter](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md##wire-service-syntax)
- [Import a reference to a Salesforce object or field](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md#import-references-to-salesforce-objects-and-fields)
- [Import a function or variable that's exported by another module](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md)

**See Also**

- [Fields, Properties, and Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-intro.md)
- [MDN: Named imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#named_import)
- [MDN: Default imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#default_import)
- [MDN: Re-exporting](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#re-exporting_aggregating)

<!-- document id=e2d80a14746f32b0062d39c363e8c76d5ddb76f50f42e5b117651d28fd9da66c url=/developer/current/en-us/lwc/lwc/guides/create/create-components-namespace.md -->

# Component Namespaces

Every component is part of a namespace, which groups related components together and prevents naming conflicts with components from another namespace. The default namespace is `c`.

To reference your own components, always code with the `c` namespace prefix. Use `c` regardless of where the code is running: in an org with or without a namespace, in a managed or unmanaged package.

Within an HTML template, to reference a component in the `lightning` namespace, use `<lightning-component-name>`. A hyphen character (`-`) separates the namespace from the component name.

A unique namespace prefix is required if you plan to make your components available in a managed package. When users install the managed package, the components can be referenced using that namespace prefix.

When you enable Lightning Web Security (LWS) in your org, your component can reference code in namespaces other than `c` and `lightning`. See [Components From Different Namespaces](#components-from-different-namespaces).

## Example: Use Components from `lightning` and `c` Namespaces

This component uses `lightning-card`, which is a base component in the `lightning` namespace that's part of the Lightning Platform. The `lightning-card` component contains `c-contact-tile`, which is a custom component that's in the same project as the `compositionBasics` component.

```lwc
// compositionBasics.html
<template>
  <lightning-card title="CompositionBasics" icon-name="custom:custom57">
    <div class="slds-m-around_medium">
      <c-contact-tile contact={contact}></c-contact-tile>
    </div>
  </lightning-card>
</template>
```

Within a JavaScript class, to use a resource from an API module component (sometimes called a service component or a library), import the resource from its `namespace/module`. The forward slash character (`/`) separates the namespace from the module name.

```lwc
// example.js
import { LightningElement } from 'lwc';

import { MyNamedExport } from 'c/commonUtils';
import MyDefaultExport from 'c/commonUtils';

export default class Example extends LightningElement {}
```

## Components from Different Namespaces

To protect customer data, LWC previously didn’t support the use of components and API modules from different namespaces. Your custom components could only use components and modules from the default `c` namespace and the base components in the `lightning` namespace. This restriction remains in effect when the legacy Lightning security architecture, Lightning Locker, is enabled. Lightning Locker is enabled when LWS is not enabled.

If you [enable Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-enable.html), you can include Lightning web components and modules from namespaces other than `lightning` and `c` in your custom components. The components from other namespaces must be deployed in the org to make them available to your component. For example, components from another developer that you install from a managed package use the developer’s namespace prefix in your organization.

LWS enables you to use components from different namespaces by virtually isolating code to its own namespace. This isolation prevents components from accessing data that belongs to another namespace, while still allowing code from different namespaces to interact.

## Example: Use Components from Different Namespaces With LWS Enabled

Here’s an example that includes a component from the [Lightning Messaging Utility](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000G12j9UAB&tab=d), which was installed from AppExchange. The example `crossNamespace` component is in the `c` namespace and uses the component in the `ltngmu` namespace.

```lwc
// crossNamespace.html
<template>
  <lightning-card>
     <div class="slds-p-around_small">
     <p>Message displayed using Lightning Messaging Utility:</p>
     <ltngmu-lwc-messaging-utility
        message-type="inline"
        show-message="true"
        message-body="hello!"
        message-variant="success"
        show-icon="true"
        icon-name="utility:check"
      ></ltngmu-lwc-messaging-utility>
    </div>
  </lightning-card>
</template>

```

## Namespace Considerations

Consider these guidelines when you're working with a namespace.

- A custom Lightning web component can't access a Lightning web component or module in a custom namespace when running in an org that’s using Lightning Locker instead of LWS.
- A custom Lightning web component can access Lightning web components and modules only in the `c` and `lightning` namespaces when running in an org that’s using Lightning Locker instead of LWS.
- A custom Lightning web component and a custom Aura component in the same namespace can't have the same name, whether the org uses Lightning Locker or LWS.

**See Also**

- [_Salesforce DX Developer Guide_: Understanding Namespaces](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_plan_namespaces.htm)

<!-- document id=730ac112a3e94c98dde75e035786973eade4030c9605ce9e335d0b5dd494d33f url=/developer/current/en-us/lwc/lwc/guides/create/create-components-svg-icon.md -->

# Component SVG Icon

A component can include an SVG resource to use as a custom icon in Lightning App Builder and Experience Builder.

To include an SVG resource as a custom icon for your component, add it to your component’s folder. It must be named _`component`_`.svg`. If the component is called `myComponent`, the svg is `myComponent.svg`. You can have only one SVG per folder.

**See Also**

- [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder.md)

<!-- document id=4848727bb26e16ab43e57693007d79975a2b8d7839221689c858fdf393330718 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-tests.md -->

# Component Tests

To create Jest tests for a component, create a folder called `__tests__` at the top level of the component’s folder. Save the tests inside the `__tests__` folder.

```asciidoc
myComponent
    ├──myComponent.html
    ├──myComponent.js
    ├──myComponent.js-meta.xml
    ├──myComponent.css
    └──__tests__
        └──myComponent.test.js

```

Jest runs JavaScript files in the `__tests__` directory. Test files must have names that end in `.js`, and we recommend that tests end in `.test.js`. You can have a single test file with all of your component tests, or you can have multiple files to organize related tests. Test files can be placed in sub folders.

**See Also**

- [Write Jest Tests for Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md)

<!-- document id=b0f30970e3861aa4213156a6bae36797195ca53fb54b64c8466363f5c02753de url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lwc-comp-fail-fix.md -->

# Components Fail to Load with a Commented-Out Import

Lightning Web Components (LWC) fail to load when Lightning Web Security (LWS) is disabled, Lightning Debug Mode is enabled, and the component contains a commented-out `import(...)` statement (such as in a JSDoc `@typedef`). The error occurs because the legacy Lightning Locker evaluator incorrectly parses the commented text as an active dynamic import.

## Workaround

Apply any one of these solutions:

- Remove the commented-out `import(...)` or JSDoc statement from your code.
- Enable Lightning Web Security (recommended).
- Disable Lightning Debug Mode.

<!-- document id=3674625be17da7d37f82916a78b2e6ef2a6da77e1d8029a2bec533a0f23b7fc4 url=/developer/current/en-us/lwc/lwc/guides/interop/interop-aura-composition.md -->

# Compose Aura Components from Lightning Web Components

You can compose Aura components from Lightning web components, but not the other way around. To communicate down the hierarchy, parents set properties on children. To decide when and how to nest a Lightning web component in an Aura component, it’s important to understand facets and slots.

In an Aura component, to refer to either Aura components or Lightning web components, use camel case with a colon separating the namespace and the component name.

This Aura component is composed of `lightning:card`, which is a base component, and `c:lwcHelloWorld`, which is a custom component you can create.

```html
<!-- auraComponent.cmp file -->
<aura:component implements="flexipage:availableForAllPageTypes">
  <lightning:card title="Aura Hello World" iconName="custom:custom30" />
  <c:lwcHelloWorld name="Earthling" />
</aura:component>
```

The `lwcHelloWorld` code displays a classic greeting. It also references the `lightning-card` component. Most base components are available for Aura and LWC.

```html
<!-- lwcHelloWorld.html -->
<template>
  <lightning-card title="LWC Hello World" icon-name="custom:custom14">
    <div class="slds-card__body slds-card__body_inner">Hello, {name}!</div>
  </lightning-card>
</template>
```

The component has a public `name` property, which the Aura component sets using the `name` attribute.

```javascript
// lwcHelloWorld.js
import { LightningElement, api } from "lwc";

export default class HelloWorld extends LightningElement {
  @api name;
}
```

![A Lightning web component nested inside an Aura component.](https://developer.salesforce.com/media/aura_hello_world.png)

**tip:** In the [trailheadapps/pure-aloe](https://github.com/trailheadapps/purealoe-lwc) sample app, see the Aura [`irrigationWrapperManager`](https://github.com/trailheadapps/purealoe-lwc/tree/master/force-app/main/default/aura/irrigationManagerWrapper) component, which sets properties on the child [`irrigationManager`](https://github.com/trailheadapps/purealoe-lwc/tree/master/force-app/main/default/lwc/irrigationManager) Lightning web component.

## Facets and Slots

In Aura components and Lightning web components, you can add components into the body of another component. In Aura, you add components into facets. In Lightning web components, you add components into [slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md).

In Aura, the `body` attribute is a facet. A facet is any attribute of type `Aura.Component[]`, which is just a fancy way of saying you can set an array of components for the attribute.

In even less fancy terms, think of a facet as a sandwich. You can stuff as many ingredients (components) as you’d like into your sandwich (facet).

```html
<aura:component>
  <!-- start of component body facet-->
  <p>Feeling hungry?</p>
  <c:bacon />
  <c:lettuce />
  <c:tomato />
  <!-- end of component body facet -->
</aura:component>
```

## Build an Aura Component or a Lightning Web Component?

You’re probably hungry for more information and maybe even lunch after reading about facets in Aura. Now, let’s see where facets factor into whether you decide to build an Aura component or a Lightning web component.

If you’re building a new Lightning web component that expects other subcomponents in its body, those subcomponents must also be Lightning web components. Remember that Lightning web components can’t contain Aura components.

Imagine a Lightning web component that’s the outermost component in a tree of nested components. Think of the Lightning web component as the biggest doll in a matryoshka doll, also known as a Russian nesting doll. A matryoshka doll contains a set of nested dolls, each containing a smaller doll. If the biggest doll is a Lightning web component, none of the smaller nested dolls can be an Aura component.

## Example: Pass a Component into a Slot

Consider a `c-wrapper` Lightning web component that allows other components in its body. The `<slot>` tag is a placeholder that an owner component can pass markup into.

```html
<!-- wrapper.html -->
<template>
  <slot></slot>
</template>
```

The `c-app` Lightning web component passes a `lightning-card` component into the slot.

```html
<!-- app.html -->
<template>
  <c-wrapper>
    <lightning-card>
      <lightning-icon icon-name="utility:connected_apps"></lightning-icon>
      Card Title
      <p class="slds-p-horizontal_small">Card Body</p>
    </lightning-card>
  </c-wrapper>
</template>
```

**important:** If a Lightning web component contains a slot, you can nest it in an Aura component but you can't use the slot.

## Call a Child Lightning Web Component Method from a Parent Aura Component

To call a method defined in a Lightning web component from an Aura component, give the Lightning web component an `aura:id` and use `cmp.find()`, just as you do to reference an Aura component. For example, `cmp.find('childLwc').childLwcMethod()`.

Lightning web components aren’t created until your Aura component renders. You can’t invoke a method on your Lightning web component before that time (for example, during your Aura component's initialization).

**See Also**

- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md)
- [Use Custom Aura Tokens](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-aura.md)

<!-- document id=f62773ca7d6acb323467f4163c781fb17dc6d89a7217d643be4ca0ca3df2a947 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-compose.md -->

# Compose Components

It’s useful to compose apps and components with a set of smaller components to make the code more reusable and maintainable. The `lightning` namespace contains many base components, such as `lightning-button`, that you can use to build your components.

Let’s look at a simple app composed of components. The markup is contrived because we want to illustrate the concepts of _owner_ and _container_. In a real app, the number of `c-todo-item` instances would be variable and populated dynamically in a `for:each` loop.

```html
<!-- todoApp.html -->
<template>
  <c-todo-wrapper>
    <c-todo-item item-name="Milk"></c-todo-item>
    <c-todo-item item-name="Bread"></c-todo-item>
  </c-todo-wrapper>
  <template></template
></template>
```

## Owner

The owner is the component that owns the template. In this example, the owner is the `c-todo-app` component. The owner controls all the composed components that it contains. The owner can:

- Set public properties on composed components
- Call methods on composed components
- Listen for any events fired by the composed components

## Container

A container contains other components but itself is contained within the owner component. In this example, `c-todo-wrapper` is a container. A container is less powerful than the owner. A container can:

- Read, but not change, public properties in contained components
- Call methods on composed components
- Listen for some, but not necessarily all, events bubbled up by components that it contains.

## Parent and child

When a component contains another component (which can in turn contain other components), we have a containment hierarchy. In the documentation, we sometimes talk about parent and child components. A parent component contains a child component, like this:

<!-- prettier-ignore -->
```
<template>
  <div>
    <child-component></child-component>
  </div>
</template>
```

In this simplified outline of a project directory, `parentComponent` and `childComponent` are nested in the same `lwc` folder. The parent-child relationship is defined in `parentComponent.html`.

<!-- prettier-ignore -->
```javascript
force-app
    ├──main
        ├──default
            ├──aura
            ├──...
            ├──lwc
                ├──parentComponent
                    ├──parentComponent.css
                    ├──parentComponent.html
                    ├──parentComponent.js
                ├──childComponent
                    ├──childComponent.css
                    ├──childComponent.html
                    ├──childComponent.js
```

**See Also**

- [Lightning Web Components and Aura Components Working Together](https://developer.salesforce.com/docs/platform/lwc/interop/interop-intro.md)
- [Set Properties on Children](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-data-binding.md)
- [Salesforce DX Developer Guide: Salesforce DX Project Structure and Source Format](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm)

<!-- document id=7111f21b91175e1a1e1bccb452eb4b4b374e9bb608f2920d3a4afb87beadf162 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-best-composition.md -->

# Compose Components Using Slots Vs Data

When creating components that contain other components, consider the lifecycle of the component’s hierarchy using the declarative approach with slots, or the data-driven approach where a child component reacts to data changes from its parent.

A common pattern for building components declaratively looks like this.

```html
<c-parent>
  <c-custom-child></c-custom-child>
  <c-custom-child></c-custom-child>
</c-parent>
```

This example has a `c-parent` component that uses a `slot` element. Although convenient for the consumer, you must manage the lifecycle of the content passed through the `slot` element.

There are several ways to manage content that’s passed into a slot.

- [Use the `slotchange` event](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md). This is the recommended approach. `slotchange` bubbles up through the DOM but doesn’t cross the shadow boundary, enabling the parent component that contains the slot to react to it.
- Use custom events to notify the parent component of changes to the child components, which enables you to make the methods on the component you are interacting with private. We no longer recommend this approach as we’re [gradually migrating components to use native shadow](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.md), which enforces components to use the `slotchange` event.

## Use the `slotchange` Event with Slots

Using the `slotchange` event with slots, you manage the lifecycle for the `slot` content between parent and child components. An example of this pattern is the `lightning-button-group` base component with child `lightning-button` components.

```html
<lightning-button-group>
  <lightning-button label="Refresh"></lightning-button>
  <lightning-button label="Edit"></lightning-button>
  <lightning-button label="Save"></lightning-button>
</lightning-button-group>
```

The parent `lightning-button-group` component contains a `slot` element with the `onslotchange` event to manage the lifecycle of content you pass in.

<!-- prettier-ignore -->
```html
<!-- buttonGroup.html -->
<template>
  <slot onslotchange={handleSlotChange}></slot>
</template>
```

**note:** The base component examples are for demonstration purposes only. Base component internals are subject to change. We document changes to the features and behavior of components, but don’t document changes to their internals. See the Component Reference for the public attributes and methods on a base component.

The `slotchange` handler handles the updates to slotted elements when the content of the slot changes. In this case, the parent `lightning-button-group` component determines the CSS classes on the child `lightning-button` components based on the order they appear in the group—first, middle, last, or whether it’s the only button in the group.

```javascript
// buttonGroup.js
handleSlotChange(event) {
  const slot = event.target;
  const children = slot.assignedElements() || [];

  // Loop through each child and
  // set the order value based on position in the group
  this.updateGroupOrder(children); }
```

Modify the button class using a getter.

<!-- prettier-ignore -->
```html
<!-- button.html -->
<template>
  <button class={computedButtonClass} ...>{label}</button>
</template>
```

Call the `classSet` method to dynamically add CSS classes. For more information about `classSet`, review `src/lightning/utils/classSet.js` in the [`lightning-base-components` package](https://www.npmjs.com/package/lightning-base-components?activeTab=code).

```javascript
// button.js
get computedButtonClass() {
    return classSet('slds-button')
    .add({
        // Other button classes here
        'slds-button_first': this._order === 'first',
        'slds-button_middle': this._order === 'middle',
        'slds-button_last': this._order === 'last'
    })
    .toString();
}
```

Fire a register event so the `lightning-button-group` component can register the `lightning-button` components.

```javascript
// button.js
connectedCallback() {
  this._connected = true;
    const privatebuttonregister = new CustomEvent('privatebuttonregister', {
        bubbles: true,
        detail: {
            callbacks: {
                setOrder: this.setOrder.bind(this),
                setDeRegistrationCallback: (deRegistrationCallback) => {
                    this._deRegistrationCallback = deRegistrationCallback;
                }
            }
        }
    });

    this.dispatchEvent(privatebuttonregister);
}
```

Notify the parent when the child component is no longer available.

```javascript
// button.js
disconnectedCallback() {
  this._connected = false;
  if (this._deRegistrationCallback) {
      this._deRegistrationCallback();
  }
}
```

## Use the Data-Driven Approach

Using the data-driven approach, the component gets the changes in a reactive way when data changes.

This example composes a child component using a data-driven approach.

<!-- prettier-ignore -->
```html
<template>
  <div class="c-parent">
    <template for:each={itemsData} for:item="itemData">
      <c-child onclick={onItemSelect} id={itemData.id} key={itemData.id}> </c-child>
    </template>
  </div>
</template>
```

To pass in data, use a JavaScript object. The child component reacts to data changes exclusively from its parent.

```javascript
itemsData = [
    {
        label : 'custom label 1',
        id : 'custom-id-1'
        selected : false
    },
    {
        label : 'custom label 2',
        id : 'custom-id-2'
        selected : false
    }
]
```

A data-driven approach is recommended when you have a complex use case. An example of a base component that’s created using the data-driven approach is [`lightning-datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

**See Also**

- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md)

<!-- document id=4a222009536f70193598a16e915d00ddd2529936bea461d8d1b1d973352d50d2 url=/developer/current/en-us/lwc/utam/references/methods.md -->

# Compose Methods

To combine several element actions, such as a method for login that sets a username, sets a password, and clicks a button, declare a `compose` method.

## Method Properties

A `compose` method has these properties:

- `name` (Required) String. The unique name of the method within this JSON file.
- `description` (Optional) String or Object. See [Method Description](#method-descriptions).
- `compose` (Required) Array. Each object is an element and a method.
  - `element` (Optional) String. The name of a basic element from the same JSON file. Defaults to `self`, which is a reference to the current page object. When a statement refers to the current page object, it can apply the page object's methods. Specify an element only if you need to operate on or interact with it. For an [explicit wait using the `waitFor` keyword](/grammar/explicit-waits), omit the element.
  - `apply` (Optional) String. If this property isn't defined, the getter method for the `element` property is called.
    - Basic element: the name of a [supported action](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md) to apply to the element.
    - Custom element: any public method.
  - `args` (Optional) Array. If the `apply` action needs parameters, provide them in an array. Each element of the array has these properties:
    - `name` (Required) String. A parameter name that is unique in the scope of the `args` array.
    - `type` (Required) String. One of these primitive types: `string`, `number`, or `boolean`.
  - `matcher` (Optional) Object. Defines the filter criteria for the data returned by the `apply` method or the element's getter method.
    - `type` (Required) String. The matcher type for filtering data. For supported types, see [Matchers](#matchers).
    - `args` (Optional) Array. If the matcher type requires arguments, pass them in this array.
  - `returnAll` (Optional) Boolean. If `true`, the method returns an array (in JavaScript) or a list (in Java) of objects. The default is `false`.
  - `returnType` (Optional) String. Explicitly set the return type for the method. You can set a primitive type, such as `"string"`, `"number"`, `"boolean"`, or a custom type, such as `"my/page/object"`. This property is optional because the return type for a compose method can sometimes be inferred by the UTAM compiler. For more information, see [Method Return Types](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/method-return-types.md).
- `args` (Optional) Array. To access an argument passed to a compose method in multiple statements, declare a reusable argument at the method level. For more information, see [Argument Reference](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/arguments.md#argument-reference).

## Method Descriptions

A compose method or element can have a description that explains its usage, return value, and parameters. The description is used to generate JavaDoc or JSDoc.

The simplified `description` format is one string property:

```json
{
  "methods": [
    {
      "name": "myMethod",
      "description": "Gets an attribute of the root element",
      "compose": [
        {
          "element": "root",
          "apply": "getAttribute",
          "args": [
            {
              "name": "attrName",
              "type": "string"
            }
          ]
        }
      ]
    }
  ]
}
```

The generated method includes the following Javadoc or JSDoc. By default, the `@return` tag contains the inferred return type and the `@param` tag has the name and type of the parameter:

```java
/**
 * Gets an attribute of the root element
 *
 * @return String
 * @param attrName String
 */
```

The extended object `description` format enables you to describe more information, such as the return value:

```json
{
  "methods": [
    {
      "name": "myMethod",
      "description": {
        "text": ["Gets an attribute of the root element"],
        "return": "string with an attribute value",
        "throws": "NullPointerException if the attribute name is null",
        "deprecated": "in Summer '22 release"
      },
      "compose": [
        {
          "element": "root",
          "apply": "getAttribute",
          "args": [
            {
              "name": "attrName",
              "type": "string",
              "description": "string with attribute name"
            }
          ]
        }
      ]
    }
  ]
}
```

- `text` string array describing what the method or element does
- `return` (Optional) string that describes the return value
- `throws` (Optional) string that describes a thrown exception and when it's thrown
- `deprecated` (Optional) if the method is no longer supported, this string explains when and why the method was deprecated.

To provide a description for the parameter, we added a `description` property for the `attrName` argument. The description is only possible for non-literal (not hardcoded by value) arguments.

The generated method has the following Javadoc or JSDoc:

```java
/**
 * Gets an attribute of the root element
 *
 * @return string with attribute value
 * @param attrName string with attribute name to get
 * @throws NullPointerException if the attribute name is null
 * @deprecated in Summer '22 release
 */
```

In Java, the generated method is marked with an `@Deprecated` annotation.

The same `description` format can be added to any element:

```json
{
  "elements": [
    {
      "public": true,
      "name": "custom",
      "type": "utam/pageObjects/MyCustomObject",
      "description": "get area inside table",
      "selector": {
        "css": "css%s",
        "args": [
          {
            "name": "selectorArg",
            "type": "string",
            "description": "parameter description"
          }
        ]
      }
    }
  ]
}
```

## Return Types

See [Method Return Types](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/method-return-types.md).

## Invoke action for a basic element

This compose method sets text on the root element and clicks a submit button.

```json
{
  "type": ["editable"],
  "elements": [
    {
      "name": "submitBtn",
      "type": ["clickable"],
      "selector": {
        "css": ".submit"
      }
    }
  ],
  "methods": [
    {
      "name": "submitForm",
      "compose": [
        {
          "element": "root",
          "apply": "setText",
          "args": [
            {
              "type": "string",
              "name": "stringToEnter"
            }
          ]
        },
        {
          "element": "submitBtn",
          "apply": "click"
        }
      ]
    }
  ]
}
```

Here's the generated Java code:

```java
public void submitForm(String stringToEnter) {
    getRoot().setText(stringToEnter);
    submitBtn.click();
  }
```

Here's the generated JavaScript code:

```js
async submitForm(stringToEnter) {
    const _statement0 = await this.__getRoot();
    await _statement0.setText(stringToEnter);
    const _statement1 = await this.__getSubmitBtn();
    const _result1 = await _statement1.click();
    return _result1;
}
```

## Invoke method from the same page object

The `invokeSubmitForm` method simply invokes the `submitForm` method declared in the same page object.

```json
{
  "elements": [
    // ...
  ],
  "methods": [
    {
      "name": "submitForm",
      "compose": [
        // ...
      ]
    },
    {
      "name": "invokeSubmitForm",
      "compose": [
        {
          "apply": "submitForm",
          "args": [
            {
              "type": "string",
              "name": "stringToEnter"
            }
          ]
        }
      ]
    }
  ]
}
```

This pattern is useful if you want to reuse the same method in multiple compose statements. For example, you could call `submitForm` from `login` and `loginWithDeepLink` methods.

Here's the generated JavaScript code:

```js
async invokeSubmitForm(stringToEnter) {
    const _result0 = await this.submitForm(stringToEnter);
    return _result0;
}
```

## Invoke an element's getter

This compose method invokes the getter for the `myCustomComponent` element.

```json
{
  "elements": [
    {
      "name": "myCustomComponent",
      "type": "my/custom/component",
      "selector": {
        "css": "custom-component"
      }
    }
  ],
  "methods": [
    {
      "name": "composeGettingCustomElement",
      "compose": [
        {
          "element": "myCustomComponent"
        }
      ]
    }
  ]
}
```

Here's the generated JavaScript code.

```js
async composeGettingCustomElement() {
    const _result0 = await this.__getMyCustomComponent();
    return _result0;
}
```

## Invoke method from a different page object

This compose method applies the `someUnknownPublicMethod` method to the `myCustomComponent` custom element.

```json
{
  "elements": [
    {
      "name": "myCustomComponent",
      "type": "my/custom/component",
      "selector": {
        "css": "custom-component"
      }
    }
  ],
  "methods": [
    {
      "name": "invokeCustomElementMethod",
      "compose": [
        {
          "element": "myCustomComponent",
          "apply": "someUnknownPublicMethod"
        }
      ]
    }
  ]
}
```

Note that the compiler can't know if the `someUnknownPublicMethod` method actually exists, and what are its return value or parameters. The responsibility to validate those things belongs to the developer or a preruntime compilation step (depending on the setup).

Here's the generated JavaScript code:

```js
async invokeCustomElementMethod() {
    const _statement0 = await this.__getMyCustomComponent();
    const _result0 = await _statement0.someUnknownPublicMethod();
    return _result0;
}
```

## Matchers

Use a matcher to transform the return value of a compose statement.

This compose statement uses a matcher to return a non-null value.

```json
{
  "name": "matcherNotNull",
  "compose": [
    {
      "element": "single",
      "apply": "getAttribute",
      "args": [
        {
          "value": "\"readonly\""
        }
      ],
      "matcher": {
        "type": "notNull"
      }
    }
  ]
}
```

For more information on matchers, see [Element Filters: Matchers](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-filters.md#matchers).

## Chain Compose Statements

It's possible to "chain" compose statements. A chain applies a method or a getter to the result of the previous statement.

**important:** Chains are supported only if the previous statement returns a custom type (another page object).

To apply a method or a getter from the current statement to the result of the previous statement, use the `"chain": true` property inside a statement.

The chain methods approach has some disadvantages and limitations:

- Because the referenced elements and methods (except the first) are defined in other JSON files, the UTAM compiler can’t validate the correctness of the chain until the page object is generated. If the element doesn’t exist, if it isn’t public, or if the type is incorrect, the problem is discovered when the generated code is compiled.
- The current page object now depends on the content of other page objects, so changes in those might prevent the page object from compiling. We notice the issue during build, but it's more difficult to manage.
- The page object author might not be aware of the internals. If another team adds a chained method, ownership of the page object is unclear.

Here are some examples of chaining compose statements.

### Compose container element with getter and public action

Consider the following test code samples:

```js
const myModal = await utam.load(MyModalWithDynamicContent);

// long version
const footerArea = await myModal.getContent(FooterAreaWrapper);
const footerButtonsPanel = await footerArea.getFooterButtonsPanel();
await footerButtonsPanel.clickButtonByIndex(1);

// short version
await myModal.clickSave();
```

It's possible to compose the long version into a short version using a chain.

```json
{
  "elements": [
    {
      "name": "content",
      "type": "container"
    }
  ],
  "methods": [
    {
      "name": "clickSave",
      "compose": [
        {
          // invoke container method with hardcoded type
          "element": "content",
          "args": [
            {
              "type": "pageObject",
              "value": "my/pageObjects/FooterAreaWrapper"
            }
          ],
          "returnType": "my/pageObjects/FooterAreaWrapper"
        },
        {
          // invoke getter
          "chain": true,
          "element": "footerButtonsPanel",
          "returnType": "my/pageObjects/FooterButtonsPanel"
        },
        {
          // invoke public method
          "chain": true,
          "apply": "clickButtonByIndex",
          "args": [
            {
              "value": 1
            }
          ]
        }
      ]
    }
  ]
}
```

### Chaining list to a list

If both previous and current statements return lists (`"returnAll": true`), the method is applied to each returned element using `flatMap`.

Consider the use case of a table with multiple rows and cells. Assume that each row and cell is a separate component.
Let's write a method that returns all cells inside a table.

- table row JSON

```json
{
    "elements": [
        {
            "type": "my/pageObjects/tableCell",
            "name": "tableCells",
            "selector": {
                "css": "table-cell",
                "returnAll": true
            }
        }
    ]
```

- table JSON

```json
{
  "elements": [
    {
      "type": "my/pageObjects/tableRow",
      "name": "tableRows",
      "selector": {
        "css": "table-row",
        "returnAll": true
      }
    }
  ],
  "methods": [
    {
      "name": "getAllCells",
      "compose": [
        {
          "returnType": "my/pageObjects/tableRow",
          "returnAll": true,
          "element": "tableRows"
        },
        {
          "chain": true,
          "returnType": "my/pageObjects/tableCell",
          "returnAll": true,
          "element": "tableCells"
        }
      ]
    }
  ]
}
```

Generated Java code:

```java
public final List<TableCell> getAllCells() {
    List<TableRow> statement0 = this.getTableRowsElement();
    List<TableCell> statement1 =
        statement0
            .stream()
            .flatMap(element -> element.getTableCells().stream())
            .collect(Collectors.toList());
    return statement1;
}
```

## Compose Container Invocation

A `pageObject` type parameter can be used to invoke a container method inside a compose statement.

```json
{
  "elements": [
    {
      "name": "containerElement",
      "type": "container"
    }
  ],
  "methods": [
    {
      "name": "composeContainerHardcoded",
      "compose": [
        {
          "element": "containerElement",
          "args": [
            {
              "type": "pageObject",
              "value": "utam-tests/pageObjects/myPageObject"
            }
          ],
          "returnType": "utam-tests/pageObjects/myPageObject"
        }
      ]
    },
    {
      "name": "composeContainer",
      "compose": [
        {
          "element": "containerElement",
          "args": [
            {
              "type": "pageObject",
              "name": "pageObjectCtor"
            }
          ]
        }
      ]
    }
  ]
}
```

Generated JavaScript code:

```js
// declaration
composeContainerHardcoded(): Promise<unknown>;
composeContainer<T extends _UtamBasePageObject>(pageObjectCtor: _PageObjectCtor<T>): Promise<unknown>;

// implementation
import _MyPageObject from 'utam-tests/pageObjects/myPageObject';

async composeContainerHardcoded() {
    const _result0 = await this.__getContainer(_MyPageObject);
    return _result0;
}

async composeContainer(pageObjectCtor) {
    const _result0 = await this.__getContainer(pageObjectCtor);
    return _result0;
}
```

## Compose Entering Frame

Frame and Root Page Object type parameters can be used to compose entering a frame:

```json
{
  "elements": [
    {
      "name": "frameElement",
      "type": "frame",
      "selector": {
        "css": "#frame"
      }
    }
  ],
  "methods": [
    {
      "name": "composeEnterFrameHardcoded",
      "compose": [
        {
          "element": "document",
          "returnType": "utam-tests/pageObjects/frameArea",
          "apply": "enterFrameAndLoad",
          "args": [
            {
              "type": "elementReference",
              "value": "frameElement"
            },
            {
              "type": "rootPageObject",
              "value": "utam-tests/pageObjects/frameArea"
            }
          ]
        }
      ]
    },
    {
      "name": "composeEnterFrame",
      "compose": [
        {
          "element": "document",
          "returnType": "rootPageObject",
          "apply": "enterFrameAndLoad",
          "args": [
            {
              "type": "frame",
              "name": "frameElementParameter"
            },
            {
              "type": "rootPageObject",
              "name": "pageObjectCtor"
            }
          ]
        }
      ]
    }
  ]
}
```

Generated JavaScript code:

```js
// declaration
import _FrameArea from 'utam-tests/pageObjects/frameArea';

composeEnterFrameHardcoded(): Promise<_FrameArea>;
composeEnterFrame<T extends _UtamBaseRootPageObject>(frameElementParameter: _FrameUtamElement, pageObjectCtor: _PageObjectCtor<T>): Promise<T>;


// implementation
import _FrameArea from 'utam-tests/pageObjects/frameArea';

async composeEnterFrameHardcoded() {
    const _statement0 = await this.getDocument();
    const _result0 = await _statement0.enterFrameAndLoad(await this.__getFrameElement(), _FrameArea);
    return _result0;
}

async composeEnterFrame(frameElementParameter, pageObjectCtor) {
    const _statement0 = await this.getDocument();
    const _result0 = await _statement0.enterFrameAndLoad(frameElementParameter, pageObjectCtor);
    return _result0;
}
```

<!-- document id=70bea40d7bf37f515c712166a7a4af878a8c879bacc556869f6a405485c656a1 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-compose-intro.md -->

# Composition

You can add components within the body of another component. Composition enables you to build complex components from simpler building-block components.

**note:** Inheritance is allowed, but it isn’t recommended because composition is usually more effective. To share logic between components, use a module that contains only logic. See [Additional JavaScript Files](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript-share.md). If you do choose to use inheritance, note that it doesn’t work across namespaces under Lightning Locker. You must enable Lightning Web Security (LWS) to use inheritance across namespaces. You can’t extend the `lightning` namespace in either security architecture.

When composing components, a template owner can nest components inside of a container component. The container component is known as the parent component, and each of the nested components are called child components. See [Compose Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-compose.md).

Additionally, a parent component can:

- [Set properties on children](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-data-binding.md)
- [Call methods on children](https://developer.salesforce.com/docs/platform/lwc/guide/create-javascript-methods.md)
- [Spread properties on children](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-spread-properties.md)
- [Pass markup into slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md)

To check your component dependencies in an org, see [View Component Dependencies](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-view-dependencies.md).

**See Also**

- [Compose Components Using Slots Vs Data](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-best-composition.md)
- [Lightning Web Components Video Gallery: Parent-Child Components](https://developer.salesforce.com/tv/lwc-video-gallery)

<!-- document id=8b627c1b7e34faf31d18010238ad72ae135cdcc978c5b86c5a59b367dbcccc69 url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks-render.md -->

# Conditionally Render a Template

Call the `render()` method to update the UI. You can call it before or after `connectedCallback()`.

It’s rare to define `render()` in a component. The main use case is to conditionally render a template. Define business logic to decide which template (HTML file) to use. The method must return a valid HTML template.

For example, imagine that you have a component that can be rendered in two different ways but you don’t want to mix the HTML in one file. Create multiple HTML files in the component bundle. Import them both and add a condition in the `render()` method to return the correct template depending on the component’s state.

For a code sample, see [Render Multiple Templates](https://developer.salesforce.com/docs/platform/lwc/create/create-render.md).

**note:** The `render()` method is not technically a lifecycle hook. It is a protected method on the `LightningElement` class. A hook usually tells you that something happened, and it may or may not exist on the prototype chain. The `render()` method must exist on the prototype chain.

<!-- document id=94bad71434e7224f890c10b6895435d9b46b5767f923ab7ec2a73c1ec157b1c6 url=/developer/current/en-us/lwc/lwc/guides/use/use-analytics-dashboard.md -->

# Configure a Component for CRM Analytics Dashboards

Implement custom functionality using Lightning web components and then use them interactively with CRM Analytics dashboard widgets and steps.

## 1. Add the CRM Analytics Target in the Configuration File

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component, including the setting to allow usage in a CRM Analytics dashboard. Add the `analytics__Dashboard` target to the component’s configuration file. Ensure that the `isExposed` attribute is set to `true` so the component is visible to the CRM Analytics designer UI.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <isExposed>true</isExposed>
    <targets>
        <target>analytics__Dashboard</target>
    </targets>
</LightningComponentBundle>
```

## 2. Set Component Configuration Options

In the [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md), add a `targetConfig` for the `analytics__Dashboard` target. Set the `hasStep` tag to `true` if the component is designed to use CRM Analytics query data from a dashboard step. For each component attribute that is designed to be used by a CRM Analytics dashboard, add `property` tag.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <targetConfig targets="analytics__Dashboard">
        <hasStep>true</hasStep>
        <property name="title" type="String" label="Title" description="Component Title" required="true" />
    </targetConfig>
</LightningComponentBundle>
```

In addition to the common data types, the `analytics__Dashboard` target also supports `Measure` and `Dimension` data types for components with `<hasStep>true</hasStep>`. The dashboard editor is able to choose a column of the given data type from the results of the attached step.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <targetConfig targets="analytics__Dashboard">
        <hasStep>true</hasStep>
        <property name="labelColumn" type="Dimension" label="Label Column" description="Segment Label" required="true" />
    </targetConfig>
</LightningComponentBundle>
```

After completing these steps, add your Lightning web component as a component widget in the CRM Analytics Studio dashboard editor. For more information, see the [Lightning Web Components in CRM Analytics Dashboards](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_lwc_in_db.meta/bi_dev_guide_lwc_in_db/bi_lwc_in_db_overview.htm) developer guide.

<!-- document id=9e909bb84b188d91a55b9d3b20c4b55fd259c2293da8483227ef156e292ee3b2 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-app-builder-dynamic-interactions.md -->

# Configure a Component for Dynamic Interactions in the Lightning App Builder

It takes both admins and developers to make Dynamic Interactions work, but the keystone is a custom source component that defines the properties of the event to be triggered. Add event metadata and properties to your source component to expose the event to the Lightning App Builder, where an admin can then configure the targets and interactions for the event.

Only Lightning web components can be source components, but any component (Aura or LWC) can be a target. To expose an event from a source component, you fire a standard JavaScript CustomEvent in its `.js` file. To make the event discoverable, use Dynamic Interactions-specific metadata in the component `js-meta.xml` file, similar to how properties for builders are exposed.

**note:** For an overview of Dynamic Interactions, see [_Salesforce Help_](https://help.salesforce.com/articleView?id=platform.dynamic_interactions_overview.htm).

## Use Dynamic Interactions to Expose an Event

Dynamic Interactions uses two `targetConfig` subtags that you can put in your source component bundle’s [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) to expose an event.

- `event`
- `schema`

**note:** These subtags are only available for a `targetConfig` with the target `lightning__AppPage`.

Here’s a sample `js-meta.xml` configuration file for an Account List source component. It includes an `itemselected` event, and its schema includes `apiName` and `recordId` as defined in the `.js` file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>52.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Account List</masterLabel>
  <targets>
    <target>lightning__AppPage</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__AppPage">
      <property name="apiName" type="String"/>
      <property name="listViewApiName" type="String"/>
      <event name="itemselected" label="Item Selected" description="This event fires when an item is selected.">
        <schema>
          {
            "type": "object",
            "properties": {
              "recordId": {
                "type": "string",
                "title": "Record ID"
                "description": "Enter an 18-digit record ID."
          },
              "apiName": {
                "type": "string"
              }
            }
          }
        </schema>
      </event>
    </targetConfig>
  </targetConfigs>
  <description>meta xml description</description>
</LightningComponentBundle>

```

## Considerations for the `.js-meta.xml` File

- Dynamic Interactions uses only `type` and `properties` from the schema. All other items in the schema are ignored.
- The only supported property attributes are `type`, `title`, and `description`.
- In the event schema, the only valid property types supported are String, Integer, and Boolean.
- The `event` tag metadata isn’t validated against the `.js` file.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=201b969149265eab4d41700a0cc4d4fc2122c3cee24ad08cda17f1f27895ec7a url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-community-builder.md -->

# Configure a Component for Experience Builder

Make a custom Lightning web component available in Experience Builder, where users can add it to the page. After you configure the component, it’s then available to all Experience Builder sites in your org.

## 1. Define Component Metadata in the Configuration File

A component’s project folder must include a configuration file—[`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)—that defines the metadata values for the component. To use a component in Experience Builder, edit the file to define the component’s design configuration values.

- To make your component usable in Experience Builder, set `isExposed` to `true`. Then, in `targets`, add one of these values as a `target`:
  - `lightningCommunity__Page` to create a drag-and-drop component that appears in the Components panel
  - `lightningCommunity__Page_Layout` to create a page layout component for LWR sites that appears in the Content Layout window
  - `lightningCommunity__Theme_Layout` to create a theme layout component for LWR sites that appears in Settings in the Theme area
- To include properties that are editable when the component is selected in Experience Builder, define `lightningCommunity__Default` in `targets` and define the properties in `targetConfigs`. Only properties defined for the `lightningCommunity__Page` or `lightningCommunity__Page_Layout` targets are editable in Experience Builder.
- For enhanced LWR Experience Cloud sites, make your component’s integer or string property screen-size responsive. Declare both the `screenResponsive` attribute with a value of `true`, and the `exposedTo` attribute with a value of `css`. You then must define media queries by using CSS variables for each screen size, and specify the property values for each view mode using Experience Builder. For more information, see [Make a Custom LWR Component Screen-Size Responsive](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_responsive_properties.htm).

See the complete list of [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

Here’s the sample code for a simple drag-and-drop Hello World component that includes editable properties.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="helloWorld">
    <apiVersion>45.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Hello World</masterLabel>
    <targets>
        <target>lightningCommunity__Page</target>
        <target>lightningCommunity__Default</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningCommunity__Default">
            <property name="string" type="String" default="jsMetaValue"></property>
            <property name="boolean" type="Boolean" default="true"></property>
            <property name="integer" type="Integer" default="5"></property>
            <property name="picklist" type="String" default="value3" datasource="value1,value2,value3"></property>
            <property name="backgroundColor" type="Color" default="#ff00ff"></property>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## 2. Optional: Add an SVG Resource to Your Component Bundle

To define a custom icon for a drag-and-drop component, add an SVG resource to your component’s folder. If you don’t include an SVG resource, the system uses a default icon (![Lightning](https://developer.salesforce.com/media/components_icon.png)) in the Components panel.

![Experience Builder Components panel](https://developer.salesforce.com/media/components_panel.png)

An SVG resource must be named `componentName.svg`. You can only have one SVG per folder.

Here’s a simple red circle SVG resource to go with the “Hello World” component.

```xml
<?xml version="1.0"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">

<svg xmlns="http://www.w3.org/2000/svg"
     width="400" height="400">
  <circle cx="100" cy="100" r="50" stroke="black"
    stroke-width="5" fill="red" />
</svg>
```

## Considerations

For new sites, Strict CSP is set as the default security level in Experience Builder. If your Lightning web component references third-party resources, you must configure the security level in Experience Builder and allowlist hosts as appropriate.

Lightning web components in a managed package that aren’t configured with the `lightningCommunity__RelaxedCSP` tag are disabled in the Components panel in Experience Builder for any site with Lightning Locker disabled. For more information, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

When you change the `js-meta.xml` file of a custom Lightning web component, certain changes can cause the component to break in a site or managed package, regardless of whether the site is published or the managed package is installed. Before you update a component’s `js-meta.xml` file, make sure that the component isn’t in use in a site or managed package.

These are the changes that you can’t make for a custom component that’s used in a site or managed package.

- You can’t add a new `<property>` tag with `required=true`.
- You can’t remove an existing `<property>` tag.
- When you modify an existing `<property>` tag:
  - You can’t specify `required=true` if the property isn’t already specified with `required=true`.
  - You can’t remove a default value if the property is already specified with `required=true` and a default value.
- When you modify an existing `<property>` tag for `min` or `max` values:
  - You can’t specify a `min` value if the property doesn’t already have a specified `min` value.
  - If the property has a specified `min` value, you can’t update it to a greater `min` value.
  - You can’t specify a `max` value if the property doesn’t already have a specified `max` value.
  - If the existing property has a specified `max` value, you can’t update it to a lesser `max` value.

**note:** These strict validations limit any future modifications to a component’s `js-meta.xml` file. So it’s especially important to make sure that your custom component is production-ready before you add it to a managed package.

If the component is used in a site but not in a managed package, you can make these updates. However, first you must remove the component from the site. Then make the updates, redeploy the component to your org, and add the component back to the site.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Get Information About the Current Experience Builder Site](https://developer.salesforce.com/docs/platform/lwc/create/create-community-info.md)
- [Component SVG Icon](https://developer.salesforce.com/docs/platform/lwc/create/create-components-svg-icon.md)
- [_Salesforce Help_: Experience Builder Overview](https://help.salesforce.com/articleView?id=community_designer_overview.htm&type=5)
- [_Salesforce Help_: CSP and Lightning Locker in Experience Builder Sites](https://help.salesforce.com/articleView?id=networks_security_csp_overview.htm)
- [Experience Cloud Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_intro.htm)
- [LWR Sites for Experience Cloud](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/intro.htm)
- [_LWR Sites for Experience Cloud_: Create Custom Layout Components](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_layout.htm)—use slots to expose drop regions in Experience Builder

<!-- document id=36070c75f7de39772fcf3a750e794319a6e6f9ec89970ab57a249b1e184c5299 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-flow-screens.md -->

# Configure a Component for Flow Screens

To use a custom Lightning web component in a flow screen, add some metadata to the component’s configuration file.

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component, including the design configuration for components intended for use in flow screens.

- To make your component usable in a flow screen, add the `lightning__FlowScreen` target.
- To add input fields to your component, add `targetConfig` properties.
- To restrict a property to `inputOnly` or `outputOnly`, use the `role` attribute. For example, if a property is restricted to `outputOnly`, users can’t set its value from a Lightning record page. If you don’t specify the `role` attribute, the default value allows input and output.

See the complete list of [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

This sample component has four flow screen input fields. The `startDate` property is set to `inputOnly`. The `name` property is set to the `New Account` default value.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>47.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Best Component Ever</masterLabel>
  <description>This is a demo component.</description>
  <targets>
    <target>lightning__FlowScreen</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__FlowScreen">
      <property name="startDate" label="Start Date" type="Date" role="inputOnly" />
      <property name="account" label="Account Chosen" type="@salesforce/schema/Account" />
      <property name="annualRevenue" label="Annual Revenue" type="Integer" role="outputOnly" />
      <property name="name" label="Account Name" type="String" default="New Account" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

The component's JavaScript file must define the default value for the `name` property to set the default value at run time.

```javascript
import { api, LightningElement } from 'lwc';
export default class BestComponentEver extends LightningElement {

    @api startDate;
    @api account;
    @api annualRevenue;
    
    @api name = 'New Account'; 
}
```

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=c7247dc689cf54162a707730abd1f87efee54b026f9162ed4b533a5364d0ba8b url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-app-builder.md -->

# Configure a Component for Lightning App Builder

There are a few steps to take before you can use your custom Lightning web component on a Lightning page in Lightning App Builder.

## 1. Define Component Metadata in the Configuration File

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component, including the design configuration for components intended for use in Lightning App Builder. Edit the configuration file to:

- Make your component usable in Lightning App Builder and in managed packages.
- Define what types of Lightning pages your component can be used on.
- Configure your component’s properties.
- Set your component’s supported objects.
- (Optional) [Add an AI-related component description](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-agentforce.md).

See the complete list of [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

This sample configuration file makes the component available for all Lightning page types, but restricts support on record pages only for account, opportunity, and warehouse objects. The component has a different set of properties defined for record pages than for app and Home pages.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>47.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Best Component Ever</masterLabel>
  <description>This is a demo component.</description>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__RecordPage">
      <property name="prop1" type="String" />
      <objects>
        <object>Account</object>
        <object>Opportunity</object>
        <object>Warehouse__c</object>
      </objects>
    </targetConfig>
    <targetConfig targets="lightning__AppPage, lightning__HomePage">
      <property name="prop2" type="Boolean" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

The `object` tag doesn't support external objects. For more information, see [`lightning__RecordPage` Target](https://developer.salesforce.com/docs/platform/lwc/reference/targets/targets-lightning-record-page.md).

**note:** When defining a component property, make sure that it has the same type assigned (String, Integer, Boolean) in the `.js` file and in the configuration file. If the assigned types don’t match, the type assignment from the configuration file takes precedence.

## 2. Optional: Add an SVG Resource to Your Component Bundle

To include an SVG resource as a custom icon for your component in the Lightning App Builder component panel, add it to your component’s folder. It must be named `componentName.svg`. You can have only one SVG per folder.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Lightning Web Components Video Gallery: Compose for App Builder](https://developer.salesforce.com/tv/lwc-video-gallery)
- [Component SVG Icon](https://developer.salesforce.com/docs/platform/lwc/create/create-components-svg-icon.md)
- [_Salesforce Help_: Lightning App Builder](https://help.salesforce.com/articleView?id=lightning_app_builder_overview.htm&type=5)

<!-- document id=7cb5782681e911ab0f5636e3fd99ae68129d188294a64e004f34bbfcc06f6c82 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-console-app.md -->

# Configure a Component for Lightning Console App

To use a Lightning web component as a navigation item in a custom console app, define the component’s metadata.

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component. To make your component available as a navigation item, set `isExposed` to true, and define a `lightning__AppPage` target.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
    </targets>
</LightningComponentBundle>
```

After configuring the component, you can [create or edit a custom console app](https://help.salesforce.com/s/articleView?id=service.console_lex_create_custom.htm&type=5) and add your component as a navigation item.

To work with workspace tabs and subtabs programmatically, use the [Lightning Console JavaScript API](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lex_getting_started.htm).

**tip:** The [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes) has examples of working with workspace tabs. Look for components that start with `workspace`, such as [workspaceAPIFocusTab](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/workspaceAPIFocusTab).

**See Also**

- [Configure a Component for the Utility Bar](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-utility-bar.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [_Salesforce Help_: Create and Edit a Custom Lightning Console App](https://help.salesforce.com/s/articleView?id=service.console_lex_create_custom.htm&type=5)

<!-- document id=80b6df5a26c7829e2d690e82c42e1feaadeeb7ae66ad9278be1315fddd526170 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-quick-actions.md -->

# Configure a Component for Quick Actions

On this page, we'll walk through how to set up a Lightning web component to perform a quick action on a record page. This process has two parts: updating the component's XML metadata and creating a quick action in Salesforce Setup.

**note:** You can use a Lightning web component as a quick action on record pages only. You can’t use a Lightning web component as a global quick action.

## Define Component Metadata in its Configuration File

Your component's project folder must include a [`componentName.js-meta.xml` configuration file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) that defines the component's metadata. To use the component as a quick action, update the file as follows.

1.  In the `targets` section, add `lightning__RecordAction` as a `target` to define the Lightning web component as a quick action on a record page.
2.  Add a `targetConfig` and set `targets` to `lightning__RecordAction`.
3.  To define the quick action type, set `actionType` to `ScreenAction` for a screen quick action or `Action` for a headless quick action. If you don’t specify `actionType`, the quick action defaults to a screen action.

This configuration file defines a screen action.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>52.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordAction</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__RecordAction">
      <actionType>ScreenAction</actionType>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

This configuration file defines a headless action.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>52.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordAction</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__RecordAction">
      <actionType>Action</actionType>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

**note:** You can't change the action type after you've defined it in your Lightning web component. For example, a component's action type can't be changed from `Action` to `ScreenAction` or vice versa.

See the complete list of [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

## Create a Quick Action in Salesforce Setup

In Salesforce Setup, [create object-specific actions](https://help.salesforce.com/s/articleView?id=platform.creating_object_specific_actions.htm&type=5) via the Object Manager page.

![Screenshot of the Buttons, Links, and Actions page for the Account object.](https://developer.salesforce.com/media/use_quick_actions_new.png)

Then add the action to the **Salesforce Mobile and Lightning Experience Actions** section of your page layout.

![Screenshot of the Salesforce Mobile and Lightning Experience Actions section for an Account object page.](https://developer.salesforce.com/media/use_quick_actions_section.png)

For more information, see [_Salesforce Help_: Actions in Lightning Experience](https://help.salesforce.com/s/articleView?id=platform.actions_in_lex.htm&type=5). The [Empower Your Users with Quick Actions](https://trailhead.salesforce.com/content/learn/modules/lex_customization/lex_customization_actions) page of the Lightning Experience Customization Trailhead module also describes this Setup step in detail.

**note:** Using a Lightning web component as a quick action isn’t supported in the Salesforce mobile app.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [_Salesforce Help_: Quick Actions](https://help.salesforce.com/articleView?id=platform.actions_overview.htm&type=5)

<!-- document id=7618f031590c49d69a176a6e0d091b07d666ef1031d23f9b682428c250d486a3 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-email-builder-component-steps.md -->

# Configure a Component for the Email Builder

Make a custom Lightning Web Component available in the Pardot Email Content Builder, where users can add it to their email content.

In the component’s configuration file, add the `lightningStatic__Email` target for the Email Content Builder. Set `<isExposed>` to `true`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>53.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__AppPage</target>
    <target>lightningStatic__Email</target>
    <target>lightning__HomePage</target>
  </targets>
</LightningComponentBundle>
```

The `lightningStatic__Email` target adds properties to your component. The properties added to the component are `Boolean`, `Color`, `Integer`, `String`, `HorizontalAlignment`, and `VerticalAlignment`. Access the properties in the component’s template.

<!-- prettier-ignore -->
```html
<template>
  <table …>
    <tr valign={valign}>
      <td>{content}</td>
    </tr>
  </table>
</template>
```

Declare the properties in the component’s `js-meta.xml` file like the example for vertical alignment.

```xml
<!-- sampleCustomComponent.js-meta.xml -->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>53.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__AppPage</target>
    <target>lightningStatic__Email</target>
    <target>lightning__HomePage</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightningStatic__Email">
      <property name="buttonAlignment" type="VerticalAlignment" default="middle" />
    </targetConfig>
  </targetConfigs>
  </LightningComponentBundle>
```

Use the following command in the project directory to prepare the metadata package for the custom component. The folder name created is `custompackage`.

```
sf project convert source -d custompackage
```

Deploy the package to a test org. First, create an alias by logging in to an arbitrary org where you want to deploy the package. Use the following command to log in and name the alias.

```
sf org login web -r http://login.salesforce.com -a isvorg
```

Use the following command to deploy the package to the alias you authorized.

```
sf project deploy --metadata-dir -d custompackage -u isvorg
```

You can verify the deployment is complete by logging in to the target org where you deployed. From Setup, in the Quick Find box, enter `Deployment Status`, and then select **Deployment Status**.

The custom components have been deployed. From Setup, in the Quick Find box, enter `Lightning Components`, and then select **Lightning Components**.

Test the components in a target org to verify that the custom component can be used in Email Content Builder.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [`lightningStatic__Email` Target](https://developer.salesforce.com/docs/platform/lwc/reference/targets/targets-lightning-static-email.md)

<!-- document id=fb40a4d0c7ebafd74d888af0ed63f98b65a585eeda02e7c3dd91d8eff4c27bd1 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-utility-bar.md -->

# Configure a Component for the Utility Bar

To use a Lightning web component as a utility item in an app’s utility bar, define the component’s metadata.

## 1. Define Component Metadata in the Configuration File

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component. To make your component usable as a utility item in the utility bar, set `isExposed` to true, and define a `lightning__UtilityBar` target. To expose editable properties in the App Manager, define the properties in `targetConfigs`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>47.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Sample Utility Bar Component</masterLabel>
  <description>This is a demo component.</description>
  <targets>
    <target>lightning__UtilityBar</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__UtilityBar">
      <property name="prop1" type="Boolean" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

See the complete list of [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

To work with utility bars programmatically, use the [Lightning Console JavaScript API](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lex_getting_started.htm).

## 2. (Optional) Add an SVG resource to your component bundle

Use the SVG resource s a custom icon for your component in the App Manager utility-item picker, where admins browse and select utility items. To add an SVG resource, place a file named `componentName.svg` in your component's folder. Each folder supports only one SVG.

The SVG resource doesn't set the icon that displays in the utility bar at runtime. To set the utility bar icon, open the App Manager, open the utility item's Properties page, and set the **Icon** field. The icon picker shows only icons from the SLDS [utility icon sprite](https://www.lightningdesignsystem.com/icons/#utility). Custom SVG resources don't appear in this picker and don't replace the utility bar icon.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Component SVG Icon](https://developer.salesforce.com/docs/platform/lwc/create/create-components-svg-icon.md)
- [_Salesforce Help_: Add a Utility Bar to Lightning Apps](https://help.salesforce.com/articleView?id=platform.dev_apps_lightning_utilities.htm&type=5)
- [_Salesforce Help_: Create and Edit a Custom Lightning Console App](https://help.salesforce.com/s/articleView?id=service.console_lex_create_custom.htm&type=5)

<!-- document id=ef357c6c65cdf38bced9c5ec1ab2b997e2131e0776bb91912dcffdae5bae09a0 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-agentforce.md -->

# Configure a Component for Use in Setup with Agentforce

Add an AI-related description to your component to make it accessible to Agentforce in Setup. AI component descriptions are used only in orgs that have Setup with Agentforce enabled. For more information, see [Setup with Agentforce](https://help.salesforce.com/s/articleView?id=xcloud.setup_agentforce_overview.htm&type=5).

When Setup with Agentforce is enabled in an org, the Setup agent can analyze and recommend custom components when creating a new Lightning page from a user utterance. For Agentforce to successfully analyze whether your custom component fits the requirements outlined in the user’s utterance, the component must contain an AI-related description of what it does as well as descriptions of its properties.

## Add an AI Description to a Lightning Web Component

In the component’s `js-meta.xml` file, add the `ai` tag set at the top level. Specify the `ai` tag only once. The `ai` tag at the top level contains one `description` tag, and can contain multiple `property` tags. The `description` tag contains the AI-related component description.

Each property tag in the `ai` tag set contains the AI-related description for a single component property, and supports only the `name` and `aiDescription` attributes.

Define the component properties using the `property` tag in the `targetConfig` tag set just like usual.

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>64.0</apiVersion>
  <isExposed>true</isExposed>
  <ai>
      <description>AI component description. Example: The component enables users to add and style text content for dashboards, supporting features such as hyperlinks, bullet points, and text alignment. Ideal for adding formatted text sections such as instructions</description>
      <property name="prop1" aiDescription="AI description for prop1"/>
      <property name="prop2" aiDescription="AI description for prop2"/>
  </ai>
  <targets>
      <target>lightning__AppPage</target>
      <target>lightning__RecordPage</target>
  </targets>
  <targetConfigs>
      <targetConfig targets="lightning__AppPage">
          <property type="String" name="prop1" description="property description"/>
          <property type="String" name="prop2" description="property description"/>

      </targetConfig>
      <targetConfig targets="lightning__RecordPage">
          <property type="String" name="prop1" description="property description"/>
          <property type="String" name="prop2" description="property description"/>
	   <objects>
              <object>Account</object>
              <object>CustomObject__c</object>
          </objects>
          <supportedFormFactors>
              <supportedFormFactor type="Large" />
              <supportedFormFactor type="Small" />
          </supportedFormFactors>

      </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

<!-- document id=fc2feca7cf4f8a28a5543950f91080e77526c212cae016be7c44082da9ba872a url=/developer/current/en-us/lwc/lwc/guides/use/use-config-custom-tab.md -->

# Configure Components for Custom Tabs

To use a Lightning web component as a custom tab in Lightning Experience or in the Salesforce mobile app, add the tab target in the component’s configuration file.

The [`componentName.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) defines the metadata values for the component, including the setting to allow usage in a custom tab. Add the `lightning__Tab` target to the component’s configuration file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
   <targets>
     <target>lightning__Tab</target>
  </targets>
</LightningComponentBundle>
```

**note:** The `lightning__Tab` target doesn't support the `property` and `supportedFormFactor` tags.

After you configure the tab target, [add your Lightning web component as a custom tab](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab-lex.md) in Lightning Experience or the Salesforce mobile app. When the component is available as a custom tab in your app, you can navigate to the tab using the `standard__navItemPage` page reference type.

```javascript
navigateToTab() {
        this[NavigationMixin.Navigate]({
            type: 'standard__navItemPage',
            attributes: {
                apiName: 'My_Custom_Tab'
            }
        });
    }
```

The `apiName` of the custom tab corresponds to the tab name. If you enter the tab label "My Custom Tab" when creating your custom tab, the tab name is "My_Custom_Tab".

**See Also**

- [Add Tabs in Lightning Experience](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab-lex.md)
- [Basic Navigation](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-basic.md)

<!-- document id=44728a4397b0c5dcdf276cce81a09aa9a34c1d805b18990d6d79e5ed0776da50 url=/developer/current/en-us/lwc/lwc/guides/events/events-propagation.md -->

# Configure Event Propagation

After an event is fired, it can propagate up through the DOM. To understand where events can be handled, understand how they propagate.

Events bubble up through the DOM; that’s how children and parents communicate—props down, events up. When an event bubbles, it becomes part of your component's API and every consumer along the event's path must understand the event. It’s important to understand how bubbling works so you can choose the most restrictive bubbling configuration that works for your component.

Lightning web component events propagate according to the same rules as DOM events. Lightning web components use only the bubbling phase. Dispatching events or adding listeners to the capture phase isn't supported. Simply think of the event’s path as starting with your component and then moving to its parent, and then grandparent, and so on.

Event targets don’t propagate beyond the shadow root of the component instance. From outside the component, all event targets are the component itself. However, inside the shadow tree, you can handle events from specific targets in the tree. Depending on where you attach a listener for the event, and where the event happens, you can have different targets.

**note:** This content is adapted from the Salesforce Developer blog post, [**How Events Bubble in Lightning Web Components**](https://developer.salesforce.com/blogs/2021/08/how-events-bubble-in-lightning-web-components).

When you create an event, define event propagation behavior using two properties on the event, `bubbles` and `composed`.

- `Event.bubbles`

  A Boolean value indicating whether the event bubbles up through the DOM or not. Defaults to `false`.

- `Event.composed`

  A Boolean value indicating whether the event can pass through the shadow boundary. Defaults to `false`.

To get information about the event, use these properties and method of the [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) Web API.

- `Event.target`

  The element that dispatched the event.

  Each component’s internal DOM is encapsulated in a [shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md). The shadow boundary is the line between the regular DOM (also called the light DOM) and the shadow DOM. If an event bubbles up and crosses the shadow boundary, the value of `Event.target` changes to represent an element in the same scope as the listener. Event retargeting preserves component encapsulation and prevents exposing a component’s internals.

  For example, a click listener on `<my-button>` always receives `my-button` as the target, even if the click happened on the `button` element.

  <!-- prettier-ignore -->
  ```html
  <!-- myButton.html -->
  <template>
    <button>{label}</button>
  </template>
  ```

- `Event.currentTarget`

  As the event traverses the DOM, this property always refers to the element to which the event handler has been attached.

- `Event.composedPath()`

  An array of the event targets on which listeners are invoked as the event traverses the DOM.

## Static Composition

A static composition doesn't use slots. In this simple example, `c-app` composes `c-parent`, which in turn composes `c-child`.

<!-- prettier-ignore -->
```html
<c-app onbuttonclick={handleButtonClick}></c-app>
```

The parent component in the app handles the button click.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <h2>My app</h2>
  <c-parent onbuttonclick={handleButtonClick}></c-parent>
</template>
```

The parent component contains a wrapper with a child component, both listening for the button click event.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <h3>I'm a parent component</h3>
  <div class="wrapper" onbuttonclick={handleButtonClick}>
    <c-child onbuttonclick={handleButtonClick}></c-child>
  </div>
</template>
```

The child component contains the button with the `onclick` handler.

<!-- prettier-ignore -->
```html
<!-- child.html -->
<template>
  <h3>I'm a child component</h3>
  <button onclick={handleClick}>click me</button>
</template>
```

```javascript
// child.js
handleClick() {
    const buttonclicked = new CustomEvent('buttonclick', {
        //event options
    });
    this.dispatchEvent(buttonclicked);
}
```

The example fires an event, `buttonclick`, from `c-child` when the button is clicked. Event listeners are attached for the custom event on the following elements:

- `body`
- `c-app` host
- `c-parent`
- `div.wrapper`
- `c-child` host

The flattened tree looks like this:

<!-- prettier-ignore -->
```html
<body>
  <!-- Listening for buttonclick event -->
  <c-app>
    <!-- Listening for buttonclick event -->
    #shadow-root
    |  <h2>My app</h2>
    |  <c-parent>
    |    <!-- Listening for buttonclick event -->
    |    #shadow-root
    |    |  <h3>I'm a parent component</h3>
    |    |  <div class="wrapper">
    |    |     <!-- Listening for buttonclick event -->
    |    |     <c-child>
    |    |      #shadow-root 
    |    |      |  <!-- Listening for buttonclick event -->
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |      </c-child>
    |    |    </div>
    |  </c-parent>
  </c-app>
</body>
```

## `bubbles: false` and `composed: false`

The default configuration. The event doesn’t bubble up through the DOM and doesn’t cross the shadow boundary. The only way to listen to this event is to add an event listener directly on the component that dispatches the event.

This configuration is recommended because it’s the least disruptive and provides the best encapsulation for your component.

The event bubbles up to `c-child` only.

<!-- prettier-ignore -->
```html
<body>
  <c-app>
    #shadow-root
    |  <c-parent>
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |     </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>
```

Inspecting `c-child` handlers returns these values on the event.

- `event.currentTarget` = `c-child`
- `event.target` = `c-child`

From here, you can start implementing more permissive configurations, as shown in the next few sections.

**tip:** The [`c-event-with-data` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/eventWithData) in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo consumes a [`c-contact-list-item` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/contactListItem), which creates an event with `bubbles: false` and `composed: false`.

## `bubbles: true` and `composed: false`

The event bubbles up through the DOM, but doesn’t cross the shadow boundary. As a result, both `c-child` and `div.wrapper` can react to the event.

<!-- prettier-ignore -->
```html
<body>
  <c-app>
    #shadow-root
    |  <c-parent>
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |  <!-- Event bubbles up here -->
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |    </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>
```

The event handlers return the following.

**`c-child` handler**

- `event.currentTarget` = `c-child`
- `event.target` = `c-child`

**`div.childWrapper` handler**

- `event.currentTarget` = `div.childWrapper`
- `event.target` = `c-child`

There are two use cases for using this configuration.

- **Create an internal event**

  To bubble an event inside the component’s template, dispatch the event on an element in the template. The event bubbles up to the element’s ancestors inside the template only. When the event reaches the shadow boundary, it stops.

  ```javascript
  // myComponent.js
  this.template.querySelector("div").dispatchEvent(new CustomEvent("notify", { bubbles: true }));
  ```

  The event must be handled in `myComponent.js`. Handlers in the containing component don’t execute because the event doesn’t cross the shadow boundary.

  <!-- prettier-ignore -->
  ```html
  <!-- container.html -->
  <template>
    <!-- handleNotify doesn’t execute -->
    <c-my-component onnotify={handleNotify}></c-my-component>
  </template>
  ```

- **Send an event to a component’s grandparent**

  If a component is [passed into a slot](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md#pass-markup-into-slots), and you want to bubble an event from that component to the template that contains it, dispatch the event on the host element. The event is visible only in the template that contains your component.

  Let’s look at sample code abridged from the `eventBubbling` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/eventBubbling/eventBubbling.html) repo. The component hierarchy from child to grandparent is `c-contact-list-item-bubbling -> lightning-layout-item -> c-event-bubbling`.

  The `c-contact-list-item-bubbling` component dispatches a custom event called `contactselect` with `bubbles: true`.

  The event listener, `oncontactselect` is on its parent, `lightning-layout-item`, and the event is handled in its grandparent, `c-event-bubbling`.

  <!-- prettier-ignore -->
  ```html
  <!-- eventBubbling.html -->
  <template>
    <lightning-card title="EventBubbling" icon-name="standard:logging">
      <template lwc:if={contacts.data}>
        <lightning-layout class="slds-var-m-around_medium">
          <!-- c-contact-list-item-bubbling emits a bubbling event so a single listener on a containing element works -->
          <lightning-layout-item class="wide" oncontactselect={handleContactSelect}>
            <template for:each={contacts.data} for:item="contact">
              <c-contact-list-item-bubbling
                class="slds-show slds-is-relative"
                key={contact.Id}
                contact={contact}
              ></c-contact-list-item-bubbling>
            </template>
          </lightning-layout-item>
        </lightning-layout>
      </template>
    </lightning-card>
  </template>
  ```

  ```javascript
  // contactListItemBubbling.js
  import { LightningElement, api } from "lwc";

  export default class ContactListItemBubbling extends LightningElement {
    @api contact;

    handleSelect(event) {
      // Prevent default behavior of anchor tag click which is to navigate to the href url
      event.preventDefault();
      const selectEvent = new CustomEvent("contactselect", {
        bubbles: true,
      });
      this.dispatchEvent(selectEvent);
    }
  }
  ```

## `bubbles: true` and `composed: true`

The event bubbles up through the DOM, crosses the shadow boundary, and continues bubbling up through the DOM to the document root.

**important:** If an event uses this configuration, the event type becomes part of the component’s public API. It also forces the consuming component and all of its ancestors to include the event as part of their APIs.

Because this configuration bubbles your event all the way to the document root, it can cause name collisions. Name collisions can cause the wrong event listeners to fire.

<!-- prettier-ignore -->
```html
<body>
<!-- Event bubbles up here -->
  <c-app>
  <!-- Event bubbles up here -->
    #shadow-root
    |  <c-parent>
    |  <!-- Event bubbles up here -->
    |    #shadow-root
    |    |  <div class="wrapper">
    |    |  <!-- Event bubbles up here -->
    |    |    <c-child>
    |    |    <!-- Event bubbles up here -->
    |    |      #shadow-root
    |    |      |  <h3>I'm a child component</h3>
    |    |      |  <button>click me</button>
    |    |   </c-child>
    |    |  </div>
    |  </c-parent>
  </c-app>
</body>
```

If you do use this configuration, prefix your event type with a namespace, like `mydomain__myevent`. The HTML event listener would have the awkward name `onmydomain__myevent`.

## `bubbles: false` and `composed: true`

Lightning web components don’t use this configuration.

**See Also**

- [_Javascript.info_: Introduction to Events: Bubbling and capturing](https://javascript.info/bubbling-and-capturing)
- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md)

<!-- document id=61e2153311a9ac487fada0aa9d827f1eb984d2bcbb3c7798881f25d0ebb6cce2 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-markup-actions.md -->

# Configure the Component Markup and Design Resource for a Flow Action

Make your custom Lightning web components available as flow local actions by targeting `lightning__FlowAction`.

Here’s sample code for a simple “Show Toast” component that sets a couple of attributes and displays a toast message on the screen.

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>63.0</apiVersion>
   <isExposed>true</isExposed>
   <targets>
       <target>lightning__FlowAction</target>
   </targets>
   <targetConfigs>
       <targetConfig targets="lightning__FlowAction">
           <property name="toastTitle" type="String" label="Toast title to display" />
           <property name="toastMessage" type="String" label="Toast message to display" />
       </targetConfig>
   </targetConfigs>
</LightningComponentBundle>
```

```
import { api, LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';


export default class ShowToastExampleComponent extends LightningElement {
   @api toastTitle;
   @api toastMessage;

   @api invoke() {
       this.dispatchEvent(new ShowToastEvent({
           title: this.toastTitle,
           message: this.toastMessage,
       }));
   }
}
```

When admins reference this component in a flow, they can pass data between the flow and the LWC component. To set an attribute using values from the flow, use the **Set Input Values** tab. To store an attribute’s value in a flow variable, use the **Store Output Values** tab.

**See Also**

- [Component Reference: `lightning:availableForFlowActions` Interface](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-available-for-flow-actions)
- [Lightning Aura Components Dev Guide: Configure the Client-Side Controller for a Flow Local Action](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_flow_actions_controller.htm)

<!-- document id=8074d0be14babf69320d431fda111e270ae26d7a3d8ccf34f5a656d5acca3ddd url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-js-actions.md -->

# Configure the Javascript Class for a Flow Local Action

When a component is executed as a flow local action, the flow calls the invoke method in the javascript class. To run the code asynchronously in your client-side component, such as when you're making an XML HTTP request (XHR), return a Promise. When the Promise is fulfilled, control is returned back to the flow.

## Asynchronous Code

When the Promise is resolved, the next element in the flow is executed. When the Promise is rejected or hits the timeout, the flow takes the local action's fault connector and sets the error message to `$Flow.FaultMessage`.

The default error message is `An error occurred when the elementName element tried to execute the c-myComponent component.` To customize the error message in `$Flow.FaultMessage`, return it as a new Error object in the `reject()` call.

```
import { api, LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';


export default class ShowToastExampleComponent extends LightningElement {
   @api toastTitle;
   @api toastMessage;

   @api invoke(cancelToken) {
       return new Promise((resolve, reject) => {

           // If the Promise times out, abort the request and
           // pass set $Flow.FaultMessage to "Request timed out"
           cancelToken.promise.then(error => {
// Here is where you can clean up ongoing async requests and customize the fault message in the event of a timeout
               reject(new Error("Request timed out."));
           });

           // Do your asynchronous work and call resolve() or reject("Custom error message") when finished.
           resolve();
       });
   }
}
```

**note:** If you’re making callouts to an external server, add the external server to the allowlist in your org and enable or configure CORS in the external server.

## Synchronous Code

When the method finishes, the next element in the flow is executed.

```
import { api, LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class ShowToastExampleComponent extends LightningElement {
   @api toastTitle;
   @api toastMessage;


   @api invoke() {
       this.dispatchEvent(new ShowToastEvent({
           title: this.toastTitle,
           message: this.toastMessage,
       }));
   }
}
```

**See Also**

- [Lightning Aura Components Dev Guide: Cancel an Asynchronous Request in a Flow Local Action](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_flow_actions_abort.htm)
- [Lightning Aura Components Dev Guide: Using External JavaScript Libraries](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_libs_platform.htm)

<!-- document id=0926836d03422346f82a19feebe2cd7e362fdd0514dfe75f88a2100cae36ee43 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-form-factors.md -->

# Configure Your Component for Different Form Factors

Configure a component to display on a Lightning app page when the page is rendered in desktop format (`Large`), phone format (`Small`), or both.

In the `<targetConfigs>` section of the component’s configuration file, use the `<supportedFormFactors>` tag set to declare which form factors the component supports for a page type.

If you don’t define `<supportedFormFactors>`, the component supports the form factors that the page type supports. However, we recommend defining `<supportedFormFactors>` for each page type.

App and record pages support the `Large` and `Small` form factors. Home pages support only the `Large` form factor.

Components on app and record pages can render on both phone and desktop because those pages support both phone and desktop. Components on Home pages can render only on desktop because Home pages support only desktop.

This sample component is supported on three page types: app, record, and Home. On app pages, it’s configured to render only on devices with a `Small` form factor. When a user views an app page on a device with a `Large` form factor, the component doesn’t render.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>42.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Best Component Ever</masterLabel>
    <description>This is a demo component.</description>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__AppPage">
            <property name="prop2" type="Boolean" />
            <supportedFormFactors>
                <supportedFormFactor type="Small" />
            </supportedFormFactors>
        </targetConfig>
        <targetConfig targets="lightning__RecordPage">
            <property name="prop1" type="String" />
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
            </supportedFormFactors>
        </targetConfig>
        <targetConfig targets="lightning__HomePage">
            <property name="prop3" type="Integer" />
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
            </supportedFormFactors>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

```

**note:** Once a component is in use on a Lightning page, you can only increase the supported form factors for the component, not decrease them.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Access Client Form Factor](https://developer.salesforce.com/docs/platform/lwc/create/create-client-form-factor.md)

<!-- document id=cd4ed9879aac887ba4732a71486891e9d600f189f655a13fa9db36b0b7cd1819 url=/developer/current/en-us/lwc/lwc/guides/use/use-dialog-confirm.md -->

# Confirm Modals

Use a confirm modal to ask users to respond before they continue. The confirm modal is displayed as a dialog on top of the page content using an overlay.

To display a confirm modal in Lightning Experience, import `LightningConfirm` from the `lightning/confirm` module, and call `LightningConfirm.open()` with your desired attributes.

`LightningConfirm` is an alternative to the native `window.confirm()` function, which isn’t supported for cross-origin iframes in Chrome and Safari. Unlike the native confirm function, `LightningConfirm.open()` doesn't halt execution on the page, it returns a promise. Use `async`/`await` or `.then()` for any code you want to execute after the confirm modal is closed.

![A headerless confirm modal over a darkened org.](https://developer.salesforce.com/media/dialog_confirm_example.png '{"class": "image-full", "title": "A headerless confirm modal"}')

This example component creates a button that opens the confirm modal that you see in the screenshot.

<!-- prettier-ignore -->
```html
<!-- c/myApp.html -->
<template>
  <lightning-button 
      onclick={handleConfirmClick} 
      label="Open Confirm Modal">
  </lightning-button>
</template>
```

Import `LightningConfirm` from `lightning/confirm` in the JavaScript file of the component that opens the confirm modal. Create and dispatch a `LightningConfirm` event with `message`, `variant`, and `label` attributes. The `.open()` function returns a promise that resolves to `true` when you click **OK** and `false` when you click **Cancel**.

```javascript
// c/myApp.js
import { LightningElement } from "lwc";
import LightningConfirm from "lightning/confirm";

export default class MyApp extends LightningElement {
  async handleConfirmClick() {
    const result = await LightningConfirm.open({
      message: "This is the confirmation message.",
      variant: "headerless",
      label: "This is the aria-label value",
      // label value isn't visible in the headerless variant
    });
    // confirm window has been closed
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [miscNotificationModules](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscNotificationModules) component that demonstrates confirm modals.

For information about the attributes for `LightningConfirm`, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-confirm?type=Specifications.

**See Also**

- [Component Reference: `lightning/confirm`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-confirm)

<!-- document id=cb766e47e975f9cff146ab57018073b587f08e359dc5d940c0d37b8569562ea8 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-considerations.md -->

# Considerations and Limitations

It’s important to remember that the purpose of template expressions is to help you write maintainable code. Keeping presentation-only expressions in the component template is a good way to do this, but not if your expressions are so complex you can’t read them. Use your best judgement for what works for you and your development team, both today, and six weeks after the last time you looked at your markup.

Additionally, while template expressions offer enhanced capabilities, certain limitations exist to maintain performance and security.

## Version Requirement

Complex template expressions are supported for components with API version 66.0 and later. Components with API versions before 66.0 in their `js-meta.xml` file don’t support complex expressions. Expression evaluation falls back to basic property binding. Attempting to use a complex expression on a component with a lower API version will result in compiler errors.

## `this` Keyword

The `this` keyword isn’t allowed in template expressions.

```html
<!-- ❌ Invalid -->
<div>{this.property}</div>
<!-- Error: 'this' is not allowed in template expressions -->

<!-- ✅ Valid - direct property access -->
<div>{property}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class ThisKeywordComponent extends LightningElement {
  property = "value";
}
```

## Function Declarations

Only arrow functions are supported, not function declarations.

```html
<!-- ❌ Invalid -->
<div>{function getName() { return 'John'; }()}</div>
<!-- Error: Function declarations are not allowed in template expressions -->

<!-- ✅ Valid -->
<div>{(() => 'John')()}</div>
```

## Block Body Arrow Functions

Arrow functions with block bodies aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{items.map(item => { return item.name; })}</div>
<!-- Error: Arrow functions with block bodies are not allowed -->

<!-- ✅ Valid -->
<div>{items.map(item => item.name)}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class BlockBodyComponent extends LightningElement {
  items = [{ name: "Item 1" }, { name: "Item 2" }, { name: "Item 3" }];
}
```

## Async Arrow Functions

Async arrow functions aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{async () => await fetchData()}</div>

<!-- ✅ Use component methods instead -->
<div>{asyncData}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class AsyncArrowComponent extends LightningElement {
  asyncData = "Loading...";

  connectedCallback() {
    this.loadData();
  }

  async loadData() {
    this.asyncData = await this.fetchData();
  }

  async fetchData() {
    // Simulate async operation
    return "Data loaded";
  }
}
```

## Await Expressions

Asynchronous operations aren’t supported in template expressions.

```html
<!-- ❌ Invalid -->
<div>{await fetchData()}</div>

<!-- ✅ Use component methods instead -->
<div>{asyncData}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class AwaitComponent extends LightningElement {
  asyncData = "Loading...";

  connectedCallback() {
    this.loadData();
  }

  async loadData() {
    this.asyncData = await this.fetchData();
  }

  async fetchData() {
    // Simulate async operation
    return "Data loaded";
  }
}
```

## Assignment Operations Outside Arrow Functions

Assignment operators aren’t allowed outside of arrow functions.

```html
<!-- ❌ Invalid -->
<div>{count = count + 1}</div>
<!-- Error: Assignment operators are not allowed outside arrow functions -->
<button>{count += 1}</button>
<!-- Error: Assignment operators are not allowed outside arrow functions -->
```

## Update Operators Outside Arrow Functions

Update operators (`++`, `--`) aren’t allowed outside of arrow functions.

```html
<!-- ❌ Invalid -->
<div>{count++}</div>
<!-- Error: Update operators are not allowed outside arrow functions -->
<button onclick="{foo++}"></button>
<!-- Error: Update operators are not allowed outside arrow functions -->
```

## New Operator

The `new` operator isn’t supported for creating instances.

```html
<!-- ❌ Invalid -->
<div>{new Date()}</div>
<!-- Error: 'new' operator is not allowed in template expressions -->
<button onclick="{() => new Day()}">Set Day</button>
<!-- Error: 'new' operator is not allowed in template expressions -->

<!-- ✅ Use component methods instead -->
<div>{currentDate}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class NewOperatorComponent extends LightningElement {
  currentDate = new Date().toLocaleDateString();
}
```

## Delete Operator

The `delete` operator isn’t supported.

```html
<!-- ❌ Invalid (Use component methods instead) -->
<button onclick="{() => delete baz}"></button>
```

## Throw Statements

Throw statements aren’t supported in template expressions.

```html
<!-- ❌ Invalid -->
<button onclick="{() => throw 'oh no!'}"></button>

<!-- ✅ Use component methods instead -->
<button onclick="{handleError}">Handle Error</button>
```

```javascript
import { LightningElement } from "lwc";

export default class ThrowComponent extends LightningElement {
  handleError = () => {
    try {
      throw new Error("oh no!");
    } catch (error) {
      console.error(error.message);
    }
  };
}
```

## Yield Expressions

Yield expressions aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{yield bar}</div>

<!-- ✅ Use component methods instead -->
<div>{generatedValue}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class YieldComponent extends LightningElement {
  bar = "value";
  generatedValue = "computed value";
}
```

## Super Keyword

The `super` keyword isn’t supported.

```html
<!-- ❌ Invalid -->
<button onclick="{super('duper')}"></button>
```

## Import Statements

Import statements aren’t supported in template expressions.

```html
<!-- ❌ Invalid -->
<button onclick="{() => import('foo').then(doThingWithFoo)}"></button>
```

## Import.meta

The `import.meta` object isn’t supported.

```html
<!-- ❌ Invalid -->
<button onclick="{() => doThing(import.meta.env.SSR)}"></button>
```

## Class Expressions

Class expressions aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{class Bar { method() {} }}</div>
```

## Regular Expression Literals

Regular expression literals aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{/wannabe/g}</div>

<!-- ✅ Use component properties instead -->
<div>{regexPattern}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class RegexComponent extends LightningElement {
  regexPattern = /wannabe/g;
}
```

## BigInt Literals

BigInt literals aren’t supported.

```html
<!-- ❌ Invalid -->
<div>{1n}</div>
<div>{transformBigInt(1n)}</div>

<!-- ✅ Use component methods instead -->
<div>{bigIntValue}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class BigIntComponent extends LightningElement {
  bigIntValue = BigInt(1).toString();

  transformBigInt(value) {
    return value.toString();
  }
}
```

## Comments Inside Expressions

Comments aren’t allowed inside template expressions.

```html
<!-- ❌ Invalid -->
<div>{/* what do you think ? */ someValue}</div>
```

## Comma Operator

The comma operator isn’t supported.

```html
<!-- ❌ Invalid -->
<button onclick="{(one(), two(), three())}"></button>

<!-- ✅ Use component methods instead -->
<button onclick="{executeSequence}">Execute Sequence</button>
```

```javascript
import { LightningElement } from "lwc";

export default class CommaOperatorComponent extends LightningElement {
  executeSequence = () => {
    this.one();
    this.two();
    this.three();
  };

  one() {
    alert("one");
  }
  two() {
    alert("two");
  }
  three() {
    alert("three");
  }
}
```

## Unquoted Expressions in Attributes

Template expressions in attributes must be quoted. Using unquoted template expressions will result in compilation or runtime errors.

```html
<!-- ❌ Error: Complex expression without quotes -->
<div class={isActive ? 'active' : 'inactive'}></div>
<!-- Error: Template syntax error: Expected quoted attribute value -->

<!-- ❌ Error: Function call without quotes -->
<button onclick={handleClick()}>Click me</button>
<!-- Error: Template syntax error: Expected quoted attribute value -->

<!-- ❌ Error: Method call without quotes -->
<input value={user?.getName() ?? 'Enter name'}>
<!-- Error: Template syntax error: Expected quoted attribute value -->

<!-- ✅ Valid - quoted complex expressions -->
<div class="{isActive ? 'active' : 'inactive'}"></div>
<button onclick="{handleClick}">Click me</button>
<input value="{user?.getName() ?? 'Enter name'}">
```

```javascript
import { LightningElement } from "lwc";

export default class QuotingErrorsComponent extends LightningElement {
  isActive = true;
  user = {
    getName() {
      return "John Doe";
    },
  };

  handleClick() {
    console.log("Clicked");
  }
}
```

<!-- document id=7435c1cfd90003e4445934f1e03cf4f13d468c8f49dc4fd53a989269ec4bb4e2 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-considerations-limitations.md -->

# Considerations and Limitations for Custom Property Types and Editors

Before you create a custom property type or editor, review these limitations and known issues.

You can create custom property types and property editors only for custom Lightning web components in Experience Builder sites. You can't create them for Aura components.

For more information about Experience Builder, see [Customize Sites with Experience Builder](https://help.salesforce.com/s/articleView?id=sf.community_designer_overview.htm&type=5) in Salesforce Help. For more information about LWR sites, see the [LWR Sites for Experience Cloud](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/intro.htm) developer guide.

When you include a custom property type or editor in a Lightning web component, the component's `js-meta.xml` file has these limitations.

- You can use custom property types and property editors only in Lightning web components that target `lightningCommunity__Default`. You can't use them in components that target `lightningCommunity__Page_Layout`, `lightningCommunity__Theme_Layout`, or other targets that are unrelated to Experience Builder. If you do, deployment of the component fails.
- If a property references a custom property type or Lightning type (for example, `<property name="myProperty" type="c__customType" />`), you can't specify these attributes in the property. If you do, deployment fails.
  - datasource
  - max
  - min
  - placeholder
- If a property references a custom property editor, you can specify `screenResponsive="true"` for that property. However, in the component property panel, the screen-responsive icon doesn't automatically appear next to that property's label. If you want this icon to be visible next to your custom property editor, add the icon manually.
- Certain features aren't exposed in the new Lightning Types Setup user interface. If you create and deploy a custom `LightningTypeBundle` via Metadata API with these unsupported features, use Metadata API when you update them. Otherwise, some of the unsupported features can disappear.

For more information on the `js-meta.xml` file, see [XML Configuration File Elements](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_configuration_tags).

When a custom property editor or type is invalid, an error message appears in the component property panel in Experience Builder.

![Error message in component property panel](https://developer.salesforce.com/media/use-experience-cloud-error-message.png)

You can find more details on the error's cause in the browser console.

**note:** Custom property types originally were created with `ExperiencePropertyTypeBundle` but are now created with `LightningTypeBundle`. To update those older custom property types, follow the steps in [Migrate from ExperiencePropertyTypeBundle to LightningTypeBundle](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-migrate-experiencepropertytypebundle.md).

Unlike with `ExperiencePropertyTypeBundle`, you can make updates to `LightningTypeBundle`. If the update contains no breaking changes, you can make the update even when the bundle is referenced by a component that's in use in a site or managed package.

However, `LightningTypeBundle` doesn't support custom layouts. If you used `ExperiencePropertyTypeBundle` to create a custom layout in an older component, replace that layout with a supported standard layout.

**See Also**

- _Salesforce Help_: [Considerations for Custom Lightning Types](https://help.salesforce.com/s/articleView?id=platform.lt_consider_limit.htm&type=5)
- [Create a LightningTypeBundle](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-create-lightningtypebundle.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_configuration_tags)
- [Standard Definitions for Layouts](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-standard-layouts.md)

<!-- document id=d310107cc50272561fefe7386ccc89cebb3067e3544beaf689059c39137a4b8c url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-refactor.md -->

# Considerations Before Using LWS-Only Features

Before you go all-in on adopting Lightning Web Security (LWS), remember that when it’s enabled, all custom Lightning components in the org are affected. All your custom components run in the new architecture.

Lightning Web Security can’t be disabled on individual components, and isn’t associated with an API version.

Suppose you refactor one component to take advantage of an LWS-only feature, described in [How Lightning Web Security Compares to Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md), such as importing a module from another namespace. That change isn’t compatible with Lightning Locker, so the component now relies on Lightning Web Security.

If you later discover that another component has issues running with LWS, you can’t solve the problem by going back to Lightning Locker because the refactored component uses features that require LWS.

**warning:** Before enabling LWS in a production org, ensure that all your Lightning components work with LWS. See [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md).

**See Also**

- [Developer’s Blog: Learn MOAR in Spring ’22 with Lightning Web Security](https://developer.salesforce.com/blogs/2022/02/learn-moar-in-spring-22-with-lightning-web-security)

<!-- document id=c7764819833ce826c44c3b8025d5254b752c567ca1400150e35c1e839c902e29 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-email-builder-custom-components-tips.md -->

# Considerations for Custom Components

Certain custom components that work in Lightning App Builder aren’t compatible for use in the Email Content Builder. Review the requirements for existing custom components before enabling them for use in the email builder.

## Unsupported Items

The rendering engine that powers our content builder is run in a secure environment. However, there are limits on what code you can add in the custom component files.

- Any type of DOM API
- The `renderedCallback()` lifecycle hook in `.js` file
- The Web API `fetch()` method in `.js` files
- `<script>` tags in `.html` files
- References to the `window` object in `.js` files
- Base components in the `lightning` namespace
- The wire service using the `@wire` syntax
- Apex classes, except for those that extend [`PicklistEntry`](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_Schema_PicklistEntry.htm) or [`DynamicPicklist`](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_VisualEditor_DynamicPickList.htm)

## CSS File

- SLDS tokens and `:host` selectors aren’t supported.
- We recommend you use a unique class name or prepend CSS class names with a namespace to differentiate from other components.

## Picklists

- Populate a picklist by creating the HTML markup using Apex.
- External callouts from Apex that are used as a picklist data source only work if the following method is overridden: `global override Boolean isValid(Object attributeValue){return true;}`

<!-- document id=e2698897f8e6e65cd87af2be54bf2b09f1f071b88fbee617e3a3658acb5869f0 url=/developer/current/en-us/lwc/lwc/guides/data/refreshview/data-refreshview-considerations.md -->

# Considerations for Using RefreshView API

Keep these considerations in mind when developing features that use RefreshView API.

- Use RefreshView API when you work with Aura components or data from third parties. In those cases, components participating in RefreshView API can use [notifyRecordUpdateAvailable(recordIds)](https://developer.salesforce.com/docs/platform/reference/reference-notify-record-update.md) or [refreshApex](https://developer.salesforce.com/docs/platform/apex/apex-result-caching.md) or both to refresh data that they receive from Lightning Data Service.
- Register the `refresh()` callback with `lightning/refresh` only for the components that you want to participate in the refresh.
- Components aren’t responsible for refreshing their descendants — descendants must register their own callbacks to participate in refresh outside of normal value propagation.
- To allow for scoped refresh trees, containers register similarly to components that want to refresh themselves.

<!-- document id=453fa61ecce6b2606283387f28b58a812da2c04bbbf07cea6139d3101a92492f url=/developer/current/en-us/lwc/lwc/guides/reference/contactsservice/reference-lightning-contactsservice.md -->

# ContactsService API

Access contacts from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how ContactsService works, see [Access Contacts on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_contactsservice.htm).

<!-- document id=e9e61fb1bb24718f6e05a495a3505056b4e0868c16eba692945550b5fe866e8b url=/developer/current/en-us/lwc/lwc/guides/reference/contactsservice/reference-lightning-contactsservice-data-types.md -->

# ContactsService Data Types

ContactsService defines and uses several data types.

## `Contact`

An object representing a contact.

| Property Name  | Type                  | Description                                                                                                  | Example                                                                                                                         |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | String                | A stringified number unique to each contact. Generated by the native device at the time of contact creation. | "42"                                                                                                                            |
| `name`         | `ContactName`         | An object representing a contact's name.                                                                     | `{familyName: "Locklear", givenName: "Awanasa"}`                                                                                |
| `phoneNumbers` | `ContactLabeledValue` | An array of objects containing phone numbers for the contact.                                                | `[{mobile: "2065550100"}, {work: "3435550101"}, { home: "6195550102"}]`                                                         |
| `emails`       | `ContactLabeledValue` | An array of objects containing email addresses for the contact.                                              | `[{personal: "awanasa_locklear_736251@hotmail.com"}, {work: "awanasa_locklear_fake_work_email@employer.com"}]`                  |
| `addresses`    | `ContactAddress`      | An object representing a contact's address.                                                                  | `{type: "work", streetAddress: "415 Mission St", locality: "San Francisco", postalCode: "94105"}`                               |
| `ims`          | `ContactLabeledValue` | An array of objects containing instant messaging (IM) usernames for the contact.                             | `[{hangouts: "a_locklear"}, {telegram: "awanasa.data"}]`                                                                        |
| `orgaizations` | `ContactOrganization` | An object representing a contact's organization.                                                             | `{name: "Main Stage Analytics", department: "Data Engineering", title: "Data Scientist"}`                                       |
| `note`         | String                | A text field for any extra information about the contact.                                                    | `Mother-in-law's neighbor`                                                                                                      |
| `urls`         | `ContactLabeledValue` | An array of objects containing URLs for the contact.                                                         | `[{company_website_1: "www.salesforce.com"}, {company_website_2: "www.tableau.com"}, {company_website_3: "https://slack.com"}]` |

## `ContactName`

An object representing a contact’s name.

| Property Name | Type   | Description                                                                                      | Example         |
| ------------- | ------ | ------------------------------------------------------------------------------------------------ | --------------- |
| `displayName` | String | A string representing the name to be displayed for the contact. Only present on Android devices. | Chan Ming Lewis |
| `familyName`  | String | A string representing the contact’s family name (also known as “surname” or “last name”).        | Lewis           |
| `givenName`   | String | A string representing the contact’s given name (also known as “first name”).                     | Chan            |
| `middleName`  | String | A string representing the contact’s middle name.                                                 | Ming            |
| `namePrefix`  | String | A string representing the contact’s name prefix.                                                 | Mr.             |
| `nameSuffix`  | String | A string representing the contact’s name suffix.                                                 | Jr.             |

## `ContactAddress`

An object representing a contact’s address.

| Property Name   | Type   | Description                                                                                         | Example          |
| --------------- | ------ | --------------------------------------------------------------------------------------------------- | ---------------- |
| `type`          | String | A string representing the type of address for a contact’s address.                                  | "Work"           |
| `streetAddress` | String | A string representing the street address for a contact’s address.                                   | "415 Mission St" |
| `locality`      | String | A string representing the locality (also known as the “city”) for a contact’s address.              | "San Francisco"  |
| `region`        | String | A string representing the region (also known as the “state” or “province”) for a contact’s address. | "California"     |
| `postalCode`    | String | A string representing the postal code for a contact’s address.                                      | "94105"          |
| `country`       | String | A string representing the country for a contact’s address.                                          | "U.S.A."         |

## `ContactOrganization`

An object representing a contact’s organization.

| Property Name | Type   | Description                                                            | Example                  |
| ------------- | ------ | ---------------------------------------------------------------------- | ------------------------ |
| `name`        | String | A string representing the name of a contact’s organization.            | "Salesforce"             |
| `department`  | String | A string representing the department of a contact’s organization.      | "Engineering"            |
| `title`       | String | A string representing the title the contact holds in the organization. | "Senior Program Manager" |

## `ContactLabeledValue`

An object containing a label and a value for a miscellaneous piece of contact information.

| Property Name | Type   | Description                                                                                                                              | Example                                                                                                                                         |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`       | String | The display name that categorizes the data in `value`. In the following examples, `home`, `homepage`, and `work` are `label` properties. | <ul><li>`{home: "6195550102"}`</li><li>`{homepage: "https://developer.salesforce.com"}`</li><li>`{work: "alex_driskell@example.com"}`</li></ul> |
| `value`       | String | The value of the data specified in `label`.                                                                                              | <ul><li>`{home: "6195550102"}`</li><li>`{homepage: "https://developer.salesforce.com"}`</li><li>`{work: "alex_driskell@example.com"}`</li></ul> |

Labels and values are provided by the platform, and aren’t altered by ContactsService. Contacts apps on Android and iOS provide standard labels for fields, such as “home” or “work” for phone numbers and emails, but it’s also possible to enter custom label values. Exercise caution when processing labeled values where you depend on specific label text, or specific formats for values like phone numbers.

## `ContactsServiceOptions`

An object representing configuration details for a ContactsService session.

| Property Name             | Type   | Description                                                                                                                                                                                                                                                                                                         | Example                                                                        |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `permissionRationaleText` | String | Optional parameter, used by Android only. This only appears after an initial denial by the user. To use the default permission message, pass in an empty object.The default permission message is “To import Contacts, permission is needed to access Contacts. Tap **Allow** in the following permissions dialog.” | "The app needs to access your contacts to use contacts-related functionality." |

## `ContactServiceFailure`

An object representing an error that occurred when accessing ContactsService features.

| Property Name | Type                         | Description                                                                                                                                                                                                                                                                                            |
| ------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`        | `ContactsServiceFailureCode` | A value representing the reason for a contacts error. Possible failure codes include the following: <ul><li>`USER_DISMISSED`</li><li>`USER_DENIED_PERMISSION`</li><li>`USER_DISABLED_PERMISSION`</li><li>`USER_RESTRICTED_PERMISSION`</li><li>`SERVICE_NOT_ENABLED`</li><li>`UNKNOWN_REASON`</li></ul> |
| `message`     | String                       | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.                                                                                                                              |

<!-- document id=30aa023116320b8e809f37cd0552a91cd91ee7ef67853e6d14c9977b4a4dfc22 url=/developer/current/en-us/lwc/lightning-components-security/guides/content-security-policy/content-security-policy-intro.md -->

# Content Security Policy Overview

The Lightning Component framework uses Content Security Policy ([CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)) to impose restrictions on content. The main objective is to help prevent cross-site scripting ([XSS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/%3Chttps://www.owasp.org/index.php/Cross-site_Scripting_(XSS)>)) and other code injection attacks.

CSP is a W3C standard that defines rules to control the source of content that can be loaded on a page. All CSP rules work at the page level, and apply to all components and libraries. Web browsers follow CSP rules specified in web page headers to block requests to unknown servers for resources including scripts, images, and other data. CSP directives also apply to client-side JavaScript, for example by restricting inline JavaScript in HTML.

The framework enables these specific CSP rules:

- JavaScript libraries can only be referenced from your org

  - : All external JavaScript libraries must be uploaded to your org as static resources. The `script-src 'self'` directive requires script source to be called from the same origin. For developing Lightning web components, see [Use Third-Party JavaScript Libraries](/docs/platform/lwc/guide/js-third-party-library.html). For developing Aura components, see [Using External JavaScript Libraries](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_libs_platform.htm).

- Resources must be located in your org by default

  - : The `font-src`, `img-src`, `media-src`, `frame-src`, `style-src`, and `connect-src` directives are set to `'self'`. As a result, resources such as fonts, images, videos, frame content, CSS, and scripts must be located in the org by default.

    You can change the CSP directives to permit access to third-party resources by adding trusted URLs (previously CSP Trusted Sites). For more information, see [Manage Trusted URLs](https://help.salesforce.com/s/articleView?id=sf.security_trusted_urls_manage.htm).

    You can’t change the protocol from HTTPS to HTTP for these resources, however.

- HTTPS connections for resources

  - : All references to external fonts, images, frames, and CSS must use an HTTPS URL. This requirement applies whether the resource is located in your org or accessed through a trusted URL.

- Inline JavaScript disallowed

  - : Script tags can’t be used to load JavaScript, and event handlers can’t use inline JavaScript. The `unsafe-inline` source for the `script-src` directive is disallowed. For example, this attempt to use an event handler to run an inline script is prevented:

    ```html
    <button onclick="doSomething()"></button>
    ```

## Browser Support

Not all browsers enforce CSP. For a list of browsers that enforce CSP, see [`caniuse.com`](http://caniuse.com/contentsecuritypolicy).

## Finding CSP Violations

CSP policy violations are logged in the browser’s developer console. If your app’s functionality isn’t affected, you can ignore the CSP violation.

This message is a sample violation.

```
Refused to load the script 'https://externaljs.docsample.com/externalLib.js'
because it violates the following Content Security Policy directive: ...
```

<!-- document id=747593dd63c886c3fe082184cac5109e1912b48a6c78544d95861b2f74bc1128 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-continuations-component-example.md -->

# Continuation Example

Here’s the markup for a component that calls a continuation with the wire service and imperatively after you click a button.

<!-- prettier-ignore -->
```html
<!-- continuationCmp.html -->
<template>
  <lightning-button label="Call Continuation" onclick={callContinuation}> </lightning-button>
  <div>@wire(startRequest) result: {formattedWireResult}</div>
  <div>Imperative result: {formattedImperativeResult}</div>
</template>
```

The HTML contains a button that triggers an imperative call to the continuation. We see more when we look at the JavaScript file next.

Here's the component's JavaScript file.

```javascript
import { LightningElement, wire } from "lwc";
import startRequest from "@salesforce/apexContinuation/SampleContinuationClass.startRequest";
export default class ContinuationComponent extends LightningElement {
  imperativeContinuation = {};

  // Using wire service
  @wire(startRequest)
  wiredContinuation;

  get formattedWireResult() {
    return JSON.stringify(this.wiredContinuation);
  }

  // Imperative Call
  async callContinuation() {
    try {
      this.imperativeContinuation = await startRequest();
      this.error = undefined;
    } catch (error) {
      this.imperativeContinuation = undefined;
      this.error = error;
    }
  }

  get formattedImperativeResult() {
    return JSON.stringify(this.imperativeContinuation);
  }
}
```

This code uses a new import syntax.

```javascript
import startRequest from "@salesforce/apexContinuation/SampleContinuationClass.startRequest";
```

This import statement tells the framework that we're calling an Apex method that can return a continuation. If the `startRequest` Apex method returns a `Continuation` object, the method must be annotated with `@AuraEnabled(continuation=true)`.

The component uses the wire service to call the `startRequest` Apex method. The wire service delegates control flow to the Lightning Web Components engine. When data becomes available from the wire adapter after the continuation executes, the template displays the results. You can use the wire service because `startRequest()` is annotated with `@AuraEnabled(cacheable=true)` in the Apex class.

Since continuations make long-running requests, you might prefer to control when the continuation execution starts by making an imperative call instead of using the wire service. This component uses the wire service and an imperative call. The wire service calls the continuation and caches the result. When you click the button to make the imperative call to the same Apex method, the cached results are returned and displayed in the template.

**See Also**

- [Make Long-Running Callouts with Continuations](https://developer.salesforce.com/docs/platform/lwc/guide/apex-continuations.md)
- [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)

<!-- document id=3c3983f83561ccf55c40fd1f2c4ebd4647873cb9531e733d9c6848aac21cd301 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-continuations-limits.md -->

# Continuation Limits

Because continuations can lead to multiple long-running actions, there are some limits on their usage.

The limits for using continuations in Apex are listed in the [Apex Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Continuation.htm).

Here are a few more limits specific to usage in Lightning web components.

- Up to three callouts per continuation

  - : A single `Continuation` object can contain a maximum of three callouts.

- Serial processing for continuation actions

  - : The framework processes actions containing a continuation serially from the client. The previous continuation invocation must have completed before the next continuation invocation is made. At any time, there can be only one continuation in progress on the client.

- DML operation restrictions

  - : An Apex method that returns a `Continuation` object can't perform any Data Manipulation Language (DML) operations. DML statements insert, update, merge, delete, and restore data in Salesforce. If there is any DML performed within the continuation method, the continuation execution doesn't proceed, the transaction is rolled back, and an error is returned.

    You can perform DML operations in the Apex callback method for the continuation.

**See Also**

- [Make Long-Running Callouts with Continuations](https://developer.salesforce.com/docs/platform/lwc/guide/apex-continuations.md)

<!-- document id=66555270c35afb916e37f6d4bbce1bee9325b3012694af941ecab52b6744b2e4 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-screen-navigate.md -->

# Control Navigation in Flow Screen Components

A flow screen component can control navigation programmatically by dispatching navigation events from the `lightning/flowSupport` module. You can advance to the next screen, go back, pause the flow, or finish it, and you can check which actions are available before firing an event.

## Navigation Events

Import navigation events from `lightning/flowSupport`.

| Event                       | Description                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `FlowNavigationNextEvent`   | Advances to the next screen. If the current screen is the last one, use `FlowNavigationFinishEvent`. |
| `FlowNavigationBackEvent`   | Returns to the previous screen.                                                                      |
| `FlowNavigationPauseEvent`  | Pauses the flow interview and saves its state for later resumption.                                  |
| `FlowNavigationFinishEvent` | Finishes the flow interview and triggers any configured post-flow behavior, such as a redirect URL.  |

## Check Which Actions Are Available

Not every navigation action is available on every screen. For example, the Back action isn't available if the current screen is the first screen, and the Pause action is available only in flows where saving is enabled. Before you fire a navigation event, check whether the corresponding action is available.

Flow Builder passes a list of available actions to your component through the `availableActions` property. Declare it as an `@api` property in your component's JavaScript file.

```javascript
// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  @api availableActions = [];
}
```

The `availableActions` array contains string values for each action the current screen supports: `"NEXT"`, `"BACK"`, `"PAUSE"`, `"FINISH"`.

Use `availableActions` to show or hide navigation buttons and to guard navigation event dispatches.

```javascript
get canGoNext() {
  return this.availableActions.find((action) => action === "NEXT");
}

get canGoBack() {
  return this.availableActions.find((action) => action === "BACK");
}
```

## Dispatch a Navigation Event

Import the events you need, then dispatch them in event handlers.

```javascript
import { LightningElement, api } from "lwc";
import {
  FlowNavigationNextEvent,
  FlowNavigationBackEvent,
  FlowNavigationPauseEvent,
  FlowNavigationFinishEvent,
} from "lightning/flowSupport";

export default class MyNavigationComponent extends LightningElement {
  @api availableActions = [];

  handleNext() {
    if (this.availableActions.find((action) => action === "NEXT")) {
      this.dispatchEvent(new FlowNavigationNextEvent());
    }
  }

  handleBack() {
    if (this.availableActions.find((action) => action === "BACK")) {
      this.dispatchEvent(new FlowNavigationBackEvent());
    }
  }

  handlePause() {
    if (this.availableActions.find((action) => action === "PAUSE")) {
      this.dispatchEvent(new FlowNavigationPauseEvent());
    }
  }

  handleFinish() {
    if (this.availableActions.find((action) => action === "FINISH")) {
      this.dispatchEvent(new FlowNavigationFinishEvent());
    }
  }
}
```

## Hide the Built-In Footer

When your component provides its own navigation buttons, hide the flow screen's built-in footer so that the screen has only one set of navigation controls. In Flow Builder, open the screen element that contains your component. In the **Configure Footer** section, disable **Show Footer**.

## Navigation Event Guidelines

Follow these guidelines when using navigation events.

- Fire navigation events in event handlers or in methods that an event handler invokes.
- Don't fire navigation events outside of event handlers. Doing so leads to a poor user experience.
- Don't fire navigation events in lifecycle hooks such as `connectedCallback` or `renderedCallback`.
- Avoid firing `FlowAttributeChangeEvent` and a navigation event at the same time. There's no guarantee that the component has rendered updated values before navigation begins, which can cause race conditions.

To improve flow performance, consider these best practices.
- Don't use a dummy screen to perform navigation. It leads to poor flow performance.
- Don't include code after dispatching a `FlowNavigationNextEvent`. Navigation moves the user away from the current screen immediately, so any code after the dispatch doesn't run.

If you encounter a scenario where navigation must be done within the initialization phase of the screen because data isn't yet available to Flow Decision Nodes, post a request for an upgrade in [Idea Exchange](https://ideas.salesforce.com/).

**See Also**

- [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens.md)
- [Runtime Considerations for Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-runtime-considerations.md)
- [Best Practices for Reactivity in Screen Flows](https://developer.salesforce.com/docs/platform/lwc/guide/use-best-practices-reactivity.md)
- [Component Reference: lightning-flow-support](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow-support)

<!-- document id=9b33d0bd3653081073b5aca4c118ab910586998aa04ed79db48a0df219cef4d9 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-control-finish-example.md -->

# Control What Happens When a Flow Interview Finishes

By embedding a flow in a custom `lightning-flow` component, you can shape what happens when the flow finishes.

To use this component, build a flow with the Salesforce Flow Builder first. The component includes the navigation buttons Back, Next, Pause, and Finish.

**note:** If your flow has custom Lightning web components or Aura components, then you can’t use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

## Embed a Flow using `lightning-flow`

By default, when a flow user clicks Finish, a new interview starts and the user sees the first screen of the flow again. By embedding a flow in a custom `lightning-flow` component, you can shape what happens when the flow finishes by using the `onstatuschange` event handler.

- To redirect to another page, use the [Navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).
- To control what happens when an auto-launched flow finishes, check for the FINISHED_SCREEN status.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-flow flow-api-name="myFlow" onstatuschange={handleStatusChange}> </lightning-flow>
</template>
```

```javascript
// myComponent.js
handleStatusChange(event) {
    if(event.detail.status === 'FINISHED') {
        // Redirect to another page in Salesforce., or
        // Redirect to a page outside of Salesforce., or
        // Show a toast, or something else
    }
}
```

## Example: Navigate to a Record When the Flow Finishes

This example redirects the user to a case created in the flow by using the `lightning/navigation` `NavigationMixin.Navigate` **method**.

```javascript
// myComponent.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class MyComponent extends NavigationMixin(LightningElement) {
  navigateToRecord(recordId) {
    this[NavigationMixin.Navigate]({
      type: "standard__recordPage",
      attributes: {
        recordId,
        actionName: "view",
      },
    });
  }

  handleStatusChange(event) {
    if (event.detail.status === "FINISHED") {
      const outputVariables = event.detail.outputVariables;
      for (let i = 0; i < outputVariables.length; i++) {
        const outputVar = outputVariables[i];
        if (outputVar.name === "redirect") {
          this.navigateToRecord(outputVar.value);
        }
      }
    }
  }
}
```

For more information, see [Navigation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation).

<!-- document id=aff4b35040e3c0efb97ee84dfa9989e328456031a8ba4146cb1555059fc7114f url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-slds-blueprint.md -->

# Create a Component from an SLDS Blueprint

Before you create a component from a blueprint, make sure that there's no other way to meet your use case.

- Examine the list of available base components in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).
- Determine if you can customize the styles on a base component with styling hooks to meet your requirements.

If you can’t find a base component for your use case, find the closest SLDS blueprint to help you build your own custom component.

**important:** When you create a component from a blueprint, the blueprint markup becomes part of your component’s code. If SLDS updates the related blueprint, your component code isn’t updated automatically. To match the latest blueprint, you must manually update your component. Salesforce automatically updates the base components when SLDS updates the associated blueprint.

To build a component from an SLDS blueprint, search the [SLDS blueprints catalog](https://v1.lightningdesignsystem.com/components/overview/) to find the closest design for your component. The blueprints are included only on the SLDS 1 site, and they are the same for SLDS 1 and SLDS 2. Only the values of CSS properties are changed in SLDS 2.

On the SLDS 1 site, an SLDS blueprint is implemented as a base component if it has a **Lightning Component** button (1) in the top-right of the page. Each blueprint provides details for its device support (2)—adaptive, responsive, or desktop-only. An adaptive blueprint has markup for non-desktop breakpoints, while a responsive blueprint scales elegantly across screen sizes.

![SLDS blueprint showing the Lightning Component and device support](https://developer.salesforce.com/media/slds_blueprint.png)

Although base components implement SLDS styling, not all base components are supported for mobile screens. The Targets panel in the [base component documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/) lists the containers that support a component.

For example, the [Data Table SLDS blueprint](https://v1.lightningdesignsystem.com/components/data-tables) is adaptive, but the `lightning-datatable` base component is not mobile-ready. Also, consider the adaptive [Tab SLDS blueprint](https://v1.lightningdesignsystem.com/components/tabs/#On-Mobile) where tabs become stacked on mobile screens and act as buttons. The corresponding `lightning-tabset` base component doesn’t support this mobile behavior.

## Start with the Base Variation

Let’s say you want to create a [scoped notification](https://v1.lightningdesignsystem.com/components/scoped-notifications/), and you know there isn’t a corresponding base component for it. Start with the base variation on the SLDS blueprint and build up from there. First, copy and paste the responsive [base variation markup](https://v1.lightningdesignsystem.com/components/scoped-notifications/#Base) into your template.

```html
<template>
  <div
    class="slds-scoped-notification slds-media slds-media_center slds-scoped-notification_light"
    role="status"
  >
    <div class="slds-media__figure">
      <span class="slds-icon_container slds-icon-utility-info" title="information">
        <svg class="slds-icon slds-icon_small slds-icon-text-default" aria-hidden="true">
          <use href="/assets/icons/utility-sprite/svg/symbols.svg#info"></use>
        </svg>
        <span class="slds-assistive-text">information</span>
      </span>
    </div>
    <div class="slds-media__body">
      <p>
        It looks as if duplicates exist for this lead.
        <a href="javascript:void(0);">View Duplicates.</a>
      </p>
    </div>
  </div>
</template>
```

The blueprints are framework-agnostic, so they use standard HTML elements in the markup. If you create a Lightning web component from a blueprint, replace standard HTML elements with Lightning base components wherever possible.

The notification includes an `svg` icon in the `<div class="slds-media__figure">` tag. Replace the icon with the `lightning-icon` base component.

```html
<template>
  <div
    class="slds-scoped-notification slds-media slds-media_center slds-scoped-notification_light"
    role="status"
  >
    <div class="slds-media__figure">
      <lightning-icon
        icon-name="utility:info"
        alternative-text="information"
        size="small"
      ></lightning-icon>
    </div>
    <div class="slds-media__body">
      <p>
        It looks as if duplicates exist for this lead.
        <a href="javascript:void(0);">View Duplicates.</a>
      </p>
    </div>
  </div>
</template>
```

Move the message to the component’s JavaScript file and bind the `message` property to your template.

```html
<template>
  <div
    class="slds-scoped-notification slds-media slds-media_center slds-scoped-notification_light"
    role="status"
  >
    <div class="slds-media__figure">
      <lightning-icon
        icon-name="utility:info"
        alternative-text="information"
        size="small"
      ></lightning-icon>
    </div>
    <div class="slds-media__body">
      <p>{message}</p>
    </div>
  </div>
</template>
```

```javascript
import { LightningElement, api } from "lwc";

export default class ScopedNotification extends LightningElement {
  @api message = "It looks as if duplicates exist ...";
}
```

## Create Styling Themes and Variations

The scoped notification blueprint includes different themes—light and dark—that you want to capture in your component. Use a getter function to return the class names for a chosen theme.

```javascript
import { LightningElement, api } from "lwc";

export default class ScopedNotification extends LightningElement {
  @api message = "Your message here";
  @api theme = "";

  get scopedNotificationClass() {
    let className = "slds-scoped-notification slds-media slds-media_center";
    if (this.theme === "light") {
      className += " slds-scoped-notification_light";
    }
    if (this.theme === "dark") {
      className += " slds-scoped-notification_dark";
    }
    return className;
  }
}
```

The icon style changes if the theme changes. The dark theme uses the inverse variant. Add a getter to return the correct variant.

```javascript
get iconVariant() {
  let iconVariant = null;

  if (this.theme == 'dark') {
    iconVariant = 'inverse';
  }

  return iconVariant;
}
```

Update the markup so it adapts based on the theme you use. Revise this static markup from the blueprint to use the dynamic styling.

```html
<div
  class="slds-scoped-notification
    slds-media
    slds-media_center
    slds-scoped-notification_light"
  role="status"
></div>
```

Bind the class in the template to the `scopedNotificationClass` getter.

<!-- prettier-ignore -->
```html
<div class={scopedNotificationClass} role="status"></div>
```

Similarly, bind the `lightning-icon` variant attribute to the `iconVariant` getter.

<!-- prettier-ignore -->
```html
<lightning-icon
  icon-name="utility:info"
  alternative-text="information"
  size="small"
  variant={iconVariant}
></lightning-icon>
```

## Implement Your Component

Your component is ready for action. You can use it in another component or include it on a page in [Lightning App Builder](https://developer.salesforce.com/docs/platform/use/use-app-builder.md).

This example uses the `c-scoped-notification` component in another Lightning web component. The `lightning-layout` example provides a responsive grid layout, and `lightning-tabset` corresponds to the [Tabs SLDS blueprint](https://v1.lightningdesignsystem.com/components/tabs/).

```html
<lightning-card>
  <lightning-layout multiple-rows>
    <lightning-layout-item size="12" small-device-size="9" padding="around-small">
      <lightning-tabset>
        <lightning-tab label="Item one">
          <div class="slds-m-bottom_small">
            <c-scoped-notification message="Hello notification!" theme="light">
            </c-scoped-notification>
          </div>
        </lightning-tab>
        <lightning-tab label="Item two"> Tab 2 content here </lightning-tab>
      </lightning-tabset>
    </lightning-layout-item>
    <lightning-layout-item size="12" small-device-size="3" padding="around-small">
      <p>Sidebar Content Goes Here</p>
    </lightning-layout-item>
  </lightning-layout>
</lightning-card>
```

Because we specify `small-device-size="9"`, the content in the first `lightning-layout-item` takes up 75% of the screen width on a tablet or desktop (480 px or more responsive breakpoint). When viewed on a mobile device, `size="12"` adjusts the content to take up 100% of the screen width. See [Creating Responsive Layouts](https://v1.lightningdesignsystem.com/utilities/grid/#Creating-Responsive-Layouts).

<!-- document id=3125f7e90c93003aec3814d5658d275a871ea8ba48799fe721c3cb4388e4ba6d url=/developer/current/en-us/lwc/lwc/guides/data/data-table-custom-types.md -->

# Create a Custom Data Type for `lightning-datatable`

The `lightning-datatable` component formats data based on the type you specify for the column.

Before you create your own data type, check the standard data types to see if one meets your requirements. You can use type attributes to customize the output for many types. The standard data types are:

- `action`
- `boolean`
- `button`
- `button-icon`
- `currency`
- `date`
- `date-local`
- `email`
- `location`
- `number`
- `percent`
- `phone`
- `text` (default)
- `url`

For more information on standard data types and their type attributes, see the [`lightning-datatable` reference documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

Additionally, consider [SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md) before you create your own data type. SLDS styling hooks help you customize a supported data type across the [shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md). For example, you can use an SLDS styling hook to apply a different color on a `button` data type.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

## How to Define Custom Data Types

The `lightning-datatable` component supports these approaches for defining custom types.

- Extend the `LightningDatatable` class. If your use case is simple, create a new datatable component that defines the custom type. A simple use case means the custom type can use a standard cell layout supplied by the datatable, and you don't require use of dynamic custom types. See [Define Your Custom Type by Extending LightningDatatable](#define-your-custom-type-by-extending-lightningdatatable).
- Use a slot. If you want to use dynamic custom types, pass the custom type into the `lightning-datatable` component in a slot. See [Pass in Custom Data Types Using a Slot](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#pass-in-custom-data-types-using-a-slot).

## Define Your Custom Type by Extending `LightningDatatable`

Create your own data type to implement a custom cell, such as a delete row button or an image, or even a custom text or number display. You can also apply a custom class for each row on your custom data type.

To define and use a custom data type, extend the `LightningDatatable` class of the `lightning-datatable` component in a new component.

**note:** You can extend from `LightningDatatable` only to create a datatable with custom data types. Unless stated otherwise, extending any class besides `LightningElement` to create a Lightning web component isn’t supported.

Create a Lightning web component and define your type in an HTML template in the component folder. The template can contain the complete UI for a simple data type that doesn’t require JavaScript. The template can also embed a component that you define in another folder. For example, use a separate component when you want to include logic that determines what to display.

The UI that you include in the template can be whatever suits your use case and usability requirements.

Let’s look at the folder structure for the component `myCustomTypeDatatable`, which defines two custom types.

```ascii
myCustomTypeDatatable
   ├──customName.html
   ├──customNumber.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml
```

In your JavaScript file `myCustomTypeDatatable.js`, extend the `LightningDatatable` class and specify your type’s name and template file. This example creates a custom name type and custom number type using the `customName.html` and `customNumber.html` templates.

**note:** The names of the type and template don't have to match. The example uses `customName` for both the type name and the template file name. We recommend that you import the templates with different names to make it clear where you specify the type name and template name.

```javascript
//myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNameTemplate from "./customName.html";
import customNumberTemplate from "./customNumber.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      standardCellLayout: true,
      typeAttributes: ["accountName"],
    },
    customNumber: {
      template: customNumberTemplate,
      standardCellLayout: false,
      typeAttributes: ["status"],
    },
    // Other custom types here
  };
}
```

**note:** You can extend from `LightningDatatable` only to create custom data types. You can also handle custom data types using slots without extending `LightningDatatable`. See [Pass in Custom Data Types Using a Slot](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#pass-in-custom-data-types-using-a-slot).

Pass in the following properties to the `customTypes` object.

| Custom Type Property | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template`           | string  | The name of your type's imported HTML template.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `typeAttributes`     | array   | The comma-separated list of attributes to pass to the custom data template. Access your data using the `typeAttributes.attributeName` syntax.                                                                                                                                                                                                                                                                                                                                                        |
| `standardCellLayout` | boolean | Specifies whether the standard layout is used. The default is false. The standard layout is used by all standard data types. The default layout for custom data types is the bare layout. See [Customize Data Type Layout and Styles](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types-styling.md). You can use the `standardCellLayout` to style cells for your custom data type to make them look similar to the standard data types. The `standardCellLayout` also supports accessibility and keyboard navigation. |

## Create a Custom Data Template

In your custom data template `customName.html`, add the markup for your data type. This example creates a custom type that renders a text label using a `lightning-badge` component.

<!-- prettier-ignore -->
```html
<!--customName.html-->
<template>
  <lightning-badge label={typeAttributes.accountName} icon-name="standard:account">
  </lightning-badge>
</template>
```

The `customNumber.html` template uses the default bare layout because `myCustomTypeDatatable.js` sets `standardCellLayout: false` for `customNumber`. You can add your own styling. This example adds a small padding around the cell and floats the number to the right. An icon is displayed if the number matches criteria specified in the data definition.

<!-- prettier-ignore -->
```html
<!--customNumber.html-->
<template>
  <div class="slds-p-around_x-small">
    <lightning-formatted-number
      value={value}
      class="slds-float_right"
    ></lightning-formatted-number>
    <lightning-icon
      icon-name={typeAttributes.status}
      alternative-text="Employer Status"
    ></lightning-icon>
  </div>
</template>
```

**tip:** These example custom data types are simple and can be expressed with only HTML. If your custom type is more complex, create a separate component with JavaScript, HTML template, and XML configuration file. Use the custom data HTML template as a container for the component. A separate component is used in [Edit Template Example for Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types-editable-example.md).

## Example: Implement Your Datatable with the Custom Types

Let’s implement a datatable that uses the custom types. The first column displays the account name using the custom type we created in the previous section. The `fieldName` property matches the `Name` field on the account object.

![Record data displayed in a datatable with a custom type](https://developer.salesforce.com/media/datatable_custom.png)

Display 10 account records in the datatable using an Apex controller.

```apex
public with sharing class AccountController {
    @AuraEnabled(cacheable=true)
    public static List<Account> getAccountList() {
        return [SELECT Id, Name, Industry, NumberOfEmployees FROM Account WITH USER_MODE LIMIT 10];
    }
}
```

To implement the custom type datatable, create a wrapper component to contain your extended datatable component, define the datatable’s columns, and fetch data. Here we use `myDatatable` as the wrapper.

When defining the columns, you can pass in SLDS utility classes using the `cellAttributes` property.

```javascript
/* myDatatable.js */
import { LightningElement, wire, track } from "lwc";
import getAccountList from "@salesforce/apex/AccountController.getAccountList";

const COLS = [
  {
    label: "Account Name",
    type: "customName",
    typeAttributes: {
      accountName: { fieldName: "Name" },
    },
  },
  {
    label: "Industry",
    fieldName: "Industry",
    cellAttributes: {
      class: { fieldName: "industryColor" },
    },
  },
  {
    label: "Employees",
    type: "customNumber",
    fieldName: "NumberOfEmployees",
    typeAttributes: {
      status: { fieldName: "status" },
    },
    cellAttributes: {
      class: "slds-theme_alert-texture",
    },
  },
];

export default class MyDatatable extends LightningElement {
  columns = COLS;
  @track accounts = [];

  @wire(getAccountList)
  wiredAccounts({ error, data }) {
    if (error) {
      // Handle error
    } else if (data) {
      // Process record data
      this.accounts = data.map((record) => {
        let industryColor = record.Industry === "Energy" ? "slds-text-color_success" : "";
        let status = record.NumberOfEmployees > 10000 ? "utility:ribbon" : "";
        return { ...record, industryColor: industryColor, status: status };
      });
    }
  }
}
```

`myDatatable.js` shows several ways to apply styling on a custom cell. The `Industry` column uses the `slds-text-color_success` class only if the field value matches `Energy`. The `NumberOfEmployees` column uses the `slds-theme_alert-texture` class on all rows of the column. Additionally, the `customNumber` type that’s used for the `NumberOfEmployees` column includes layout and padding classes implemented directly in the `customNumber.html` markup.

Next, pass the data returned by the `getAccountList` Apex controller to the `data` attribute in your custom type datatable component.

<!-- prettier-ignore -->
```html
<!--myDatatable.html-->
<template>
  <c-my-custom-type-datatable
    key-field="Id"
    data={accounts}
    columns={columns}
    show-row-number-column
  >
  </c-my-custom-type-datatable>
</template>
```

**tip:** The `datatableCustomDataType` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo creates a custom data type for `lightning-datatable`.

## Pass in Custom Data Types Using a Slot

You can determine which custom data types to load dynamically at run time based on context. For example, you can pass one set of data types when the datatable displays data from a specific object and then have a different set of data types for another object.

To dynamically load a custom data type, use a data provider component and pass in your templates via the `customdatatypes` slot. To create a data provider component, import your template files and use an `@api` annotated `getDataTypes()` method in your component class.

```javascript
// myCustomDataTypesProvider.js
import { LightningElement, api } from "lwc";

import customNameTemplate from "./customNameTemplate.html";
import customNumberTemplate from "./customNumberTemplate.html";

export default class MyCustomDataTypesProvider extends LightningElement {
  @api
  getDataTypes() {
    return {
      customName: {
        template: customNameTemplate,
        standardCellLayout: true,
        typeAttributes: ["accountName"],
      },
      customNumber: {
        template: customNumberTemplate,
        standardCellLayout: false,
        typeAttributes: ["status"],
      },
    };
  }
}
```

Return the template names and properties using `getDataTypes()` instead of the `static customTypes` property. You also don’t need to extend `LightningDatatable` to create a custom type.

Your `lightning-datatable` component passes in the custom data types using a `customdatatypes` slot.

```html
<!-- myWrapperDataTable.html -->
<template>
  <lightning-datatable>
    <c-my-custom-data-types-provider slot="customdatatypes"></c-my-custom-data-types-provider>
  </lightning-datatable>
</template>
```

When passing in custom data types using a slot, the `lightning-datatable` component listens to slot changes and updates the columns accordingly.

**tip:** Custom data types passed in a slot can also support keyboard navigation. See [Accessibility for Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.md#accessibility-for-custom-data-types).

## Example: Implement a Datatable with a Dynamic Custom Data Type

Let’s implement a datatable with a button that loads a Contact Picture column using a custom data type.

**tip:** This example modifies the [`datatableCustomDataType` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/datatableCustomDataType) in the lwc-recipes GitHub repo.

![Datatable with a dynamic custom data type](https://developer.salesforce.com/media/datatable_slot_custom_data_type.gif)

When you click the **Add Custom Type** button, the Contact Picture column is only displayed using the `customdatatypes` slot. The button is disabled after you load the custom data type.

Create your custom data type and add the custom data type component in the same folder. For example, the `customProvider.html` file contains an empty `<template>` tag and the `customPicture.html` file contains the UI for a custom data type that displays an image.

```ascii
customProvider
   ├──customProvider.html
   ├──customProvider.js
   ├──customProvider.js-meta.xml
   └──customPicture.html
```

The `customProvider.js` file imports and defines the custom data type within the same folder. It extends `LightningElement` instead of `LightningDatatable`, and it returns the custom data type definition via the public `getDataTypes()` method.

```javascript
//customProvider.js
import { LightningElement, api } from "lwc";
import customPicture from "./customPicture.html";

export default class CustomProvider extends LightningElement {
  @api
  getDataTypes() {
    return {
      customPictureType: {
        template: customPicture,
        standardCellLayout: true,
        typeAttributes: ["pictureUrl"],
      },
      // Other custom types here
    };
  }
}
```

The `customPicture.html` file displays the picture using the `typeAttributes` column property `pictureUrl`.

<!-- prettier-ignore -->
```html
<template>
    <img
        src={typeAttributes.pictureUrl}
        class="slds-avatar slds-avatar_circle slds-avatar_large"
        alt="Profile photo"
    />
</template>
```

Next, create your `lightning-datatable` component wrapper.

```ascii
datatableCustomDataType
   ├──datatableCustomDataType.html
   ├──datatableCustomDataType.js
   └──datatableCustomDataType.js-meta.xml
```

Pass in the custom data type using the `customdatatypes` slot.

<!-- prettier-ignore -->
```html
<!-- datatableCustomDataType.html -->
<template>
    <lightning-card
        title="Datatable Custom Data Type"
        icon-name="custom:custom62"
    >
        <lightning-button label="Add Custom Type" onclick={addCustomTypes} disabled={buttonDisabled}></lightning-button>
        <lightning-datatable
            key-field="Id"
            data={contacts.data}
            show-row-number-column
            column-widths-mode="auto"
            columns={columns}>
            <template if:true={showCustomTypes}>
                <c-custom-provider slot="customdatatypes"></c-custom-provider>
            </template>
        </lightning-datatable>
    </lightning-card>
</template>
```

Define your column data and pass in the `customPictureType` custom data type.

```javascript
// datatableCustomDataType.js
import { LightningElement, wire } from "lwc";
import getContacts from "@salesforce/apex/ContactController.getContactList";

const COLS = [
  { label: "First Name", fieldName: "FirstName" },
  { label: "Last Name", fieldName: "LastName" },
  { label: "Title", fieldName: "Title" },
  { label: "Phone", fieldName: "Phone", type: "phone" },
  { label: "Email", fieldName: "Email", type: "email" },
  {
    label: "Contact Picture",
    type: "customPictureType",
    typeAttributes: {
      pictureUrl: { fieldName: "Picture__c" },
    },
    cellAttributes: { alignment: "center" },
  },
];
export default class DatatableCustomDataType extends LightningElement {
  columns = COLS;

  @wire(getContacts)
  contacts;

  showCustomTypes = false;
  buttonDisabled = false;

  addCustomTypes() {
    this.showCustomTypes = true;
    this.columns = [...COLS];
    this.buttonDisabled = true;
  }
  constructor() {
    super();
    this.columns = [...COLS].filter((col) => col.type != "customPictureType");
  }
}
```

On initialization, the custom data type column is empty because the `showCustomTypes` property is false. The `constructor()` method removes the `customPictureType` column from the `columns` object and the `addCustomTypes()` method sets all columns on the `columns` object.

## Usage Considerations

If the standard data types don't meet your requirements, use a custom data type to define how a cell displays your data. With custom data types, you can also [customize data type layout and styles](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-styling.md). Similar to a standard data type, you can [make a custom data type editable](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-editable.md). To support keyboard navigation in a custom data type, see [Accessibility for Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.md#accessibility-for-custom-data-types).

When sorting with a standard data type, you can identify which column is being sorted via the `onsort` event handler using `event.detail.fieldName`. For an example, see the [lightning-datatable reference documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

However, when sorting a custom data type, you can't use `event.detail.fieldName` as it returns `undefined`. To sort a custom data type, pass in the field name to your sorting function. This example shows how to sort when your custom data type returns the `Picture__c` field name.

```javascript
handleSorting(event) {
    const { fieldName, sortDirection } = event.detail;
    this.sortBy == undefined ? this.sortBy = "Picture__c" : this.sortBy = fieldName;
    this.sortDirection = sortDirection;
    this.sortData(this.sortBy, this.sortDirection);
}
```

Using a `connectedCallback()` method in a custom class that extends `LightningDatatable` overrides the parent `connectedCallback()`
implementation on the `lightning-datatable` component. If you provide your own `connectedCallback()` method,
run `super.connectedCallback()` before your own code to ensure the datatable is initialized correctly.

```javascript
export default class MyCustomTypeDatatable extends LightningDatatable {
  connectedCallback() {
    // Call the parent's connectedCallback() first
    // to ensure the core datatable setup is initialized.
    super.connectedCallback();

    // Add your custom initialization logic here, if needed.
  }
}
```

Using a `lightning-datatable` within a custom data type cell isn't supported. The rendering of a `lightning-datatable` as a child of another `lightning-datatable` leads to undesired style inheritance or styles leaking from the parent data table to the child data table.

**See Also**

- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md)
- [Dispatch a Custom Event From a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-events.md)
- [Datatable Accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.md)

<!-- document id=d01e3daad8b00bc89f6fc37ed648656c0b42c8e914b994d8a02bb76c4008cccf url=/developer/current/en-us/lwc/lwc/guides/data/tree-grid-custom-types.md -->

# Create a Custom Data Type for `lightning-tree-grid`

The `lightning-tree-grid` component uses `lightning-datatable` to format data based on the type you specify for the column.

Before you create your own data type, check the standard data types to see if one meets your requirements. You can use type attributes to customize the output for many types. The standard data types are:

- `action`
- `boolean`
- `button`
- `button-icon`
- `currency`
- `date`
- `date-local`
- `email`
- `location`
- `number`
- `percent`
- `phone`
- `text` (default)
- `url`

For more information on standard data types and their type attributes, see the [`lightning-tree-grid` reference documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree-grid).

**note:** This documentation uses the term _`lightning-tree-grid` component_ and _tree grid_ interchangeably.

## How to Define Custom Data Types

The `lightning-tree-grid` component supports these approaches for defining custom types.

- Extend the `LightningTreeGrid` class. If your use case is simple, create a new tree grid component that defines the custom type. A simple use case means the custom type can use a standard cell layout supplied by the tree grid, and you don't require use of dynamic custom types.
- Use a slot. If you want to use dynamic custom types, pass the custom type into the `lightning-tree-grid` component in a slot. See [Pass in Custom Data Types Using a Slot](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#pass-in-custom-data-types-using-a-slot).

## Define Your Custom Type by Extending `LightningTreeGrid`

Create your own data type to implement a custom cell, such as a custom text or number display. You can also apply a custom class for each row on your custom data type.

To define and use a custom data type, extend the `LightningTreeGrid` class of the `lightning-tree-grid` component in a new component.

**note:** You can extend from `LightningTreeGrid` only to create a tree grid with custom data types. Unless stated otherwise, extending any class besides `LightningElement` to create a Lightning web component isn’t supported.

Create a Lightning web component and define your type in an HTML template in the component folder. The template can contain the complete UI for a simple data type that doesn’t require JavaScript. The template can also embed a component that you define in another folder. For example, use a separate component when you want to include logic that determines what to display.

The UI that you include in the template can be whatever suits your use case and usability requirements.

Let’s look at the folder structure for the component `customDatatypeTreegrid`, which defines two custom types.

```ascii
customDatatypeTreegrid
   ├──customName.html
   ├──customNumber.html
   ├──customDatatypeTreegrid.js
   └──customDatatypeTreegrid.js-meta.xml
```

In your JavaScript file `customDatatypeTreegrid.js`, extend the `LightningTreegrid` class and specify your type's name and template file. This example creates a custom name type and custom number type using the `customName.html` and `customNumber.html` templates.

**note:** The names of the type and template don't have to match. The example uses `customName` for both the type name and the template file name. We recommend that you import the templates with different names to make it clear where you specify the type name and template name.

```javascript
// customDatatypeTreegrid.js
import LightningTreeGrid from "lightning/treeGrid";
import customNameTemplate from "./customName.html";
import customNumberTemplate from "./customNumber.html";

export default class CustomDatatypeTreegrid extends LightningTreeGrid {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      typeAttributes: ["industryName"],
      standardCellLayout: true,
    },
    customNumber: {
      template: customNumberTemplate,
      typeAttributes: ["min"],
    },
  };
}
```

Pass in the following properties to the `customTypes` object.

| Custom Type Property | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template`           | string  | The name of your type's imported HTML template.                                                                                                                                                                                                                                                                                                                                                             |
| `typeAttributes`     | array   | The comma-separated list of attributes to pass to the custom data template. Access your data using the `typeAttributes.attributeName` syntax.                                                                                                                                                                                                                                                               |
| `standardCellLayout` | boolean | Specifies whether the standard layout is used. The default is false. The standard layout is used by all standard data types. The default layout for custom data types is the bare layout. You can use the `standardCellLayout` to style cells for your custom data type to make them look similar to the standard data types. The `standardCellLayout` also supports accessibility and keyboard navigation. |

**note:** The first data column supports custom data types with `standardCellLayout` set to `true` only.

## Create a Custom Data Template

In your custom data template `customName.html`, add the markup for your data type. This example creates a custom type that renders a text label using a `lightning-badge` component.

<!-- prettier-ignore -->
```html
<!-- customName.html -->
<template>
    <template lwc:if={typeAttributes.industryName}>
        <lightning-badge label={typeAttributes.industryName} icon-name="standard:account">
        </lightning-badge>
    </template>
</template>
```

Using the `lwc:if` conditional directive makes sure that the badge is displayed only when the record includes an industry name.

## Create a Nested Custom Data Template

The `customName` example is a simple data type that's expressed with only HTML. Let's take a look at the more complex `customNumber` example, which composes a child component from a separate component bundle.

<!-- prettier-ignore -->
```html
<!-- customNumber.html -->
<template>
    <c-custom-datatype-number value={value}></c-custom-datatype-number>
</template>
```

The child component contains a [`lightning-formatted-number`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number) base component that displays in red or green text color depending on its value. An icon is displayed next to the number based on its value.

<!-- prettier-ignore -->
```html
<!-- customDataTypeNumber.html -->
<template>
    <div class={computedClass}>
        <lightning-formatted-number format-style="currency" value={value}>
        </lightning-formatted-number>
        <template lwc:if={value}>
            <lightning-icon class="slds-p-horizontal_xx-small" icon-name={computedIcon} size="xx-small"
                variant={iconVariant}>
        </lightning-icon>
    </template>
    </div>
</template>
```

The JavaScript file contains the customization for the text colors, icon names, and icon variants.

```javascript
// customDataTypeNumber.js
import { LightningElement, api } from "lwc";

export default class CustomDatatypeNumber extends LightningElement {
  @api value;

  get computedClass() {
    return this.value > 100000000 ? "slds-text-color_success" : "slds-text-color_error";
  }

  get computedIcon() {
    return this.value > 100000000 ? "utility:arrowup" : "utility:arrowdown";
  }

  get iconVariant() {
    return this.value > 100000000 ? "success" : "error";
  }
}
```

## Example: Implement Your Treegrid with the Custom Types

Let's implement a `lightning-tree-grid` component that uses the custom data types. The first column displays the account name using the standard `text` type. The second column uses the `customName` data type and the third column uses the `customNumber` data type. The nested contact names and email use standard data types. The last column is a `button-icon` standard type that displays a record edit modal when clicked.

![Record data displayed in a treegrid with custom types](https://developer.salesforce.com/media/tree-grid-custom-data-types.png)

Display 10 account records with associated contacts in your component using an Apex controller.

```apex
// AccountController.cls
public with sharing class AccountController {
  @AuraEnabled(Cacheable=true)
    public static list<Account> getAccountsWithContacts(){
        return [SELECT Id, Name, Industry, AnnualRevenue, (SELECT Id, FirstName, LastName, Email FROM Contacts) FROM Account WITH USER_MODE LIMIT 10];
    }
}
```

To implement the treegrid with the custom data types, create a wrapper component to contain your extended treegrid component. Define the columns and fetch data. Here we use `accountsTreegrid` as the wrapper component. It extends `NavigationMixin(LightningElement)` so we can use the `lightning/navigation` module to navigate to a record edit modal.

```javascript
// accountsTreegrid.js
import { LightningElement, track, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import getAccountsWithContacts from "@salesforce/apex/AccountController.getAccountsWithContacts";

export default class AccountsTreegrid extends NavigationMixin(LightningElement) {
  accounts;
  error;

  @wire(getAccountsWithContacts)
  wiredAccounts({ error, data }) {
    if (data) {
      this.accounts = data.map((account) => ({
        ...account,
        _children: account.Contacts,
      }));
    } else if (error) {
      this.error = error;
      this.accounts = undefined;
    }
  }
  constructor() {
    super();
    this.columns = [
      {
        type: "text",
        fieldName: "Name",
        label: "Account Name",
      },
      {
        type: "customName",
        label: "Industry",
        typeAttributes: {
          industryName: { fieldName: "Industry" },
        },
      },
      {
        type: "customNumber",
        fieldName: "AnnualRevenue",
        label: "Annual Revenue",
      },
      {
        type: "text",
        fieldName: "FirstName",
        label: "First Name",
      },
      {
        type: "text",
        fieldName: "LastName",
        label: "Last Name",
      },
      {
        type: "email",
        fieldName: "Email",
        label: "Contact Email",
      },

      {
        type: "button-icon",
        typeAttributes: { iconName: "utility:edit", name: "edit", size: "x-small" },
      },
    ];
  }

  handleRowAction(event) {
    if (event.detail.action.name === "edit") {
      this[NavigationMixin.Navigate]({
        type: "standard__recordPage",
        attributes: {
          recordId: event.detail.row.Id,
          objectApiName: "Account",
          actionName: "edit",
        },
      });
    }
  }
}
```

The wrapper component uses `data.map` to create a new array based on the original data retrieved from the Apex controller. For each account in `data`, it creates a new object using the spread operator `...` to copy all existing properties. It then adds the `_children` property with the value of `account.Contacts`. The resulting array is directly assigned to `this.accounts`.

Finally, assign `accounts` on the `data` attribute of the `lightning-tree-grid` component.

<!-- prettier-ignore -->
```html
<!-- accountsTreegrid.html -->
<template>
  <lightning-card title="Treegrid with Custom Data Types" icon-name="utility:table">
    <c-custom-datatype-treegrid
      key-field="Id"
      data="{accounts}"
      columns="{columns}"
      onrowaction="{handleRowAction}"
    >
    </c-custom-datatype-treegrid>
  </lightning-card>
</template>
```

The `handleRowAction` event handler displays a record edit modal using the `lightning/navigation` module.

## Example: Implement a Treegrid with a Dynamic Custom Data Type

Let's implement a `lightning-tree-grid` component that loads a Ratings column using a custom data type. The example adds several buttons that you can click to expand or collapse nested rows. It also adds a Ratings button that you can click to display the Ratings column.

![Treegrid with a dynamic custom data type](https://developer.salesforce.com/media/treegrid-dynamic.gif)

Create your custom data type and add the custom data type component in the same folder. For example, the `customProvider.html` file contains an empty `<template>` tag and the `customRating.html` file contains the UI for the account rating.

```ascii
customProvider
   ├──customProvider.html
   ├──customProvider.js
   ├──customProvider.js-meta.xml
   └──customRating.html
```

The `customProvider.js` file imports and defines the custom data type within the same folder. It extends `LightningElement` instead of `LightningTreeGrid`, and it returns the custom data type definition via the public `getDataTypes()` method.

```javascript
// customProvider.js
import { LightningElement, api } from "lwc";
import customRatingTemplate from "./customRating.html";

export default class CustomProvider extends LightningElement {
  @api
  getDataTypes() {
    return {
      customRating: {
        template: customRatingTemplate,
        standardCellLayout: true,
        typeAttributes: ["optionValue"],
      },
      // Other custom types here
    };
  }
}
```

The `customRating` component composes a child component that renders the corresponding icon for the account rating. It uses the `lwc:if` conditional directive to render the child component only if the account has a rating value passed into the `optionValue` property.

<!-- prettier-ignore -->
```html
<!-- customRating.html -->
<template>
    <template lwc:if={typeAttributes.optionValue}>
        <c-custom-datatype-rating option-value={typeAttributes.optionValue}></c-custom-datatype-rating>  
    </template>
</template>
```

The `option-value` attribute passes the data to the `customDatatypeRating` child component.

```ascii
customDatatypeRating
   ├──customDatatypeRating.html
   ├──customDatatypeRating.js
   └──customDatatypeRating.js-meta.xml
```

This component receives data from the parent component through the `optionValue` property.

<!-- prettier-ignore -->
```html
<!-- customDatatypeRating.html -->
<template>
    <template lwc:if={optionValue}>
        <lightning-dynamic-icon 
          type="trend" 
          option={option}>
    </lightning-dynamic-icon>  
  </template>
</template>
```

In the JavaScript file, the `option` getter function calculates the value of the `option` property. If the account rating that's returned by `optionValue` is `Hot`, the `lightning-dynamic-icon` base component sets the `option` property to `up`, which displays the up trending icon. If the account rating that's returned by `optionValue` is `Warm`, the component displays the neutral trending icon. Otherwise, the component displays the down trending icon for `Cold` and unknown ratings.

```javascript
import { LightningElement, api } from "lwc";

export default class CustomDatatypeRating extends LightningElement {
  @api optionValue;

  get option() {
    return this.optionValue === "Hot" ? "up" : this.optionValue === "Warm" ? "neutral" : "down";
  }
}
```

Finally, create your `lightning-tree-grid` component wrapper.

```ascii
accountsTreegridDynamic
   ├──accountsTreegridDynamic.html
   ├──accountsTreegridDynamic.js
   └──accountsTreegridDynamic.js-meta.xml
```

Pass in the custom data type using the `customdatatypes` slot.

<!-- prettier-ignore -->
```html
<!-- accountsTreegridDynamic.html -->
<template>
  <lightning-card title="Treegrid Dynamic Custom Data Types" icon-name="utility:table">
    <lightning-button-group slot="actions">
      <lightning-button-icon icon-name="utility:expand_all" alternative-text="Expand all" onclick={handleExpandAll}></lightning-button-icon>
      <lightning-button-icon icon-name="utility:collapse_all" alternative-text="Collapse all" onclick={handleCollapseAll}></lightning-button-icon>
      <lightning-button-icon icon-name="utility:trending" alternative-text="Show ratings" onclick={handleCustomRating} disabled={buttonDisabled}></lightning-button-icon>
  </lightning-button-group>
    <lightning-tree-grid
      lwc:ref="treegrid"
      columns={columns}
      data={accounts}
      key-field="Id"
      onrowaction={handleRowAction}
    >
      <c-custom-provider slot="customdatatypes"></c-custom-provider>
    </lightning-tree-grid>
  </lightning-card>
</template>
```

Define your column data and pass in the `customRating` custom data type to the Rating column.

```javascript
import { LightningElement, track, wire } from "lwc";
import getAccountsWithContacts from "@salesforce/apex/AccountController.getAccountsWithContacts";

const COLS = [
  {
    type: "text",
    fieldName: "Name",
    label: "Account Name",
  },
  {
    type: "text",
    fieldName: "FirstName",
    label: "First Name",
  },
  {
    type: "text",
    fieldName: "LastName",
    label: "Last Name",
  },
  {
    type: "email",
    fieldName: "Email",
    label: "Contact Email",
  },
  {
    type: "customRating",
    label: "Rating",
    typeAttributes: {
      optionValue: { fieldName: "Rating" },
    },
  },
];

export default class AccountsTreegridDynamic extends LightningElement {
  accounts;
  error;

  showCustomTypes = false;
  buttonDisabled = false;

  @wire(getAccountsWithContacts)
  wiredAccounts({ error, data }) {
    if (data) {
      this.accounts = data.map((account) => ({
        ...account,
        _children: account.Contacts,
      }));
    } else if (error) {
      this.error = error;
      this.accounts = undefined;
    }
  }
  constructor() {
    super();
    this.columns = [...COLS].filter((col) => col.type != "customRating");
  }

  handleExpandAll() {
    this.refs.treegrid.expandAll();
  }

  handleCollapseAll() {
    this.refs.treegrid.collapseAll();
  }

  handleCustomRating() {
    this.showCustomTypes = true;
    this.columns = [...COLS];
    this.buttonDisabled = true;
  }
}
```

On initialization, the custom data type column is empty because the `showCustomTypes` property is false. The `constructor()` method removes the `customRating` column from the `columns` object and the `handleCustomRating()` method sets all columns on the `columns` object.

Additionally, the `handleExpandAll()` method calls the `expandAll()` public method on the `lightning-tree-grid` component to expand all nested rows. And the `handleCollapseAll()` method calls the `collapseAll()` public method on the `lightning-tree-grid` component. In both cases, the [`lwc:ref` directive](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md#lwccolonrefuniqueid) locates the `lightning-tree-grid` component in the DOM using a unique ID you specify.

<!-- document id=7be6b7aaa475cad8413a0c5f5a8dc1aa298e856f68fb0c4e2ab5f9a59e44536e url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-create-custom-editor.md -->

# Create a Custom Property Editor

To replace the default property editor for a given property type in a custom Lightning web component, create a custom property editor. First create a Lightning web component, including HTML and CSS, to serve as the property editor. Then link your custom property editor back to the component properties that you want to use this editor for.

**See Also**

- [Create Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-introduction.html)
- [Link a Custom Property Editor or Property Type to Your Custom Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-link-editor-type.md)

<!-- document id=d051d0cf67e7351b1f0932fcd71a7c6751026e4a359f5fc720ea0b962632ce9b url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-custom-property-editor-type.md -->

# Create a Custom Property Editor or Type for a Custom Component in Experience Builder

Add custom property editors and property types to your custom Lightning web components to make component configuration more intuitive in Experience Builder. Without custom property editors and Lightning types, property editing options are limited to a few field types, such as text boxes and dropdown menus. With custom property editors, you can create color selectors, sliders, and other types of editors.

<!-- document id=c7ab877f35dc5650151042c10c1dfbaef222d0a5896010044ceddc27c90b1a1f url=/developer/current/en-us/lwc/lwc/guides/data/data-table-tree-grid.md -->

# Create a Hierarchical Table of Record Data

The `lightning-tree-grid` component displays rows of data that can be expanded to reveal child records.

The `lightning-tree-grid` component is built on `lightning-datatable` and supports a subset of its features. See [Display Record Data in a Table](https://developer.salesforce.com/docs/platform/lwc/data/data-table-intro.md) for a comparison of features offered by each component.

## Display Records and Child Records

Let’s create a table that displays accounts with associated cases. Each row-level action enables you to edit the account or case record using the navigation service.

![A data table displaying accounts and associated new cases](https://developer.salesforce.com/media/data_table_tree_grid.png)

Let’s get our data using Apex. In this example, `CaseController.cls` contains a SOQL statement that returns the account names and all associated cases with a status of `New`.

```apex
//CaseController.cls
public with sharing class CaseController {
    @AuraEnabled(cacheable=true)
    public static list<Account> getNewCasesForAccounts(){
        return [SELECT Name, (
                SELECT Id, CaseNumber, Status FROM Cases WHERE toLabel(Status) = 'New')
                FROM Account WHERE Id IN (SELECT AccountId FROM Case)];
    }
}

```

In your JavaScript file `myTreeGrid.js`, use `@wire` to call the Apex method. Define rows that contain child items using the `_children` key. Rows with child items display with a chevron button that toggles the child items.

```javascript
//myTreeGrid.js
import { LightningElement, wire, track } from "lwc";
import { NavigationMixin } from "lightning/navigation";

import getNewCases from "@salesforce/apex/CaseController.getNewCasesForAccounts";

const actions = [{ label: "Edit", name: "edit_record" }];

const COLS = [
  {
    fieldName: "Name",
    label: "Account Name",
  },
  {
    fieldName: "CaseNumber",
    label: "New Cases",
    cellAttributes: {
      iconName: { fieldName: "iconName" },
    },
  },
  {
    type: "action",
    label: "Edit Record",
    typeAttributes: {
      rowActions: actions,
      menuAlignment: "right",
    },
  },
];

export default class MyTreeGrid extends NavigationMixin(LightningElement) {
  @track myData = [];
  columns = COLS;
  error;

  @wire(getNewCases)
  wiredCases({ error, data }) {
    if (error) {
      // Handle error
      this.error = error;
    } else if (data) {
      // Process record data
      var strData = JSON.parse(JSON.stringify(data));

      strData.map((row, index) => {
        if (row["Cases"]) {
          row._children = row["Cases"]; //define rows with children
          delete row.Cases;

          let iconKey = "iconName";
          row[iconKey] = "standard:case";
        }
      });
      this.myData = strData;
    }
  }

  handleRowAction(event) {
    const action = event.detail.action;
    const row = event.detail.row;
    switch (action.name) {
      case "edit_record":
        this[NavigationMixin.Navigate]({
          type: "standard__objectPage",
          attributes: {
            objectApiName: "Case",
            actionName: "edit",
            recordId: row.Id,
          },
        });
        break;
    }
  }
}
```

## Use the `lightning-tree-grid` Component

After you define the rows and columns, you can display your data using the `lightning-tree-grid` component.

<!-- prettier-ignore -->
```html
<!--myTreeGrid.html-->
<template>
  <lightning-tree-grid
    columns={columns}
    data={myData}
    key-field="Id"
    onrowaction={handleRowAction}
  >
  </lightning-tree-grid>
</template>
```

**See Also**

- [_Component Reference_: `lightning-tree-grid`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-tree-grid)

<!-- document id=156480473b4aadc1d751d4b51427068a2f404e450877fa985bd60a51b0a3fc0f url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-create-lightningtypebundle.md -->

# Create a LightningTypeBundle

To create a custom property type, first create a `LightningTypeBundle`. Experience Builder supports only object-based custom `LightningTypeBundle`. It doesn't support Apex-based custom `LightningTypeBundle`.

Only these Lightning types are supported for a custom `LightningTypeBundle`'s nested properties.

- `lightning__booleanType`
- `lightning__dateType`
- `lightning__dateTimeType`
- `lightning__integerType`
- `lightning__multilineTextType`
- `lightning__numberType`
- `lightning__richTextType`
- `lightning__textType`
- `lightning__urlType`

For example, as this code sample illustrates, you can't use `lightning__dateTimeStringType` or a custom property type such as `c__layoutProperty`.

```json
{
  "title": "Container Properties",
  "lightning:type": "lightning__objectType",
  "properties": {
    "borderStyle": {
      "lightning:type": "lightning__textType",
      "title": "Border Style"
    },
    "layoutStyle": {
      "lightning:type": "c__layoutProperty",
      "title": "Layout Style"
    },
    "expiryDate": {
      "lightning:type": "lightning__dateTimeStringType",
      "title": "Expiry Date"
    }
  },
  "required": []
}
```

In the Custom Article component example, here's how the `schema.json` file for the `layoutProperty LightningTypeBundle` is defined. Download the [sample components](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples) to follow along.

```json
{
  "title": "Layout Properties",
  "lightning:type": "lightning__objectType",
  "properties": {
    "borderStyle": {
      "lightning:type": "lightning__textType",
      "title": "Border Style"
    },
    "borderWeight": {
      "lightning:type": "lightning__integerType",
      "title": "Border Weight (px)"
    },
    "borderRadius": {
      "lightning:type": "lightning__integerType",
      "title": "Border Radius (px)"
    },
    "layoutHeight": {
      "lightning:type": "lightning__integerType",
      "title": "Layout Height (px)"
    },
    "layoutWidth": {
      "lightning:type": "lightning__integerType",
      "title": "Layout Width (px)"
    }
  },
  "required": []
}
```

In this example, for the `layoutProperty LightningTypeBundle` to override the editor component for the `borderStyle` property and lay out the properties in a tabset format, create this editor.json file in the experienceBuilder folder.

```json
{
  "editor": {
    "componentOverrides": {
      "borderStyle": {
        "definition": "c/borderStyleDropdownCPE"
      }
    },
    "layout": {
      "definition": "lightning/tabSetLayout",
      "children": [
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Borders"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderStyle"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderWeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderRadius"
              }
            }
          ]
        },
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Size"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutHeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutWidth"
              }
            }
          ]
        }
      ]
    }
  }
}
```

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)
- _Lightning Types Developer Guide_: [Object-Based Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-object.html)
- _Lightning Types Developer Guide_: [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.html)

<!-- document id=c0418a091c2465261ef6224fec9465f65a04e7cc7a0c1d83a522a76b038c187d url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel-intro.md -->

# Create a Message Channel

To create a Lightning message channel, use the LightningMessageChannel metadata type.

## Define Message Channel Metadata in Your Org

To deploy a LightningMessageChannel into your org, create an SFDX project. Include the XML definition in the `force-app/main/default/messageChannels/` directory. The LightningMessageChannel file name follows the format `messageChannelName.messageChannel-meta.xml`.

For an example metadata file, see [Metadata API Developer Guide: LightningMessageChannel](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_lightningmessagechannel.htm).

To add it to your scratch org or another type of org, such as a sandbox or a Developer Edition org, run `sf project deploy start`.

## Import a Message Channel

Here’s how to import a Lightning message channel that a component can use to communicate via the Lightning Message Service.

```javascript
// Basic syntax
import channelName from "@salesforce/messageChannel/channelReference";

// Syntax for resources in a managed package
import channelName from "@salesforce/messageChannel/namespace__channelReference";
```

```javascript
// Examples
import recordSelected from "@salesforce/messageChannel/Record_Selected__c";
import recordSelectedFromPackage from "@salesforce/messageChannel/namespace__Record_Selected__c";
```

**note:** `Record_Selected__c` refers to a custom instance of the LightningMessageChannel metadata type. Although it uses the `__c` suffix, it isn’t a custom object.

- `channelName`—An imported symbol that identifies the message channel.
- `channelReference`—The API name of the message channel in the format `Channel_Name__c`.
- `namespace`—If the message channel is in a managed package, this value is the namespace of the managed package. If the message channel is not in a managed package, do not include a namespace.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [messageChannel-meta.xml example](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/messageChannels).

<!-- document id=d9b86134501a7b2bf907d4cd24e4bbccb0d0f58eaf7b4c2289e3c500e16c4d3e url=/developer/current/en-us/lwc/lwc/guides/data/data-create-record.md -->

# Create a Record

The simplest way to create a form that enables a user to create a record is to use `lightning-record-form`. To customize the form layout or to preload custom values, use `lightning-record-edit-form`.

**tip:** If you need more flexibility than these components provide, see [Build Custom UI to Create and Edit Records](https://developer.salesforce.com/docs/platform/lwc/data/data-salesforce-write.md).

## Create a Record Using `lightning-record-form`

To create a record using `lightning-record-form`, leave out the `record-id` attribute. This example creates a record using import references for the account object and its fields. The form displays a Save button that updates the record, and a Cancel button that reverts changes.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-form
    object-api-name={accountObject}
    fields={myFields}
    onsuccess={handleAccountCreated}
  >
  </lightning-record-form>
</template>
```

The field imports are passed in to the `myFields` array. When you import references, the references are validated at compile time. Place this example on a record page to inherit its `record-id` and `object-api-name` properties.

```javascript
import { LightningElement } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import WEBSITE_FIELD from "@salesforce/schema/Account.Website";

/**
 * Creates Account records.
 */
export default class AccountCreator extends LightningElement {
  accountObject = ACCOUNT_OBJECT;
  myFields = [NAME_FIELD, WEBSITE_FIELD];

  handleAccountCreated() {
    // Run code when account is created.
  }
}
```

![Form with Cancel and Save buttons](https://developer.salesforce.com/media/data_record_form.png)

When data saves successfully, the fields display pencil icons to denote that inline editing is available. This view is displayed until you refresh or reload the page.

![Inline edits](https://developer.salesforce.com/media/data_record_form_editmode.png)

## Create a Record with a Custom Field Layout Using `lightning-record-edit-form`

Use `lightning-record-edit-form` to customize field layout or data rendering.

Pass in the fields you want to `lightning-input-field`, which displays an input control based on the record field type. To enable automatic display of error messages, include the `lightning-messages` component.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-edit-form object-api-name={accountObject} onsuccess={handleAccountCreated}>
    <lightning-messages></lightning-messages>
    <div class="slds-grid">
      <div class="slds-col slds-size_1-of-2">
        <lightning-input-field field-name={nameField}></lightning-input-field>
        <lightning-input-field field-name={websiteField}></lightning-input-field>
      </div>
      <div class="slds-col slds-size_1-of-2">
        <!-- More lightning-input-field components here -->
      </div>
    </div>
    <lightning-button type="submit" variant="brand" label="Create Account"></lightning-button>
  </lightning-record-edit-form>
</template>
```

To access the fields you want, use the field imports from `@salesforce/schema`. Importing references to objects and fields ensures that your code works, even when object and field names change.

```javascript
import { LightningElement } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import WEBSITE_FIELD from "@salesforce/schema/Account.Website";

/**
 * Creates Account records.
 */
export default class AccountCreator extends LightningElement {
  accountObject = ACCOUNT_OBJECT;
  nameField = NAME_FIELD;
  websiteField = WEBSITE_FIELD;

  handleAccountCreated() {
    // Run code when account is created.
  }
}
```

## Prepopulate Field Values Using `lightning-record-edit-form`

To provide a field value when the form displays, use the `value` attribute on `lightning-input-field`.

This example displays a form with a custom value for the account name field. The form creates an account record when the button is clicked.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-edit-form object-api-name="Account">
    <lightning-input-field field-name="Name" value="My Field Value"> </lightning-input-field>
    <lightning-button class="slds-m-top_small" type="submit" label="Create new"> </lightning-button>
  </lightning-record-edit-form>
</template>
```

To programmatically set the value when the form loads, provide the value in JavaScript. This example sets the value using the `myValue` property. You can set this value programmatically later, as shown by the `onclick` event handler, which calls the `overrideValue` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-edit-form object-api-name="Account">
    <lightning-input-field field-name="Name" value={myValue}></lightning-input-field>
    <lightning-button class="slds-m-top_small" type="submit" label="Create new"></lightning-button>
  </lightning-record-edit-form>

  <lightning-button label="Override Value" onclick={overrideValue}></lightning-button>
</template>
```

```javascript
import { LightningElement, api } from "lwc";
export default class FieldValueCreateExample extends LightningElement {
  myValue = "My Account Name";
  overrideValue(event) {
    this.myValue = "My New Name";
  }
}
```

## Reset the Form to the Original Field Values

`lightning-record-edit-form` doesn’t provide its own **Cancel** and **Save** buttons like `lightning-record-form` does. To create your own **Cancel** button that reverts the field values, include a `lightning-button` component that calls the `reset()` method. Replace the `record-id` with your own. For an example, see [Edit a Record](https://developer.salesforce.com/docs/platform/lwc/data/data-edit-record.md).

## Override Default Behaviors Using Custom Events

`lightning-record-edit-form` handles form submission and errors automatically. To display an error message above or below the form fields automatically, include `lightning-messages` before or after your `lightning-input-field` components.

`lightning-record-edit-form` enables you to handle the following custom events.

- `error`—Fired when the form returns a server-side error.
- `load`—Fired when the form loads record data.
- `submit`—Fired when the form submits changed record data.
- `success`—Fired when the form submits changed record data.

For an example, see [Edit a Record](https://developer.salesforce.com/docs/platform/lwc/data/data-edit-record.md).

<!-- document id=7dfba504db0bbe194f0c2d81ef386652001dd662b06dda1ec3ff3f0ab6600492 url=/developer/current/en-us/lwc/lwc/guides/use/use-quick-actions-email.md -->

# Create an Email as a Quick Action

To enable users to send an email from anywhere in Lightning Experience, you can [create a global quick action](https://help.salesforce.com/s/articleView?id=platform.actions_overview_global.htm). Alternatively, you can create an [object-specific email action](https://help.salesforce.com/s/articleView?id=platform.actions_overview_object_specific.htm&type=5). After you create a global or object-specific email action, you can add predefined values and add the action to page layouts.

If the global quick action and object-specific action don't meet your requirements, consider using an LWC quick action. For example, use an LWC quick action if you want to:

- Display prequisite content before displaying the email composer
- Set predefined field values for an email based on user input

The LWC quick email action isn't supported in Experience Builder sites.

## Send an Email with an LWC Quick Action

Use APIs from the [`lightning/navigation` and `lightning/pageReferenceUtils` modules](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate.md) to create a QuickAction (Global) Send Email action, which opens an email draft with pre-populated field values.

In your component’s HTML file, import the navigation services from the `lightning/navigation` module and the page reference utilities from `lightning/pageReferenceUtils`.

Here's a basic syntax example that demonstrates how to display the email composer from an LWC quick action.

```javascript
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";

export default class EmailQuickActionExample extends NavigationMixin(LightningElement) {
  handleClick() {
    var pageRef = {
      type: "standard__quickAction",
      attributes: {
        apiName: "Global.SendEmail",
      },
      state: {
        recordId: "00QB000000BLjUrMAL",
        defaultFieldValues: encodeDefaultFieldValues({
          HtmlBody: "Pre-populated text for the email body.",
          Subject: "Pre-populated Subject of the Email",
          To: "target@example.com",
        }),
      },
    };

    this[NavigationMixin.Navigate](pageRef);
  }
}
```

In this example, the `handleClick` function launches the email composer with pre-populated content on the Subject and Body text.

To include default text in the email composer, use the `encodeDefaultFieldValues` function. To populate the email with input from your component, pass the field values into the `encodeDefaultFieldValues` function.

## Default Email Field Values

By default, Salesforce prepopulates the To field with a contact or lead email address when you open the email action from the contact or lead record home pages. Ensure that the fields you specify in the `encodeDefaultFieldValues` function aren’t Read-Only in the Send Email global action’s layout. If the HTML Body and Subject fields are Read-Only, the email draft doesn’t include pre-populated text for those fields.

These fields are supported:

- `ValidatedFromAddress`
- `ToAddress`
- `CcAddress`
- `BccAddress`
- `Subject`
- `HTMLBody`
- `RelatedToId`

The `ValidatedFromAddress` field accepts an organization-wide email address or the running user's verified email address. The `Subject` and `HTMLBody` fields have no default value.

Only [fields that are available on the email quick action](https://help.salesforce.com/s/articleView?id=sales.send_email_quick_action_fields.htm) are supported. For example, `AttachmentId` and `ContentDocumentIds` aren't supported as they are not part of the email quick action layout.

For more information on the supported fields, see [_Object Reference for the Salesforce Platform_: EmailMessage](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_emailmessage.htm).

## Example: Set the Email Recipient on a Contact

You can set predefined field values for an email based on user input. This example adds the `test@example.com` recipient to the To field.

To use this LWC quick action example, add it to the contact record page. The component retrieves the associated account ID on the contact that's being viewed using `@api recordId`, which makes the component aware of its [record context](https://developer.salesforce.com/docs/platform/lwc/guide/use-record-context.md). To retrieve the associated account ID, use the [`getRecord` wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md).

```
import { LightningElement, api, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";

import { getRecord } from "lightning/uiRecordApi";
import ACCOUNT_ID_FIELD from "@salesforce/schema/Contact.AccountId";

const fields = [ACCOUNT_ID_FIELD];

export default class SendEmailSimple extends NavigationMixin(LightningElement) {
@api recordId;
contact;
accountId;

  @wire(getRecord, { recordId: "$recordId", fields })
  wiredContact({ error, data }) {
    if (error) {
      // handle error
    } else if (data) {
      this.contact = data;
      this.accountId = this.contact.fields.AccountId.value;
      this.handleEmail();
    }
  }

  handleEmail() {
    var pageRef = {
      type: "standard__quickAction",
      attributes: {
        apiName: "Global.SendEmail",
      },
      state: {
        recordId: this.recordId,
        defaultFieldValues: encodeDefaultFieldValues({
          Subject: 'Pre-populated Subject of the Email',
          ToAddress: 'test@example.com',
          RelatedToId: this.accountId
        }),
      },
    };
    this[NavigationMixin.Navigate](pageRef);
  }
}
```

If a contact record includes an email field value, the `ToAddress` field displays both `test@example.com` and the contact's email. The `RelatedToId` field preselects the associated account on the contact if it's available.

## Example: Set the Email Recipient on User Input on an Account

Using an LWC quick action, you can display a helpful message before displaying the email composer. To improve usability, you can also get user input to help determine the field values on your email composer.

![A quick action that displays a record ID and record picker](https://developer.salesforce.com/media/use_quick_action_record_picker.png)

To use this LWC quick action example, add it to the account record page. The component displays a message with the account record ID using `@api recordId`, which makes the component aware of its [record context](https://developer.salesforce.com/docs/platform/lwc/guide/use-record-context.md). It uses the [`lightning-record-picker` base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-picker) to let users search for a contact associated on the account they're viewing. When a user selects a contact, the [`getRecord` wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) retrieves the email for the selected contact and displays the email composer.

```
<template>
  <div class="slds-m-around_medium">
    <p>You are viewing record {recordId}. Please choose an email recipient.</p>
    <lightning-record-picker
      object-api-name="Contact"
      label="Contacts"
      filter={filter}
      display-info={displayInfo}
      onchange={handleEmailChange}
    >
    </lightning-record-picker>
  </div>
</template>
```

The `lightning-record-picker` base component uses the `filter` attribute to filter the searchable contacts to only those contacts that are associated to the account.

In your component's JavaScript, add an event handler using the `standard__quickAction` page reference type. Pass in the default field values using the `state` object.

**note:** This example assumes that an account record has at least one contact. For error handling, see the [`lightning-record-picker` base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-picker).

```
import { LightningElement, api, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";
import { getRecord } from "lightning/uiRecordApi";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";

const fields = [EMAIL_FIELD];

export default class SendEmail extends NavigationMixin(LightningElement) {
  @api recordId;
  @api contactId;
  contact;
  email;
  errors;

  // Limit the filter to contacts with
  // the AccountId that match the account's recordId
  get filter() {
    return {
      criteria: [
        {
          fieldPath: "AccountId",
          operator: "eq",
          value: this.recordId,
        },
      ],
    };
  }

  // Set the labels on the record picker results
  displayInfo = {
    primaryField: "Name",
    additionalFields: ["Title", "Email"],
  };

  // Set the user input on contactId,
  // which is used to retrieve the contact record using getRecord
  handleEmailChange(e) {
    this.contactId = e.detail.recordId;
  }

  // Retrieve the email information for the selected contact
  @wire(getRecord, { recordId: "$contactId", fields })
  wiredContact({ error, data }) {
    if (error) {
      console.log("getRecord error: ", error);
    } else if (data) {
      this.contact = data;
      this.email = this.contact.fields.Email.value;
      this.setEmail();
    }
  }

  // Display the email composer with predefined values,
  // including the retrieved email from the selected contact
  setEmail() {
    var pageRef = {
      type: "standard__quickAction",
      attributes: {
        apiName: "Global.SendEmail",
      },
      state: {
        recordId: this.recordId,
        defaultFieldValues: encodeDefaultFieldValues({
          Subject: "Pre-populated Subject of the Email",
          ToAddress: this.email,
          HtmlBody: "Pre-populated text for the email body."
        }),
      },
    };
    this[NavigationMixin.Navigate](pageRef);
  }
}
```

To make this component available as a quick action, update the `.js-meta.xml` configuration file.

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__RecordAction</target>
      </targets>
      <targetConfigs>
        <targetConfig targets="lightning__RecordAction">
          <actionType>ScreenAction</actionType>
        </targetConfig>
      </targetConfigs>
</LightningComponentBundle>
```

Alternatively, you can create the email as a [headless action](https://developer.salesforce.com/docs/platform/lwc/guide/use-quick-actions-headless.md), which opens a modal with the email composer directly. Opening a modal that displays an email composer is similar to the [global Send Email action](https://help.salesforce.com/s/articleView?id=platform.actions_overview_global.htm).

**See Also**

- [Configure a Component for the Email Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-email-builder-component-steps.md)
- [_Salesforce Help_: Lightning Web Component Action](https://help.salesforce.com/s/articleView?id=platform.lightning_web_component_actions.htm)
- [_Salesforce Help_: Quick Action Layout](https://help.salesforce.com/s/articleView?id=platform.action_layout_editor_about.htm)
- [_Salesforce Help_: Email Action Considerations](https://help.salesforce.com/s/articleView?id=sales.send_email_action_considerations.htm)

<!-- document id=824a569407327a9065fd7f3af032063dbc2f645f3fe9753cade1624d928f8e8d url=/developer/current/en-us/lwc/lwc/guides/events/events-create-dispatch.md -->

# Create and Dispatch Events

Create and dispatch events in a component’s JavaScript class. To create an event, use the `CustomEvent()` constructor. To dispatch an event, call the `EventTarget.dispatchEvent()` method.

The `CustomEvent()` constructor has one required parameter, which is a string indicating the event type. As a component author, you name the event type when you create the event. You can use any string as your event type. However, we recommend that you conform with the DOM event standard.

- No uppercase letters
- No spaces
- Use underscores to separate words

Don’t prefix your event name with the string `on`, because inline event handler names must start with the string `on`. If your event is called `onmessage`, the markup would be `<c-my-component ononmessage={handleMessage}>`. Notice the doubled word `onon`, which is confusing.

::video{src="https://youtube.com/embed/hIv22aTl3-g" title="Cross Component Communication with Custom Events" type="youtube" }

## Example: Dispatch and Handle Events

Let’s jump into some code.

The `c-paginator` component contains **Previous** and **Next** buttons. When a user clicks the buttons, the component creates and dispatches `previous` and `next` events. You can drop the `paginator` component into any component that needs **Previous** and **Next** buttons. That parent component listens for the events and handles them.

<!-- prettier-ignore -->
```html
<!-- paginator.html -->
<template>
  <lightning-layout>
    <lightning-layout-item>
      <lightning-button
        label="Previous"
        icon-name="utility:chevronleft"
        onclick={previousHandler}
      ></lightning-button>
    </lightning-layout-item>
    <lightning-layout-item flexibility="grow"></lightning-layout-item>
    <lightning-layout-item>
      <lightning-button
        label="Next"
        icon-name="utility:chevronright"
        icon-position="right"
        onclick={nextHandler}
      ></lightning-button>
    </lightning-layout-item>
  </lightning-layout>
</template>
```

When a user clicks a button, the `previousHandler` or `nextHandler` function executes. These functions create and dispatch the `previous` and `next` events.

```javascript
// paginator.js
import { LightningElement } from "lwc";

export default class Paginator extends LightningElement {
  previousHandler() {
    this.dispatchEvent(new CustomEvent("previous"));
  }

  nextHandler() {
    this.dispatchEvent(new CustomEvent("next"));
  }
}
```

These events are simple “something happened” events. They don’t pass a data payload up the DOM tree, they simply announce that a user clicked a button.

Let’s drop `paginator` into a component called `c-event-simple`, which listens for and handles the `previous` and `next` events.

To listen for events, use an HTML attribute with the syntax `oneventtype`. Since our event types are `previous` and `next`, the listeners are `onprevious` and `onnext`.

<!-- prettier-ignore -->
```html
<!-- eventSimple.html -->
<template>
  <lightning-card title="EventSimple" icon-name="custom:custom9">
    <div class="slds-m-around_medium">
      <p class="slds-m-vertical_medium content">Page {page}</p>
      <c-paginator onprevious={previousHandler} onnext={nextHandler}></c-paginator>
    </div>
  </lightning-card>
</template>
```

When `c-event-simple` receives the `previous` and `next` events, `previousHandler` and `nextHandler` increase and decrease the page number.

```javascript
// eventSimple.js
import { LightningElement } from "lwc";

export default class EventSimple extends LightningElement {
  page = 1;

  previousHandler() {
    if (this.page > 1) {
      this.page = this.page - 1;
    }
  }

  nextHandler() {
    this.page = this.page + 1;
  }
}
```

**tip:** Check out the [`c-event-simple` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/eventSimple) and the [`c-paginator` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/paginator) in the [`github.com/trailheadapps/lwc-recipes`](https://github.com/trailheadapps/lwc-recipes) repo.

## Pass Data in an Event

To pass data up to a receiving component, set a `detail` property in the `CustomEvent` constructor. Receiving components access the data in the `detail` property in the event listener’s handler function.

**note:** The `CustomEvent` interface imposes no type requirements or structure on the `detail` property. However it’s important to send only primitive data. JavaScript passes all data types by reference except for primitives. If a component includes an object in its `detail` property, any listener can mutate that object without the component’s knowledge. This is a bad thing! It’s a best practice either to send only primitives, or to copy data to a new object before adding it to the `detail` property. Copying the data to a new object ensures that you’re sending only the data you want, and that the receiver can’t mutate your data.

Let’s look at the `c-event-with-data` component from the lwc-recipes repo.

![List of contacts with a selected contact that shows name, title, phone number, and email address.](https://developer.salesforce.com/media/event_with_data.png)

Each item in the list of contacts is a nested `c-contact-list-item` component.

The `c-contact-list-item` component wraps the contact name and picture in an anchor tag with an `onclick` event listener that executes the `selectHandler` function.

<!-- prettier-ignore -->
```html
<!-- contactListItem.html -->
<template>
    <a href="#" onclick={selectHandler}>
        <lightning-layout vertical-align="center">
            <lightning-layout-item>
                <img src={contact.Picture__c}></img>
            </lightning-layout-item>
            <lightning-layout-item padding="around-small">
                <p>{contact.Name}</p>
            </lightning-layout-item>
        </lightning-layout>
    </a>
</template>
```

When a user clicks to select a contact, the component creates and dispatches a `CustomEvent` called `selected`. The event includes the data `detail: this.contact.Id`, which is the ID of the selected contact. The parent, `c-event-custom`, uses the contact reference to display more information about the contact.

```javascript
// contactListItem.js
import { LightningElement, api } from "lwc";

export default class ContactListItem extends LightningElement {
  @api contact;

  selectHandler(event) {
    // Prevents the anchor element from navigating to a URL.
    event.preventDefault();

    // Creates the event with the contact ID data.
    const selectedEvent = new CustomEvent("selected", { detail: this.contact.Id });

    // Dispatches the event.
    this.dispatchEvent(selectedEvent);
  }
}
```

The `c-event-with-data` component listens for the `selected` event in the `onselected` attribute and handles it in the `contactSelected` event handler.

<!-- prettier-ignore -->
```html
<!-- eventWithData.html -->
<template>
    <lightning-card title="EventWithData" icon-name="custom:custom9">
        <lightning-layout class="slds-m-around_medium">
            <lightning-layout-item>
                <template lwc:if={listIsNotEmpty}>
                    <template for:each={contacts.data} for:item="contact">
                        <c-contact-list-item key={contact.Id} contact={contact} onselected={contactSelected}></c-contact-list-item>
                    </template>
                </template>
            </lightning-layout-item>
            <lightning-layout-item class="slds-m-left_medium">
                <template lwc:if={selectedContact}>
                    <img src={selectedContact.Picture__c}></img>
                    <p>{selectedContact.Name}</p>
                    <p>{selectedContact.Title}</p>
                    <p><lightning-formatted-phone value={selectedContact.Phone}></lightning-formatted-phone></p>
                    <p><lightning-formatted-email value={selectedContact.Email}></lightning-formatted-email></p>
                </template>
            </lightning-layout-item>
        </lightning-layout>
    </lightning-card>
</template>
```

In the `contactSelected` event handler, the component assigns the `event.detail` property to the `contactId` property. It finds the contact with that ID in the `contacts` array provisioned via `@wire`, and displays the contact’s name, title, phone, and email in the template.

```javascript
// eventWithData.js
import { LightningElement, wire } from "lwc";
import getContactList from "@salesforce/apex/ContactController.getContactList";

export default class EventWithData extends LightningElement {
  selectedContact;

  @wire(getContactList) contacts;

  contactSelected(event) {
    const contactId = event.detail;
    this.selectedContact = this.contacts.data.find((contact) => contact.Id === contactId);
  }

  get listIsNotEmpty() {
    return this.contacts && Array.isArray(this.contacts.data) && this.contacts.data.length > 0;
  }
}
```

**tip:** Check out the [`c-event-with-data` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/eventWithData) in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

**See Also**

- [Events Best Practices](https://developer.salesforce.com/docs/platform/lwc/events/events-best-practices.md)
- [_MDN web docs_: CustomEvent()](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent)
- [_MDN web docs_: EventTarget.dispatchEvent()](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent)
- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md)

<!-- document id=059af949aa761e63417451c4806da2ad9e47dce4f62f9cb3e05c893eacd2a07d url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-create-start.md -->

# Create and Start a Flow in a Custom Lightning Web Component

Create and start a screen flow from any Lightning web component to yours.

`lightning-flow` represents a flow interview in Lightning runtime. To create a flow in your component, set the `lightning-flow` component’s `flow-api-name` attribute to the API name of the flow that you want to use. To use this component, build a flow with the Salesforce Flow Builder first. The component includes the navigation buttons Back, Next, Pause, and Finish.

**note:** If your flow has custom Lightning web components or Aura components, then you can’t use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

## Example

This example creates and starts the Survey Customers flow.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-flow flow-api-name="Survey_customers"> </lightning-flow>
</template>
```

You can provide initial inputs for the interview by setting the `flow-input-variables` attribute to an array of input values.

This example creates and starts an interview by passing in initial values for the flow. It handles a change in the interview using the `onstatuschange` event handler.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-flow
    flow-api-name={flowName}
    flow-input-variables={inputVariables}
    onstatuschange={handleStatusChange}>
  </lightning-flow>
</template>
```

```javascript
// myComponent.js
import { LightningElement } from "lwc";

export default class MyComponent extends LightningElement {
  opportunityId;
  accountId;
  customerLocation;

  get flowName() {
    if (this.customerLocation === "USA") {
      flowname = "Survey_USA";
    } else {
      flowname = "Survey_General";
    }
  }

  get inputVariables() {
    return [
      {
        // Match with the input variable name declared in the flow.
        name: "OpportunityID",
        type: "String",
        // Initial value to send to the flow input.
        value: this.opportunityId,
      },
      {
        // Match with the input variable name declared in the flow.
        name: "AccountID",
        type: "String",
        // Initial value to send to the flow input.
        value: this.accountId,
      },
    ];
  }

  handleStatusChange(event) {
    if (event.detail.status === "FINISHED") {
      // set behavior after a finished flow interview.
    }
  }
}
```

## Usage Considerations

The `lightning-flow` component only supports active flows for the `flow-api-name` attribute.

The `onstatuschange` event returns these parameters.

If your flow has custom Lightning web components or Aura components, then you can’t use`lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

| Parameter       | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activeStages    | Object[] | The current value of the **$Flow.ActiveStages** variable in the flow. Available in API version 42.0 and later.                                                                                                                                                                                                                                                                                                                                                                                    |
| currentStage    | Object   | The current value of **$Flow.CurrentStage** variable in the flow. Available in API version 42.0 and later.                                                                                                                                                                                                                                                                                                                                                                                        |
| flowTitle       | String   | The flow’s label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| helpText        | String   | The help text for the current screen. Available in API version 42.0 and later.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| guid            | String   | The interview’s GUID. Available in API version 42.0 and later.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| outputVariables | Object[] | The current values for the flow’s output variables.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| status          | String   | The status of the interview. Valid statuses for a flow interview are: <ul><li>`STARTED`: The interview successfully started.</li><li>`PAUSED`: The interview successfully paused.</li><li>`FINISHED`: The interview for a flow with screens finished.</li><li>`FINISHED_SCREEN:` The interview for a flow without screens finished, and the component displayed a default screen with this message: Your flow finished.</li><li>`ERROR`: Something went wrong and the interview failed.</li></ul> |

## Customizing a Flow’s Finish Behavior

Each flow component includes the navigation buttons Back, Next, Pause, and Finish, which navigate within the flow. By default, when the flow finishes, the component reloads the first screen for a new interview. To customize what happens when the flow finishes, add an event handler for the `onstatuschange` action when status is FINISHED.

<!-- document id=b118904071e638348f64409ae3accc347fe35d163709eacd813397eb04e887ef url=/developer/current/en-us/lwc/slds_linter/guides/support/support-create-requests.md -->

# Create Bugs, Feedback, and Feature Requests

- To report an issue with SLDS Linter, create an [issue](https://github.com/salesforce-ux/slds-linter/issues/new/choose).
- To suggest a feature enhancement, create a [feature request](https://github.com/salesforce-ux/slds-linter/issues/new?template=feature_request.md).
- To report any security issues, follow [these instructions](https://github.com/salesforce-ux/slds-linter/security/policy).

<!-- document id=cba9adab63101e2fa0599920a6b658974d320f07631fdd5b8b9d0e1d568c514e url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-forecasting.md -->

# Create Components for Forecasts Pages

Create custom Lightning web components that are available in Lightning forecasts pages.

In the component’s configuration file, add the `lightning__ForecastingPage` target and set `<isExposed>` to `true`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>55.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__RecordPage</target>
        <target>lightning__HomePage</target>
        <target>lightning__ForecastingPage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__ForecastingPage">
            <property type="String" name="forecastingTypeId" label="forecast ID"  />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

The `lightning__ForecastingPage` target adds properties to your component. Declare the properties in the component’s JavaScript file.

For a list of properties supported by the `lightning__ForecastingPage` target, see [_Lightning Aura Components Developer Guide_: Create Components for Forecast Pages](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_forecasts_page.htm).

```javascript
// custom.js
import { LightningElement, api } from "lwc";
import {
  publish,
  subscribe,
  unsubscribe,
  createMessageContext,
  releaseMessageContext,
} from "lightning/messageService";
import SAMPLEMC from "@salesforce/messageChannel/lightning__forecasting_flexipageUpdated";

export default class LMCWebComponentDemo extends LightningElement {
  receivedMessage = "";
  myMessage = "";

  _forecastingTypeId;

  @api
  get forecastingTypeId() {
    return this._forecastingTypeId;
  }

  set forecastingTypeId(value) {
    this._forecastingTypeId = value;
  }

  subscription = null;
  context = createMessageContext();

  constructor() {
    super();
  }

  handleChange(event) {
    this.myMessage = event.target.value;
  }

  publishMC() {
    const message = {
      messageToSend: this.myMessage,
      sourceSystem: "From LWC",
    };
    publish(this.context, SAMPLEMC, message);
  }

  subscribeMC() {
    if (this.subscription) {
      return;
    }
    this.subscription = subscribe(this.context, SAMPLEMC, (message) => {
      this.displayMessage(message);
    });
  }

  unsubscribeMC() {
    unsubscribe(this.subscription);
    this.subscription = null;
  }

  displayMessage(message) {
    this.receivedMessage = message ? JSON.stringify(message, null, "\t") : "no message payload";
  }

  disconnectedCallback() {
    releaseMessageContext(this.context);
  }
}
```

When the Lightning forecasts page changes, such as owner or forecast type, the page header publishes a Lightning message. You can subscribe to the `lightning__forecasting_flexipageUpdated` LightningMessageChannel to update your custom components based on Lightning forecasts page header changes.

Lightning forecasts pages don’t support any standard or custom events published from custom components.

Access the properties in the component’s template.

<!-- prettier-ignore -->
```html
<!-- custom.html -->
<template>
  <lightning-card title="LMC Web Component" icon-name="custom:custom14">
    <div class="slds-m-around_medium">
      <p>MessageChannel: MyMessageChannel__c</p>
      <br />
    </div>
    <!-- Default/basic -->
    <div class="slds-p-around_medium lgc-bg">
      <lightning-input
        type="text"
        label="Enter some text"
        value={myMessage}
        onchange={handleChange}
      ></lightning-input>
      <lightning-button label="Publish" onclick={publishMC}></lightning-button>
    </div>

    <div class="slds-p-around_medium lgc-bg">
      <lightning-button label="Subscribe" onclick={subscribeMC}></lightning-button>
      <lightning-button label="Unsubscribe" onclick={unsubscribeMC}></lightning-button>
      <p>Latest Message Received</p>
      <lightning-formatted-text value={receivedMessage}></lightning-formatted-text>
    </div>

    <div class="slds-p-around_medium lgc-bg">
      <p>forecastingTypeId</p>
      <lightning-formatted-text value={forecastingTypeId}></lightning-formatted-text>
    </div>
  </lightning-card>
</template>
```

**note:** To ensure that custom components appear correctly, enable them to adjust to variable widths.

<!-- document id=ab9d7309ae59ed058d8d744eeb8161371e04e1f5303b7e5aaf9a5fd19c46bc78 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-app-builder-email-app-pane.md -->

# Create Components for the Outlook and Gmail Integrations

Create custom Lightning web components that are available in Lightning App Builder to add to email application panes for the Outlook and Gmail integrations.

In the component’s configuration file, add the `lightning__Inbox` target and set `<isExposed>` to `true`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <isExposed>true</isExposed>
    <apiVersion>46.0</apiVersion>
    <targets>
        <target>lightning__Inbox</target>
    </targets>
    <description>Sample Email Application Pane</description>
</LightningComponentBundle>
```

The `lightning__Inbox` target adds properties to your component. Declare the properties in the component’s JavaScript file. This example declares the three properties that it uses in the template.

```javascript
// sampleEmailAppPane.js

import { LightningElement, api } from "lwc";

export default class SampleEmailAppPane extends LightningElement {
  @api messageBody;
  @api subject;
  @api people = { from: [], to: [] }; // Empty defaults prevent for:each errors before data loads
}
```

Access the properties in the component’s template.

<!-- prettier-ignore -->
```html
<!-- sampleEmailAppPane.html -->

<template>
  <div>Sample Email Application Pane</div>

  <template for:each={people.from} for:item="from">
    <div key={from.email}>{from.email}</div>
  </template>

  <template for:each={people.to} for:item="to">
    <div key={to.email}>{to.email}</div>
  </template>

  <div>{subject}</div>

  <div>{messageBody}</div>
</template>
```

**note:** Usually, to allow users to set a component’s property in Lightning App Builder, you must add the property to the component’s [configuration file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md). However, you don’t need to add a `lightning__Inbox` property to the component’s configuration file unless you want to set its default value.

## `dates`

Data Type: Object

The event’s date.

```javascript
dates: {
  start: 'value',
  end: 'value'
}
```

Supported Source: `event`

## `emails`

Data Type: Array

The email addresses of the recipients in a simple array. Use this property if you don’t care whether the address is in the To, From, or CC field, or what kind of an attendee the addressee is.

```javascript
["abc@salesforce.com", "def@salesforce.com"];
```

Supported Source: `email`, `event`

## `location`

Data Type: String

The location of the event.

Supported Source: `event`

## `messageBody`

Data Type: String

The message body of the email in plain text. HTML formatting isn't preserved.

Supported Source: `email`, `event`

## `mode`

Data Type: String

The access mode. Possible values: `'view'`, `'edit'`

Supported Source: `email`, `event`

## `people`

Data Type: Object

The recipients’ email addresses on the current email or event. The shape of the people attribute changes according to the value of the source attribute. When the `source` attribute is set to `email`, the `people` object contains these elements.

```javascript
{
  to: [
    {
      name: 'name',
      email: 'email'
    }
  ],
  cc: [
    {
      name: 'name',
      email: 'email'
    }
  ],
  from: [
    {
      name: 'senderName',
      email: 'senderEmail'
    }
  ]
}
```

When the `source` attribute is set to `event`, the `people` object contains these elements.

```javascript

{
  requiredAttendees: [
    {
      name: 'attendeeName',
      email: 'email'
    }
  ],
  optionalAttendees: [
    {
      name: 'optAttendeeName',
      email: 'email'
    }
  ],
  organizer: {
    name: 'organizerName',
    email: 'senderEmail'
  }
}
```

Supported Source: `email`, `event`

## `source`

Data Type: String

Possible values: `'email'`,`'event'`

Supported Source: `email`, `event`

## `subject`

Object Type: String

The subject of the email.

Supported Source: `email`, `event`

**note:** To ensure that a custom component appears correctly in an email application pane, enable it to adjust to variable widths. See [Make a Component Width-Aware](https://developer.salesforce.com/docs/platform/lwc/use/use-width-aware.md).

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [_Salesforce Help_: Customize the Outlook Integration Pane](https://help.salesforce.com/articleView?id=app_for_outlook_customize_mailapp_pane.htm&type=5)
- [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-interfaces.md)
- [`lightning\_\_Inbox` Target](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-inbox.html)
- [Salesforce Developers Blog: Lightning Web Components for Your Inbox](https://developer.salesforce.com/blogs/2021/09/lightning-web-components-for-your-inbox)

<!-- document id=3d27d8c882a5180318a1957c360e61c5826e16e0c376472e79f9ffce428b548b url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-email-builder-custom-components.md -->

# Create Components for the Pardot Email Content Builder

Custom components in the email content builder allow marketers and managers to create more engaging email content for their customers.

<!-- document id=eab8119082d5df58c2a30f584c66345992a505ea3503c7d487a8c47b39bc9504 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-local-actions.md -->

# Create Flow Local Actions using Lightning Web Components

To execute client-side logic in your flow, build or modify custom Lightning web components to use as local actions in flows. For example, get data from third-party systems without going through the Salesforce server, or open a URL in another browser tab. After you configure the component’s meta XML, and JavaScript code, it’s available in Flow Builder as a Core Action element.

**note:** - Lightning web components in flows must comply with [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-intro.html) restrictions.
- Flows that include Lightning web components are supported only in [Lightning runtime](https://help.salesforce.com/s/articleView?id=flow_distribute_runtime.htm&language=en_US).
- Lightning web components require a browser context to run, so flow local action components are supported only in screen flows.

## Example

Here’s a sample `ShowToastExampleComponent` component and JavaScript class, which triggers an alert that displays a toast message on screen before navigating to the next flow screen. In Flow Builder, local actions are available from the Core Action element.

**tip:** Use the `lightning/toast` module instead to display a toast notification on LWR sites. For more information, check out [Component Reference: Toast](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast).

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>63.0</apiVersion>
   <isExposed>true</isExposed>
   <targets>
       <target>lightning__FlowAction</target>
   </targets>
   <targetConfigs>
       <targetConfig targets="lightning__FlowAction">
           <property name="toastTitle" type="String" label="Toast title to display" />
           <property name="toastMessage" type="String" label="Toast message to display" />
       </targetConfig>
   </targetConfigs>
</LightningComponentBundle>
```

```
<template>
   Local action templates should be blank.
</template>
```

```
import { api, LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';


export default class ShowToastExampleComponent extends LightningElement {
   @api toastTitle;
   @api toastMessage;

   @api invoke() {
       this.dispatchEvent(new ShowToastEvent({
           title: this.toastTitle,
           message: this.toastMessage,
       }));
   }
}
```

<!-- document id=109bf64a7f1a3268f03a2f7474d30aaa68df4b0c0521b6402e2144d5310d6be9 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-screens.md -->

# Create Flow Screen Components

Just as admins configure the user experience of record pages in Lightning App Builder, they use flow screen components to do the same for flow users. Each screen is made up of one or more screen components. To use a custom Lightning web component in a flow screen, [add the corresponding metadata to the component’s configuration file](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens.md). You can also [embed a flow in a custom component](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-create-start.md).

<!-- document id=5ee70bcbbefe03592c3b7b588ead7d4bd6c68a6ff7cbbc82997dbd6fa3d2357c url=/developer/current/en-us/lwc/lwc/guides/use/use-quick-actions-headless.md -->

# Create Headless Quick Actions

A headless quick action executes custom code in a Lightning web component. Unlike a screen action, a headless action doesn’t open a modal window.

To enable your component to be used as a headless quick action, configure a target. See [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md).

Unlike other [Lightning web components on record pages](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md), LWC quick actions don’t pass in `recordId` in `connectedCallback()`. If you need access to `recordId`, set the value of `recordId` in your code.

```javascript
_recordId;

@api
get recordId() {
    return this._recordId;
}

set recordId(recordId) {
    if (recordId !== this._recordId) {
        this._recordId = recordId;
   }
}
```

## Implement `invoke()`

In your Lightning web component, always expose `invoke()` as a public method for headless quick actions. The `invoke()` method executes every time the quick action is triggered.

```javascript
import { LightningElement, api } from "lwc";

export default class HeadlessSimple extends LightningElement {
  @api invoke() {
    console.log("Hi, I'm an action.");
  }
}
```

Create an empty template for your Lightning web component.

<!-- prettier-ignore -->
```html
<template> </template>
```

To prevent the quick action from being executed multiple times in parallel in long-running actions, add an internal boolean flag.

The return type of `invoke()` is `void`. Returning a `Promise` makes your method asynchronous, but the returned `Promise` is ignored.

This code uses a boolean flag to block a double execution and a `Promise` to wait for the `sleep` to finish. Even though the return type is `void`, the code executes asynchronously.

```javascript
import { LightningElement, api } from "lwc";

export default class HeadlessAsync extends LightningElement {
  isExecuting = false;

  @api async invoke() {
    if (this.isExecuting) {
      return;
    }

    this.isExecuting = true;
    await this.sleep(2000);
    this.isExecuting = false;
  }

  sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
}
```

## Navigate

To navigate to another page, record, or list in Lightning Experience, use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).

This example navigates to the contact home page.

```
import { LightningElement, api } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';

export default class NavigateToRecordHeadlessAction extends NavigationMixin(
    LightningElement
) {
    @api invoke() {
        this[NavigationMixin.Navigate]({
            type: 'standard__objectPage',
            attributes: {
                objectApiName: 'Contact',
                actionName: 'home'
            }
        });
    }
}

```

See [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).

## Dispatch Events

You can dispatch a custom event from a quick action. This example dispatches two toasts sequentially using the event provided by the `lightning/platformShowToastEvent` module.

```
import { LightningElement, api } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class DispatchEventHeadlessAction extends LightningElement {
    @api recordId;
    @api async invoke() {
        // Fire Toast message
        let event = new ShowToastEvent({
            title: 'I am a headless action!',
            message: 'Hi there! Starting...'
        });
        this.dispatchEvent(event);
        // Wait and fire another another Toast message
        await this.sleep(2000);
        // Fire Toast message
        event = new ShowToastEvent({
            title: 'I am a headless action on record with id ' + this.recordId,
            message: 'All done!'
        });
        this.dispatchEvent(event);
    }

    sleep(ms) {
        // eslint-disable-next-line @lwc/lwc/no-async-operation
        return new Promise((resolve) => setTimeout(resolve, ms));
    }
}

```

See [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/use/use-toast.md) and [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md).

**See Also**

- [Test the Navigation Service](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md#test-the-navigation-service)

<!-- document id=032c2e426c6f5acb8f3e643a1080bd8e11d69eb19a1eb21b81e50ae0435257ca url=/developer/current/en-us/lwc/lwc/guides/create/create-components-introduction.md -->

# Create Lightning Web Components

A Lightning web component is a reusable custom HTML element with its own API.

Check out these sections to learn more about creating your own Lightning web components.

- [Define a Component](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-define.md)
- [HTML Templates](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html.md)
- [CSS](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-intro.md)
- [Composition](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-compose-intro.md)
- [Fields, Properties, and Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-intro.md)
- [Javascript](https://developer.salesforce.com/docs/platform/lwc/js/js-intro.md)
- [Access Salesforce Resources](https://developer.salesforce.com/docs/platform/lwc/guide/create-global-value-providers.md)
- [Component Accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-accessibility.md)
- [Lifecycle Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)

<!-- document id=fad98cddb961a9865ddbafbea047e2ba3a0a0018b272ed40c598a9602fc8a760 url=/developer/current/en-us/lwc/lwc/guides/use/use-quick-actions-screen.md -->

# Create Screen Quick Actions

A screen quick action appears in a modal window. Provide your own markup or use the `lightning-quick-action-panel` component for a consistent user interface based on Lightning Design System.

To enable your component to be used as a screen quick action, configure a target. See [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md).

Unlike other [Lightning web components on record pages](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md), LWC quick actions don’t pass in `recordId` through `connectedCallback()`. To capture `recordId` when the framework assigns it, declare an `@api` setter that stores the value in a private field. In your template and JavaScript, reference `this._recordId` to read the record ID.

```javascript
_recordId;
@api set recordId(value) {
    this._recordId = value;
}
```

## Open and Close the Modal Window

A screen quick action opens a Lightning web component in a modal window. To close the modal window programmatically, for example, to create a **Cancel** button, build UI that dispatches the custom event `CloseActionScreenEvent`. Import the event from the `lightning/actions` module.

```javascript
import { CloseActionScreenEvent } from "lightning/actions";
```

The following sections contain complete code samples.

**note:** If you build a screen quick action with custom footer buttons, pressing **X** only closes the modal, there are no hooks to execute additional logic on close. If a screen quick action has logic that executes on **Cancel**, the logic is bypassed when the panel closes.

## Use `lightning-quick-action-panel` for a Consistent UI

To provide a consistent Salesforce UI, wrap your Lightning web component in a [`lightning-quick-action-panel`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-quick-action-panel) component, which provides a header, body, and footer consistent with the [modal blueprint](https://v1.lightningdesignsystem.com/components/modals/) in the Salesforce Lightning Design System.

<!-- prettier-ignore -->
```html
<template>
  <lightning-quick-action-panel header="My action">
    Here's some content for the modal body.

    <div slot="footer">
      <lightning-button variant="neutral" label="Cancel"></lightning-button>
      <lightning-button variant="brand" label="Save" class="slds-m-left_x-small"></lightning-button>
    </div>
  </lightning-quick-action-panel>
</template>
```

## Create a Form in the Modal Body

One way to create the modal body is to use the `lightning-record-edit-form` component with field values populated by `lightning-input-field` components. The cancel and submit buttons must be nested within the `lightning-record-edit-form` component, so with this approach the footer slot isn't needed.

This example creates a form that populates the name and phone fields on the `lightning-record-edit-form` without a footer. It renders a modal window with a header containing the text **Edit Fields Action**.

<!-- prettier-ignore -->
```html
<template>
  <lightning-quick-action-panel header="Edit Fields Action">
    <lightning-record-edit-form
      record-id={recordId}
      object-api-name={objectApiName}
      onsuccess={handleSuccess}>
      <lightning-input-field field-name="Name"></lightning-input-field>
      <lightning-input-field field-name="Phone"></lightning-input-field>
      <lightning-button variant="neutral" label="Cancel"></lightning-button>
      <lightning-button variant="brand" class="slds-m-left_x-small" label="Save" type="submit">
      </lightning-button>
    </lightning-record-edit-form>
  </lightning-quick-action-panel>
</template>
```

When a user clicks the submit button, the `handleSuccess` event handler is called. The handler closes the modal window using the `CloseActionScreenEvent` function.

```javascript
import { LightningElement, api } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { CloseActionScreenEvent } from "lightning/actions";

export default class QuickEditFormExample extends LightningElement {
  @api recordId;
  @api objectApiName;

  handleSuccess(e) {
    // Close the modal window and display a success toast
    this.dispatchEvent(new CloseActionScreenEvent());
    this.dispatchEvent(
      new ShowToastEvent({
        title: "Success",
        message: "Record updated!",
        variant: "success",
      }),
    );
  }
}
```

## Create a Custom Form with Buttons in the Footer

You can create a form in the modal body using `lightning-input` and `lightning-button` components. With this approach, use the `lightning-quick-action-panel` component's footer slot to contain the buttons.

This example creates a form for a quick action on a contact record similar to the previous example, and uses buttons in the footer because it doesn't use a record form component. The field displays the initial values using the `getRecord` wire adapter.

<!-- prettier-ignore -->
```html
<lightning-quick-action-panel header="Quick Contact Edit">
  <template lwc:if={contact.data}>
    <lightning-input
      label="First Name"
      value={firstname}
      class="slds-m-bottom_x-small">
    </lightning-input>
    <lightning-input
      label="Last Name"
      value={lastname}
      onchange={handleLastNameChange}
      class="slds-m-bottom_x-small"
      required>
    </lightning-input>
    <lightning-input
      label="Phone"
      type="tel"
      value={phone}
      class="slds-m-bottom_x-small">
    </lightning-input>
  </template>
  <div slot="footer">
    <lightning-button variant="neutral" label="Cancel" onclick={handleCancel}></lightning-button>
    <lightning-button
      variant="brand"
      class="slds-m-left_x-small"
      label="Save"
      type="submit"
      onclick={handleSubmit}
      disabled={disabled}>
    </lightning-button>
  </div>
</lightning-quick-action-panel>
```

The **Save** button is disabled if the Last Name field is blank. Clicking the **Save** button closes the modal window and displays a toast if the save is successful. To save your record changes, call [`updateRecord(recordInput, clientOptions)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-update-record.md).

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import { updateRecord } from "lightning/uiRecordApi";
import { CloseActionScreenEvent } from "lightning/actions";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import FNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LNAME_FIELD from "@salesforce/schema/Contact.LastName";
import PHONE_FIELD from "@salesforce/schema/Contact.Phone";

const FIELDS = [FNAME_FIELD, LNAME_FIELD, PHONE_FIELD];

export default class QuickEditExample extends LightningElement {
  disabled = false;
  @api recordId;
  @api objectApiName;

  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  contact;

  get firstname() {
    return getFieldValue(this.contact.data, FNAME_FIELD);
  }

  get lastname() {
    return getFieldValue(this.contact.data, LNAME_FIELD);
  }

  get phone() {
    return getFieldValue(this.contact.data, PHONE_FIELD);
  }

  handleCancel(event) {
    // Add your cancel button implementation here
    this.dispatchEvent(new CloseActionScreenEvent());
  }

  handleLastNameChange(event) {
    // Display field-level errors if last name field is empty.
    if (!event.target.value) {
      event.target.reportValidity();
      this.disabled = true;
    } else {
      this.disabled = false;
    }
  }

  handleSubmit(e) {
    // Add your updateRecord implementation

    // Close the modal window and display a success toast
    this.dispatchEvent(new CloseActionScreenEvent());
    this.dispatchEvent(
      new ShowToastEvent({
        title: "Success",
        message: "Record updated!",
        variant: "success",
      }),
    );
  }
}
```

## Get Information about the Page

You can use standard LWC features to get information about the current page, including a page reference from the navigation service, the record ID, and the object API name of the current record.

To return the page reference, import `CurrentPageReference` from [`lightning/navigation`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation). See [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).

To get the record ID and object API name, expose `recordId` and `objectApiName` as properties. See [Make a Component Aware of Its Record Context](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md) and [Make a Component Aware of Its Object Context](https://developer.salesforce.com/docs/platform/lwc/use/use-object-context.md).

This example displays the record ID and object API name of the current record. It also returns the [current page reference](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-add-params-url.md), which describes the current page and its state.

<!-- prettier-ignore -->
```html
<template>
  <p>These two fields are auto-populated based on the record context:</p>
  <p>RecordId: <i>{recordId}</i>, objectApiName: <i>{objectApiName}</i></p>
  <p>{pageRefString}</p>
</template>
```

```javascript
import { LightningElement, api, wire } from "lwc";
import { CurrentPageReference } from "lightning/navigation";

export default class RecordContextAction extends LightningElement {
  @api recordId;
  @api objectApiName;

  @wire(CurrentPageReference)
  pageRef;

  get pageRefString() {
    return JSON.stringify(this.pageRef);
  }
}
```

**See Also**

- [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input-intro.md)

<!-- document id=20e53b39996adb4a95a84cdc5f0b6e0c5623e393d4f9ca92e1729446e99b08b5 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-styling-hooks.md -->

# Create Styling Hooks for Your Components

To expose styling hooks for your custom components, use CSS custom properties. CSS custom properties also make code easier to read and update.

Document your component's styling hooks as part of your component's API. To change a component's style, a consumer simply sets values for the styling hooks—they don't need to know how you implemented the styles.

::video{src="https://youtube.com/embed/ENRVbA3bqzY" title="Styling LWC using Public Properties" type="youtube" }

To define a CSS custom property in a component's stylesheet, prefix the property with `--`. To insert the value of the property, use `var()`.

```css
:host {
  --important-color: red;
}

.important {
  color: var(--important-color);
}
```

A [CSS custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) inherits its value from its parent component. [Inherited properties](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance) pierce the shadow DOM. Some CSS properties, like color, are also inherited. Because CSS custom properties are inherited, a consumer can set their values at a higher level in the DOM tree and style your component.

These CSS custom properties create styling hooks for two themes: light and dark. Pass the fallback value as an optional second parameter to `var()`.

```css
.light {
  background-color: var(--light-theme-background-color, lightcyan);
  color: var(--light-theme-text-color, darkblue);
}

.dark {
  background-color: var(--dark-theme-background-color, darkslategray);
  color: var(--dark-theme-text-color, ghostwhite);
}
```

**tip:** Experiment with this code in playgrounds at [lwc.dev](https://lwc.dev/guide/css#create-styling-hooks).

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [stylingHooks](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/stylingHooks) component that demonstrates SLDS styling hooks.

**See Also**

- [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md)

<!-- document id=068d375ee83695c1cc42b54ea83d4d3a82253577dd6989f669674b5434c0d386 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-cart/reference-lightning-commerce-cart-create-cart.md -->

# `createCart(cartInput)`

Creates a cart for a buyer in a webstore.

## Syntax

```javascript
import { createCart } from 'lightning/commerceCartApi';
createCart(cartInput: object): Promise<CartSummary>
```

## Commerce API Resource

```
POST /commerce/webstores/{webstoreId}/carts
```

`createCart` uses this [Commerce API resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts.htm).

## Parameters

- `webstoreId`—(Required) The ID of the webstore. The ID prefix is `0ZE`.
- `version`—(Required) The API version for the adapter, for example, `v62.0`. Without this parameter, the call doesn't fire.
- `cart`—(Required) The cart input object. Accepts these fields:
  - `effectiveAccountId`—(Optional) The effective account ID for the cart.
  - `name`—(Optional) The friendly name for the cart.
  - `type`—(Optional) The cart type. Valid values: `Cart`, `PayNowReadOnly`, `ReadOnly`, `Template`.
  - `currencyIsoCode`—(Optional) The ISO currency code for the cart, for example, `USD`.

**note:** Additional fields (`orderOwnerId`, `isSecondary`, `description`, `typeAsString`, `customFields`) are available in API version 64.0 and later.

## Returns

A `Promise` that resolves with a `CartSummary` object with these fields:

- `cartId`—The ID of the created cart.
- `name`—The name of the cart.
- `status`—The status of the cart, for example, `Active`.
- `type`—The cart type.
- `webStoreId`—The ID of the webstore associated with the cart.

## Usage

`createCart` is an imperative function, not a `@wire` adapter. Call it in response to a user action.

```javascript
import { LightningElement } from 'lwc';
import { createCart } from 'lightning/commerceCartApi';

export default class CreateCartExample extends LightningElement {
  async handleCreateCart() {
    try {
      const result = await createCart({
        webstoreId: '0ZExx0000000001',
        version: 'v62.0',
        cart: {
          name: 'My Cart',
          currencyIsoCode: 'USD',
        },
      });
      console.log('Cart created:', result.cartId);
    } catch (error) {
      console.error('Error creating cart:', error);
    }
  }
}
```

## Error Handling

If the call fails, the `Promise` rejects with an error object containing an `errorCode` and a `message`.

**See Also**

- [`deleteCart(cartInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-cart-delete-cart.md)

<!-- document id=858c3a32f1b52943e496285d189f6ab15d071c59c68f2d7a109d3deccb76272b url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-create-data-connector.md -->

# `createDataConnector`

Creates an instance of a prebuilt CRM Analytics connector to connect to data in your Salesforce orgs, apps, data warehouses, and database services.

## Syntax

```javascript
import { createDataConnector } from 'lightning/analyticsWaveApi';
createDataConnector( dataConnector : DataConnectorInput ): Promise<DataConnector>
```

## CRM Analytics API Resource

```html
POST /wave/dataConnectors
```

`createDataConnector` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                                                                                                                                                    | Required?                                  |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `dataConnector` | Object | The data connector instance to create. Use a [Data Connector Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_data_connector_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that resolves with the [Data Connector](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_data_connector.htm) response.

## Usage

Use `createDataConnector` to create an instance of a prebuilt CRM Analytics connector. For example, create a connector to another Salesforce org to pull in Account data.

This example adds a create button to a page. The page must contain form elements for the information required to create the connector, like the properties. Creating a data connector displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { createDataConnector } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class CreateDataConnector extends LightningElement {
  dataConnector = {
    "name" : "mySFDCExt",
    "label" : "My SFDC External Connector",
    "description" : "My connection to another SFDC org",
    "connectionProperties" : [
      { "name" : "Password", "value" : "*******" },
      { "name" : "Service_URL", "value" : "https://MyDomainName.my.salesforce.com/services/Soap/u/53.0" },
      { "name" : "Username", "value" : "user@yourSFDCorg.com" },
      { "name" : "APIType", "value" : "BULKV2" }
    ],
    "connectorType" : "SalesforceExternal",
    "connectorHandler" : "Legacy"
  };

  create(event) {
      createDataConnector({ dataConnector : this.dataConnector } })
        .then(() => {
          this.dispatchEvent(
              new ShowToastEvent({
                title: 'Success',
                message: 'Data Connector Created',
                variant: 'success'
              })
          );
        })
        .catch(error => {
          this.dispatchEvent(
              new ShowToastEvent({
                title: 'Error creating data connector',
                message: error.body.message,
                variant: 'error'
              })
          );
      });
  }
}
```

This button calls the `createDataConnector()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Create"
    icon-name="utility:play"
    icon-position="right"
    onclick={create}
  ></lightning-button>
</template>
```

<!-- document id=4c0f9c3d0f04c2b84a4a88c9b7f93fc806d6c51df8b209fe327512d81f6dd1b1 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-create-dataflow-job.md -->

# `createDataflowJob`

Creates a CRM Analytics dataflow job, which is the equivalent of clicking **Run Now** for a data prep recipe, a data sync, or a dataflow in the CRM Analytics Data Manager UI. For more information on the different IDs that are used to start a job, see [Run, Schedule, and Sync CRM Analytics Data with REST APIs](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_run_schedule_sync_data.htm).

## Syntax

```javascript
import { createDataflowJob } from 'lightning/analyticsWaveApi';
createDataflowJob({ dataflowJob: { DATAFLOWID: string, COMMAND: string } }): Promise<DataflowJob>
```

## CRM Analytics API Resource

```html
POST /wave/dataflowjobs
```

`createDataflowJob` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                    | Required?                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `dataflowId`   | String | The dataflow, data prep recipe, or data sync ID for the job.                                                   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `command`      | String | The job command to execute. Must be `start` to create a dataflow job. <ul><li>`start`</li><li>`stop`</li></ul> | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that resolves with the [Dataflow Job](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job.htm) response.

## Usage

There are several ways to use `createDataflowJob`. For example, you can display a list of recipes and enable start on each recipe on the list.

This example adds a start button to a page with recipes. Starting a recipe displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { createDataflowJob } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class CreateDataflowJob extends LightningElement {
  @api dfId; // or fetch the dataflowId of the data prep recipe
  command = "start";

  start(event) {
    createDataflowJob({
      dataflowJob: { dataflowId: this.dfId, command: this.command },
    })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Recipe Started",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error starting recipe",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `createDataflowJob()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Start"
    icon-name="utility:play"
    icon-position="right"
    onclick={start}
  ></lightning-button>
</template>
```

<!-- document id=21613f02a8737b542f5d07af0225a50a6d41ed4255251fba5354283c2554c317 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-create-dataset.md -->

# `createDataset`

Creates a CRM Analytics dataset.

## Syntax

```javascript
import { createDataset } from 'lightning/analyticsWaveApi';
createDataset( dataset : DatasetInput ): Promise<Dataset>
```

## CRM Analytics API Resource

```html
POST /wave/datasets
```

`createDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                       | Required?                                  |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `dataset`      | Object | The dataset to create. Use a [Dataset Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_dataset_input.html) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that resolves with the [Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset.htm) response.

## Usage

Use `createDataset` to create a CRM Analytics dataset. For example, create a dataset from the Accounts object.

This example adds a create button to a page. The page must contain form elements for the information required to create the dataset, like the dataset type. Creating a dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { createDataset } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class CreateDataset extends LightningElement {
  dataset = {
    type: "Default",
  };

  create(event) {
    createDataset({ dataset: this.dataset })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Dataset Created",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error creating dataset",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `createDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Create"
    icon-name="utility:play"
    icon-position="right"
    onclick={create}
  ></lightning-button>
</template>
```

<!-- document id=dbd377a6876859b99b4c3dd61ccf55314f71766788bc0eefeee261215a004da1 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-create-dataset-version.md -->

# `createDatasetVersion`

Creates a version of a CRM Analytics dataset.

## Syntax

```javascript
import { createDatasetVersion } from 'lightning/analyticsWaveApi';
createDatasetVersion( DATASETVERSION : RestoreDatasetVersionInput ): Promise<RestoreDataset>
```

## CRM Analytics API Resource

```html
POST /wave/datasets/${datasetIdOrApiName}/versions
```

`createDatasetVersion` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets_id_versions.htm).

## Parameters

| Parameter Name   | Type   | Description                                                                                                                                                                                                               | Required?                                  |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetVersion` | Object | The dataset version to create. Use a [Restore Dataset Version Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_restore_dataset_version_input.html) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Restore Dataset Version](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_restore_dataset_version.htm) response.

## Usage

Use `createDatasetVersion` to create a version of a CRM Analytics dataset. For example, create a version of the Accounts dataset with updated data.

This example adds a create button to a page. The page must contain form elements for the information required to create the dataset version, like the dataset ID. Creating a dataset version displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { createDatasetVersion } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class CreateDatasetVersion extends LightningElement {
  datasetVersion = {
    datasetIdOrApiName: "0Fbxx000000xxxxxx",
    sourceVersion: {
      sourceVersion: {
        id: "0Fcxx000000xxxxxx",
      },
    },
  };

  create(event) {
    createDatasetVersion({ datasetVersion: this.datasetVersion })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Dataset Version Created",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error creating dataset version",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `createDatasetVersion()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Create"
    icon-name="utility:play"
    icon-position="right"
    onclick={create}
  ></lightning-button>
</template>
```

<!-- document id=596d682c49918ec835eb0f29e8b930548ac38af9c6771dc19b8b96f751ac515d url=/developer/current/en-us/lwc/lwc/guides/reference/reference-create-list-info.md -->

# `createListInfo`

Use this wire adapter to create a list view associated with a supported object.

## Syntax

```javascript
import { createListInfo } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

createListInfo({ objectApiName: ACCOUNT_OBJECT, listViewApiName: "MyAccountListView" });
```

## User Interface API Resource

```html
POST /ui-api/list-info/${objectApiName}
```

See [Create a List View for an Object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_lists_object_post.htm).

## Parameters

| Parameter Name      | Type     | Description                                                                                                                                                                             | Required?                               |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`     | String   | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html).                                                        | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName`   | String   | The API name of a list view, such as `AllAccounts`.                                                                                                                                     | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `displayColumns`    | String[] | Display columns (field API names) for the list.                                                                                                                                         |                                         |
| `filterLogicString` | String   | The filter logic string, such as `(1 OR 2) and 3`. Indexes start with 1.                                                                                                                |                                         |
| `filteredByInfo`    | Object   | Filtering information for the list. Type [List Filter By Info Input](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_list_filter_by_info_input.htm). |                                         |
| `label`             | String   | The list’s display label, such as All Accounts.                                                                                                                                         |                                         |
| `listShares`        | String[] | Objects that the list is shared with, if `visibility` is `Shared`.                                                                                                                      |                                         |
| `scope`             | Object   | Scope information for the list. See [List Scope Input](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_list_scope_input.htm).                        |                                         |
| `visibility`        | String   | The list’s level of visibility. Valid values are: `Private`, `Public`, `Shared`.                                                                                                        |                                         |

## Returns

- `data`—[List Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_metadata.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example creates a new list view on the button click.

<!-- prettier-ignore -->
```html
<!-- wireCreateListInfo.html -->
<template>
   <lightning-card title="wireCreateListInfo">
       <lightning-button variant="brand" label="Create new List View" title="Primary action" onclick={createListView} class="slds-m-left_x-small"></lightning-button>
       <template lwc:if={displayColumns}>
           <div class="slds-m-around_medium">
               New list View display columns:
               <template title="thing" for:each={displayColumns} for:item="col">
                   <p key={col.fieldApiName}>{col.fieldApiName} : {col.label}</p>
               </template>
           </div>
       </template>
   </lightning-card>
</template>
```

```javascript
// wireCreateListInfo.js
import { createListInfo } from "lightning/uiListsApi";
import { LightningElement, api } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class CreateListInfo extends LightningElement {
  error;
  displayColumns;
  @api async createListView() {
    createListInfo({
      objectApiName: ACCOUNT_OBJECT.objectApiName,
      listViewApiName: "AllAccounts_createListInfoTest",
    })
      .then((result) => {
        this.displayColumns = result.data.displayColumns;
      })
      .catch((error) => {
        this.error = error;
      });
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=e44d4be4c08366ae5930acda95a628fd9216b6dd8e0780eac5033ea667d58cce url=/developer/current/en-us/lwc/lwc/guides/reference/reference-create-record.md -->

# `createRecord(recordInput)`

Creates a record.

## Syntax

```javascript
import { createRecord } from 'lightning/uiRecordApi';
createRecord(recordInput: Record): Promise<Record>
```

## User Interface API Resource

```html
POST /ui-api/records
```

`createRecord` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                            | Required?                               |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `recordInput`  | Object | A [RecordInput](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm) object used to create the record. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

`recordInput` takes two properties.

| Property Name | Type   | Description                                                                                                                      | Required?                               |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `apiName`     | String | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`      | Object | Map of field names to field values.                                                                                              |                                         |

**note:** Passing in `allowOnSaveDuplicate` or `recordTypeId` isn't currently supported. To prevent the creation of duplicate records, use a [duplicate rule with a matching rule](https://help.salesforce.com/s/articleView?id=sales.duplicate_prevention_map_of_tasks.htm).

## Returns

A Promise object that resolves with the created record. The record contains data for the fields in the record layout.

## Usage

Before you use this wire adapter, make sure that there isn’t an easier way to create the data. Consider using the [`lightning-record-*-form` components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md) to work with records. To update a record, use [`updateRecord`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-update-record.md) instead.

Use `createRecord` by passing in the record input. To create a RecordInput object, use [`generateRecordInputForCreate(record,objectInfo)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-generate-record-input-create.md). Alternatively, pass in a `recordInput` object with the `apiName` and `fields` properties.

```javascript
import { createRecord } from "lightning/uiRecordApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";

export default class createRecordExample extends LightningElement {
  name;

  handleInput(event) {
    this.name = event.target.value;
  }

  async handleCreate() {
    const fields = {};
    // Map the user input to the fields
    fields[NAME_FIELD.fieldApiName] = this.name;

    // Configure your recordInput object with the object and field API names
    const recordInput = { apiName: ACCOUNT_OBJECT.objectApiName, fields };

    try {
      // Invoke createRecord
      const account = await createRecord(recordInput);
    } catch (error) {
      // Handle error
    }
  }
}
```

**See Also**

- [Build Custom UI to Create and Edit Records](https://developer.salesforce.com/docs/platform/lwc/data/data-salesforce-write.md)
- [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/use/use-toast.md)

<!-- document id=9c8ddc643681c85489228adbb5a5fc21dd63585f597b48c6c720d48a62eec4ad url=/developer/current/en-us/lwc/lwc/guides/reference/reference-create-record-input-update.md -->

# `createRecordInputFilteredByEditedFields(recordInput, originalRecord)`

Creates a RecordInput object with a list of fields that have been edited from their original values to pass in a call to `updateRecord(recordInput)`.

## Syntax

```javascript
import { createRecordInputFilteredByEditedFields } from 'lightning/uiRecordApi';
createRecordInputFilteredByEditedFields(recordInput: Record, originalRecord: Record): Record
```

## User Interface API Resource

```html
PATCH /ui-api/records/{recordId}
```

`createRecordInputFilteredByEditedFields` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_patch.htm), but doesn’t support all its parameters.

## Parameters

| Parameter Name   | Type   | Description                                                                                                                                                                        | Required?                               |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `recordInput`    | Object | A [RecordInput](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm) object to filter.                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `originalRecord` | Object | A [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm#ui_api_responses_record) object that contains the original field values. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

An object with a list of fields that have been edited from their original values (excluding `Id` which is always included).

<!-- document id=6d037dfa5e0c11e9fb01c5e79fd19fb1d9c369bab4221b0921476750c30854df url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-create-replicated-dataset.md -->

# `createReplicatedDataset`

Creates a replicated dataset, also known as a connected object.

## Syntax

```javascript
import { createReplicatedDataset } from 'lightning/analyticsWaveApi';
createReplicatedDataset( replicated Dataset : ReplicatedDatasetInputRepresentation ): Promise<ReplicatedDatasetRepresentation>
```

## CRM Analytics API Resource

```html
POST /wave/replicatedDatasets
```

`createReplicatedDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets.htm).

## Parameters

| Parameter Name      | Type   | Description                                                                                                                                                                                                              | Required?                                  |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `replicatedDataset` | Object | The connected object instance to create. Use a [Replicated Dataset Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_replicated_dataset_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Replicated Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_dataset.htm) response.

## Usage

Use `createReplicatedDataset` to create a connected object. For example, create a connected object for Asset data with the _connectorId_, _connectionMode_, and _sourceObjectName_.

This example adds a create button to a page. The page must contain form elements for the information required to create the connected object, like the _sourceObjectName_. Creating a connected object displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { createReplicatedDataset } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class CreateReplicatedDataset extends LightningElement {
  @api connectId; // or fetch the ID of the connector to create the dataset from
  replicatedDataset = {
    "connectorId" : $connectId,
    "connectionMode" : "incremental",
    "sourceObjectName" : "Asset"
  };

  create(event) {
    createReplicatedDataset({ replicatedDataset: this.replicatedDataset } })
      .then(() => {
      this.dispatchEvent(
          new ShowToastEvent({
          title: 'Success',
          message: 'Connected Object Created',
          variant: 'success'
          })
      );
    })
    .catch(error => {
      this.dispatchEvent(
        new ShowToastEvent({
            title: 'Error creating connected object',
            message: error.body.message,
            variant: 'error'
        })
      );
    });
  }
}

```

This button calls the `createReplicatedDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Create"
    icon-name="utility:play"
    icon-position="right"
    onclick={create}
  ></lightning-button>
</template>
```

<!-- document id=63aa93f1cb3377a1cefcd16cf6e99d6110eae53c8e48c5b398f22f8bf98926bc url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-createtextrecord.md -->

# `createTextRecord(payload)`

Given a text payload, this function creates a properly formatted `NFCRecord` to be written to an NFC tag.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
createTextRecord(payload: TextPayload): Promise<Object>;
```

## Parameters

- payload-(Required) A [TextPayload](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md#textpayload) object, which contains the text to be converted to an NFC record. 


## Returns

A Promise object that resolves to an `NFCRecord` object.

A rejected promise returns an `NFCServiceFailure`.

## Usage

Use this function to create and return an NFC record to use as a parameter for the `write()` function.

```javascript
myNFCService
  .createTextRecord(payload)
  .then((result) => {
    this.newNFCRecord = result;
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels the operation, the promise is rejected with a `NFCServiceFailure.code` value of USER_DISMISSED.

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)
- [createUriRecord()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-createurirecord.md)

<!-- document id=2a82d8d3512ad7d7c204799ffe48be65f1c7415bc5f98ff9d55c7d7ad88c7805 url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-createurirecord.md -->

# `createUriRecord(payload)`

Given a URI string payload, this function creates a properly formatted `NFCRecord` to be written to an NFC tag.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
createUriRecord(payload: String): Promise<Object>;
```

## Parameters

- payload–(Required) The URI to be converted to an NFC record.

## Returns

A Promise object that resolves to an `NFCRecord` object.

A rejected promise returns an `NFCServiceFailure`.

## Usage

Use this function to create and return an NFC record to use as a parameter for the `write()` function.

```javascript
myNFCService
  .createUriRecord(payload)
  .then((result) => {
    this.newNFCRecord = result;
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels the operation, the promise is rejected with a `NFCServiceFailure.code` value of USER_DISMISSED.

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)
- [createTextRecord()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-createtextrecord.md)

<!-- document id=81167c2759e44494c1b4250e3b0c70a4d64340097e9bb3a7374532b2f373036e url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics.md -->

# CRM Analytics for LWC

Access CRM Analytics data, metadata, and management capabilities from LWC with these modules.

- [Analytics Wave API (`lightning/analyticsWaveApi`)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-analytics-wave-api.md)
- [Analytics Smart Data Discovery API (`lightning/analyticsSmartDataDiscoveryApi`](https://developer.salesforce.com/docs/platform/lwc/reference-lightning-analytics-smart-data-discovery-api.md)

**See Also**

- [CRM Analytics REST API Overview](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_rest_overview.htm)

<!-- document id=db6e9ada2c2e10f5f7bf18bc6f83aa0f06ffd282653b5ed8409b28575faae998 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-interface.md -->

# Custom Property Editor JavaScript Interface

A custom property editor uses these JavaScript functions to communicate with Flow Builder.

## `inputVariables`

The `inputVariables` interface provides data about the FlowScreenField metadata.

```javascript
_inputVariables = [];

@api
get inputVariables() {
    return this._inputVariables;
}

// Set a field with the data that was stored from the flow.
set inputVariables(variables) {
    this._inputVariables = variables || [];
}
```

The data structure in `_inputVariables` includes the name, value, and data type for each input variable.

```xml
[{
    name: 'volume',
    value: '10',
    valueDataType: 'Number'
}]
```

For more information about flow metadata, see [Flow Metadata API](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_visual_workflow.htm).

## `builderContext`

The `builderContext` interface provides data about elements and resources in the flow. For example, the `screens` and `actionCalls` data structures include the names and types of input variables. In Flow Builder, an admin can use the data about other elements and resources as inputs on the custom property editor for the screen component’s input attributes.

The data structure passed into the custom property editor from the `builderContext` interface includes the elements and resources in the flow.

```xml
{
    actionCalls: [],
    apexPluginCalls: [],
    constants: [],
    formulas: [],
    recordCreates: [],
    recordDeletes: [],
    recordLookups: [],
    recordUpdates: [],
    screens: [],
    stages: [],
    textTemplates: [],
    variables: []
}
```

For more information about flow metadata, see [Flow Metadata API](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_visual_workflow.htm).

In the following example, a developer creates a custom flow screen component and its custom property editor. In Flow Builder, an admin uses the combo box to set the sender’s name for an email. When users run the flow, the flow screen shows the selected name for the email.

The following HTML, JavaScript, and configuration file define the custom flow screen component.

<!-- prettier-ignore -->
```html
<!--htmlEmail.html-->
<template>
  <p>Selected sender's name is: {senderName}</p>
</template>
```

This JavaScript file defines a `senderName` public property.

```javascript
// htmlEmail.js

import { LightningElement, api } from "lwc";

export default class HTMLEmail extends LightningElement {
  @api senderName;
}
```

This configuration file registers the custom property editor.

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>49.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__FlowScreen</target>
    </targets>
    <masterLabel>HTMLEmail</masterLabel>
    <targetConfigs>
        <targetConfig targets="lightning__FlowScreen" configurationEditor="c-html-email-editor">
            <property name="senderName" type="String" role="inputOnly" />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

The following HTML, JavaScript, and configuration files define the custom property editor for the screen component.

This HTML file defines the UI for the custom property editor in Flow Builder. The UI shows a combo box Lightning base component.

<!-- prettier-ignore -->
```html
<!--htmlEmailEditor.html-->
<template>
  <div class="slds-p-around_xx-small">
    <lightning-combobox
      name="senderName"
      label="Sender Display Name"
      value={senderName}
      placeholder="Select Sender"
      options={options}
      onchange={handleChange}
    >
    </lightning-combobox>

    <p class="slds-p-top_xx-small">Selected sender's name is: {senderName}</p>
  </div>
</template>
```

The JavaScript class receives a copy of the flow metadata from Flow Builder when the custom property editor is initialized. If the admin makes an update in the custom property editor, an event is dispatched to propagate the change back to Flow Builder.

```javascript
// htmlEmailEditor.js
import { LightningElement, api } from "lwc";
export default class HtmlEmailEditor extends LightningElement {
  @api
  inputVariables;

  @api
  builderContext;

  get senderName() {
    const param = this.inputVariables.find(({ name }) => name === "senderName");
    return param && param.value;
  }

  get options() {
    const variables = this.builderContext.variables;
    return variables.map(({ name, value }) => ({
      label: name,
      value: value.stringValue,
    }));
  }

  handleChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
          name: "senderName",
          newValue,
          newValueDataType: "String",
        },
      });
      this.dispatchEvent(valueChangedEvent);
    }
  }
}
```

The `senderName` method returns information about the `senderName` input variable that was stored using the `inputVariables` interface. The `options` method returns a list of merge fields that was stored using the `builderContext` interface method. The custom property editor shows the merge fields as input values for the screen component’s input attributes.

![Custom property editor with a combo box](https://developer.salesforce.com/media/flow_custom_property_editor_combobox.png)

## `elementInfo`

The `elementInfo` interface provides data about the custom flow screen component or custom action that is invoking the custom property editor. Use this interface to disambiguate different instances of a screen component or an action.

This example stores the flow metadata in `_elementInfo`, but you can name the field whatever you like.

```
_elementInfo = {};
@api
get elementInfo() {
    return this._elementInfo;
}

// Set a local variable with the data that was stored from flow.
set elementInfo(info) {
    this._elementInfo = info || {};
}
```

The data structure in `_elementInfo` includes the flow element’s API name and type from the flow metadata.

```xml
{
    apiName: 'slider',
    type: 'Screen'
}
```

Valid values for type are:

- `Screen`—A screen element
- `Action`—An action element

## `validate`

Use the `validate` interface to perform custom validation in the custom property editor. When a flow admin clicks **Done** in Flow Builder’s screen editor, Flow Builder evaluates the `validate` function in each custom property editor. If the function returns the `key` and `errorString` data structure, the screen editor shows the number of errors.

**note:** Flow Builder shows only the number of errors. Write code to show error strings in your custom property editor.

This example stores the data in the `validity` field, but you can use any field name. To show error strings in the custom property editor, we use `sliderCmp` to query, set, and report the error string.

```javascript
@api
validate() {
    const sliderCmp = this.template.querySelector('lightning-slider');
    const validity = [];
    if (this.volume < 0 || this.volume > 100) {
        sliderCmp.setCustomValidity('The slider range is between 0 and     100.');
        validity.push({
            key: 'Slider Range',
            errorString: 'The slider range is between 0 and 100.',
        });
    } else {
        sliderCmp.setCustomValidity('');
    }
    sliderCmp.reportValidity();
    return validity;
}
```

## `genericTypeMappings`

The `genericTypeMappings` data structure includes the name and value for each input. The `typeName` is the name of the generic `sObject` input; for example, `‘T__param1’`. The `typeValue` is the specific value for the generic `sObject` input; for example, `Account`.

```xml
[{
    typeName: 'T__param1',
    typeValue: 'Account'
}]
```

## Event Types

To report input value changes to Flow Builder, dispatch events from the custom property editor’s `handleChange` function. Set `bubbles` and `composed` to true.

The valid values for event types are:

- `configuration_editor_input_value_changed`—An event type that dispatches when an input value changes.
- `configuration_editor_input_value_deleted`—An event type that dispatches when an input value is deleted.
- `configuration_editor_generic_type_mapping_changed`—An event type that dispatches when a generic `sObject` input value changes.

These `detail` properties define the input for reporting changes.

- `name`—The input variable in the screen component’s JavaScript class.
- `newValue`—The new value of the input.
- `newValueDataType`—The new data type of the input.
- `typeName`—The generic `sObject` input in the screen component’s JavaScript class or invocable method’s Apex class. To reference the `typeName` in the custom property editor for a screen component, reference the `propertyType` subtag’s `name` attribute. The value must be inside curly braces for example `property type="{T}"`. To define the property as a generic `sObject` collection data type, append `[]`, for example `property type="{T[]}"`. To reference the `typeName` in the custom property editor for an invocable action, prepend `T__` to input names and `U__` to output names for example `T__param1`.
- `typeValue`—The specific value for the generic `sObject` input or output.

For example, when an admin enters a value for `volume` in the custom property editor, it dispatches an event. Flow Builder receives the event and updates the value in the flow.

```javascript
handleChange(event) {
    if (event && event.detail) {
        const newValue = event.detail.value;
        const valueChangedEvent = new CustomEvent(
            'configuration_editor_input_value_changed', {
            bubbles: true,
            cancelable: false,
            composed: true,
            detail: {
                name: 'volume',
                newValue,
                newValueDataType: 'Number'
            }
            }
        );
        this.dispatchEvent(valueChangedEvent);
    }
}
```

When a value is removed from the input, dispatch a custom `configuration_editor_input_value_deleted` event.

```javascript
handleDelete(event) {
  if (event) {
    const valueDeletedEvent = new CustomEvent('configuration_editor_input_value_deleted', {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
            name: 'volume'
        }
    });
    this.dispatchEvent(valueDeletedEvent);
  }
}
```

**See Also**

- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/events/events-create-dispatch.md)

<!-- document id=08382c0890ba1d825edf6a882e2e9d2ca20a2408260afd0b90371b525e4d8e11 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-custom-tab-intro.md -->

# Custom Tabs

You can add a Lightning web component as a custom tab in Lightning Experience or in the Salesforce mobile app.

To use a Lightning web component as a custom tab:

1. [Configure the component.](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab.md)
2. [Add the component as a custom tab.](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab-lex.md)

<!-- document id=8c0ab6df933aa766dc1e5a68de952df5676bf074cc8128a1a266cf30be5031f9 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor.md -->

# Customize Action and Screen Component UI in Flow Builder

Develop a custom property editor that provides a simplified UI for an admin when they configure a custom screen component or invocable action in Flow Builder. A custom property editor is a Lightning web component that provides a custom UI for entering input values, which you can use with your Apex actions and flow screen components.

To learn more about creating a custom property editor for Flow Builder, check out these links.

- [Compare a Custom Property Editor to a Standard Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-intro.md)
- [Custom Property Editor JavaScript Interface](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-interface.md)
- Custom Property Editor Examples
  - [Invocable Action](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-action-example.md)
  - [Screen Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-lwc-example.md)
  - [Generic SObject Input for Invocable Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-sobject-action-example.md)
  - [Generic SObject Input for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-sobject-lwc-example.md)
  - [SObject Input for Invocable Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-literal-sobject-action-example.md)

**See Also**

- [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)
- [Use Getters and Setters to Modify Data](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getters-setters.md)

<!-- document id=70c66c58eee20d098caae629fbe005c5e7e9ee14a8ef76d825af7c3187813aa5 url=/developer/current/en-us/lwc/lwc/guides/data/data-table-custom-types-styling.md -->

# Customize Data Type Layout and Styles

You can customize the look of `lightning-datatable` cells that use custom data types.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

## Use a Layout for a Custom Data Type

A custom cell can use a standard or bare layout.

Standard layout:

- Spreads content evenly across the cell, with the first item flush to the left border and the last item flush to the right border
- Aligns text to the left and vertically to the center
- Adds a small padding to the left and right of the content
- Supports accessibility and keyboard navigation for editable types

The bare layout, which is the default layout for custom cells:

- Aligns text to the left and vertically to the center
- Removes padding from the left and right of the content
- Doesn’t support accessibility and keyboard navigation for editable types

The standard data types supported in `lightning-datatable` all use the standard layout.

To use the standard layout, specify `standardCellLayout: true` when you define your custom types.

```javascript
static customTypes = { customName: { template: customNameTemplate, standardCellLayout: true,
typeAttributes: ['accountName'], }, // Other types here }
```

See [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md).

When you create a custom data type and use the default bare layout, you can apply your own styles, align content in a column, configure text wrapping and clipping.

To support accessibility and keyboard navigation for a custom data type, use a slot for the custom data type. See [Accessibility for Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#accessibility-for-custom-data-types).

## Apply Styles on a Column

To apply styling to all rows in a column, pass the CSS classes to `cellAttributes` in the column configuration.

```javascript
const COLS = [
  {
    label: "Employees",
    type: "number",
    fieldName: "NumberOfEmployees",
    cellAttributes: {
      class: "slds-theme_shade slds-theme_alert-texture",
    },
  },
];
```

To apply styling to particular rows, use the `fieldName` attribute to wire up the CSS classes to your data definition. This example uses the `fieldName` property `industryClass` to apply blue text to rows that are in the Energy industry.

```javascript
/* myDatatable.js */
import { LightningElement, wire, track } from 'lwc';
import getAccountList from '@salesforce/apex/AccountController.getAccountList';

const COLS = [{
    label: 'Industry', fieldName: 'Industry',
    cellAttributes: {
        class: { fieldName: 'industryClass' },
    }
}, // Other columns here
];

export default class MyDatatable extends LightningElement {
    columns = COLS;
    @track accounts = [];

    @wire(getAccountList)
    wiredAccounts({error, data}) {
        if (error) {
            // Handle error
        } else if (data) {
            // Process record data
            this.accounts = data.map((record) => {
                let industryClass = record.Industry === 'Energy' ? 'slds-text-color_success' : '';
                return {...record, industryClass: industryClass}
            });

        }
    }
```

Custom classes are currently not supported. To apply custom styling, use the SLDS utility classes. For example, apply text color using the [SLDS text utility classes](https://www.lightningdesignsystem.com/utilities/text/).

## Align Content in a Custom Cell

You can align content in a column that uses the standard layout on a custom data type. In your `cellAttributes` definition, pass in the `alignment` property.

```javascript
const COLS = [
  {
    label: "Account Name",
    type: "customName",
    fieldName: "Name",
    cellAttributes: {
      alignment: "right",
    },
  },
];
```

Supported `alignment` values are `left`, `center`, and `right`.

By default, standard number types align to the right. Standard number types include the `currency`, `number`, and `percent` data types.

## Text Wrapping and Clipping

When you create a custom data type, implement the text wrapping and clipping with the SLDS utility classes `slds-hyphenate` and `slds-truncate`. These classes enable the custom data cell to display correctly when users change the wrap text selection in the datatable column header. Text wrapping expands the rows vertically to reveal more content. Text clipping truncates the content to a single line within the column.

Let’s say you have a custom data type template that displays account names. The column displays with the text clipped by default, which truncates content with a trailing ellipsis.

<!-- prettier-ignore -->
```html
<template>
  <template lwc:if={wrapText}>
    <div class="slds-hyphenate">{typeAttributes.accountName}</div>
  </template>
  <template lwc:else>
    <div class="slds-truncate">{typeAttributes.accountName}</div>
  </template>
</template>
```

You can also create a getter that returns the SLDS utility classes based on the `wrapText` value.

To display wrapped text, select **Wrap text** from the dropdown menu on the column header.

Alternatively, to display wrapped text on a column when the datatable loads, pass in `wrapText: true` to the column definition.

```javascript
const COLS = [
  {
    label: "Account Name",
    type: "customText",
    wrapText: true,
    typeAttributes: {
      accountName: { fieldName: "Name" },
    },
  },
];
```

You can control how many lines are displayed when column content is wrapped. Set `wrap-text-max-lines` in your extended datatable component to display a number of lines before hiding the rest. The datatable applies [line clamping](https://www.lightningdesignsystem.com/utilities/line-clamp) to allow for multi-line text truncation.

<!-- prettier-ignore -->
```html
<template>
  <c-my-custom-type-datatable
    key-field="id"
    data={accounts}
    columns={columns}
    wrap-text-max-lines="2"
  >
  </c-my-custom-type-datatable>
</template>
```

**note:** `wrap-text-max-lines` isn't supported for [Internet Explorer 11](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md). The entire text in a column appears if `wrapText` is true.

**See Also**

- [_Lightning Design System_: Hyphenation](https://www.lightningdesignsystem.com/utilities/hyphenation/)
- [_Lightning Design System_: Truncation](https://www.lightningdesignsystem.com/utilities/truncation/)

<!-- document id=d7ad306ad7a0a28184dfc830d2b807c6156eebdca42b12fc534bdc19a80ba896 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-validate-external-internal-input.md -->

# Customize Input Validation Errors for Screen Components

Create a Lightning web component that gives your screen flow users the best experience with the component’s error messages at run time. To customize where and how to display errors, implement these methods in the component to take control of rendering errors.

- `validate()`
- `setCustomValidity(externalErrorMessage: string)`
- `reportValidity()`

The flow calls the `validate()` method when a flow user navigates to the next screen or finishes the flow. The flow calls the new `setCustomValidity(externalErrorMessage: string)` method when there are input validation errors. When the `setCustomValidity(externalErrorMessage: string)` method is called, the component stores the input validation error message from the flow, so it can be displayed later. The flow calls the `reportValidity()` method when it’s time to render any errors that your component is aware of.

**See Also**

- [Example: Custom Validation for Components in Flows](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-example.md)

<!-- document id=4dc9f81473595b7fa540a46e2df732529441dd7535e132e22bba9e06a759c703 url=/developer/current/en-us/lwc/slds-validator/guides/customize.md -->

# Customize SLDS Validator

If you’re working in SLDS 2, you must turn on SLDS 2 validation in VS Code Settings. To maximize your use of SLDS Validator with SLDS 1 or SLDS 2, consider turning on other available custom settings.

You can access custom settings for SLDS Validator by either of these methods.

- Open VS Code Settings > Settings. Select **SLDS Validator**.
- Open the VS Code Command Palette, then search for **SLDS:**.

## SLDS 2

Turn on SLDS 2 recommendations by using one of these methods.

- In Settings, select **Enable SLDS 2 validation**. When selected, SLDS 2 validation is enabled.
- In Command Palette, select **SLDS: Enable SLDS 2 validation**.

To turn off SLDS 2 validation, use one of these methods.

- In Settings, deselect **Enable SLDS 2 validation**.
- In Command Palette, select **SLDS: Disable SLDS 2 validation**.

As you work in SLDS 2, you use styling hooks, not design tokens. To eliminate noise, turn off the design token settings by using one of these methods.

- In Settings, deselect the **Deprecated** and **Design Token** settings. When checked, these settings are turned off.
- In Command Palette, select **SLDS: Disable Design Token Suggestion** and **SLDS: Disable Deprecated Suggestion**

## Custom Settings

To enhance your work with SLDS Validator, consider turning on these customizations in Settings.

- **Auto Suggest**. Receive suggestions automatically.
- **BEM Naming**. Receive BEM naming suggestions.
- **Color Contrast**. Detect color contrast.
- **Density**. Detect density tokens and classes.
- **Enabled**. Turn on or off SLDS Validator in VS Code.
- **Invalid**. Detect invalid SLDS utility classes.
- **Mobile Validation**. Receive SLDS validation for Salesforce mobile app.
- **Override**. Override the detection of SLDS utility classes.
- **Scope With In SLDS**. Run SLDS Validator only on Salesforce DX files.

<!-- document id=100dfaff7629a2f69c46de8607b09320f798f933b3b9fbb2bda8aaa2334481b0 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-data-binding.md -->

# Data Binding Behavior Differences With Aura

When you add a component in markup, you can initialize public property values in the component based on property values of the owner component. In Lightning Web Components, the data binding for property values is one-way. The data-binding behavior is different for the Lightning Web Components and Aura development models.

## Aura

Aura has two forms of expression syntax for data binding.

Here’s a summary of the differences between the forms of expression syntax.

- `{#expression}` (Unbound Expressions)

  - : Data updates behave as you would expect in JavaScript. Primitives, such as `String`, are passed by value, and data updates for the expression in the parent and child are decoupled.

    Objects, such as `Array` or `Map`, are passed by reference, so changes to the data in the child propagate to the parent. However, change handlers in the parent aren’t notified. The same behavior applies for changes in the parent propagating to the child.

- `{!expression}` (Bound Expressions)

  - : Data updates in either component are reflected through bidirectional data binding in both components. Similarly, change handlers are triggered in both the parent and child components.

## Lightning Web Components

The data binding between components for property values is one-way.

To communicate down from a parent component to a child component, set a property or call a method on the child component.

To communicate up from a child component to a parent component, send an event.

For more information, see [Set Properties on Child Components](https://developer.salesforce.com/docs/platform/lwc/create/create-components-data-binding.md).

<!-- document id=169585d56dfb2963113fbb805e4999ef1c89c6e8e4907052e1cc2d39453e327d url=/developer/current/en-us/lwc/lwc/guides/create/create-components-data-flow.md -->

# Data Flow

To prevent code complexity and unexpected side effects, data should flow in one direction, from parent to child.

When a component decorates a field with `@api` to expose it as a [public property](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md), it should set the value only when it initializes the field. After the field is initialized, only the owner component should set the value. A component should treat values passed to it as read-only.

To trigger a mutation for a property value provided by an owner component, a child component can send an [event](https://developer.salesforce.com/docs/platform/lwc/events/events.md) to the parent. If the parent owns the data, the parent can change the property value, which propagates down to the child component via the one-way data binding.

## Objects Passed to Components Are Read-Only

A non-primitive value like an object or array that's passed to a component is read-only. The component cannot change the content of the object or array. If the component tries to change the content, you see an error in the browser console: `Uncaught Error: Invalid mutation: Cannot set "msg" on "[object Object]". "[object Object]" is read-only.`

To mutate the data, make a [shallow copy](https://developer.mozilla.org/en-US/docs/Glossary/Shallow_copy) of the objects you want to mutate. Let's take a look at a component that updates the value on an object.

<!-- prettier-ignore-->
```html
<!-- myCmp.html -->
<template>
  <p>{serializedObj}</p>
  <button onclick={updateShallowCopy}>Update</button>
</template>
```

Create a shallow copy of the object, which copies only the top-level properties. The values of the nested objects are not copied. In this example, `{"msg":"hello"}` is updated to `{"msg":"hello!"}` when the button is clicked.

```javascript
// myCmp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  obj = {
    msg: "hello",
  };

  get serializedObj() {
    return JSON.stringify(this.obj);
  }

  updateShallowCopy() {
    this.obj = { ...this.obj, msg: this.obj.msg + "!" };
  }
}
```

You can also reassign the value of the object using `this.obj = { msg: 'My new message' }`. The `myCmp` component owns the `obj` field, and it can assign a new value to the field. Contrastingly, if the component attempts to change the nested value on the object with `this.obj.msg = 'new value'`, you get an invalid mutation error in the web console.

Similarly, non-primitive values with references from a parent component are wrapped in a proxy and can't be modified. See [Set Properties on Child Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-data-binding.md).

To trigger a mutation for a property value provided by an owner component, a component should send an [event](https://developer.salesforce.com/docs/platform/lwc/events/events.md) to the owner.

## Use Primitive Values for Public Properties

We recommend using primitive data types for properties instead of using object data types. Slice complex data structures in a higher-level component and pass the primitive values to the component descendants.

There are a few reasons that it’s better to use primitive values.

- Primitive values require specific `@api` properties that clearly define the data shape. Accepting an object or an array requires documentation to specify the shape. If an object shape changes, consumers break.
- Standard HTML elements accept only primitive values for attributes. When a standard HTML element needs a complex shape, it uses child components. For example, a `table` element uses `tr` and `td` elements. Only primitive types can be defined in HTML. For example, `<table data={...}>` isn't a value in HTML, only in Lightning Web Components.

**See Also**

- [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md)

<!-- document id=7d288ca87b1d28ea0543a8ed55854d3d0e0a52216b3e0d1ca1458dabf0759f70 url=/developer/current/en-us/lwc/lwc/guides/data/data-guidelines.md -->

# Data Guidelines

The easiest way to work with Salesforce data is to [use base components built on Lightning Data Service (LDS)](#use-base-components-built-on-lightning-data-service).
If you need more flexibility, [use a Lightning Data Service wire adapter](#use-lightning-data-service-wire-adapters-and-functions) directly. Each wire adapter provides different data and metadata. The wire service provisions the data and metadata to your component.

Start with the GraphQL wire adapter if you want to send multiple queries in one operation. Finally, if GraphQL and LDS wire adapters aren’t flexible enough, use Apex.

**important:** Lightning Data Service supports all custom objects and all the [standard objects](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) that User Interface API supports. Custom metadata types are not supported. Lightning Data Service doesn’t incur any API usage calls, but it is subject to general limits like the numbers of records returned.

## Use Base Components Built on Lightning Data Service

Lightning Data Service manages data for you; changes to a record are reflected in all the technologies built on it.

The base components built on [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md) are `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form`. They provide a UI to view, create, and edit a record—similar to the record detail page in Salesforce.

Use the `lightning-record*form` components to:

- Create a metadata-driven UI or form-based UI similar to the record detail page in Salesforce.
- Display record values based on the field metadata.
- Display or hide localized field labels.
- Display the help text on a custom field.
- Perform client-side validation and enforce validation rules.

Consider the following guidelines when using the `lightning-record*form` components.

### `lightning-record-form`

This component is the easiest way to display a form to create, edit, or view a record. The form switches between view and edit modes automatically when the user begins editing a field. The component uses the object's default record layout with support for multiple columns. It loads all fields in the object's compact or full layout, or only the fields that you specify.

**note:** To improve performance, specify fields instead of a layout whenever possible. Specify a layout only when you want the administrator, not the component, to control the fields that are provisioned. The component must handle receiving every field that is assigned to the layout for the context user.

### `lightning-record-edit-form` and `lightning-record-view-form`

To customize the form display or provide custom rendering of record data, use `lightning-record-edit-form` (to add or update a record) and `lightning-record-view-form` (to view a record). `lightning-record-edit-form` enables you to prepopulate field values using the `lightning-input-field` component.

See [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input-intro.md).

**note:** To create a custom UI or if you don’t need a metadata-driven UI, use a wire adapter.

## Use Lightning Data Service Wire Adapters and Functions

The `lightning/uiGraphQLApi` and `lightning/ui*Api` modules provide the Lightning Data Service (LDS) wire adapters and functions.

### GraphQL Wire Adapter

The GraphQL wire adapter manages your data using LDS via the [`lightning/graphql` module](https://developer.salesforce.com/docs/platform/lwc/reference/graphql/reference-graphql-intro.md). It provides a single endpoint that lets you query exact fields and objects without Apex. It reduces request payloads and minimizes the number of requests you need to fetch data for users, compared to other LWC wire adapters.

GraphQL can be more performant if you're replacing multiple requests via other wire adapters. When working with a large number of records, the wire adapter's pagination functionality can also help you present your data with ease and efficiency.

With shared caching by Lightning Data Service, field-level security, and user and org permissions, you can use GraphQL wire adapter features in these scenarios:

- Send multiple queries in one operation
- Request record data for multiple objects
- Query records with parent and child relationships
- Filter by criteria and order query results
- Work with dynamic record IDs
- Run mutation operations such as creating, updating, or deleting records

See [GraphQL API for LWC](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html).

### `lightning/ui*Api` Wire Adapters and Functions

To provision data reactively into your component, use the [wire service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md). In contrast, imperative JavaScript functions such as `createRecord`, `updateRecord`, and `deleteRecord` run only when you call them in your code—for example, in response to a user action. Imperative calls are explicit operations, not reactive data provisioning.

For example, you use the `@wire` annotation with [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) to access record data so that you can perform business logic or create a form that needs more customization than the LDS base components allow.

To create, edit, or delete single records, call the `createRecord`, `updateRecord`, and `deleteRecord` functions in the [`lightning/ui*Api`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md) module. Like the LDS wire adapters, you can use multiple functions to work with multiple records, but each operation is an independent transaction. To work with multiple records in a single transaction, use Apex.

To display a list of field values, such as a list of contact names, use [`getListUi`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-list-ui.md).

You can use multiple wire adapters to provision data for multiple records, but each operation is an independent transaction. To work with multiple records in a single transaction, use Apex.

**note:** To improve performance, use the wire adapter that returns the least amount of data that your use case requires.
For example, the GraphQL wire adapter returns only the data you query. In contrast, the `getRecord` LDS wire adapter returns child relationships and layout types in addition to the fields you specify.

See [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md) and [Create a Record](https://developer.salesforce.com/docs/platform/lwc/data/data-create-record.md).

## Use Apex

If you can’t use a base component, and you can’t use the Lightning Data Service wire adapters or functions, use Apex.

Unlike Lightning Data Service data, Apex data is not managed; you must refresh the data. If Apex data is provisioned via the wire service, refresh it by calling [`refreshApex()`](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md), which uses the wire configuration to get data and update the cache. If your code calls an Apex method imperatively, refresh the data by calling the method and then call [`notifyRecordUpdateAvailable(recordIds)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-notify-record-update.md) to update the cache. You only need to call `notifyRecordUpdateAvailable()` if you expect any relevant data to be updated in the LDS cache.`notifyRecordUpdateAvailable()` signals to LDS that some records are stale and refreshes those records that are in the LDS cache.

**note:** The use of `refreshApex` to refresh data from non-Apex wire adapters is deprecated. To refresh record data returned by a non-Apex wire adapter, use [`notifyRecordUpdateAvailable(recordIds)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-notify-record-update.md) instead.

Use Apex in these scenarios:

- To work with objects that aren’t [supported by User Interface API](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm), like Task and Event.
- To work with operations that User Interface API doesn’t support, like loading a list of records by criteria (for example, to load the first 200 Accounts with Amount > \$1M).
- To perform a transactional operation. For example, to create an Account and create an Opportunity associated with the new Account. If either create fails, the entire transaction is rolled back.
- To call a method imperatively, as opposed to via the wire service. You may want to call a method imperatively in response to clicking a button, or to delay loading to outside the critical path. When you call an Apex method imperatively, to refresh the data, invoke the Apex method again.

See [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md).

**important:** To prevent code complexity and unwanted side-effects, data should flow in one direction, from parent to child. To trigger a mutation, a component should send an [event](https://developer.salesforce.com/docs/platform/lwc/events/events.md) to its parent. Objects passed to a component are read-only. To mutate the data, a component should make a shallow copy of the objects it wants to mutate. It’s important to understand these concepts when working with data. See [Data Flow](https://developer.salesforce.com/docs/platform/lwc/create/create-components-data-flow.md).

## Apex and Lightning Data Service Considerations

Depending on your use case, you could be working with a combination of Apex and Lightning Data Service (LDS) wire adapters. Consider these guidelines when you work with data returned by Apex and LDS.

- Apex doesn't share a data cache or data store with LDS. Data that you fetch using Apex can be inconsistent with data fetched using LDS wire adapters in both online and offline conditions. For example, your component can behave unexpectedly if it fetches data using Apex and then uses the GraphQL wire adapter to perform a search query on the same data.
- When using SOQL to get data, use the GraphQL wire adapter when performing a fetch and search query. Using the GraphQL wire adapter consistently for both fetch and search can prevent issues such as fetching Apex data while retrieving a corresponding null value on your GraphQL wire adapter.

**See Also**

- [_Component Reference_: `lightning-record-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-form)
- [_Component Reference_: `lightning-record-edit-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-edit-form)
- [_Component Reference_: `lightning-record-view-form`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-view-form)

<!-- document id=1f6cc35ae41d88e1fb85a321eb9363bbfd0294109a0ffc8ad205c42ab48ab37b url=/developer/current/en-us/lwc/lwc/guides/data/data-table-a11y.md -->

# Datatable Accessibility

`lightning-datatable` allows user interaction via two modes—navigation mode and action mode. Use navigation mode to navigate from one data cell to another. Use action mode to move from one data cell to another and focus on actionable elements in a cell.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

## Navigation Mode

To enter navigation mode, begin by pressing Tab to go into the datatable. The first data cell in the table body receives focus, skipping over the checkbox column and header. Use the arrow keys to move to other cells. If you move to another cell and then click away from the datatable, tab back into the datatable to place focus on the last cell you were on.

In navigation mode, when you tab to a cell with an actionable element such as an email link or a button, press the Enter key or spacebar to switch to action mode and focus the item. If the cell contains only one actionable item, such as a record link, pressing the enter key or spacebar activates the item.

In navigation mode, actionable elements render with `tabindex="-1"`.

For example, a telephone number that uses the standard `phone` type renders like this.

```html
<a href="tel:(415) 000-0000" tabindex="-1">(415) 000-0000</a>
```

## Action Mode

To enter action mode, press the Enter key or Spacebar. Navigate to each actionable element in the table using the Tab or arrow keys.

In action mode, pressing tab or shift+tab moves between actionable elements in the table as expected. Press the arrow keys to move between actionable elements in that direction. Focus moves to the next cell in the given direction, as long as the cell doesn't contain any actionable elements.

In action mode, actionable elements render with `tabindex="0"`.

For example, a telephone number that uses the standard `phone` type renders like this.

```html
<a href="tel:(415) 000-0000" tabindex="0">(415) 000-0000</a>
```

When an actionable element is in focus and you press Enter, the action is triggered. For example, if you tab to a telephone link and press Enter, the link's `tel` protocol causes the browser to prompt you to open the default application to dial the number.

## Keyboard Navigation

In both navigation mode and action mode, you can use the arrow keys to move around the table.

| Arrow Key | Description                                                                                                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Up (↑)    | Moves focus to a cell above the current cell. If pressed on the header row, this key does not move focus.                                                                                                                         |
| Right (→) | Moves focus to the next cell. If pressed on the last cell of a row, this key does not move focus.                                                                                                                                 |
| Down (↓)  | Moves focus to a cell below the current cell. If pressed on a cell in the bottom row, this key does not move focus.                                                                                                               |
| Left (←)  | Moves focus to the previous cell. If pressed on the row numbering column, this key does not move focus. If the row numbering column isn't available and this key is pressed on the checkbox column, this key does not move focus. |

## Accessibility for Custom Data Types

In navigation mode, elements in a standard or custom data type don't participate in keyboard navigation. When you tab or press the arrow keys, focus moves to the cell but not to the elements within a standard or custom data type.

In this screen capture, the Name column uses a custom data type.

![Datatable that shows focus on cells in navigation mode](https://developer.salesforce.com/media/datatable_nav_mode.gif)

In action mode, interactive elements such as links and buttons can be focusable and become part of the tabbing order. For custom data types to participate in action mode, you must enable keyboard navigation on the elements in the component's custom data type template.

In this screen capture, the Name column uses a custom data type.

![Datatable that shows focus on cells and actionable elements](https://developer.salesforce.com/media/datatable_action_mode.gif)

To enable keyboard navigation in custom data types:

- Pass the attribute `tabindex="internalTabIndex"` to any component or element in the custom type. If you don't want an element to be focusable, set `tabindex=-1`.
- Set `data-navigation="enable"` on any elements within the custom type that you want to be keyboard navigable. Also set `data-navigation="enable"` on any element that has a child component that's focusable.

`lightning-datatable` passes the accessibility attribute values to the custom data type as it reacts to the user’s keyboard navigation and focus actions.

<!-- prettier-ignore -->
```html
<a href="#" data-navigation="enable" tabindex={internalTabIndex}>Link 1</a>
<a href="#" data-navigation="enable" tabindex={internalTabIndex}>Link 2</a>
<lightning-formatted-url
  data-navigation="enable"
  tabindex={internalTabIndex}
  value="my/path"
  target="_blank"
></lightning-formatted-url>
```

## Example: Enable Keyboard Navigation in a Custom Data Type

In your custom data type template, pass in the accessibility attributes on a component or element to make it focusable and part of the tabbing order.

Let's say you have a custom data type template `customName.html`.

```ascii
myCustomTypeDatatable
   ├──customName.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml
```

This example makes the button icon in the custom data type focusable.

![Datatable that uses a custom data type with a focusable element](https://developer.salesforce.com/media/datatable_keyboard_nav.png)

Add the `data-navigation="enable"` and `tabindex={internalTabIndex}` attributes to an element or multiple elements in your template, which makes the element focusable and part of the tabbing order.

<!-- prettier-ignore -->
```html
<!-- customName.html -->
<template>
  <lightning-badge
    label={typeAttributes.contactName}
    icon-name="standard:contact">
  </lightning-badge>
  <lightning-button-icon
    icon-name="utility:edit"
    alternative-text="Edit"
    class="slds-m-left_xx-small"
    title="Save"
    data-navigation="enable"
    tabindex={internalTabIndex}>
  </lightning-button-icon>
</template>
```

In your JavaScript file, define the custom data type template for `lightning-datatable`.

```javascript
// myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNameTemplate from "./customName.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      standardCellLayout: true,
      typeAttributes: ["contactName"],
    },
    // Other custom types here
  };
}
```

Since the JavaScript file imports the custom data type template `customName.html`, you don't need the `myCustomTypeDatatable.html` file. If you include it, use only an empty root `<template>` tag in the file.

Use your custom datatable in a component. For example:

```ascii
myDatatable
   ├──myDatatable.html
   ├──myDatatable.js
   └──myDatatable.js-meta.xml
```

Load the record data on your datatable.

<!-- prettier-ignore -->
```html
<!-- myDatatable.html -->
<template>
  <lightning-card title="Custom Data Type with Keyboard Navigation" icon-name="custom:custom62">
    <c-my-custom-type-datatable
      key-field="Id"
      data={contacts.data}
      columns={columns}
    >
    </c-my-custom-type-datatable>
  </lightning-card>
</template>
```

In your JavaScript file, define your column data and get your record data.

```javascript
// myDatatable.js
import { LightningElement, wire } from "lwc";
import getContacts from "@salesforce/apex/ContactController.getContactList";

const COLS = [
  { label: "First Name", fieldName: "FirstName" },
  { label: "Last Name", fieldName: "LastName" },
  {
    label: "Name",
    type: "customName",
    typeAttributes: {
      contactName: { fieldName: "Name" },
    },
  },
  { label: "Title", fieldName: "Title" },
  { label: "Phone", fieldName: "Phone", type: "phone" },
  { label: "Email", fieldName: "Email", type: "email" },
];

export default class MyDatatable extends LightningElement {
  columns = COLS;

  @wire(getContacts)
  contacts;
}
```

The Apex controller for this example looks like this.

```java
// ContactController.cls
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT
                Id, Name, FirstName, LastName, Title, Phone, Email
            FROM Contact
            LIMIT 10
        ];
    }
}
```

## Accessibility for Custom Data Types with Slot

To work with dynamic custom data types, use the `customdatatypes` slot on `lightning-datatable`. See [How to Define Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md#how-to-define-custom-data-types).

If you use a slot for a custom data type, the custom data type can also participate in the datatable's keyboard navigation. As described in the previous sections, you must first use the `data-navigation` and `tabindex` accessibility attributes on elements in the custom data type template.

<!-- prettier-ignore -->
```html
<!-- exampleCustomDataType.html -->
<template>
  <img
  src={pictureUrl}
  alt="Profile photo"
  data-navigation="enable"
  tabindex={internalTabIndex}
  />
</template>
```

## Example: Enable Keyboard Navigation in a Custom Data Type with Slot

In some cases, you may want to use a custom data type with a child component. For example, the child component can include JavaScript code to handle a click event.

Let's say you have a custom data type template `customPicture.html` that's defined in `myCustomTypeDatatable.js`.

```ascii
myCustomTypeDatatable
   ├──customPicture.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml
```

This example makes an image element focusable in the child custom data type. It builds on the [custom data type with slot example](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md#example-implement-a-datatable-with-a-dynamic-custom-data-type) to add keyboard navigation support. The accessibility attributes pass from a child component to the custom data type template.

![Datatable that uses a custom data type with a focusable element](https://developer.salesforce.com/media/datatable_keyboard_nav_slot.png)

The `customPicture.html` template contains a child component `customPic`, which handles the click event. Note that the parent `customPicture` component uses `internal-tab-index={internalTabIndex}` instead of `tabindex={internalTabIndex}`.

<!-- prettier-ignore -->
```html
<!-- customPicture.html -->
<template>
  <c-custom-pic
    picture-url={typeAttributes.pictureUrl}
    record-id={typeAttributes.recordId}
    internal-tab-index={internalTabIndex}
    data-navigation="enable"
  >
  </c-custom-pic>
</template>
```

In the JavaScript file, use the `getDataTypes()` function to return your custom data type template. Use the `pictureUrl` attribute to provide the source path of the contact image. Use `recordId` attribute to navigate to the corresponding contact record page when you click a contact image on the datatable.

```javascript
// myCustomTypeDatatable.js
import { LightningElement, api } from "lwc";
import customPicture from "./customPicture.html";

export default class CustomDataTypes extends LightningElement {
  @api getDataTypes() {
    return {
      customPictureType: {
        template: customPicture,
        standardCellLayout: true,
        typeAttributes: ["pictureUrl", "recordId"],
      },
      // Other custom types here
    };
  }
}
```

The `internalTabIndex` property is exposed as a public property on the `customPic` child component.

```ascii
customPic
   ├──customPic.html
   ├──customPic.js
   └──customPic.js-meta.xml
```

The child component also uses the `data-navigation` and `tabindex` accessibility attributes. It contains an image for the contact record. Using the accessibility attributes on the image ensures that it's focusable and part of the tabbing order.

<!-- prettier-ignore -->
```html
<!-- customPic.html -->
<template>
  <img
    src={pictureUrl}
    class="slds-avatar slds-avatar_circle slds-avatar_large"
    alt="Navigate to record page"
    onclick={handleClick}
    data-navigation="enable"
    tabindex={internalTabIndex}
  />
</template>
```

When clicked, the image redirects you to the contact record page using the [`lightning/navigation` module](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-basic.md).

```javascript
// customPic.js
import { LightningElement, api } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class CustomPic extends NavigationMixin(LightningElement) {
  @api pictureUrl;
  @api recordId;
  @api internalTabIndex;

  handleClick() {
    // View a custom object record.
    this[NavigationMixin.Navigate]({
      type: "standard__recordPage",
      attributes: {
        recordId: this.recordId,
        actionName: "view",
      },
    });
  }
}
```

Use your custom datatable in a component. For example:

```ascii
myDatatableSlot
   ├──myDatatableSlot.html
   ├──myDatatableSlot.js
   └──myDatatableSlot.js-meta.xml
```

Load the record data on your datatable. This example includes a button that when clicked displays the custom data type via the `customdatatypes` slot.

<!-- prettier-ignore -->
```html
<!-- myDatatableSlot.html -->
<template>
    <lightning-card
        title="Datatable Custom Data Type (with slot)"
        icon-name="custom:custom62"
    >
        <lightning-button label="Add Custom Type" onclick={addCustomTypes} disabled={buttonDisabled}></lightning-button>

        <lightning-datatable
            key-field="Id"
            data={contacts.data}
            show-row-number-column
            column-widths-mode="auto"
            columns={columns}>
            <template if:true={showCustomTypes}>
                <c-my-custom-type-datatable slot="customdatatypes"></c-my-custom-type-datatable>
            </template>
        </lightning-datatable>
    </lightning-card>
</template>

```

In your JavaScript file, define your column data and get your record data.

```javascript
// myDatatableSlot.js
import { LightningElement, wire } from "lwc";

import getContacts from "@salesforce/apex/ContactController.getContactList";

const COLS = [
  { label: "First Name", fieldName: "FirstName" },
  { label: "Last Name", fieldName: "LastName" },
  { label: "Title", fieldName: "Title" },
  { label: "Phone", fieldName: "Phone", type: "phone" },
  { label: "Email", fieldName: "Email", type: "email" },
  {
    label: "Contact Picture",
    type: "customPictureType",
    typeAttributes: {
      pictureUrl: { fieldName: "Picture__c" },
      recordId: { fieldName: "Id" },
    },
  },
];
export default class MyDatatableSlot extends LightningElement {
  columns = COLS;

  @wire(getContacts)
  contacts;

  showCustomTypes = false;
  buttonDisabled = false;

  addCustomTypes() {
    this.showCustomTypes = true;
    this.columns = [...COLS];
    this.buttonDisabled = true;
  }
  constructor() {
    super();
    this.columns = [...COLS].filter((col) => col.type != "customPictureType");
  }
}
```

The Apex controller for this example looks like this.

```java
// ContactController.cls
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT
                Id, Name, FirstName, LastName, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Picture__c != NULL
            LIMIT 10
        ];
    }
}
```

**See Also**

- [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md)

<!-- document id=68f97240c52b69ea6e28d1ebb81b71323e95c51ea26cba082c6ef01b95053435 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-lwsec.md -->

# Debug Components in an Org with LWS Enabled

To debug Lightning web components in an org where [Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html) is enabled, first [enable debug mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md) for the best debugging experience.

Debugging techniques are generally the same for code that's sandboxed by LWS compared to code in orgs where LWS isn't enabled, but there are a few differences. See [Debug with Lightning Web Security Enabled](/docs/platform/lightning-components-security/guide/lws-debug.html) in _Security for Lightning Components_.

**See Also**

- [Debug Mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-debug-mode.md)
- [Debug Using Chrome DevTools](https://developer.salesforce.com/docs/platform/lwc/debug/debug-dev-tools.md)
- [_Security for Lightning Components_: Limitations for Debugging with LWS Enabled](/docs/platform/lightning-components-security/guide/lws-debug-limitations.html)
- [_Security for Lightning Components_: Workflow to Test Your Components with Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-test-workflow.html)

<!-- document id=170416c7894e8d34ac98a05287de8937a0163baed59c9f67d73571afa04bd4f5 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-debug-tests.md -->

# Debug Jest Tests for Lightning Web Components

VS Code provides tools to help you debug Jest tests efficiently. Use the Salesforce Extension Pack, Chrome DevTools, or the VS Code debugger advanced configuration, depending on your testing requirements.

## Debug Tests Using the Salesforce Extension Pack

[Salesforce Extensions for Visual Studio Code](https://developer.salesforce.com/tools/vscode/en/getting-started/install) provides an LWC Tests sidebar for you to run tests easily. You can run one test case, all the test cases in one file, or all the tests for your project. For more information, see the [overview of capabilities in the LWC Tests sidebar.](https://developer.salesforce.com/tools/vscode/en/lwc/testing).

To debug your test, add breakpoints in the test.

![Add breakpoints and debug your Jest test](https://developer.salesforce.com/media/unit_test_debug_breakpoint.png '{"class": "image-md"}')

For example, if you want to make sure that an event is dispatched correctly, click the line number (1) that contains your `dispatchEvent()` method. You can also add a breakpoint on your event handler in the component's JavaScript file to observe when the event handler is fired.

After adding breakpoints, click Debug Test (2). This link runs the command: `node --inspect-brk node_modules/.bin/jest --runInBand`.

**tip:** See `helloConditionalRendering.test.js` in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repository.

Display information related to running and debugging in the [Run view](https://code.visualstudio.com/docs/editor/debugging#_run-view).

![Run and debug your tests and inspect the elements in the debug console](https://developer.salesforce.com/media/unit_test_debug_panels.png '{"class": "image-md"}')

To open the Run view, click Run and Debug (1), where you can watch your expressions (2), and use the debug toolbar (3) to step through the test execution. In the Debug Console (4), you can inspect the element at the point of the test execution.

Click Continue on the [debug toolbar](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) (3) to step through your breakpoints. Your test finishes successfully if you don't receive an error. View any test execution output in the VS Code terminal.

::video{src="https://youtube.com/embed/OOGn0JLabS0" title="Debugging Jest Salesforce Extensions" type="youtube" }

**tip:** See [Run, Debug or Watch Jest Tests from Within a File](https://developer.salesforce.com/tools/vscode/en/lwc/testing#run-debug-or-watch-jest-tests-from-within-a-file) for more debugging techniques.

## Debug Tests Using Chrome DevTools

While the Salesforce Extension Pack enables you to debug your Jest tests from within VS Code, [Chrome DevTools](https://developer.chrome.com/docs/devtools/) offers you comprehensive diagnostics features for web development.

To run all the tests in your project in debug mode, enter this command in the VS Code terminal.

```bash
npm run test:unit:debug
```

This command calls `sfdx-lwc-jest --debug`, which then runs `node --inspect-brk node_modules/.bin/jest --runInBand`.

**note:** We recommend that you use the `npm run test:unit:debug` command since `sfdx-lwc-jest` is resolved as a node dependency and isn't accessible on the command line.

To run a single test in debug mode, enter this command, where `testName` is the name of the test you want to debug.

```bash
npm run test:unit:debug -- testName
```

Next, open a Chrome browser and go to `chrome://inspect`. The Remote Target section lists all the node processes running in your system in debug mode.

![Launch Chrome Developer Tools to debug your tests](https://developer.salesforce.com/media/unit_test_debug_chrome.png '{"class": "image-md"}')

To open the DevTools window, click the **inspect** link under the Jest test listed in the Remote Target section.

The DevTools Sources panel enables you to debug your tests. First, add a `debugger` statement in your test code in VS Code.

**note:** The Chrome inspector doesn't step through the breakpoints you specify in VS Code in the previous section. Use the `debugger` statement in your test instead.

To resume test execution, click the Resume script execution (![Resume icon](https://developer.salesforce.com/media/unit_test_debug_resume.png)) button in DevTools. The test displays your test code and stops at the `debugger` statement you added, as shown on line 36 of the compiled code. You can then add breakpoints in the Sources panel, as shown on line 37 in this screenshot.

![Add breakpoints in the DevTools window](https://developer.salesforce.com/media/unit_test_debug_devtools.png '{"class": "image-md"}')

**tip:** See [Debug JavaScript](https://developer.chrome.com/docs/devtools/javascript/) for more debugging techniques using Chrome DevTools.

If you require more control on how to run your Jest tests in debug mode, consider [using the VS Code advanced configuration](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-advanced.md).

::video{src="https://youtube.com/embed/TDHCrLAn33E" title="Debugging Jest Tests with Chrome Developer Tools " type="youtube" }

<!-- document id=71fdc2be8ac2f4cf63e78dba2479dfb12da12012c9f5ad9670daee6a21f0199b url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-advanced.md -->

# Debug Jest Tests Using VS Code Advanced Configuration

VS Code lets you configure how you want to run your Jest tests in debug mode.

To use the advanced configuration:

1.  Generate the launch configuration file.

    1.  In the [Run view](https://code.visualstudio.com/docs/editor/debugging#_run-view), click the **create a launch.json file** link.

        ![Generate a launch.json file from the Run and Debug tab](https://developer.salesforce.com/media/unit_test_debug_customize.png)

    2.  In the dropdown that appears, select **Node.js**, which creates a `launch.json` file for you. Replace the content of `launch.json` with the configuration shown in [Debugging in Visual Studio Code](https://github.com/salesforce/sfdx-lwc-jest#debugging-in-visual-studio-code) in the sfdx-lwc-jest repository.

        **note:** The configuration is different for Mac and Windows users. Follow the directions in the sfdx-lwc-jest repository to find the configuration for your operating system.

        To customize your launch configuration for different debuggers and debugging scenarios, use [VS Code's `launch.json` attributes](https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes).

2.  Add a Jest configuration file `jest.config.js` at the root of your Salesforce DX project. In this file, include the configuration code available at [Overriding Jest Config](https://github.com/salesforce/sfdx-lwc-jest#overriding-jest-config) in the sfdx-lwc-jest repository. The configuration code looks like this.

    ```javascript
    const { jestConfig } = require("@salesforce/sfdx-lwc-jest/config");
    module.exports = {
      ...jestConfig,
      // add any custom configurations here
    };
    ```

3.  Add `debugger` statements in your test code and component's JavaScript file.

    **note:** When debugging using the advanced configuration in VS Code, adding breakpoints isn't supported. The line number to which you add a breakpoint doesn’t match the line number in the compiled file. Use the `debugger` statement instead.

4.  Launch the configuration file. Go to the [Run view](https://code.visualstudio.com/docs/editor/debugging#_run-view). Select the **Debug Jest Tests** configuration and click Start Debugging (![Start debugging icon](https://developer.salesforce.com/media/unit_test_debug_run.png)).

    This command runs all the tests in your project by default, stopping in all the debugger statements you added in your test code and component's JavaScript file. You can view the execution output in the VS Code terminal, and use the debug features in VS Code, such as inspecting the variables using the Debug Console.

::video{src="https://youtube.com/embed/x3EbNOiczm4" title="Debugging Jest Tests with VSCode Debugger Advanced Configuration" type="youtube" }

**tip:** For information about troubleshooting Jest issues, see [`jestjs.io/docs/en/troubleshooting`](https://jestjs.io/docs/troubleshooting).

<!-- document id=0f8f819bac9201adde07d91b91f7cb327e0df51ee5180522513324e000db6e6e url=/developer/current/en-us/lwc/lwc/guides/debug/debug-intro.md -->

# Debug Lightning Web Components

Lightning web components are built using standard HTML and JavaScript, and on the desktop they run in a variety of supported browsers. You can use standard browser and JavaScript debugging tools, like Chrome DevTools, to debug your components during development. To review mobile-specific features, use a mobile device or virtual device build.

The simplest way to run and debug a component during development is to create a [Lightning Page](https://help.salesforce.com/s/articleView?language=en_US&id=platform.lightning_page_overview.htm&type=5) and add your component to it. Then load the Lightning Page in your preferred browser and use your favorite inspection and debugging tools. LWC debugging is optimized for Chrome DevTools.

**note:** This content is adapted from Salesforce Principal Developer Evangelist René Winklemeyer’s blog post, [**Debug Your Lightning Web Components**](https://developer.salesforce.com/2019/02/debug-your-lightning-web-components).

**See Also**

- [_Salesforce Developers Blog_: Debug Your Lightning Web Components](https://developer.salesforce.com/2019/02/debug-your-lightning-web-components)
- [Supported Browsers](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md)
- [View Component Dependencies](https://developer.salesforce.com/docs/platform/lwc/create/create-components-view-dependencies.md)

<!-- document id=0e541447d7aa36a41905f1791c94d3daa9584f21593fb53b8ff4695575b8252c url=/developer/current/en-us/lwc/lwc/guides/debug/debug-mobile.md -->

# Debug Mobile Components

You can test mobile basics, like small screen sizes and responsive design, in a desktop browser using tools like Device Mode in Chrome DevTools. To review mobile-specific features, use the Salesforce Mobile app on a real mobile device.

With Lightning on Mobile, the desktop and mobile versions of Salesforce provide the same user interface: Lightning Experience. This means that, while it’s not a substitute for comprehensive testing on actual mobile devices, you can use your desktop browser to run and debug many aspects of your mobile Lightning apps and components.

Chrome DevTools Device Mode lets you simulate these aspects of mobile devices:

- Screen size
- Device orientation
- Location changes
- Mobile device CPU constraints
- Wireless network constraints

To learn more about Device Mode, refer to [Simulate Mobile Devices with Device Mode in Chrome DevTools](https://developer.chrome.com/docs/devtools/device-mode/) on the Google Chrome DevTools website.

**See Also**

- [_Google_: Simulate Mobile Devices with Device Mode in Chrome DevTools](https://developer.chrome.com/docs/devtools/device-mode/)
- [_Apple_: Simulate responsive web content on Apple devices DevTools](https://support.apple.com/guide/safari-developer/simulate-responsive-web-content-apple-devices-dev84bd42758/mac)

<!-- document id=15e022b6d38b6413af19b50a1baf15bd4c9429816dd972428a372c20a7e9745e url=/developer/current/en-us/lwc/lwc/guides/debug/debug-debug-mode.md -->

# Debug Mode

In debug mode, JavaScript code is easier to read and debug. The JavaScript source you see in DevTools looks similar to your uncompiled source code. Debug mode also adds more detailed output for some warnings and errors.

Component code is compiled in both production mode and debug mode. In debug mode, the compiled JavaScript code isn’t optimized or minified. The LWC compiler can generate information that enables more advanced debugging features.

After your user account is [enabled for debug mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md), you see these changes.

- A banner appears at the top to remind you that debug mode is on and that it slows things down.
- An [Experienced Page Time (EPT)](https://help.salesforce.com/s/articleView?id=xcloud.technical_requirements_ept.htm&type=5) metric appears in the page header. It’s presented in green, orange, or red to indicate the health of the page’s load time.
- A storage metric in the page header shows kilobytes of data stored by the page to indicate memory usage and caching. The metric is similarly color-coded with green, orange, or red.

![Page header with EPT and kilobyte metrics](https://developer.salesforce.com/media/debug_enabled_ept.png)

The same lwc-recipes sample code we looked at in production mode with pretty print looks less cryptic when unminified with debug mode enabled. It’s more readable and shows names of functions and variables.

![Source unminified in debug mode](https://developer.salesforce.com/media/debug_source_debug_mode.png)

**See Also**

- [Enable Debug Mode in Salesforce](https://developer.salesforce.com/docs/platform/lwc/guide/debug-mode-enable.md)
- [HTTP Caching for Custom Components](https://developer.salesforce.com/docs/platform/lwc/guide/debug-http-caching.md)

<!-- document id=6b54a893f20939c58d2e61da21041ffa92bab8f9355eec1e08c47ccb8f7ceecc url=/developer/current/en-us/lwc/lwc/guides/debug/debug-dev-tools.md -->

# Debug Using Chrome DevTools

To debug Lightning web components code, use Chrome DevTools.

Google Chrome includes a comprehensive suite of excellent web development tools, Chrome DevTools. These tools are great for debugging your Lightning web components.

To get started, load the simplest page possible that can run your Lightning component. Then open DevTools.

- On Windows and Linux, press Control-Shift-I in your Google Chrome browser.
- On Mac, press Option-Command-I.
- On any platform, press F12 or right-click in the page and select Inspect.

To quickly find which line of code is failing, in the Sources panel, enable the **Pause on all exceptions** option in the DevTools debugger panel before running your code.

![Debugger panel's Pause on exceptions button](https://developer.salesforce.com/media/debug_pause_exceptions.png)

When you enable Pause on exceptions, the browser halts on exceptions that are caused by Salesforce code, other library code, and your component code. Exceptions thrown by your components can be caught in the framework code.

To learn more about debugging JavaScript on Google Chrome, refer to the [Google Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/) website.

Check out [Troubleshooting Lightning Web Components](https://trailhead.salesforce.com/en/content/learn/trails/troubleshoot-lightning-web-components) on Trailhead for step-by-step instructions using Chrome DevTools with Lightning web components.

## Find Your Code in the Sources Panel

In the Sources panel of Chrome DevTools, find your Lightning web component code in the Page pane in the `lightning/n/modules` folder. Here you see components in the default `c` namespace folder.

![Source code in the lightning/n/modules/c folder](https://developer.salesforce.com/media/debug_source_modules_folder.png)

**tip:** For info about debugging with Lightning Web Security (LWS) enabled, see [Debug with Lightning Web Security Enabled
](/docs/platform/lightning-components-security/guide/lws-debug.html) in _Security for Lightning Components_.

## Enable Custom Formatters

More debugging features are available when you enable custom formatters.

In Chrome DevTools, select **Settings (![DevTools Settings icon ](https://developer.salesforce.com/media/debug_chrome_gear.png))** | **Preferences** | **Console** | **Enable custom formatters**.

The custom formatter for Lightning Web Components lets you see the real values contained in proxy objects. While you don’t see proxy objects while debugging, they’re still present and preventing modifications. The custom formatter enables visibility into the proxies without removing them.

**tip:** If Lightning Web Security is enabled in the org, custom formatters also let you see additional messages and a filtered call stack in the DevTools console. See [Debug with Lightning Web Security Enabled
](/docs/platform/lightning-components-security/guide/lws-debug.html) in _Security for Lightning Components_.

## Console Warnings from the LWC Engine

In debug mode, the Lightning Web Components engine identifies bad patterns that are only detectable during runtime, and prints them as console warnings.

It’s a best practice to develop your Lightning web components in an org using debug mode. You can improve your code while you develop by using feedback from the LWC engine.

One way to filter for only your own components is to remove the “info” log level to hide the stack traces.

**See Also**

- [_Trailhead_: Troubleshoot Lightning Web Components](https://trailhead.salesforce.com/en/content/learn/trails/troubleshoot-lightning-web-components)
- [_lwc-recipes_ repository](https://github.com/trailheadapps/lwc-recipes)
- [_Security for Lightning Components_: Debug with Lightning Web Security Enabled
  ](/docs/platform/lightning-components-security/guide/lws-debug.html)

<!-- document id=5bfc474aca1a4557dfea683bbba3166790e097f7a1fb1b6d92d2dc193bbb2da7 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-wire.md -->

# Debug Wire Adapters

Use debug mode to troubleshoot your wire adapters with unminified JavaScript and custom formatting.

The easiest way to debug your wire adapters is via Chrome DevTools.

To debug a wire adapter:

1.  [Enable debug mode.](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md)
2.  [In Chrome DevTools, enable custom formatters.](https://developer.salesforce.com/docs/platform/lwc/debug/debug-dev-tools.md)

When you receive data via an `@wire`, your data is bound to a function or a property.

## Inspect a Wired Function

If you use a wired function, you can debug based on the deconstructed `data` and `error` properties in the Sources panel of Chrome DevTools.

![View the Sources panel to inspect your wired function.](https://developer.salesforce.com/media/debug_wire_function.png)

Alternatively, you can debug a wired function using the method described in the next section.

## Inspect a Wired Property or Method

If you use a wired property or method on a component, debug information is available via the custom object formatter.

Each wired property or method returns information with the following shape:

- `data`—The last value returned by the wire adapter
- `config`—The last config reported to the wire adapter
- `context`—Only for context wire adapters
- `isDataProvisionedForConfig`—A boolean that returns whether or not the data provisioned by the wire adapter corresponds to the config. If a config was reported, it returns `true`.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an [`apexWireMethodToProperty`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/apexWireMethodToProperty) component that uses a wired property.

Inspect a component instance using `this` or inspect a rendered LWC custom element. For example, click the `<c-apex-wire-method-to-property>` element in the Elements panel of Chrome DevTools.

![Inspect your element in the Elements panel.](https://developer.salesforce.com/media/debug_wire_elements.png)

After you click on the element, open the Console panel and [enter `$0`](https://developer.chrome.com/docs/devtools/console/utilities/) to return the debug information.

![Review the debug information on your element.](https://developer.salesforce.com/media/debug_wire_property.png)

**tip:** An undefined reactive parameter prevents the wire from firing, so both `data` and `error` stay undefined. Confirm that every `$`-prefixed config value has an initial value on the class. See [Wire Service Syntax](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md#wire-service-syntax).

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

<!-- document id=98a30c35cb9b65ce72b3e09fbfff6e6462ae43ee215afbbbad5fb16b887f1ec1 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-debug-distortion-flags.md -->

# Debug with Distortions Disabled

To switch Lightning Web Security (LWS) [distortions](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md#distortions) off and on for certain APIs while you debug, use commands in your browser’s developer console. It can be helpful to observe how your component’s behavior changes when you disable distortions on a particular API and then enable them again.

Before you can disable distortions, you must [enable debug mode](/docs/platform/lwc/guide/debug-mode-enable.html) for your username in the org. Then you can set flags in the browser’s developer console to disable and enable distortions on APIs.

**tip:** We recommend using Chrome and [Chrome DevTools](https://developer.chrome.com/docs/devtools). See [Debug Using Chrome DevTools](/docs/platform/lwc/guide/debug-dev-tools.html) in the _Lightning Web Components Developer Guide_.

## Workflow to Debug with Distortion Flags

The distortion flags are most useful if you set them when the execution is paused, such as when you hit a breakpoint. We recommend using this workflow:

1. Identify a point in your code that you want to debug and set a breakpoint.
2. Refresh the browser page and walk through the steps needed to reach that breakpoint.
3. When execution pauses at the breakpoint, go to the console and [disable distortions](#disable-and-enable-distortions-while-debugging) that you suspect are affecting your code.
4. Allow the code execution to continue and observe if the behavior of your code changes with the distortions disabled.

## Disable and Enable Distortions While Debugging

To disable and enable distortions for a given API, use `$LWS.namespaces` commands in the browser’s developer console to set the values of corresponding distortion flags.

You can work with multiple namespaces that are present in your org. The commands target distortions in the namespace you specify.

The command syntax is:

`$LWS.namespaces.`_ns_`.distortions.`_flag_

where _ns_ represents the namespace and _flag_ represents a distortion flag name.

### List the Distortion Flags

To list the distortion flags in the `c` default namespace, enter this command in the browser’s developer console and press Enter.

```
$LWS.namespaces.c.distortions
```

The list of distortion flags is collapsed initially. Click the expander icon to reveal the distortion flag names.

![List of distortion flags in c](https://developer.salesforce.com/media/debug_lws_distortion_flags.png)

See [LWS Distortion Flags for Debug Sessions](#lws-distortion-flags-for-debug-sessions) for descriptions of the distortion flags.

**note:** Don’t use these deprecated flags. Disabling the distortions associated with these flags can cause your code to break in the debugger.

- `dataset`
- `history`
- `indexedDB`
- `notification`
- `performance`
- `postMessage`
- `style`

### Disable a Distortion

To disable distortions for an API using one of the listed distortion flags, set the flag to `false`. For example, to disable distortions for the `XMLHttpRequest` API, type this command and press **Enter**.

```
$LWS.namespaces.c.distortions.xhr = false
```

In the developer tools’ Sources view, use the debugger panel to observe the component running with the specified LWS distortions disabled.

### Enable a Distortion

To enable the distortion again in the current session, set the property to `true`.

```
$LWS.namespaces.c.distortions.xhr = true
```

**tip:** When you reload the page all the properties reset to `true`.

### List the Namespaces in Your Org

You can view which namespaces support disabling and enabling distortion flags in your org. The command reveals only custom namespaces. You can’t see the namespaces that Salesforce owns, for example.

Enter this command in the console:

```
$LWS.namespaces
```

The console displays a list of available namespaces. If you’re only using the default namespace, you see the `c` namespace.

![List of c namespace](https://developer.salesforce.com/media/debug_lws_distortion_flags_namespaces.png)

To see the distortion flags for a namespace, click the expander icon by the namespace.

In this example, the command shows the namespaces `external` and `untrusted` in a test org.

![List of other namespaces](https://developer.salesforce.com/media/debug_lws_distortion_flags_external_namespace.png)

All namespaces support the same flags. You can set the values separately in different namespaces, whichever is appropriate for the component you’re debugging.

You can also enter a command to display the distortion flags of a namespace. This example uses the command to display distortion properties in the `external` namespace.

```
$LWS.namespaces.external.distortions
```

### Check the Value of a Distortion Flag

To check the current value of a distortion flag, enter a command specifying the flag name.

For example, use this command to determine if all `XMLHttpRequest` distortions are enabled in the `c` namespace.

```
$LWS.namespaces.c.distortions.xhr
```

The flags are all set to `true` by default.

![Command shows the value of the xhr flag set to true](https://developer.salesforce.com/media/debug_lws_distortion_flag_value.png)

To disable all `XMLHttpRequest` distortions in the debugging session, set the `xhr` flag to `false`.

![Command shows the value of the xhr flag set to false](https://developer.salesforce.com/media/debug_lws_distortion_flag_false.png)

Setting `xhr` to `false` turns off all of the security-based API distortions for `XMLHttpRequest`.

## LWS Distortion Flags for Debug Sessions

Here’s a list of the distortion flags and the corresponding distortions that are disabled when you set the flag to `false`.

| Flag                       | What it controls                                                                                                                                                                                                                                                                                                        |
| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attributes`               | All distortions related to `getAttribute`, `setAttribute`, `hasAttribute`, `toggleAttribute` for attributes described in [LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer)                                                                                   |
| `caches`                   | All [`CacheStorage`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#CacheStorage_delete-value) API distortions                                                                                                                                                                     |
| `cookieStore`              | All [`CookieStore`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#CookieStore_addEventListener-value) API distortions                                                                                                                                                             |
| `customElements`           | [`CustomElementRegistry`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#CustomElementRegistry_define-value) distortions                                                                                                                                                           |
| `dataset`                  | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `documentCookie`           | [`Document.prototype.cookie` getter and setter](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Document_cookie-setter) distortions                                                                                                                                                 |
| `documentDomain`           | [`Document.prototype.domain` setter](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Document_domain-setter) distortion                                                                                                                                                             |
| `documentExecCommand`      | [`Document.prototype.execCommand`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Document_execCommand-value) distortion                                                                                                                                                           |
| `domParserParseFromString` | [`DOMParser.prototype.parseFromString`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#DOMParser_parseFromString-value) distortion                                                                                                                                                 |
| `element`                  | All [`Element.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Element_after-value) distortions except the `Element.prototype.innerHTML` setter, which is controlled with the `innerHTML` flag                                                                           |
| `history`                  | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `indexdDB`                 | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `innerHTML`                | [`Element.prototype.getInnerHTML`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Element_getInnerHTML-value) and [`Element.prototype.innerHTML` setter](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Element_innerHTML-setter) distortions |
| `navigatorSendBeacon`      | [`Navigator.sendBeacon`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Navigator_sendBeacon-value) distortion                                                                                                                                                                     |
| `node`                     | All [`Node.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Node_appendChild-value) API distortions                                                                                                                                                                      |
| `notification`             | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `performance`              | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `postMessage`              | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `range`                    | All [`Range.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Range_createContextualFragment-value) API distortions                                                                                                                                                       |
| `script`                   | [`SVGScriptElement.prototype.href` setter](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#SVGScriptElement_href-setter) distortion                                                                                                                                                 |
| `selection`                | [`Selection.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Selection_collapse-value) API distortions                                                                                                                                                                   |
| `setInterval`              | [`Window.setInterval`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Window_setInterval-value) API distortion                                                                                                                                                                     |
| `setTimeout`               | [`Window.setTimeout`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Window_setTimeout-value) API distortion                                                                                                                                                                       |
| `storage`                  | All [`Storage.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Storage_clear-value) API distortions                                                                                                                                                                      |
| `style`                    | This flag is deprecated. Don’t use it.                                                                                                                                                                                                                                                                                  |
| `windowFetch`              | [`Window.fetch`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Window_fetch-value) distortion                                                                                                                                                                                     |
| `windowFrames`             | [`Window.frames` getter](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Window_frames-getter) distortion                                                                                                                                                                           |
| `xhr`                      | All [`XMLHttpRequest.prototype`](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#XMLHttpRequest_open-value) distortions                                                                                                                                                             |

**See Also**

- [LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer)
- [Debug with Lightning Web Security Enabled
  ](lws-debug.md)
- [Limitations for Debugging with Lightning Web Security Enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-debug-limitations.md)
- [_Lightning Web Components Developer Guide_: Debug Lightning Web Components](/docs/platform/lwc/guide/debug-intro.html)
- [_Lightning Web Components Developer Guide_: Debug Using Chrome DevTools](/docs/platform/lwc/guide/debug-dev-tools.html)

<!-- document id=605a1a6910a506e818653567df13a56de8b268165444199f5210ed718b5fa8fd url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-debug.md -->

# Debug with Lightning Web Security Enabled

To debug Lightning components in an org where Lightning Web Security (LWS) is enabled, first [enable debug mode](/docs/platform/lwc/guide/debug-mode-enable.html). With [debug mode](/docs/platform/lwc/guide/debug-debug-mode.html), JavaScript code is easier to read because it isn’t optimized or minified. Debug mode also adds more detailed output for some warnings and errors.

To inspect your client-side code, we recommend using [Chrome DevTools](https://developer.chrome.com/docs/devtools/). To open DevTools on Windows and Linux, press Control-Shift-I in your Google Chrome browser. On Mac, press Option-Command-I.

## Source Code Location for LWC Debugging Under LWS

Beginning in Winter ’24, as you debug Lightning web components with Chrome DevTools, your component source code is displayed in the Sources panel inside the `lightning/n/modules` folder. This location is described in the [Find Your Code in the Sources Panel](/docs/platform/lwc/guide/debug-dev-tools.html#find-your-code-in-the-sources-panel) section of the _Lightning Web Components Developer Guide_. The location is the same regardless of whether Lightning Locker or LWS is enabled.

Previously, when your Lightning web components ran in an org where Lightning Web Security was enabled, a special `lws` folder separately organized your component files under a namespace folder.

![Source files in Page pane](https://developer.salesforce.com/media/debug_source_debug_mode_lws.png)

Here you see the `c` namespace and its components on the current page. The `compositionBasics.js` file with LWS enabled is shown with source mapping.

Source mapping enables the sandboxed code to appear similar to your components’ original source code. You can inspect it, use breakpoints, and so on. You must enable debug mode to see the source mapping and to enable breakpoints.

**tip:** If the code in the Sources panel doesn’t look like your original source code, make sure the setting **Enable JavaScript source maps** in Chrome DevTools is enabled. It’s enabled by default.

You can also find the source file in the Page pane when you’re already in the debugger. Right-click and select **Reveal in sidebar**.

Here the debugger stopped in `compositionContactSearch.js`, but the file is not selected in the sidebar. When you select **Reveal in sidebar**, the correct file is selected.

![Context menu with Reveal in sidebar option](https://developer.salesforce.com/media/debug_reveal_sidebar.png)

## Source Code Location for Aura Component Debugging Under LWS

When you’re debugging Aura components, the source code is displayed in the Sources panel in the `lightning/n/components` subfolder inside a folder named for the org.

The `lightning/n/components` folder’s exact location can vary between browsers and sessions, and is also dependent on how you use the component. If you don’t see the folder right away, expand the nodes until you find it.

This example shows the Aura Interop component from lwc-recipes. The top folder name `Aura_Interoperability` matches the name of the Lightning page that contains the component. The highlighted file is used for debugging.

![Aura source file used for debugging](https://developer.salesforce.com/media/lws_aura_debug.png)

## Console Stack Traces

The stack trace in the Console filters out LWS calls to give you a clearer picture of errors in your components. The LWS calls are contained in their own folder (1).

![LWS folder in console](https://developer.salesforce.com/media/debug_lws_stack_trace.png)

To see filtered stack traces, enable custom formatters as described the [Enable Custom Formatters](/docs/platform/lwc/guide/debug-dev-tools.html#enable-custom-formatters) section of the _Lightning Web Components Developer Guide_.

## Console Messages

Console messages show information about LWS in console methods such as `console.warn` and `console.info`. For example, `console.warn` is called when an object mutation is tracked on one side of the sandbox and not the other.

To see LWS console messages, enable custom formatters as described in the [Enable Custom Formatters](/docs/platform/lwc/guide/debug-dev-tools.html#enable-custom-formatters) section of the _Lightning Web Components Developer Guide_.

**note:** LWS changes the source code line number and source code file for console messages. Console messages appear to come from the Salesforce `aura_proddebug.js` file instead of from the component’s JavaScript file that logs the message. This behavior is a known issue that is due to browser implementations so we’re waiting for browser vendors to implement a fix.

**See Also**

- [Limitations for Debugging with LWS Enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-debug-limitations.md)
- [_Lightning Web Components Developer Guide_: Debug Lightning Web Components](/docs/platform/lwc/guide/debug-intro.html)
- [_Lightning Web Components Developer Guide_: Debug Using Chrome DevTools](/docs/platform/lwc/guide/debug-dev-tools.html)
- [_Lightning Aura Components Developer Guide_: Debugging](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/debug_intro.htm)

<!-- document id=46938a20a2b5114f9e3cea20c17840713b6fd34345b1c1bbe7590f60279edee5 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-decide-editor.md -->

# Decide on the Editor for Each Property in the Component

Your desired user experience for entering values into each property of a custom component determines whether you can use a standard property editor or whether to create a custom one.

For example, for a text alignment property, consider whether you want the property editor to be a text input field, dropdown menu, or button group. Look at the default property editor that comes with the property type for each property in your custom component and decide if that editor offers the user experience that you want. If it doesn't, create a custom property editor. (For a list of standard Lightning property types, including images of their default property editors, see [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html) in the Lightning Types Developer Guide.)

In the Custom Article component example, these are the desired editors for the properties in the component.

- **`articleDate`**—The default property editor for [`lightning_dateType`](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html#lightning__datetype) is a date selector. That's the desired user experience, so you don't need to create a custom editor for this property.
- **`textAlignment`**—The default property editor for this property is a combobox. You want a button group to visually show the alignment options. This user experience requires a custom property editor.
- **`layoutProperties`**—You want to arrange the layout properties on separate tabs in the property panel, but the default editor for [`lightning__objectType`](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html#lightning__objecttype) is a vertical layout. For the `borderStyle` property, you want to show different labels for each of the dropdown options and not their actual values. For these user experiences, you must create a custom property type and a custom property editor.

In this example, the desired property editors require you to create a custom property editor for `textAlignment` and `layoutProperties`. In addition, the desired separate tab layout for `layoutProperties` requires you to define this layout in an editor.json file.

**See Also**

- _Lightning Types Developer Guide_: [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html)
- [Decide on the Validation for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-validation.md)
- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)

<!-- document id=c77f3aa47dae0e9531648cf91593a0502cd929a55a565a1881f13492c48da79d url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-decide-validation.md -->

# Decide on the Validation for Each Property in the Component

The type of data validation that you require for each property in a custom component determines whether you can use an existing standard property type or whether to create a custom one.

Usually when you create a custom Lightning web component, you include validations to verify that the data values that users enter into each component property are acceptable. In the Custom Article component example, these are the desired validations for the component's properties.

- **`articleDate`**—You want to ensure that users enter a date. The standard `lightning_dateType` provides the validation that you need, so you can use that standard Lightning type for this property.

- **`textAlignment`**—You don't need any data validations for this property, so you don't need a custom property type. You can just specify `<property type="String">` in the `js-meta.xml` file for the Custom Article component.

- **`layoutProperties`**—You want to ensure that users always indicate a style, weight, and radius for the borders around the article. You can use the standard property type called `lightning__objectType` to create a custom property type with multiple properties.

In this example, the desired validations require you to create one custom property type for `layoutProperties`. You can use standard property types for the other two custom properties.

**See Also**

- _Lightning Types Developer Guide_: [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html)
- [Decide on the Editor for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-editor.md)
- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)

<!-- document id=6508982e044edae743e5b70ad724dd68f957a74c0a3a67f2b7f61e81fd17681c url=/developer/current/en-us/lwc/lwc/guides/reference/reference-decorators.md -->

# Decorators

The Lightning Web Components programming model has three decorators that add functionality to a property or function.

The ability to create decorators is part of ECMAScript, but these three decorators are unique to Lightning Web Components.

## `@api`

To expose a public property, decorate a field with `@api`. Public properties define the API for a component.

See [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md).

To expose a public method, decorate it with `@api`. Public methods are part of a component’s API. To communicate down the containment hierarchy, owner and parent components can call JavaScript methods on child components.

See [Public Methods](https://developer.salesforce.com/docs/platform/lwc/create/create-javascript-methods.md).

## `@track`

Previously, you had to use the `@track` decorator to make a field reactive. Beginning in Spring '20, all fields in a LWC class are reactive. If a field’s value changes, and the field is used in a template or in a getter of a property that’s used in a template, the component rerenders and displays the new value. If a field is assigned an object or an array, the framework observes some changes to the internals of the object or array, such as when you assign a new value.

You still need to decorate a field with `@track` in these use cases:

- Observing changes to the properties of an object
- Observing changes to the elements of an array

See [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md).

## `@wire`

To read Salesforce data, Lightning web components use a reactive wire service. When the wire service provisions data, the component rerenders. Components use `@wire` in their JavaScript class to specify a [wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md) or an Apex method.

See [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md) and [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)

**See Also**

- [TC39: Decorators proposal](https://tc39.github.io/proposal-decorators)

<!-- document id=4b42d8bdc0c655be36fa9cb79e42be51f3d86460860ec983d5a8d4fe2161ae57 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-define.md -->

# Define a Component

A Lightning web component that renders UI must include:

- [An HTML file](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-file.md)
- [A JavaScript file](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript.md)
- [A metadata configuration file](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-meta-file.md)

An HTML file is not required for an API module component. To ensure that the LWC framework can autowire a component to the correct files, place them in [a component folder](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-folder.md) with the same name as the component's name.

The component can optionally include:

- [A CSS file](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-file.md)
- [An SVG icon](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-svg-icon.md)
- [Additional JavaScript files](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript-share.md)
- [Jest tests](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-tests.md)

**See Also**

- [Lightning Web Components Video Gallery: Anatomy of an LWC](https://developer.salesforce.com/tv/lwc-video-gallery)

<!-- document id=8637dbacf3e84a7f1bf871e56b7d9f606f5277b2c0f215a89d03c715b2654449 url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-define.md -->

# Define a State Manager

Use the `defineState` function to define a state manager. State management relies on extensive infrastructure within the LWC Framework. The `defineState` function makes it straightforward to ensure that all connections are made correctly.

There are two aspects of using `defineState` to create a state manager. The first is the specific JavaScript syntax that you use to define a state manager with `defineState`. The syntax uses a few advanced JavaScript features. Using `defineState` to define a state manager might feel awkward at first, but this syntax is what makes state managers self-contained, and isolated from other instances of the same or other state managers.

The second is the internal implementation of your state manager, in the form of an anonymous function. This function is used to create instances of your state manager, and also defines the API your state manager provides to other LWC components. Specifically, you must understand:

- How to use the state management primitives `atom`, `computed`, and `setAtom` to define the properties and actions of your state manager.
- How to expose the properties and actions your state manager provides (its API).

Learn the outer syntax first, in [Syntax Introduction: A Simple Counter](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-define-syntax.md). The example is deceptively short and simple. A thorough explanation covers the concepts of the syntax that you must understand.

Then learn how to build your state manager's implementation using the state management primitives, in [Implement a State Manager](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-define-implementation.md). The example used is an expanded version of the counter state manager used in [Syntax Introduction: A Simple Counter](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-define-syntax.md). While still simple, it illustrates all three state manager implementation functions, and how to interact with the state manager from a component's user interface.

Moving beyond syntax, [Share a State Manager Across Components](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-example-fromcontext.md) illustrates how many components can access and interact with a shared state manager. The example is, once again, a counter manager, but refactored into multiple separate user interface components. This example also uses the best practice of putting the state manager into a standalone [API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md).

Finally, you'll want some longer code samples that illustrate more complete use of state managers. Look at the examples [published externally](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-examples.md), and in [Nested State Manager Example](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-example-nested.md). That example is longer, and shows off additional features of LWC state management, including using nested state managers as an alternative to using `@wire` or other UI API calls.

<!-- document id=0bc4a552fe0c6d2a369d7b48b6ee76b51d088246272264dca55ddf0e4d259a82 url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel-scope.md -->

# Define the Scope of the Message Service

The Lightning message service lets you define the scope of where subscribing components receive messages in your application. You can limit the scope to the active area of the application or set the scope to the entire application.

**important:** For Lightning web components, the scoping feature is available only when using `@wire(MessageContext)`.

The application's active area includes selected navigation tabs and items, utility items, and ES6 libraries. Utility items are always active. Navigation tabs and items include:

- Standard navigation tabs
- Console navigation workspace tabs
- Console navigation subtabs
- Console navigation items

![Diagram illustrating active subscription scope regions versus application subscription scope regions](https://developer.salesforce.com/media/lms_scope.png)

To receive messages on a message channel from anywhere in the application, import `APPLICATION_SCOPE` from `lightning/messageService`. Then, call `subscribe()` and pass `{ scope: APPLICATION_SCOPE }` for the optional fourth `subscriberOptions` parameter.

```javascript
// Import message service features.
import {
    subscribe,
    unsubscribe,
    APPLICATION_SCOPE,
    MessageContext
} from 'lightning/messageService';

// Import your message channel
import RECORD_SELECTED_CHANNEL from '@salesforce/messageChannel/Record_Selected__c';

// To pass scope, you must get a message context.
@wire(MessageContext)
    messageContext;

// Pass scope to the subscribe() method.
    subscribeToMessageChannel() {
        if (!this.subscription) {
            this.subscription = subscribe(
                this.messageContext,
                recordSelected,
                (message) => this.handleMessage(message),
                { scope: APPLICATION_SCOPE }
            );
        }
    }
```

Receiving messages from the active area is the default behavior. You don’t need to include the scope property to limit scope to the active area.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has several examples that demonstrate Lightning message service usage. Look for components that start with `lms`, such as [lmsPublisherWebComponent](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/lmsPublisherWebComponent).

**See Also**

- [Create a Message Channel](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-channel-intro.md)

<!-- document id=e3cab2d25bab8ce47342ce194172f61a08afff093a017c8886308d1d52a26c59 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-caching.md -->

# Delayed Enabling or Disabling of Lightning Web Security

If your component is using a feature that’s allowed by Lightning Web Security (LWS) but blocked by Lightning Locker, it can still be blocked after you enable LWS. The reverse can also be true if you disable LWS but see a behavior is allowed but you expected it to be blocked by Lightning Locker. The reason can be that your browser is still using the previous environment due to caching.

To check for evidence that your code is running with LWS, see [Determine if LWS is Enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-is-enabled.md).

Multiple types of caching can be in effect. For the simplest solution, try refreshing the browser window and clearing the browser cache.

However, sometimes those measures aren’t enough to get the correct behavior, especially if you’re switching LWS on and off frequently while developing and testing.

If the issue persists, try the measures described here.

## Disable Caching in the Browser

Supported browsers enable you to disable caching while using the browser developer tools. In the Network panel of the developer tools window, select the **Disable Cache** checkbox. Then the browser doesn’t load from cache while the developer tools window is open.

## Disable Secure Caching in Salesforce

Disable the secure and persistent browser caching setting during development in a sandbox or Developer Edition org to see the effect of any code changes without needing to empty the cache.

The caching setting improves page reload performance by avoiding extra round trips to the server.

**warning:** Disabling secure and persistent browser caching has a significant negative performance impact on Lightning Experience. Always enable the setting in production orgs.

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.
2.  Deselect the checkbox for **Enable secure and persistent browser caching to improve performance**.
3.  Click **Save**.

<!-- document id=fcfc14628b96604893e82111c145e3f48dd7961f34fcc4b62d5a2fe9432087d6 url=/developer/current/en-us/lwc/lwc/guides/use/use-packaging-delete.md -->

# Delete Components from Managed Packages

After you’ve released a managed package, you may decide to refactor the package and delete a component. It’s your responsibility to educate your customers about the potential impact from any components you delete. In the Release Notes for your upgraded package, list all custom components you’ve deleted and notify customers of any necessary actions.

**note:** To enable component deletion in your packaging org, log a case in the [Partner Community](https://partners.salesforce.com/).

To delete a component from a managed package:

1.  From Setup, enter `Lightning Components` in the Quick Find box.
2.  Select **Lightning Components**.
3.  Click **Del** for the component that you want to delete.

    ![Lightning Components in Setup](https://developer.salesforce.com/media/delete_from_managed_package.png)

**note:** When you remove a Lightning web component from a package, the component remains in a subscriber’s org after they install the upgraded package. The administrator of the subscriber’s org can delete the component, if desired.

AppExchange partners have two types of managed packaging to choose from, second-generation managed packaging (2GP) and first-generation managed packaging (1GP). We recommend using 2GP for all new managed packages. To delete components from your managed package, follow these guidelines.

- Delete components from your 2GP by removing them from your package directory and then [create a new package version](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/sfdx_dev_dev2gp_create_pkg_ver.htm).
- Delete components from your 1GP by [deleting them from your 1GP packaging org](https://developer.salesforce.com/docs/atlas.en-us.pkg1_dev.meta/pkg1_dev/viewing_deleted_components.htm).

<!-- document id=5599003d059b0b5c12d6262dd5e96b799f47ba15f58e01bdb1e44b92461de411 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-cart/reference-lightning-commerce-cart-delete-cart.md -->

# `deleteCart(cartInput)`

Deletes a cart in a webstore.

## Syntax

```javascript
import { deleteCart } from 'lightning/commerceCartApi';
deleteCart(cartInput: object): Promise<void>
```

## Commerce API Resource

```
DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}
```

`deleteCart` uses this [Commerce API resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart.htm).

## Parameters

- `webstoreId`—(Required) The ID of the webstore. The ID prefix is `0ZE`.
- `activeCartOrId`—(Required) The ID of the cart to delete, or the string `active` to target the buyer's active cart.
- `version`—(Required) The API version for the adapter, for example, `v62.0`. Without this parameter, the call doesn't fire.
- `effectiveAccountId`—(Optional) The effective account ID for the cart operation.

## Returns

The return type is `void`. On success, the server returns `204 No Content`. On error, the `Promise` rejects with an error object containing an `errorCode` and a `message`.

## Usage

`deleteCart` is an imperative function, not a `@wire` adapter. Call it in response to a user action.

```javascript
import { LightningElement, api } from 'lwc';
import { deleteCart } from 'lightning/commerceCartApi';

export default class DeleteCartExample extends LightningElement {
  @api webstoreId;
  @api cartId;

  async handleDeleteCart() {
    try {
      await deleteCart({
        webstoreId: this.webstoreId,
        activeCartOrId: this.cartId,
        version: 'v62.0',
      });
      console.log('Cart deleted successfully');
    } catch (error) {
      console.error('Error deleting cart:', error);
    }
  }
}
```

## Error Handling

If the call fails, the `Promise` rejects with an error object containing an `errorCode` and a `message`.

**See Also**

- [`createCart(cartInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-cart-create-cart.md)

<!-- document id=a40b69467c1fe9ea730d0b75623a193b551a28acb734a8a631bc579f9f7695dc url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-delete-data-connector.md -->

# `deleteDataConnector`

Deletes a specific CRM Analytics data connector by ID or developer name.

## Syntax

```javascript
import { deleteDataConnector } from 'lightning/analyticsWaveApi';
deleteDataConnector({ connectorIdOrApiName: string }): Promise<void>
```

## CRM Analytics API Resource

```html
DELETE /wave/dataConnectors/${connectorIdOrApiName}
```

`deleteDataConnector` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid.htm).

## Parameters

| Parameter Name         | Type   | Description                                | Required?                                  |
| ---------------------- | ------ | ------------------------------------------ | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the connector. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

There are several ways to use `deleteDataConnector`. For example, you can display a list of connectors and enable delete on each connector on the list.

This example adds a delete button to a page with data connectors. Deleting a connector displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { deleteDataConnector } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class DeleteDataConnector extends LightningElement {
  @api idOrApiName; // or fetch the ID or developer name

  delete(event) {
    deleteDataConnector({ connectorIdOrApiName: this.idOrApiName })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Connector Deleted",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error deleting connector",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `deleteDataConnector()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Delete"
    icon-name="utility:delete"
    icon-position="right"
    onclick={delete}
  >
  </lightning-button>
</template>
```

<!-- document id=f1ef4efc2ff008b48bcee7a813b2cd9970df8f5faa5ad05d05586cc82d3a142d url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-delete-dataset.md -->

# `deleteDataset`

Deletes a specific CRM Analytics dataset by ID or developer name.

## Syntax

```javascript
import { deleteDataset } from 'lightning/analyticsWaveApi';
deleteDataset({ datasetIdOrApiName: string }): Promise<void>
```

## CRM Analytics API Resource

```html
DELETE /wave/datasets/${datasetIdOrApiName}
```

`deleteDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataset_id.htm).

## Parameters

| Parameter Name       | Type   | Description                              | Required?                                  |
| -------------------- | ------ | ---------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The ID or developer name of the dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

There are several ways to use `deleteDataset`. For example, you can display a list of datasets and enable delete on each dataset on the list.

This example adds a delete button to a page with datasets. Deleting a dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { deleteDataset } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class DeleteDataset extends LightningElement {
  @api idOrApiName; // or fetch the ID or developer name

  delete(event) {
    deleteDataset({ datasetIdOrApiName: this.idOrApiName })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Dataset Deleted",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error deleting dataset",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `deleteDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Delete"
    icon-name="utility:delete"
    icon-position="right"
    onclick={delete}
  >
  </lightning-button>
</template>
```

<!-- document id=e3a634a88aa9aa823f2e946491ca00e603421ef7dc641ed8034dd2789f34d446 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-delete-list-info.md -->

# `deleteListInfo`

Use this wire adapter to delete a list view.

## Syntax

```javascript
import { deleteListInfo } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

deleteListInfo({ objectApiName: ACCOUNT_OBJECT, listViewApiName: "MyAccountListView" });
```

## User Interface API Resource

```html
DELETE /ui-api/list-info/${objectApiName}/${listviewApiName}
```

See [Delete List View Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_md_delete.htm).

## Parameters

| Parameter Name    | Type   | Description                                                                                                                      | Required?                               |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName` | String | The API name of a list view, such as `AllAccounts`.                                                                              | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

If a list view is deleted successfully, there’s no response.

- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example deletes a list view when the button is clicked.

<!-- prettier-ignore -->
```html
<!-- wireDeletListInfo.html -->
<template>
   <lightning-card title="wireDeleteListInfo">
       <lightning-button variant="brand" label="Delete List View" title="Primary action" onclick={deleteListView} class="slds-m-left_x-small"></lightning-button>
       <template lwc:if={deleted}>
           <p>List View Deleted</p>
       </template>
       <template lwc:if={errorMessage}>
           <p>{errorMessage}</p>
       </template>

   </lightning-card>
</template>
```

```javascript
// wireDeleteListInfo.js
import { deleteListInfo } from "lightning/uiListsApi";
import { LightningElement, api } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class DeleteListInfo extends LightningElement {
  errorMessage;
  deleted;
  @api async deleteListView() {
    deleteListInfo({
      objectApiName: ACCOUNT_OBJECT.objectApiName,
      listViewApiName: "AllAccounts_deleteListInfoTest",
    })
      .then(() => {
        this.deleted = true;
        this.errorMessage = undefined;
      })
      .catch((error) => {
        this.errorMessage = error.body.message;
        this.deleted = undefined;
      });
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=eeb22390d33f0c29b8b6a6edc212f4c849caefeeab99ff8ad37b93b3617b13bc url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-delete-recipe.md -->

# `deleteRecipe`

Deletes a specific data prep recipe by ID.

## Syntax

```javascript
import { deleteRecipe } from 'lightning/analyticsWaveApi';
deleteRecipe({ id: string }): Promise<void>
```

## Data Prep Recipe API Resource

```html
DELETE /wave/recipes/${id}
```

`deleteRecipe` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes_id.htm).

## Parameters

| Parameter Name | Type   | Description                     | Required?                                  |
| -------------- | ------ | ------------------------------- | ------------------------------------------ |
| `id`           | String | The ID of the data prep recipe. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

There are several ways to use `deleteRecipe`. For example, you can display a list of recipes and enable delete on each recipe on the list.

This example adds a delete button to a page with recipes. Deleting a recipe displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { deleteRecipe } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class DeleteRecipe extends LightningElement {
  @api id; // or fetch the ID

  delete(event) {
    deleteRecipe({ id: this.id })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Recipe Deleted",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error deleting recipe",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `deleteRecipe()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Delete"
    icon-name="utility:delete"
    icon-position="right"
    onclick={delete}
  >
  </lightning-button>
</template>
```

<!-- document id=6281bca004db4bee88b78dea992b0d5d734da18db3d02f79c35a4590632c6ec1 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-delete-record.md -->

# `deleteRecord(recordId)`

Deletes a record.

## Syntax

```javascript
import { deleteRecord } from 'lightning/uiRecordApi';
deleteRecord(recordId: string): Promise<void>
```

## User Interface API Resource

```html
DELETE /ui-api/records/{recordId}
```

`deleteRecord` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_delete.htm).

## Parameters

| Parameter Name | Type   | Description                     | Required?                               |
| -------------- | ------ | ------------------------------- | --------------------------------------- |
| `recordId`     | String | The ID of the record to delete. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

`deleteRecord` accepts a single record ID. To delete multiple records, use `Promise.all()` or Apex.

This example displays a list of account records with a delete button next to each account name. When a record is deleted successfully, the component displays a toast message and uses `refreshApex()` to refresh the data provisioned via the Apex `@wire`.

```
import { LightningElement, wire } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import { refreshApex } from '@salesforce/apex';
import { deleteRecord } from 'lightning/uiRecordApi';
import getAccountList from '@salesforce/apex/AccountController.getAccountList';
import { reduceErrors } from 'c/ldsUtils';

export default class LdsDeleteRecord extends LightningElement {
    accounts;
    error;

    /** Wired Apex result so it can be refreshed programmatically */
    wiredAccountsResult;

    @wire(getAccountList)
    wiredAccounts(result) {
        this.wiredAccountsResult = result;
        if (result.data) {
            this.accounts = result.data;
            this.error = undefined;
        } else if (result.error) {
            this.error = result.error;
            this.accounts = undefined;
        }
    }

    async deleteAccount(event) {
        const recordId = event.target.dataset.recordid;

        try {
            await deleteRecord(recordId);
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Success',
                    message: 'Account deleted',
                    variant: 'success'
                })
            );
            await refreshApex(this.wiredAccountsResult);
        } catch (error) {
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Error deleting record',
                    message: reduceErrors(error).join(', '),
                    variant: 'error'
                })
            );
        }
    }
}

```

When you successfully delete a record, any component that's subscribed to the deleted record via a wire returns a 404 error for that record data.

Don't call `deleteRecord` from a record page for a record that you want to delete. The record is deleted and you receive a 404 error with a message "The requested resource does not exist".

**See Also**

- [Client-Side Caching of Apex Method Results](https://developer.salesforce.com/docs/platform/lwc/apex/apex-result-caching.md)

<!-- document id=002c34fcd85a40441506c3ffaf7dbdb675c3494e5926a083ed71a2ce7ff656a5 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-delete-replicated-dataset.md -->

# `deleteReplicatedDataset`

Deletes a specific CRM Analytics replicated dataset by ID.

## Syntax

```javascript
import { deleteReplicatedDataset } from 'lightning/analyticsWaveApi';
deleteReplicatedDataset({ id: string }): Promise<void>
```

## CRM Analytics API Resource

```html
DELETE /wave/replicatedDatasets/${id}
```

`deleteReplicatedDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id.htm).

## Parameters

| Parameter Name | Type   | Description                       | Required?                                  |
| -------------- | ------ | --------------------------------- | ------------------------------------------ |
| `id`           | String | The ID of the replicated dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

There are several ways to use `deleteReplicatedDataset`. For example, you can display a list of replicated datasets and enable delete on each replicated dataset on the list.

This example adds a delete button to a page with replicated datasets. Deleting a replicated dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { deleteReplicatedDataset } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class DeleteReplicatedDataset extends LightningElement {
  @api rdId; // or fetch the ID

  delete(event) {
    deleteReplicatedDataset({ id: this.rdId })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Replicated Dataset Deleted",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error deleting replicated dataset",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `deleteReplicatedDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Delete"
    icon-name="utility:delete"
    icon-position="right"
    onclick={delete}
  >
  </lightning-button>
</template>
```

<!-- document id=8f35c5e0c9c847625c18a621d2ec40a8877b0493a2a95c6cd879c4c7cb118940 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-delete-wave-folder.md -->

# `deleteWaveFolder`

Deletes a specific CRM Analytics folder by ID.

## Syntax

```javascript
import { deleteWaveFolder } from 'lightning/analyticsWaveApi';
deleteWaveFolder({ folderId: string }): Promise<void>
```

## CRM Analytics API Resource

```html
DELETE /wave/folders/${folderId}
```

`deleteWaveFolder` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders_id.htm).

## Parameters

| Parameter Name | Type   | Description                         | Required?                                  |
| -------------- | ------ | ----------------------------------- | ------------------------------------------ |
| `folderId`     | String | The ID of the CRM Analytics folder. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The return type is `void`.

## Usage

There are several ways to use `deleteWaveFolder`. For example, you can display a list of folders and enable delete on each folder on the list.

This example adds a delete button to a page with folders. Deleting a folder displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { deleteWaveFolder } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class DeleteWaveFolder extends LightningElement {
  @api id; // or fetch the ID

  delete(event) {
    deleteWaveFolder({ folderId: this.id })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Analytics Folder Deleted",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error deleting folder",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `deleteWaveFolder()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Delete"
    icon-name="utility:delete"
    icon-position="right"
    onclick={delete}
  >
  </lightning-button>
</template>
```

<!-- document id=fbd33845f22e91fa7e26e3779811a10d07ca28ba0ee0278a64fdf48f5afb4a77 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-with-your-tools.md -->

# Deploy Using Your Own Tools

Not using Salesforce DX tools? That’s OK! Use your own tools and the Metadata API to deploy Lightning web components.

Sometimes, developers and release management teams use deployment environments that don’t use Salesforce DX tools. For example, a deployment environment might use Eclipse, multiple repositories, and tools like ANT or GNU Make. Or, your team may have an established in-house release process. While we recommend using our tools, you can use metadata to deploy components in your own way.

To develop and deploy Lightning web components using packages and Metadata API, follow these steps.

1.  [Create a zip archive](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm) that includes your component files and a package.xml manifest file. The Metadata API type for Lightning web components is [LightningComponentBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_lightningcomponentbundle.htm).
2.  Use a tool like the [ANT Migration Tool](https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/meta_development.htm) or your own tool to deploy the component to a sandbox or scratch org.

**important:** When you use the Salesforce CLI, you get change tracking between your project and your target scratch org. Without these tools, you must come up with your own solution. A repository like Github monitors code changes. Sandboxes support Auditing for changes to data or fields.

If you’re using Prettier, consider adding a [pre-commit hook](https://lwc.dev/guide/install#tools) to ensure that your code is properly formatted.

<!-- document id=8bb86360a26448fa1004ea1ca6840e49be313df5f4dc501bc10d2baa04d3c404 url=/developer/current/en-us/lwc/utam/guide/page-objects.md -->

# Design Page Objects

UTAM is based on the popular Page Object model design pattern commonly used in Selenium tests. The page object design pattern uses an object-oriented class to decouple a test from the target web page for robustness and easier test maintenance. Instead of using an object-oriented class to write a page object, a UTAM page object is authored in JSON, and described by an easy-to-understand UTAM grammar. These JSON page objects are easy to write and easy to read.

Any UI page can be expressed in UTAM page object grammar. Each web application page or component has a corresponding JSON page object that defines the UI interface for your tests. The UTAM compiler transforms the JSON page objects into JavaScript and Java page objects. You write your tests against the generated JavaScript or Java code. The JSON page object is the single source of truth for all your tests, no matter which testing language you use.

You can write your own page objects and use page objects created by other developers.

When you create a page object, start small and iterate. Think about the parts of the page that your test needs to exercise and model those parts in JSON. Think of the methods exposed in a page object as an API that covers the interactions and assertions that a test writer can exercise.

Writing a test and a page object from scratch is like preparing a meal. When you cook, you might want to marinade your protein and then prepare your vegetables before returning to cook the protein. With UTAM, you can start with the skeleton code for your test and then switch over to make sure that your page object exposes the interactions and assertions needed for the test. Continue to switch back and forth between the page object and test until the test is complete and it passes!

## Create a JSON File

Create a declarative page object in a JSON file with the filename _pageName_.utam.json. We recommend using the filename _componentName_.utam.json.

The _componentName_.utam.json file can live anywhere in the component tree. We suggest putting _componentName_.utam.json in a folder named `__utam__` next to the component’s .html, .js, and .css files.

```txt
src/
  ├── assets/
  ├── modules / example
     └── app/
     └── home/
         └── __utam__/
           └── home.utam.json
         ├── home.css
         └── home.html
```

## Set Root Page Object Properties

To load a page object from a test, set `root` to `true` and add a selector element that points to its most outer (root) element. A root page object can be loaded directly inside the browser.

If a component can be loaded only inside its immediate parent (for example, a navigation item can be loaded only inside a navigation bar), don’t mark it as root. You can set set `root` to `true` for a non-root page object but if the page object is moved inside a shadow root, tests will break. To make page objects more durable, never treat a non-root page object as a root.

For example:

```json
{
  "root": true,
  "selector": {
    "css": "one-app-nav-bar"
  }
}
```

For more information, see JSON Grammar: [Root Element](/docs/platform/utam/references/utam-grammar/root-elements.html) and Tutorials: [Root Page Objects](/docs/platform/utam/references/utam-grammar/root-elements.html).

## Add Elements

A JSON page object is a tree of elements that map to the DOM of the corresponding page. Define a nested structure of page object elements to expose the parts of the DOM that your test needs to access. To improve encapsulation and the robustness of a page object, declare a public method for a use case instead of setting an element as public. A public element makes it harder to evolve your page object in the future without breaking tests.

There are a few types of page object elements:

- A [basic element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#basic-elements) acts either as a scope for other elements or as an HTML element (or mobile widget) for user interactions, like a button, link, or input box.

- A [custom element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#custom-elements) references another page object nested inside the application component.

- A [container element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#container-elements) provides a scope to inject another component, like a slot inside a button group.

- A [frame element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#frame-elements) references a frame or an iframe.

## Add Public Methods

Define public compose methods that your test can call to interact with the page. A [compose method](/docs/platform/utam/references/utam-grammar/methods.html) combines interactions with basic elements into reusable abstractions for common use cases like login where we enter a username and password, and then click submit.

## Use Explicit Waits

Use explicit waits in page objects to wait for certain actions to complete and yield until the conditions are met. Explicit waits help you to write more durable and less flappy tests.

For more information, see [Explicit Waits](/docs/platform/utam/references/utam-grammar/explicit-waits.html).

## Add Imperative Extensions

Imperative extensions enable you to create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar. For example, you can't use the JSON grammar to navigate a data table where each column shows data from a different type of component with different markup.

**important:** While imperative extensions are powerful, only use them as a last resort. They violate the declarative nature of UTAM and require you to individually implement and maintain them in each programming language that you use with UTAM.

For more information, see [Imperative Extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md) and JSON Grammar: [Imperative Extensions](/docs/platform/utam/references/utam-grammar/imperative-extensions.html).

<!-- document id=2c234603caf3432f57d395a4ee796df8f309bb0247ce1d553d49a3a356466ede url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-components-affected.md -->

# Determine if Lightning Web Security Affects Your Org

Lightning Web Security (LWS) is generally available for Lightning web components (LWC) and Aura components. LWS affects custom Lightning components created in your org or installed through packages.

If you’re unsure whether your org has custom Lightning components, use Setup to list the components in your org.

From Setup, in the Quick Find box, enter `Lightning Components` and select **Lightning Components**.

![Setup’s Lightning Components page lists components in an org](https://developer.salesforce.com/media/setup_component_list.png)

The Lightning Components page lists your org’s components, indicating the component type and whether the component is from a managed package.

- The Type column specifies LWC or Aura.
- The ![Managed package icon](https://developer.salesforce.com/media/icoManagedInstalled.png) icon indicates a component is from a managed package. Only the owner of the AppExchange app can modify the managed package. If there isn’t an icon, then the component isn’t managed, and you can modify the component’s code.

**tip:** If the Lightning Components list is empty, then your org doesn’t have any custom Lightning components. Lightning Web Security doesn’t affect your org.

If custom Lightning components are listed, see [When to Enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-when.md).

<!-- document id=8a22ef9416ce7bd7e8c33c2c6f066dcfeedd5da639008bd5873a780b75e73588 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-is-enabled.md -->

# Determine if Lightning Web Security is Enabled

When your user account is [enabled for debug mode](/docs/platform/lwc/guide/debug-mode-enable.html), you can check whether Lightning Web Security (LWS) is enabled.

In Chrome DevTools, look in the **Sources** panel’s **Page** tab. For Lightning web components (LWC), find the component JavaScript files in the folder _your-org-domain_`/lightning/modules/c` or your specific namespace if not using the `c` namespace. For Aura components, look in the folder _your-org-domain_`/lightning/components/c` or your specific namespace if not using the `c` namespace.

Search for the string "LWS Version" in the JavaScript files of the components.

![JavaScript file with LWS Version string highlighted](https://developer.salesforce.com/media/lws_version.png)

If LWS is disabled, the LWS version string isn’t found in the components’ JavaScript files.

Although a search can detect the string in `aura_proddebug.js`, the string’s presence in this file doesn’t indicate that LWS is enabled in the org.

**See Also**

- [Delayed Enabling or Disabling of Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-caching.md)

<!-- document id=8a5df60f6f4e2d12e0ebc54a4b89fc365ab7dd3268b282cd032a44e30311517d url=/developer/current/en-us/lwc/lwc/guides/js/js-third-party-guidance.md -->

# Determine Whether a JavaScript Library Is Locker-Compliant

Use this guide to determine if a third-party JavaScript library is compatible with Lightning Locker.

**note:** This guide applies when an org is using Lightning Locker. If an org has [enabled Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-enable.html) (LWS), most third-party JavaScript libraries work as expected without changes. However, libraries that set `"use strict"` explicitly require changes to work with LWS. See [Third-Party Library Considerations for LWS](/docs/platform/lightning-components-security/guide/lws-js.html).

Any library used by your component must meet the same Lightning Locker requirements as your component.

- Avoid direct DOM manipulation across namespaces. See [DOM Access Containment](/docs/platform/lightning-components-security/guide/locker-dom.html).
- Support JavaScript ES5 strict mode as described in [JavaScript Strict Mode Enforcement](/docs/platform/lightning-components-security/guide/js-strict-mode-intro.html).
- Avoid JavaScript APIs that are blocked by Lightning Locker as shown in the [Locker API Viewer](https://developer.salesforce.com/docs/component-library/tools/locker-service-viewer) described in [Lightning Locker Tools](/docs/platform/lightning-components-security/guide/locker-tools.html).

To determine if a third-party library is compliant with Lightning Locker, we recommend these steps.

1.  Create a small sample app that uses the library.
2.  Verify that the library loads without error and that you can call basic functionality.
3.  Use [Locker Console](https://developer.salesforce.com/docs/component-library/tools/locker-service-console) with Locker enabled.
4.  Check for these common violations:

    - Declaring a variable that becomes global

      - : Strict mode disallows variables from becoming global variables. To avoid violating this rule, in the library, explicitly attach a library global to `window`.

        ```javascript
        window.myLib = (function () {
          return {
            myFunction: function (a, b) {
              return a * b;
            },
          };
        })();
        ```

    - CSP violations

      - : Scan code for any usages of `eval()`, `new Function()`, or `<script>` tags.

    - DOM access violations

      - : Libraries are blocked if they attempt to do broad scans of the DOM instead of manipulating only the elements passed to their APIs. If the library manipulates the DOM, you can add the `lwc:dom="manual"` directive to a native HTML element to allow it, as described in [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md).

    - Use of non-standard or unsupported DOM APIs

      - : See the APIs marked Supported and Not Supported in the [Locker API Viewer](https://developer.salesforce.com/docs/component-library/tools/locker-service-viewer).

If the library isn’t compliant, ask the library maintainers to update the code to comply with Lightning Locker, or, if the project is open-source, contribute the changes yourself. Another option is to fork the repository, make the changes, and build your own version of the library. It's your responsibility to make sure any third-party libraries work with your Lightning web components before deployment.

<!-- document id=df54697965c6a10324100cfc174d4351254be8778db4241d942a5221dcc7e13a url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-sfdx-deploy.md -->

# Develop in Non-Scratch Orgs

You can deploy Lightning web components source code to non-scratch orgs. In these orgs, metadata changes aren’t tracked, so you deploy all the specified metadata instead of only what's changed. You can also retrieve code from these orgs.

**note:** Before you create a component, see [Set Up an Editor, Linter, and Org](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md) and [Install the Salesforce CLI](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-cli.md).

## Create a Salesforce DX Project

A Salesforce DX project has a specific structure and a configuration file that identifies the directory as a Salesforce DX project.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Project**.

You can also run this command from the command line.

```bash
cd PATH/TO/YOUR/SFDX/PROJECTS
sf project generate --name MyLWC
cd MyLWC
```

## Install, Configure, and Run Linting

ESLint is a program that runs in the background and looks for problems as you code. It analyzes your code against a set of rules. These linting rules can include best practices, guard rails, and errors. You can configure the linting rules for your project. If code breaks a rule, a squiggly line appears below the code. Mouse over the code to see the rule and a suggested fix.

1.  To install the [ESLint rules for Lightning Web Components](https://github.com/salesforce/eslint-plugin-lwc), run this command in your Salesforce DX project directory.

    ```bash
    npm install
    ```

    If you have issues, verify that the project’s `package.json` file matches the [salesforcedx-templates `package.json` file](https://github.com/forcedotcom/salesforcedx-templates/blob/master/src/templates/project/package.json). For example, the `.eslintignore` file is no longer needed and has been superseded by the `"lint": "eslint **/{aura,lwc}/**/*.js"` script in `package.json`. The script runs linting only for the JS files under the `lwc` and `aura` folders.

2.  There are three configuration levels for linting. Check out the [eslint-config-lwc](https://github.com/salesforce/eslint-config-lwc) README and choose the configuration that matches your coding needs. In your project, set the configuration level in the `/force-app/main/default/lwc/.eslintrc.json` file.

    If your project doesn’t have the file, copy it from [salesforcedx-templates](https://github.com/forcedotcom/salesforcedx-templates/blob/main/src/templates/project/lwc.eslintrc.json) and paste it in the `/force-app/main/default/lwc` folder.

3.  To run linting, you must have at least one Lightning web component in your project.

    ```bash
    npm run lint
    ```

**note:** Lightning Web Security provides additional ESLint rules. For more information, see [Install ESLint Rules for Lightning Web Security](/docs/platform/lwc/guide/security-lwsec-tools-lint.html).


## Create a Lightning Web Component

Create Lightning web components in the `force-app/main/default/lwc` folder.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Lightning Web Component**.

You can also run this command from the command line.

```bash
sf lightning generate component --type lwc -n myComponent -d force-app/main/default/lwc
```

## Deploy Source to an Org

You’re ready to deploy new source code, including Lightning web components, to your org for testing. Save your code first!

When you deploy source code to an org, the entire path that you specify is deployed.

Run this command from the command line.

```bash
sf project deploy start -d <PATHTODEPLOY> -o <ORGUSERNAME>
```

This example deploys the root directory of a Salesforce DX project to an org with the username `example@force.com`.

```bash
sf project deploy start -d force-app -o example@force.com
```

## Retrieve Source from an Org

Run this command from the command line.

```bash
sf project retrieve start -d <PATHTORETRIEVE> -o <ORGUSERNAME>
```

## Lather, Rinse, Repeat

To see changes in Salesforce, deploy source code to your org and hard refresh the browser.

**See Also**

- [Salesforce CLI Command Reference](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/)
- [Salesforce DX Developer Guide: Develop Against Any Org](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_develop_any_org.htm)

<!-- document id=ea81cd3ab3a91c38f02213c3242d2221877689f48d26f2ff34b779ab4ceb6c61 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-sfdx-scratch-org.md -->

# Develop in Scratch Orgs

You can develop Lightning web components in scratch orgs. Scratch orgs are short-term Salesforce environments that you can spin up to work on a feature. Pushing to a scratch org includes only files that have changed.

**note:** Before you create a component for a scratch org, see [Set Up an Editor, Linter, and Org](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md) and [Install the Salesforce CLI](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-cli.md).

## Create a Salesforce DX Project

A Salesforce DX project has a specific structure and a configuration file that identifies the directory as a Salesforce DX project.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Project**.

You can also run this command from the command line.

```bash
cd PATH/TO/YOUR/SFDX/PROJECTS
sf project generate --name MyLWC
cd MyLWC
```

## Install, Configure, and Run Linting

ESLint is a program that runs in the background and looks for problems as you code. It analyzes your code against a set of rules. These linting rules can include best practices, guard rails, and errors. You can configure the linting rules for your project. If code breaks a rule, a squiggly line appears below the code. Mouse over the code to see the rule and a suggested fix.

1.  To install the [ESLint rules for Lightning Web Components](https://github.com/salesforce/eslint-plugin-lwc), run this command in your Salesforce DX project directory.

    ```bash
    npm install
    ```

    If you have issues, verify that the project’s `package.json` file matches the [salesforcedx-templates `package.json` file](https://github.com/forcedotcom/salesforcedx-templates/blob/master/src/templates/project/package.json). For example, the `.eslintignore` file is no longer needed and has been superseded by the `"lint": "eslint **/{aura,lwc}/**/*.js"` script in `package.json`. The script runs linting only for the JS files under the `lwc` and `aura` folders.

2.  There are three configuration levels for linting. Check out the [eslint-config-lwc](https://github.com/salesforce/eslint-config-lwc) README and choose the configuration that matches your coding needs. In your project, set the configuration level in the `/force-app/main/default/lwc/.eslintrc.json` file.

    If your project doesn’t have the file, copy it from [salesforcedx-templates](https://github.com/forcedotcom/salesforcedx-templates/blob/main/src/templates/project/lwc.eslintrc.json) and paste it in the `/force-app/main/default/lwc` folder.

3.  To run linting, you must have at least one Lightning web component in your project.

    ```bash
    npm run lint
    ```

**note:** Lightning Web Security provides additional ESLint rules. For more information, see [Install ESLint Rules for Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-tools-lint.html).

## Enable Dev Hub in Your Org

A dev hub is the main Salesforce org that you and your team use to create and manage your scratch orgs.

1.  From Setup, enter `Dev Hub` in the Quick Find box and select **Dev Hub**.

    If you don't see Dev Hub in the Setup menu, make sure that your org is one of the supported editions.

2.  To enable Dev Hub, click **Enable**. After you enable Dev Hub, you can’t disable it.

For more information, see [Salesforce DX Setup Guide: Enable Dev Hub in Your Org](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_setup_enable_devhub.htm).

## Authorize Your Dev Hub

Before you can create a scratch org, authorize your Dev Hub org. Running this command opens a browser to the Salesforce login page. Enter your Dev Hub username and password. Authorize only once, not every time you work on your project.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Authorize a Dev Hub**.

You can also run this command from the command line.

```bash
sf org login web -d -a LWC-Hub
```

“LWC-Hub” is an alias for the Dev Hub org that you can use in other Salesforce CLI commands. You can create any alias that you like.

## Create a Default Scratch Org

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create a Default Scratch Org**.

You can also run this command from the command line.

```bash
sf org create scratch -s -f config/project-scratch-def.json -a "LWC"
```

“LWC” is an alias for the scratch org that you can use in other Salesforce CLI commands. You can create any alias that you like.

To create a scratch org, specify a scratch org definition file. This example uses the default scratch org definition file, `project-scratch-def.json`.

**tip:** Beginning in Winter ’23, [Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-intro.html) is enabled by default in new orgs, including scratch orgs. For more information see [Enable and Disable LWS in Scratch Orgs](/docs/platform/lightning-components-security/guide/lws-enable-scratch-orgs.html)

## Create a Lightning Web Component

Create Lightning web components in the `force-app/main/default/lwc` folder.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Lightning Web Component**.

You can also run this command from the command line.

```bash
sf lightning generate component --type lwc -n myComponent -d force-app/main/default/lwc
```

## Push Source to the Scratch Org

You’re ready to push new source code, including Lightning web components, to your scratch org for testing. Remember to save your code before you push.

When you push source code to a scratch org, only files that have changed are pushed.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Push Source to Default Scratch Org**.

You can also run this command from the command line.

```bash
sf project deploy start
```

## Pull Source from the Scratch Org

You can also run this command from the command line.

```bash
sf project retrieve start
```

## Open the Scratch Org

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Open Default Scratch Org**.

You can also run this command from the command line.

```bash
sf org open
```

## Lather, Rinse, Repeat

To see changes in Salesforce, push source code to your org and hard refresh the browser.

**See Also**

- [Salesforce CLI Command Reference](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/)
- [Salesforce DX Developer Guide: Scratch Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs.htm)

<!-- document id=dae44db26a104d3d3c553347e5fe44443fda5a43d0d1dda53839ca71ded03967 url=/developer/current/en-us/lwc/lwc/guides/get-started/mobile-extensions/mobile-extensions.md -->

# Develop Mobile Components

When you’re developing Lightning web components, it’s important to review and validate your components not only on the desktop, but also on mobile devices. To preview your components on virtual mobile devices and see changes as you code, use the Salesforce CLI Mobile Extensions plug-in. Then download and run virtual device builds of the Salesforce mobile app to preview how your components coexist with other components in Salesforce.

Mobile development with LWC is a large subject area, covering additional features, considerations, and approaches that are different for mobile devices, with their smaller screens, different input methods, and possibly limited or zero connectivity.

Learn the fundamentals of Lightning Web Components from this guide. When you're ready to build mobile-friendly features, see the _[Mobile and Offline Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/),_ an essential companion to this guide when doing mobile development.

**See Also**

- [Mobile Development Tools and Processes](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/dx.htm)
- [Set Up Mobile Development Tools](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/dx_set_up_dev_environment.htm)
- [Preview Lightning Web Components on Mobile](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/dx_mobile_previews.htm)

<!-- document id=b55331fe79bcb19c82a37fdb969ac95894066b03d6241e8161f92fe35500ad87 url=/developer/current/en-us/lwc/lwc/guides/security/security-intro.md -->

# Develop Secure Code

Lightning web components (LWC) have a client-side security architectural layer that protects your custom components by automatically blocking or modifying any insecure behavior of APIs. This layer prevents components from accessing data that belongs to platform code or components from other namespaces without explicit permission.

To learn how to build components that work with the new architecture [Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html) or the legacy architecture [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html), see [_Security for Lightning Components_](/docs/platform/lightning-components-security/guide).

Regardless of the security architecture, LWC use [JavaScript strict mode](/docs/platform/lightning-components-security/guide/js-strict-mode-intro.html) to turn on native security features in the browser and [Content Security Policy (CSP)](/docs/platform/lightning-components-security/guide/content-security-policy-intro.html) rules to control the source of content that can be loaded on a page.

**See Also**

- [_Security for Lightning Components_: How Lightning Web Security Compares to Lightning Locker](/docs/platform/lightning-components-security/guide/get-started-compare-lws-locker.html)
- [_Salesforce Developers Blog_: What ISV Partners Need to Know About Lightning Web Security](https://developer.salesforce.com/blogs/2022/12/what-isv-partners-need-to-know-about-lightning-web-security)

<!-- document id=ca407cda5ca494c204979be9eda747ed73ce56dce322670ea08b69fc4bd1c399 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-sfdx.md -->

# Develop with Salesforce DX Tools

We recommend using Salesforce DX tools for the most tightly integrated development experience. This workflow leverages the Salesforce CLI, the VS Code editor with the Salesforce Extension Pack, Salesforce DX projects, and scratch or sandbox orgs.

**tip:** To set up your developer environment with Salesforce DX tools and create your first component, head over to Trailhead and complete the [Quick Start: Lightning Web Components](https://trailhead.salesforce.com/content/learn/projects/quick-start-lightning-web-components/) project.

**See Also**

- [Lightning Web Components Video Gallery](https://developer.salesforce.com/tv/lwc-video-gallery)
- [Salesforce DX Developer Guide: How Salesforce DX Changes the Way You Work](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm)

<!-- document id=3f92d785962073d68f134891f31331def7aac64919c2c3dd5c2d5736cbe73133 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-disable-caching.md -->

# Disable Caching During Development

Disable the secure and persistent browser caching setting in a sandbox or Developer Edition org to see the effect of any code changes without emptying the cache.

The caching setting improves page reload performance by avoiding extra round trips to the server.

**warning:** Disabling secure and persistent browser caching has a significant negative performance impact on Lightning Experience. Always enable the setting in production orgs.

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.

2.  Deselect the checkbox for **Enable secure and persistent browser caching to improve performance**.

3.  Click **Save**.

After disabling the browser caching setting, you can reload a page to test your code changes without clearing your cache. We recommend that you reenable the browser caching setting after debugging your code.

**See Also**

- [Enable Debug Mode in Salesforce](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md)

<!-- document id=6fc4bcbb2e3b8b4478d9e8b41e5d1ed78bca4edb6252a6a92cfb5e2c64e952c9 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-disable.md -->

# Disable Lightning Locker for an Aura Component

To disable Lightning Locker for an Aura component, set the component's API version to 39.0 or earlier. If a component is set to API version 40.0 or later, Lightning Locker is enabled. If your Aura component uses a base component that has a minimum API version later than 39.0, you can’t disable Locker on your component.

Salesforce API version 40.0 corresponds to Summer ’17, when Lightning Locker was enabled for all orgs. Lightning Locker is disabled for any component created before Summer ’17 because these components have an API version earlier than 40.0.

**important:** This topic only applies to Aura components. You can't disable Lightning Locker for an individual Lightning web component (LWC).

If your org enables [Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md), the Aura component's API version has no effect on LWS.

## Set the API Version in the Component’s Metadata File

To disable Lightning Locker for an Aura component, in the [AuraDefinitionBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_auradefinitionbundle.htm) metadata of the component, set the `apiVersion` field to `39.0`.

In this example, the metadata file `myComponent.cmp-meta.xml` for component `myComponent.cmp` sets the API version to 39.0.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<AuraDefinitionBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>39.0</apiVersion>
    <description>My Component</description>
</AuraDefinitionBundle>
```

If your Aura component uses a base component that has a minimum API version later than 39.0, you can’t disable Locker on your component. For example, the base component [`lightning:map`](https://developer.salesforce.com/docs/component-library/bundle/lightning:map/specification) requires API version 44.0 or later. If you use `lightning:map` and set `apiVersion` to 39.0 in `myComponent.cmp-meta.xml`, an error occurs. For example, if you add the component to a page in Lightning App Builder, this error message is shown.

`Component API version is too old: 'markup://c:myComponent' must be set to API version '44' or later to use component 'markup://lightning:map'`

**note:** If a component’s `apiVersion`is set to 39.0 to disable Lightning Locker, the component is not affected by the Locker API version setting for the org. Lightning Locker is still disabled in the component.

## Don’t Mix API Versions Within a Component Hierarchy

For consistency and ease of debugging, we recommend that you set the same Salesforce API version for all custom components in your app, containment hierarchy (component within component), or extension hierarchy (component extending component).

If you mix API versions in your containment or extension hierarchy, and Lightning Locker is enabled for some components but disabled for other components, then your app is harder to debug.

### Extension Hierarchy Example

Lightning Locker is enabled for a component or an application purely based on component API version. The extension hierarchy for a component doesn’t factor into Lightning Locker enforcement.

Let’s look at an example where a `Car` component extends a `Vehicle` component. `Car` has API version 39.0 so Lightning Locker is disabled. `Vehicle` has API version 40.0 so Lightning Locker is enabled.

Now, let’s say that `Vehicle` adds an expando property, `_counter`, to the `window` object by assigning a value to `window._counter`. Because Lightning Locker is enabled for `Vehicle`, the `_counter` property is added to `SecureWindow`, which is the secure wrapper for `window` for the component’s namespace. The property isn’t added to the native `window` object.

Lightning Locker is disabled for `Car`, so the component has access to the native `window` object. `Car` can’t see the `_counter` property as it’s only available in the `SecureWindow` object.

### Containment Hierarchy Example

The containment hierarchy within an application or a component doesn’t factor into Lightning Locker enforcement.

Let’s look at an example where a `Bicycle` component contains a `Wheel` component. If `Bicycle` has API version 40.0, Lightning Locker is enabled. If `Wheel` has API version 39.0, Lightning Locker is disabled for `Wheel` even though it’s contained in a component, `Bicycle`, that has Lightning Locker enabled.

**See Also**

- [Select the Locker API Version for an Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-api-setting.md)
- [Secure Wrappers](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-global-access.md)
- [Sharing JavaScript Code Across Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/security_share_code.htm)
- [_Lightning Aura Components Developer Guide_: Aura Component Versioning for Managed Packages](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_versioning.htm)
- [_Lightning Aura Components Developer Guide_: Base Components with Minimum API Version Requirements](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_versioning_min_version.htm)

<!-- document id=130e947d0410ea8e97678751ec0b5f8fe83af4cd92ded0d75f78b82bcbabf64b url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-sanitize-disable.md -->

# Disable Sanitization

By default, the [`aura:unescapedHTML`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-unescaped-html.html) component sanitizes HTML content when Lightning Web Security is enabled in your org. This sanitization allows [safe HTML tags](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-html.md) and removes other dangerous elements and attributes.

When you disable sanitization in your org, `aura:unescapedHTML` renders all HTML content without modification, including tags that sanitization normally removes for security reasons.

**warning:** Disabling sanitization can expose your org to cross-site scripting (XSS) vulnerabilities if you render untrusted content. Only disable sanitization if you have a specific requirement and understand the security implications.

To disable sanitization when you use `aura:unescapedHTML`:

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.
2.  In the Lightning Web Security section, select the **Disable sanitization in aura:unescapedHtml component** option.
3.  Save your changes.

## Examples of Unsafe Tags When Sanitization is Disabled

When sanitization is enabled (default), `aura:unescapedHTML` removes unsafe elements and attributes.

When you disable sanitization, certain attack vectors become possible and can potentially expose your org to XSS vulnerabilities. Content Security Policy (CSP) provides some protection but it isn't sufficient to prevent all XSS attacks.

### Script Tags

- Scripts that run directly in `script` tags
- Scripts that are embedded in iframe `srcdoc` attributes
- Base64-encoded scripts in `iframe` data URIs
- Blob URLs that contain runnable JavaScript

### Event Handlers

- Image error handlers that run when images fail to load
- SVG `onload` events that fire when SVG elements render
- Input `onfocus` events that fire automatically with `autofocus`
- Mouse events that trigger when users hover over elements
- Details elements with `toggle` events that fire when disclosure widgets are opened
- Video and audio error handlers that run when media fails to load
- Marquee `onstart` events that fire when animations begin

### JavaScript Protocols

- Anchor tags that use the `javascript:` protocol in `href` attributes
- Iframes that use the `javascript:` protocol in `src` attributes
- Object elements that use the `javascript:` protocol in `data-*` attributes
- Meta elements with the `http-equiv` tag set to `refresh` and redirect to `javascript:` URLs

### Iframe Usage

- Iframe `onload` events that run in the parent context when frames load
- Nested iframes that attempt to bypass simple content filters
- Iframe target injection where named iframes are targets
- SVG elements with event handlers that are embedded inside iframes

### Style and CSS

- Style tags that attempt to run JavaScript through URL expressions
- Hidden iframes that use CSS to conceal malicious content from users

### Obfuscation Techniques

- HTML entity encoding that obfuscates `javascript:` protocols and bypasses detection
- Polyglot or malformed tags that browsers attempt to fix during parsing
- XML or XSLT content that embeds scripts via stylesheets
- PostMessage injection that uses cross-frame communication to run code

**warning:** These attack vectors are blocked when sanitization is enabled. Disabling sanitization makes your application vulnerable to XSS attacks if your component renders untrusted content.

## When to Disable Sanitization

Consider disabling sanitization only when:

- You want to render complex HTML that includes interactive elements or embedded scripts
- The HTML content comes from trusted sources that you fully control
- You have implemented security measures to validate and sanitize content before rendering
- Your use case requires functionality that's blocked by sanitization

**See Also**

- [HTML Allowlist for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-html.md)
- [SVG Allowlist for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg.md)
- [How LWS Sanitizes Static Resources in SVG Elements](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg-static-resource.md)

<!-- document id=2b53ec578a9526fc62db58a598fa6a068071ac5e2aee408f332268ddcf20bf8f url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-dismiss.md -->

# `dismiss()`

Use this function to end a scanning session, close the mobile OS scanning interface, and dispose of resources.

## Syntax

```javascript
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
dismiss(): void
```

## Parameters

None.

## Returns

None.

## Usage

```javascript
myScanner
  .scan(scanningOptions)
  .then((result) => {
    console.log(result);
    this.scannedBarcode = result.value;
  })
  .catch((error) => {
    console.error(error);
  })
  .finally(() => {
    // Handle final cleanup
    myScanner.dismiss();
  });
```

After calling `dismiss()`, you can call `scan()` on an existing or new `BarcodeScanner` instance to start a new scanning session.

<!-- document id=bd023c2e0063ec23bd26d7380022cde0a9af6f0b47a97cc51e6394391a03f2ee url=/developer/current/en-us/lwc/lwc/guides/data/data-table-custom-types-events.md -->

# Dispatch a Custom Event From a Custom Data Type

The `lightning-datatable` component fires several custom events, including the `rowselection` event when a row is selected.
For more information on the custom events available for `lightning-datatable`, see the [`lightning-datatable` reference documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

If these custom events don't meet your requirements, you can dispatch your own custom event and handle it from your parent component.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

## Example: Navigate to a Record with a Custom Data Type

Here's an example that navigates to a record when a custom data type is clicked. The datatable loads a Contact Picture column using a custom data type.

**tip:** This example modifies the [`customDataTypes` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/customDataTypes) in the lwc-recipes GitHub repo.

Clicking a contact's photo redirects you to the corresponding contact record page using the navigation service.

```ascii
customDataTypes
   ├──customDataTypes.html
   ├──customDataTypes.js
   ├──customDataTypes.js-meta.xml
   └──customPicture.html
```

The `customDataTypes.js` file imports and defines the `customPicture` data type within the same folder. To make the record ID available when the photo is clicked, the custom data type includes the `recordId` type attribute.

```
import LightningDatatable from "lightning/datatable";
import customPicture from "./customPicture.html";
export default class CustomDataTypes extends LightningDatatable {
  static customTypes = {
    customPictureType: {
      template: customPicture,
      standardCellLayout: true,
      typeAttributes: ["pictureUrl", "recordId"],
    },
    // Other Custom Types
  };
}
```

The `customPicture` template passes in the `pictureUrl` and `recordId` type attributes to the `c-custom-pic` child component, which is a new component you can create on your own that's not part of the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes).

```
<template>
  <c-custom-pic picture-url={typeAttributes.pictureUrl} record-id={typeAttributes.recordId}>
  </c-custom-pic>
</template>
```

The `c-custom-pic` component includes a click handler. It displays an image based on the `pictureUrl` value passed in to the custom data type.

```
<template>
  <img
  src={pictureUrl}
  class="slds-avatar slds-avatar_circle slds-avatar_large"
  alt="Profile photo"
  title="Click photo to edit contact"
  onclick={handleClick}
  />
</template>
```

The click handler dispatches a `clicked` custom event with the `detail` property.

```
import { LightningElement, api } from 'lwc';

export default class CustomPic extends LightningElement {

  @api pictureUrl;
  @api recordId;

  handleClick() {
    const photoClickEvent = new CustomEvent("photoclick", {
        composed: true,
        bubbles: true,
        cancelable: true,
        detail: {
          pictureUrl: this.pictureUrl,
          recordId: this.recordId
        },
    });
    this.dispatchEvent(photoClickEvent);
  }
}
```

The `datatableCustomDataType` parent component listens to and handles the `photoclick` custom event.

```
<template>
    <lightning-card
        title="Datatable Custom Data Type"
        icon-name="custom:custom62"
    >
        <c-custom-data-types
            key-field="Id"
            data={data}
            show-row-number-column
            column-widths-mode="auto"
            columns={columns}
            onphotoclick={handlePhotoClick}>
          </c-custom-data-types>
      </lightning-card>
</template>
```

The parent component imports the `lightning/navigation` module so it can navigate to a record edit page.

```
import { LightningElement, wire } from 'lwc';
import { NavigationMixin } from "lightning/navigation";

import getContacts from '@salesforce/apex/ContactController.getContactList';

const COLS = [
    { label: 'First Name', fieldName: 'FirstName' },
    { label: 'Last Name', fieldName: 'LastName' },
    { label: 'Title', fieldName: 'Title' },
    { label: 'Phone', fieldName: 'Phone', type: 'phone'},
    { label: 'Email', fieldName: 'Email', type: 'email' },
    {
        label: 'Contact Picture',
        type: 'customPictureType',
        typeAttributes: {
            pictureUrl: { fieldName: 'Picture__c' },
            recordId: { fieldName: 'Id'}
        },
    }
];
export default class DatatableCustomDataType extends NavigationMixin(LightningElement) {
    columns = COLS;
    data = [];

    @wire(getContacts)
    contacts(result) {
        if (result.data) {
            this.data = result.data;
            this.error = undefined;

        } else if (result.error) {
            this.error = result.error;
            this.data = undefined;
        }
    }

    handlePhotoClick(e) {
        const { pictureUrl, recordId } = e.detail;

        // View the contact record
        this[NavigationMixin.Navigate]({
            type: "standard__recordPage",
            attributes: {
            recordId: recordId,
            actionName: "view",
            },
        });
    }
}
```

The `ContactController.cls` Apex class returns a list of contacts.

```
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT
                Id,
                Name,
                FirstName,
                LastName,
                Title,
                Phone,
                Email,
                Picture__c
            FROM Contact
            WHERE Picture__c != NULL
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

## Dispatch a Custom Event via a Slot

If you dispatch a custom event on a custom data type via the `customdatatypes` slot, you can handle the custom event on the `lightning-datatable` component. For example, add the `onphotoclick` handler like this.

```
<lightning-datatable
    key-field="Id"
    data={contacts.data}
    show-row-number-column
    column-widths-mode="auto"
    columns={columns}
    onphotoclick={handlePhotoClick}>
    <template if:true={showCustomTypes}>
        <c-custom-data-types slot="customdatatypes"></c-custom-data-types>
    </template>
</lightning-datatable>
```

For more information, see [Pass in Custom Data Types Using a Slot](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md#pass-in-custom-data-types-using-a-slot).

**See Also**

- [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md)
- [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md)

<!-- document id=a777ba1b291c59601facebe85eb7768f5bff6136f404c3db08c616f15fdfb544 url=/developer/current/en-us/lwc/lwc/guides/data/data-table-inline-edit.md -->

# Display Data in a Table with Inline Editing

To display Salesforce data in a table, use the `lightning-datatable` component. The component supports inline editing, which enables users to update a field value without navigating to the record.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

To load a list of records, use the [`getListUi (Deprecated)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-list-ui.md) wire adapter or use SOQL in an Apex method. See [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/data/data-guidelines.md).

This example uses SOQL in an Apex method to load contacts on an account record.

```apex
public with sharing class ContactController {

    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList(String accId) {
        return [
            SELECT AccountId, Id, FirstName, LastName, Title, Phone, Email
            FROM Contact
            WHERE AccountId = :accId
            WITH USER_MODE
        ];
    }
}
```

The `@AuraEnabled(cacheable=true)` annotation exposes the method to Lightning components and caches the list of contacts on the client. The `accId` parameter filters the contacts for the given account record.

![A toast notification displaying as a green banner in the LWC Recipes sample app.](https://developer.salesforce.com/media/datatable_edit.png)

If the Apex method returns data, the HTML template displays the `lightning-datatable` component with editable first name and last name fields (1). When you edit a field, the **Save** button appears, and you can click it to update the contact record. Updating a contact record successfully also updates the record data in the [related lists](https://help.salesforce.com/articleView?id=lex_find_related_lists.htm) (2), and other components on the page that are managed by Lightning Data Service.

## Implement Inline Editing

**tip:** This example is based on the `datatableInlineEditWithUiApi` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. This version differs slightly to enable the datatable to be used on a record page.

To enable inline editing, configure the `lightning-datatable` component as shown in this `apexContactsForAccount` template.

<!-- prettier-ignore -->
```html
<!-- apexContactsForAccount.html -->
<template>
  <lightning-card title="Datatable Example" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <template lwc:if={contacts.data}>
        <lightning-datatable
          key-field="Id"
          data={contacts.data}
          columns={columns}
          onsave={handleSave}
          draft-values={draftValues}
        >
        </lightning-datatable>
      </template>
      <template lwc:if={contacts.error}>
        <!-- Handle Apex error -->
      </template>
    </div>
  </lightning-card>
</template>
```

The required `key-field` attribute associates each row with a contact record. The `data` attribute holds the data retrieved through the wire service from either an Apex method or a wire adapter. The `columns` attribute assigns a record field to each column and customizes the behavior of the columns. When a user edits a cell, the updated value is stored in `draft-values`.

Clicking the **Save** button triggers the `save` event. Use the `onsave` event handler to persist changes in the datatable. In the example, the `onsave` event handler calls [`updateRecord(recordInput, clientOptions)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-update-record.md) to save record changes.

**note:** For a list of attributes and supported features, see [`lightning-datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

## Enable Inline Editing in Columns

A row of data corresponds to a single record and each column displays the value of one of that record’s fields. To enable inline editing, specify which fields are editable by setting `editable: true` in the column definition. In this example, the First Name and Last Name fields are editable. Since the Name field on contacts is a compound field, you must use the First Name and Last Name fields separately.

<!-- prettier-ignore -->
```javascript
// apexContactsForAccount.js

import { LightningElement, wire, api } from "lwc";
import getContactList from "@salesforce/apex/ContactController.getContactList";
import { refreshApex } from "@salesforce/apex";
import { updateRecord } from "lightning/uiRecordApi";

import { ShowToastEvent } from "lightning/platformShowToastEvent";
import FIRSTNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LASTNAME_FIELD from "@salesforce/schema/Contact.LastName";
import TITLE_FIELD from "@salesforce/schema/Contact.Title";
import PHONE_FIELD from "@salesforce/schema/Contact.Phone";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";
import ID_FIELD from "@salesforce/schema/Contact.Id";

const COLS = [
  {
    label: "First Name",
    fieldName: FIRSTNAME_FIELD.fieldApiName,
    editable: true
  },
  {
    label: "Last Name",
    fieldName: LASTNAME_FIELD.fieldApiName,
    editable: true
  },
  { label: "Title", fieldName: TITLE_FIELD.fieldApiName, editable: true },
  {
    label: "Phone",
    fieldName: PHONE_FIELD.fieldApiName,
    type: "phone",
    editable: true
  },
  {
    label: "Email",
    fieldName: EMAIL_FIELD.fieldApiName,
    type: "email",
    editable: true
  }
];
export default class DatatableInlineEditWithUiApi extends LightningElement {
  @api recordId;
  columns = COLS;
  draftValues = [];

  @wire(getContactList, { accId: "$recordId" })
  contacts;

  async handleSave(event) {
    // Convert datatable draft values into record objects
    const records = event.detail.draftValues.slice().map((draftValue) => {
      const fields = Object.assign({}, draftValue);
      return { fields };
    });

    // Clear all datatable draft values
    this.draftValues = [];

    try {
      // Update all records in parallel thanks to the UI API
      const recordUpdatePromises = records.map((record) => updateRecord(record));
      await Promise.all(recordUpdatePromises);

      // Report success with a toast
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Success",
          message: "Contacts updated",
          variant: "success"
        })
      );

      // Display fresh data in the datatable
      await refreshApex(this.contacts);
    } catch (error) {
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Error updating or reloading contacts",
          message: error.body.message,
          variant: "error"
        })
      );
    }
  }
}
```

`@wire(getContactList)` provisions data to `contacts.data` and the record Id to `accId`.

When you edit fields, `event.detail.draftValues` stores the edited field values and the record `Id` as an array of objects.

<!-- prettier-ignore -->
```javascript
[
  {
    FirstName: "Sean",
    Id: "003R0000002J2wHIAS"
  },
  {
    FirstName: "Jack",
    Id: "003R0000002J2wIIAS"
  }
];
```

When you press the Tab key or click outside the cell after making changes, the datatable footer appears with the **Cancel** and **Save** buttons. To hide the datatable footer, clear the `draftValues` property. The `onsave` event handler clears `draftValues` after copying the values into a record object.

Call [`updateRecord(recordInput, clientOptions)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-update-record.md) to save the new field values to the records.

`updateRecord()` expects a single record only. Pass in a `recordInput` object for each record whose fields you’re updating. In this example, the `record` parameter contains an object with the updated fields for multiple records. To update multiple records simultaneously, pass the parameter to `updateRecord()` for processing.

After a successful save, the `onsave` event handler dispatches the `ShowToastEvent` event to display a success toast message.

After a record is updated, `refreshApex(this.contacts)` refreshes the list of contacts from the Apex method so that the datatable always presents the latest data.

**note:** For bulk record updates in a single transaction, we recommend using Apex. See the **Enabling Inline Editing Using Apex** section.

## Enable Inline Editing Using Apex

For bulk record updates, pass your record changes to an Apex controller that calls an `update` Data Manipulation Language (DML) operation. In this example, the edited field values are passed to the `updateContacts` Apex controller. Since the records are updated by Apex, you must notify Lightning Data Service (LDS) using the [`notifyRecordUpdateAvailable(recordIds)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-notify-record-update.md) function so that the Lightning Data Service cache and wires are refreshed.

**note:** This example is based on the `datatableInlineEditWithApex` component in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. This version differs slightly by using Apex without LDS.

In the `apexContactsForAccount.js` file you created in the previous example, import the Apex controller and the `notifyRecordUpdateAvailable` function.

```javascript
import updateContacts from "@salesforce/apex/ContactController.updateContacts";
import { notifyRecordUpdateAvailable } from "lightning/uiRecordApi";
```

Update the `handleSave()` function to handle the edited values. To ensure that `notifyRecordUpdateAvailable()` is called after the record is updated via Apex, use the `async`/`await` pattern or a Promise chain. This example uses `async`/`await`.

```javascript
async handleSave(event) {
    const updatedFields = event.detail.draftValues;

    // Prepare the record IDs for notifyRecordUpdateAvailable()
    const notifyChangeIds = updatedFields.map(row => { return { "recordId": row.Id } });

    try {
        // Pass edited fields to the updateContacts Apex controller
        const result = await updateContacts({data: updatedFields});
        console.log(JSON.stringify("Apex update result: "+ result));
        this.dispatchEvent(
            new ShowToastEvent({
                title: 'Success',
                message: 'Contact updated',
                variant: 'success'
            })
        );

        // Refresh LDS cache and wires
        notifyRecordUpdateAvailable(notifyChangeIds);

        // Display fresh data in the datatable
        await refreshApex(this.contacts);
            // Clear all draft values in the datatable
            this.draftValues = [];
        }
   } catch(error) {
           this.dispatchEvent(
               new ShowToastEvent({
                   title: 'Error updating or refreshing records',
                   message: error.body.message,
                   variant: 'error'
               })
         );
    };
}
```

The `updateContacts` Apex controller deserializes the JSON string containing the updated fields into a Contact object. It updates the changed records using the `update` DML operation.

```apex
@AuraEnabled
public static string updateContacts(Object data) {
    List<Contact> contactsForUpdate = (List<Contact>) JSON.deserialize(
         JSON.serialize(data),
         List<Contact>.class
    );
    try {
        update contactsForUpdate;
        return 'Success: contacts updated successfully';
    }
    catch (Exception e) {
        return 'The following exception has occurred: ' + e.getMessage();
    }
}
```

**See Also**

- [_Apex Developer Guide_: JSON Support](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_methods_system_json_overview.htm)
- [_Apex Developer Guide_: How DML Works](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/langCon_apex_dml_examples.htm)

<!-- document id=903e3653d51e7d5d452e0ecd03ba9591e2ccb22e8e799bd53669825ed0e2c4a0 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-screen-stages.md -->

# Display Flow Stages in a Flow Screen Component

To create a fully custom visual design for your flow's progress indicator, or to maintain an existing custom stages component, you can build a screen component that renders stages by wiring it to the `$Flow.ActiveStages` and `$Flow.CurrentStage` global variables in Flow Builder.

To show stages in a standard path or steps style, use the built-in progress indicator instead. No custom component required. See [Showing Users Their Progress in a Screen Flow](https://help.salesforce.com/s/articleView?id=platform.flow_build_stages.htm&type=5).

## How Flow Stages Work

You can define stages as resources with Flow Builder. Each stage has a label, an API name, and an order. Stages can be active by default, meaning they appear in `$Flow.ActiveStages` when a flow interview starts. You control which stage is current by updating `$Flow.CurrentStage` with assignment elements between screens.

Your screen component receives two values:

- `stages` — the list of active stage labels, sourced from `$Flow.ActiveStages` as a `String[]`
- `currentStage` — the label of the current stage, sourced from `$Flow.CurrentStage` as a `String`

## Create the Screen Component

The component declares `stages` and `currentStage` as `@api` properties and registers them in the component's configuration file so Flow Builder can wire them to flow variables.

### JavaScript

```javascript
// flowStages.js
import { LightningElement, api } from "lwc";

export default class FlowStages extends LightningElement {
  @api stages = [];
  @api currentStage;
}
```

### HTML Template

<!-- prettier-ignore -->
```html
<!-- flowStages.html -->
<template>
  <lightning-progress-indicator current-step={currentStage} type="path">
    <template for:each={stages} for:item="stage">
      <lightning-progress-step key={stage} label={stage} value={stage}>
      </lightning-progress-step>
    </template>
  </lightning-progress-indicator>
</template>
```

### Configuration File

```xml
<!-- flowStages.js-meta.xml -->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>68.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__FlowScreen</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__FlowScreen">
      <property name="stages" type="String[]" />
      <property name="currentStage" type="String" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

## Add the Component to Your Flow Screens in Flow Builder

1. Open your screen flow in Flow Builder.
2. Define your stages as flow resources. In the Manager panel, click **New Resource**, select **Stage**, and enter a label and order for each stage. To include a stage in `$Flow.ActiveStages` at the start of the flow interview, select **Active by default**.
3. On each screen element that should show the progress indicator, add the custom stages component.
4. For the **Stages** property, enter `{!$Flow.ActiveStages}`. For the **Current Stage** property, enter `{!$Flow.CurrentStage}`. In the **Advanced** section, select **Manually Assign Variables**.
5. Between each pair of screen elements, add an assignment element that sets `$Flow.CurrentStage` to the label of the next stage.

**See Also**

- [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens.md)
- [Control Navigation in Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-screen-navigate.md)
- [Runtime Considerations for Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-runtime-considerations.md)
- [Component Reference: lightning-progress-indicator](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-progress-indicator)

<!-- document id=52420460484d467bcbd7114881eb83cf5f0fd18c8b842e12f81ce8b06afa58e2 url=/developer/current/en-us/lwc/lwc/guides/data/data-table-intro.md -->

# Display Record Data in a Table

To display rows and columns of record data, use the `lightning-datatable` component. To display data in a table with a structural hierarchy, such as account records and associated contacts, use the `lightning-tree-grid` component. For more information, see [Compare lightning-datatable and lightning-tree-grid](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-vs-tree-grid.md).

With the `lightning-datatable` component, you can:

- [Display data in a table with inline editing](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-inline-edit.md)
- [Create a custom data type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types.md)
- [Customize data type layout and styles](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-styling.md)
- [Make a custom data type editable](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-editable.md)
- [Improve datatable performance](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-performance.md)
- [Support datatable accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.md)

Alternatively, the `lightning-tree-grid` component is built on `lightning-datatable` and supports a subset of its features. You can [create a hierarchical table of record data](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-tree-grid.md) using `lightning-tree-grid`, which can present child records using a toggle in the datatable.

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

<!-- document id=9b4c30fc8f78fca25c13a8be573b2f96aee14a1f9aed7c9446bc429cdf86ce02 url=/developer/current/en-us/lwc/lwc/guides/use/use-packaging.md -->

# Distribute Components on AppExchange

As an ISV or Salesforce partner, you can package components and distribute them to other Salesforce users and organizations on AppExchange, the Salesforce store.

**See Also**

- [AppExchange](https://appexchange.salesforce.com/)
- [_Salesforce Help_: Understanding Packages](https://help.salesforce.com/articleView?id=sharing_apps.htm)
- [ISVforce Guide](https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/packaging_intro.htm)

<!-- document id=6eff3073e8e8a26b80f59abb8b5cd0f860a1ee99f3a7aad25bbf685e7df6fade url=/developer/current/en-us/lwc/utam/references/descriptions-metadata.md -->

# document, navigation, and window Objects

The `document` and `navigation` objects can be used as an element in a compose statement.

## document object

The `document` object exposes methods to interact with the DOM, such as waiting until its state is ready or checking the URL. It also exposes methods for frames.

Reference the `document` object inside a compose statement in JSON using this syntax:

```json
{
  "element": "document",
  "apply": "getUrl"
}
```

Here are the supported methods for the `document` object. The return value is asynchronous. For example, in JavaScript, a Promise is returned.

| Method                              | Description                                                                      | Returns               | Example                                          |
| ----------------------------------- | -------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------ |
| `waitFor<T>`                        | Waits for specified criteria to be satisfied.                                    | `<T>`                 | [beforeLoad](/grammar/explicit-waits#beforeload) |
| `waitForDocumentReady()`            | Waits for the document to be ready for JavaScript code to execute.               | `boolean`             | [beforeLoad](/grammar/explicit-waits#beforeload) |
| `containsElement(locator: Locator)` | Checks whether the document contains an element with a matching selector.        | `boolean`             | [Explicit Waits](/grammar/explicit-waits)        |
| `getUrl()`                          | Gets the URL of the document.                                                    | `string`              |                                                  |
| `enterFrame`                        | enters a frame or iframe element                                                 | `frame`               |                                                  |
| `enterFrameAndLoad`                 | enters a frame or iframe element and then loads a Page Object that is a new root | `frame`, `pageObject` |                                                  |
| `exitFrame`                         | exits focus from a current frame or iframe                                       |                       |                                                  |
| `exitToParentFrame`                 | exits focus from a frame or iframe to the immediate parent frame                 |                       |                                                  |

## navigation object

The `navigation` object exposes methods for browser navigation, such as back and forward, as well as methods
for managing multiple browser windows or tabs.

Reference the `navigation` object inside a compose statement in JSON using this syntax:

```json
{
  "element": "navigation",
  "apply": "back"
}
```

Here are the supported methods for the `navigation` object.
| Method | Description | Returns |
| ---------------------------- | ------------------------------------------------------ | --------- |
| `back` | Browser navigates backward | void |
| `forward` | Browser navigates forward | void |
| `switchToWindow(url)` | Switches to the window navigated to the specified URL | `window` |
| `closeWindow(url)` | Closes the window navigated to the specified URL; if no URL is specified, closes the current window | void |
| `closeWindow()` | Closes the current window | void |
| `getWindowCount` | Gets the number of currently opened managed windows | `integer` |
| `currentWindow` | Gets the window with the current command context | `window` |
| `setupWaitForNewWindow` | Sets up a wait for a new window to appear after taking a subsequent action | void |
| `waitForNewWindow` | Waits for a new window to be opened and switches the command context to the new window; if called without a prior call to `setupWaitForNewWindow`, an exception is thrown | `window` |
| `waitForNewWindowAndLoad` | Waits for a new window to be opened, switches to it, and loads a Page Object that is a new root | `pageObject` |
| `switchToWindowAndLoad(url)` | Switches to the window navigated to the specified URL and loads a Page Object that is a new root | `pageObject` |

## window object

The `window` object exposes methods for manipulating a single browser window or tab.

Here are the methods for the `window` object.
| Method | Description | Returns |
| --------------- | ---------------------------------------------------- | ---------- |
| `getRect` | Gets the rectangle of the window | `rect` |
| `setRect(rect)` | Sets the rectangle of the window | void |
| `close` | Closes the window | void |
| `getDocument` | Gets the document object associated with this window | `document` |

<!-- document id=7e8a604423af4834e790b2acb10b30b6f633e2f50531bda1fdc31569a2cc48fb url=/developer/current/en-us/lwc/utam/references/navigation-objects.md -->

# document, navigation, and window Objects

The `document` and `navigation` objects can be used as an element in a compose statement.

## document object

The `document` object exposes methods to interact with the DOM, such as waiting until its state is ready or checking the URL. It also exposes methods for frames.

Reference the `document` object inside a compose statement in JSON using this syntax:

```json
{
  "element": "document",
  "apply": "getUrl"
}
```

Here are the supported methods for the `document` object. The return value is asynchronous. For example, in JavaScript, a Promise is returned.

| Method                              | Description                                                                      | Returns               | Example                                          |
| ----------------------------------- | -------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------ |
| `waitFor<T>`                        | Waits for specified criteria to be satisfied.                                    | `<T>`                 | [beforeLoad](/grammar/explicit-waits#beforeload) |
| `waitForDocumentReady()`            | Waits for the document to be ready for JavaScript code to execute.               | `boolean`             | [beforeLoad](/grammar/explicit-waits#beforeload) |
| `containsElement(locator: Locator)` | Checks whether the document contains an element with a matching selector.        | `boolean`             | [Explicit Waits](/grammar/explicit-waits)        |
| `getUrl()`                          | Gets the URL of the document.                                                    | `string`              |                                                  |
| `enterFrame`                        | enters a frame or iframe element                                                 | `frame`               |                                                  |
| `enterFrameAndLoad`                 | enters a frame or iframe element and then loads a Page Object that is a new root | `frame`, `pageObject` |                                                  |
| `exitFrame`                         | exits focus from a current frame or iframe                                       |                       |                                                  |
| `exitToParentFrame`                 | exits focus from a frame or iframe to the immediate parent frame                 |                       |                                                  |

## navigation object

The `navigation` object exposes methods for browser navigation, such as back and forward, as well as methods
for managing multiple browser windows or tabs.

Reference the `navigation` object inside a compose statement in JSON using this syntax:

```json
{
  "element": "navigation",
  "apply": "back"
}
```

Here are the supported methods for the `navigation` object.
| Method | Description | Returns |
| ---------------------------- | ------------------------------------------------------ | --------- |
| `back` | Browser navigates backward | void |
| `forward` | Browser navigates forward | void |
| `switchToWindow(url)` | Switches to the window navigated to the specified URL | `window` |
| `closeWindow(url)` | Closes the window navigated to the specified URL; if no URL is specified, closes the current window | void |
| `closeWindow()` | Closes the current window | void |
| `getWindowCount` | Gets the number of currently opened managed windows | `integer` |
| `currentWindow` | Gets the window with the current command context | `window` |
| `setupWaitForNewWindow` | Sets up a wait for a new window to appear after taking a subsequent action | void |
| `waitForNewWindow` | Waits for a new window to be opened and switches the command context to the new window; if called without a prior call to `setupWaitForNewWindow`, an exception is thrown | `window` |
| `waitForNewWindowAndLoad` | Waits for a new window to be opened, switches to it, and loads a Page Object that is a new root | `pageObject` |
| `switchToWindowAndLoad(url)` | Switches to the window navigated to the specified URL and loads a Page Object that is a new root | `pageObject` |

## window object

The `window` object exposes methods for manipulating a single browser window or tab.

Here are the methods for the `window` object.
| Method | Description | Returns |
| --------------- | ---------------------------------------------------- | ---------- |
| `getRect` | Gets the rectangle of the window | `rect` |
| `setRect(rect)` | Sets the rectangle of the window | void |
| `close` | Closes the window | void |
| `getDocument` | Gets the document object associated with this window | `document` |

<!-- document id=10bf524e90b9d4b4e8d487dd0d9b68170a2647133e74379f5024327f189674b0 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner.md -->

# DocumentScanner API

Scan documents from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how DocumentScanner works, see [Scan Documents on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_documentscanner.htm).

<!-- document id=8f0abb5c644ce218fa53ce20f6cf882f3d95aad2292039b2febecfeb279e9755 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-constants.md -->

# DocumentScanner Constants

DocumentScanner defines and uses several constants. Each of the following constants enumerates the accepted string values for the associated properties.

## Constant Values

The following constants are available as properties on an instance of `DocumentScanner`.
The constants enumerate the accepted values for the associated properties.

| Constant Name           | Accepted Value                                         | Description                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DocumentScannerSource` | "INPUT_IMAGE", "PHOTO_LIBRARY", "DEVICE CAMERA"        | Possible sources for the document image to be scanned. Correlates with the `imageSource` property on the `DocumentScannerOptions` object.                        |
| `Script`                | "CHINESE", "DEVANAGARI", "JAPANESE", "KOREAN", "LATIN" | Possible hint values for the script system used in the document to be scanned. Correlates with the `scriptHint` property on the `DocumentScannerOptions` object. |

## `DocumentScannerFailureCode`

Correlates with the `code` property on the `DocumentScannerFailure` object.

| Accepted Value                         | Description                                                                                                                                                      |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "USER_DISMISSED"                       | The user dismissed the scanner.                                                                                                                                  |
| "USER_DENIED_CAMERA_PERMISSION"        | A user denied permission to access the device camera when prompted.                                                                                              |
| "USER_DENIED_PHOTO_LIBRARY_PERMISSION" | A user denied permission to access the device photo library when prompted.                                                                                       |
| "NO_SUPPORTED_CAMERA"                  | The device doesn’t have a supported camera.                                                                                                                      |
| "INVALID_INPUT_IMAGE"                  | The input image data can’t be read as an image.                                                                                                                  |
| "SERVICE_NOT_ENABLED"                  | DocumentScanner is not enabled and cannot be used.                                                                                                               |
| "UNKNOWN_REASON"                       | An error occurred in the native code that isn’t related to permissions or hardware issues. More information is provided in the `DocumentScannerFailure` message. |

**See Also**

- [DocumentScanner Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-data-types.md)
- [DocumentScanner Constants](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-constants.md)

<!-- document id=69914535ae7e1f01ce8ed4ecd5cc899364a499fa30e39056566fac811cf3a254 url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-constants.md -->

# DocumentScanner Constants

NFCService defines and uses several constants. Each of the following constants enumerate the accepted string values for the associated properties.

## Constant Values

The following constants are available as properties on an instance of `NFCService`.
The constants enumerate the accepted values for the associated properties.

| Constant Name    | Accepted Value                                                                    | Description                                                              |
| ---------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `TypeNameFormat` | "ABSOLUTE_URI", "EMPTY", "EXTERNAL", "MEDIA", "WELLKNOWN", "UNCHANGED", "UNKNOWN" | Correlates with the `typeNameFormat` property on the `NFCRecord` object. |

## `NFCServiceFailureCode`

Correlates with the `code` property on the `NFCServiceFailure` object.

| Accepted Value        | Description                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "USER_DISMISSED"      | The user dismissed the scanner.                                                                                                                             |
| "NFC_NOT_SUPPORTED"   | The device doesn’t support NFC capabilities.                                                                                                                |
| "NFC_NOT_ENABLED"     | The device NFC feature is turned off.                                                                                                                       |
| "TAG_EMPTY"           | The NFC tag contains no data to be read.                                                                                                                    |
| "SERVICE_NOT_ENABLED" | NFCService is not enabled and cannot be used.                                                                                                               |
| "UNKNOWN_REASON"      | An error occurred in the native code that isn’t related to permissions or hardware issues. More information is provided in the `NFCServiceFailure` message. |

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)

<!-- document id=f0cb924aac733dee70be472f0518b5e818b5fd255b9121fa4b24d2d91bd7587f url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-data-types.md -->

# DocumentScanner Data Types

DocumentScanner defines and uses several data types.

## Document

An object representing a scanned document. Returned as the result of a successful scan operation.

The following image illustrates how DocumentScanner might scan and structure a document (in this case, some sample text). There are three `TextBlock` elements, each outlined in purple, and each `TextBlock` is further broken down by line (`TextLine`) and word or character (`TextElement`).

![A representation of the data model used to return scanned document results.](https://developer.salesforce.com/media/documentscanner_scan_results_data_model.png)

| Property Name | Type          | Description                                                                                                                                                                                          | Example                                                                                                                                                                                                                            |
| ------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `imageBytes`  | String        | A string containing the base64 image data of the scanned document. Only provided when `returnImageBytes` is set to `true` in your `DocumentScannerOptions` configuration object.                     | "2432BcYPJhSkzZjHS-Uiz1g8iZdQnRHtPnFKbMltJEc"                                                                                                                                                                                      |
| `text`        | String        | A string value providing the recognized text from the scanned document.                                                                                                                              | "This is a demonstration of how the text in a document is detected and broken down to TextBlock objects."                                                                                                                          |
| `blocks`      | `TextBlock[]` | An array of `TextBlock` objects that represent a structured text result that is visually aligned with the corresponding image. See [TextBlock](#textblock) for details of this structured text data. | `blocks[0] = [ [ ["This"], ["is"], ["a"], ["demonstration"], ["of"], ["how"], ["the"], ["text"], ["in"], ["a"], ["document"], ], [ ["is"], ["detected"], ["and"], ["broken"], ["down"], ["to"], ["TextBlock"], ["objects."], ], ]` |

## TextBlock

An object representing a contiguous section of the scanned text. Text that is visually close together is grouped into a _block_ of text. A document is made up of one to many blocks, and each block can be further broken down into smaller text elements: `TextLine` (a single line of text in a visually aligned run of text) and `TextElement` (an individual word or glyph).

| Property Name         | Type         | Description                                                                                                                                        | Example                                                                                                                                                |
| --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`                | String       | A string containing the text content of the block.                                                                                                 | "This is a demonstration of how the text in a document is detected and broken down to TextBlock objects."                                              |
| `lines`               | `TextLine[]` | An array of TextLine objects, each of which represents a visually aligned line of text within the TextBlock.                                       | `lines = blocks[0].lines; lines[0] = [ ["This"], ["is"], ["a"], ["demonstration"], ["of"], ["how"], ["the"], ["text"], ["in"], ["a"], ["document"], ]` |
| `recognizedLangCodes` | `String[]`   | The BCP-47 language code values for the languages detected in the recognized text.                                                                 | `["en", "ja"]`                                                                                                                                         |
| `frame`               | `Frame`      | An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the TextBlock. | `{ x: 100, y: 100, width: 650, height: 200 }`                                                                                                          |
| `cornerPoints`        | `Point[]`    | An array of Point objects that define a closed shape within the scanned image that contains the TextBlock.                                         | `[ { x: 100, y: 100 }, { x: 750, y: 100 }, { x: 750, y: 300 }, { x: 100, y: 300 } ]`                                                                   |

`frame` and `cornerPoints` both represent shapes that enclose the `TextBlock` in the scanned document image. You can use these regions to create user interfaces and displays for interacting with the scan results to further process them. For example, to assign different `TextBlocks` or `TextLines` to different form fields. An example of this would be scanning a business card into name, company, and contact fields.

The difference between the two is that `frame` is a rectangle, the smallest that fully encloses the scanned text within the image, while `cornerPoints` defines a not-necessarily rectangular shape, which more tightly encloses the scanned text. Use `frame` for approximate shapes, and `cornerPoints` when you want to be as close as possible to the scanned text.

**note:** The preceding example values of `frame` and `cornerPoints` represent the same region of a scanned document image. That’s unlikely to happen in a real world scan, where it’s hard to hold a camera perfectly aligned with a document. The nice, round numbers for the size of the region are similarly unlikely.

## TextLine

An object representing a single line of scanned text.

| Property Name         | Type            | Description                                                                                                                                       | Example                                                                                                            |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `text`                | String          | A string containing the text content of the line.                                                                                                 | "This is a demonstration of how the text in a document"                                                            |
| `elements`            | `TextElement[]` | An array of TextElement objects, each of which represents a word or glyph within the TextLine.                                                    | `[ ["This"], ["is"], ["a"], ["demonstration"], ["of"], ["how"], ["the"], ["text"], ["in"], ["a"], ["document"], ]` |
| `recognizedLangCodes` | `String[]`      | The BCP-47 language code values for the languages detected in the recognized text.                                                                | `["en"]`                                                                                                           |
| `frame`               | `Frame`         | An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the TextLine. | `{ x: 100, y: 100, width: 650, height: 100 }`                                                                      |
| `cornerPoints`        | `Point[]`       | An array of Point objects that define a closed shape within the scanned image that contains the TextLine.                                         | `[ { x: 100, y: 100 }, { x: 750, y: 100 }, { x: 750, y: 200 }, { x: 100, y: 200 } ]`                               |

## TextElement

An object representing a single word, individual character, or glyph.

| Property Name         | Type       | Description                                                                                                                                          | Example                                                                              |
| --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `text`                | String     | A string containing the text content of the word or character.                                                                                       | “This”                                                                               |
| `recognizedLangCodes` | `String[]` | The BCP-47 language code values for the languages detected in the recognized text.                                                                   | `["en"]`                                                                             |
| `frame`               | `Frame`    | An object containing the coordinates — position and size — that represent the bounding rectangle in the scanned image that contains the TextElement. | `{ x: 100, y: 100, width: 45, height: 100 }`                                         |
| `cornerPoints`        | `Point[]`  | An array of Point objects that define a closed shape within the scanned image that contains the TextElement.                                         | `[ { x: 100, y: 100 }, { x: 145, y: 100 }, { x: 145, y: 200 }, { x: 100, y: 200 } ]` |

## Frame

An object representing a bounding rectangle. When used in DocumentScanner, the Frame is the smallest that fully encloses a region of scanned text for a TextBlock, TextLine, or TextElement.

| Property Name | Type   | Description                                                                                                        | Example |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | ------- |
| `x`           | Number | The _X_ coordinate of the top-left of the rectangle, in pixels, within the coordinate system of the scanned image. | 100     |
| `y`           | Number | The _Y_ coordinate of the top-left of the rectangle, in pixels, within the coordinate system of the scanned image. | 100     |
| `width`       | Number | The width of the rectangle, in pixels.                                                                             | 650     |
| `height`      | Number | The height of the rectangle, in pixels.                                                                            | 200     |

## Point

An object representing a point in a coordinate system.

| Property Name | Type   | Description                      | Example |
| ------------- | ------ | -------------------------------- | ------- |
| `x`           | Number | The _X_ coordinate of the point. | 100     |
| `y`           | Number | The _Y_ coordinate of the point. | 100     |

## `DocumentScannerOptions`

An object containing configuration details for a document scanning session.

| Property Name             | Type                    | Description                                                                                                                                                                                                                  | Example                                                                    |
| ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `permissionRationaleText` | String                  | Optional, and only for Android implementations. The text shown in the UI when the device prompts the user to grant permission for your app to use the camera.                                                                | "Grant permission for [app name here] to use the camera to scan documents" |
| `imageSource`             | `DocumentScannerSource` | Optional. Specifies the source of the document to be scanned. Defaults to "DEVICE_CAMERA".                                                                                                                                   | "PHOTO_LIBRARY"                                                            |
| `scriptHint`              | `Script`                | Optional. Specifies the language writing system of the text to be scanned. Defaults to "LATIN".                                                                                                                              | "DEVANAGARI"                                                               |
| `returnImageBytes`        | Boolean                 | Optional. Specifies whether the image data should (`true`) or should not (`false`) be returned by the plugin. Defaults to `false`. This setting is overridden and set to `false` when `imageSource` is set to “INPUT_IMAGE”. | true                                                                       |
| `inputImageBytes`         | `String[]`              | Optional. A stringified array of base64 image data to be scanned. Used when `imageSource` is set to "INPUT_IMAGE".                                                                                                           | "2432BcYPJhSkzZjHS-Uiz1g8iZdQnRHtPnFKbMltJEc"                              |

## `DocumentScannerFailure`

An object representing an error that occurred when accessing DocumentScanner features.

| Property Name | Type                         | Description                                                                                                                                                                                                    |
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `DocumentScannerFailureCode` | A value representing the reason for a biometrics service error. See [DocumentScannerFailureCode](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-constants.md#documentscannerfailurecode) for the list of possible values. |
| `message`     | String                       | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.                                       |

**See Also**

- [DocumentScanner Constants](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-constants.md)

<!-- document id=d2304548592b1c550aa5a3cad00cc7cdf073a87acbca9616cfb69b01a1037e55 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-dom.md -->

# DOM Access Containment

A Lightning component can only traverse the DOM and access elements that it created. This behavior prevents the anti-pattern of reaching into DOM elements owned by other components.

**tip:** It’s an anti-pattern for any component to “reach into” another component, regardless of namespace, because it breaks encapsulation. Lightning Locker only prevents cross-namespace access. Your good judgment should prevent cross-component access within your own namespace as it makes components tightly coupled and more likely to break.

## DOM Access Containment with Lightning Web Components (LWC)

Lightning web components can’t use the `window` or `document` global properties to query for DOM elements when Lightning Locker is enabled. For example, use `this.template.querySelector()` instead of `document.querySelector()`. The `document.querySelector()` method isn’t supported for Shadow DOM.

**note:** If your org has [Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md) enabled instead of Lightning Locker, component access to the DOM is controlled by the browser through Shadow DOM, which is a web standard implemented in web browsers. Inside a component’s sandbox, LWS abides by the developer’s intent for the `shadowRoot`. An open mode `shadowRoot` allows JavaScript in the same sandbox to access and manipulate the Shadow DOM. A closed mode keeps internal elements inaccessible, even within the sandbox, preserving encapsulation. LWS makes `shadowRoot` appear closed to code running outside a component's sandbox. See [ShadowRoot.mode](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode) in MDN. Although we don’t recommend using `window` and `document` global properties directly, LWS permits access to those properties within an LWC component and its parent hierarchy.

## DOM Access Containment with Aura Components

Let’s look at a sample component that demonstrates DOM containment.

```
<!--c:domLocker-->
<aura:component>
    <div id="myDiv" aura:id="div1">
        <p>See how Lightning Locker restricts DOM access</p>
    </div>
    <lightning:button name="myButton" label="Peek in DOM"
                aura:id="button1" onclick="{!c.peekInDom}"/>
</aura:component>
```

The `c:domLocker` component creates a `<div>` element and a `lightning:button` component.

Here’s the client-side controller that peeks around in the DOM.

```javascript
({
  /* domLockerController.js */
  peekInDom: function (cmp, event, helper) {
    console.log("cmp.getElements(): ", cmp.getElements());
    // access the DOM in c:domLocker
    console.log("div1: ", cmp.find("div1").getElement());
    console.log("button1: ", cmp.find("button1"));
    console.log("button name: ", event.getSource().get("v.name"));

    // returns an error only with Locker, but not with Lightning Web Security
    //console.log("button1 element: ", cmp.find("button1").getElement());
  },
});
```

### Valid DOM Access

The following methods are valid DOM access because the elements are created by `c:domLocker`.

- `cmp.getElements()`
  :- Returns the elements in the DOM rendered by the component.
- `cmp.find()`
  :- Returns the div and button components, identified by their aura:id attributes.
- `cmp.find("div1").getElement()`
  :- Returns the DOM element for the div as c:domLocker created the div.
- `event.getSource().get("v.name")`
  :- Returns the name of the button that dispatched the event; in this case, myButton.

### Invalid DOM Access

You can’t use `cmp.find("button1").getElement()` to access the DOM element created by `lightning:button`. Lightning Locker doesn’t allow `c:domLocker` to access the DOM for `lightning:button` because the button is in the `lightning` namespace and `c:domLocker` is in the `c` namespace.

If you uncomment the code for `cmp.find("button1").getElement()`, you see an error:

```
c:domLocker$controller$peekInDom [cmp.find(...).getElement is not a function]
```

This code doesn’t return an error if your org has LWS enabled instead because cross-namespace component use is allowed with LWS. See [How Lightning Web Security Compares to Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md).

**See Also**

- [querySelector APIs Running with Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-queryselector.md)
- [_Lightning Web Components Developer Guide_: Access Elements the Component Owns](/docs/platform/lwc/guide/create-components-dom-work.html)
- [_Lightning Web Components Developer Guide_: Use Third-Party JavaScript Libraries](/docs/platform/lwc/guide/js-third-party-library.html)
- [_Lightning Aura Components Developer Guide_: Using JavaScript](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_intro.htm)

<!-- document id=82ffbe91cd7aa5be5ea14fac62fcbb1388696ab233e31e45be6173ec2f956a4e url=/developer/current/en-us/lwc/lwc/guides/testing/testing-dom-api.md -->

# DOM Inspection Tests Are Subject to Change

The content and structure of HTML, CSS, and the DOM in Lightning Experience can change at any time and can’t be considered a stable API. UI tests that use tools like Selenium WebDriver to reach into component internals require your ongoing maintenance.

Salesforce has never guaranteed backward-compatible HTML, CSS, or DOM. We’re calling out the fragility of these tests due to changes as Lightning Experience continues to evolve with modern web standards. We understand the value that you gain from automated UI testing, and the maintenance burden this puts on you.

Lightning web components are based on the Web Components standard. This standard includes [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md), which hides a component's markup, style, and behavior from other components. This encapsulation poses challenges for UI tests, especially tests that rely on globally searching the DOM or reaching into the internals of custom elements.

The `shadowRoot` property encapsulates an element's DOM subtree. This `shadowRoot` is represented as a `DocumentFragment` in the DOM. Elements inside this DOM subtree are not available by traditional DOM querying methods. Elements that are rendered by Lightning web components contain this new `shadowRoot` property, and these elements are hidden from normal DOM queries.

We recommend using Jest to unit test individual Lightning web components.

Use UI testing tools like Selenium WebDriver only for end-to-end testing.

## Jest Tests

To write unit tests for Lightning web components, use [sfdx-lwc-jest](https://developer.salesforce.com/docs/platform/lwc/guide/testing.md).

In a Jest test context, code can use the `shadowRoot` property of the element under test to access the shadow tree. The `shadowRoot` property encapsulates an element’s shadow tree.

This code accesses the `<div>` in the shadow tree of the `<lightning-lwc-parent>` component in the Example section.

```javascript
const element = createElement("c-lightning-lwc-parent", { is: LightningLwcParent });
document.body.appendChild(element);
const div = element.shadowRoot.querySelector(".in-the-shadow");
```

For more information, see [Write Jest Tests](https://developer.salesforce.com/docs/platform/lwc/guide/unit-testing-using-jest-create-tests.md).

## Selenium WebDriver Tests

For end-to-end UI tests, adapt your existing tests for Shadow DOM use. Adapting your tests varies by tool, and strategies are rapidly evolving.
To look for an element inside a Lightning web component’s shadow tree, execute JavaScript on the client to query off the component’s `shadowRoot` property. For more information, see [Selenium.dev: WebDriver](https://www.selenium.dev/documentation/webdriver/).

**note:** In Chrome or Firefox Developer Tools, you see a `#shadow-root` document fragment when inspecting the DOM. This document fragment is the top node of a component’s shadow tree. However, if you look at a Lightning web component in Chrome Developer Tools, you don’t see the `#shadow-root` because LWC uses a shadow DOM polyfill, also known as [synthetic shadow](https://developer.salesforce.com/docs/platform/lwc/create/create-dom-synthetic.md). Salesforce supports some browsers that don’t implement the Shadow DOM web standard. The polyfill provides a shadow DOM in these browsers. To find Lightning web components on the page, look for element names that contain a hyphen. Select the element and run `$0.shadowRoot` in the Console. A Lightning web component returns `#document-fragment`.

<!-- document id=aee44e44016c26f65c3de24807cee88752e9d76102972354f5da57f44928177b url=/developer/current/en-us/lwc/utam/guide/downloads.md -->

# Downloads

Install UTAM through the official registries for either Java (Maven) or JavaScript (npm).
This page lists the required dependencies to get started with UTAM.

## Test Author

As a test author, include these dependencies in your project:

- [`wdio-utam-service`](https://www.npmjs.com/package/wdio-utam-service) for JavaScript
- [`utam-core`](https://mvnrepository.com/artifact/com.salesforce.utam/utam-core) for Java

## Page Object Author

As a page object author, include these dependencies in your project:

- [`utam`](https://www.npmjs.com/package/utam) for JavaScript
- [`utam-compiler`](https://mvnrepository.com/artifact/com.salesforce.utam/utam-compiler) for Java

To learn more about configuring UTAM for your project, see the guide for [JavaScript](https://developer.salesforce.com/docs/platform/utam/guide/js-guide.md) or the guide for [Java](https://developer.salesforce.com/docs/platform/utam/guide/java-guide.md).

<!-- document id=283aa9288ee729a929543768a93d3190a5edc7079a71a5a6ed1e93d3c574a2ac url=/developer/current/en-us/lwc/utam/guide/draggable-actions.md -->

# Draggable actions

A draggable element can be selected by the user with a mouse, dragged to a droppable element, and dropped by releasing the mouse button.

## Draggable element declaration

A draggable element must include `draggable` in its `type` property. In this example, one element is just draggable, but usually an element is both clickable and draggable because a user needs to click before they can drag.

```json
{
  "elements": [
    {
      "name": "onlyDraggable",
      "type": ["draggable"],
      "selector": {
        "css": ".drag-me"
      },
      "public": true
    },
    {
      "name": "myDraggable",
      "type": ["clickable", "draggable"],
      "selector": {
        "css": ".drag-me-too"
      },
      "public": true
    }
  ]
}
```

## DragAndDrop API

The `draggable` type exposes the following API for an element:

- `dragAndDrop(target: Element, hold: number)` clicks and drags an element to the location of the target element, then drops. The target element is provided as a parameter and doesn't have to be draggable.

A second optional parameter defines a hold duration in seconds that is applied after the click and before the drag. This hold duration can be useful to simulate a real user in some cases.

Usage in a JavaScript test:

```js
const source = await pageObject.getMyDraggable();
const target = await pageObject.getDropTarget();
// drag and drop without hold
await source.dragAndDrop(target);
```

Usage in a Java test:

```java
Draggable source = pageObject.getMyDraggable();
BasicElement target = pageObject.getDropTarget();
// drag and drop with 3 sec hold
source.dragAndDrop(target, 3);
```

- `dragAndDropByOffset(xOffset: number, yOffset: number, hold: number)` drops an element using coordinates relative to the current location of the element. It has an optional parameter for hold duration in seconds.

Usage in a JavaScript test:

```js
const source = await pageObject.getMyDraggable();
// drag and drop with 3 sec hold
await source.dragAndDropByOffset(100, 100, 3);
```

Usage in a Java test:

```java
Draggable source = pageObject.getMyDraggable();
// drag and drop without hold
source.dragAndDropByOffset(100, 100);
```

## Compose dragAndDrop

It's a good practice to compose a UI interaction as a public method inside a page object. Here are some examples of how to compose `dragAndDrop` and `dragAndDropByOffset` and how to provide a target element as a parameter.

### Drop at a known target element

The most common use case is to drop an element at a known target element location.
To do that, we pass `elementReference` to a known element as an argument:

```json
{
  "elements": [
    {
      "name": "myDraggable",
      "type": ["draggable"],
      "selector": { "css": ".foo" }
    },
    {
      "name": "dropTarget",
      "selector": { "css": ".moo" }
    }
  ],
  "methods": [
    {
      "name": "dragAndDropAtTarget",
      "compose": [
        {
          "element": "myDraggable",
          "apply": "dragAndDrop",
          "args": [
            {
              "type": "elementReference",
              "value": "dropTarget"
            }
          ]
        }
      ]
    }
  ]
}
```

The generated method declarations have no parameters because the target element is referenced inside the statement of the `dragAndDropAtTarget` method.

Generated JavaScript method declaration:

```js
dragAndDropAtTarget(): Promise<unknown>;
```

Generated Java method declaration:

```java
public void dragAndDropAtTarget();
```

### Drop at a known target element with hardcoded arguments

It's possible that the target element needs arguments for the selector or filter. Those arguments can be hardcoded in a compose statement. This example passes a hardcoded `myClass` value to the `dropTarget` in the `dragAndDropAtTarget` method.

```json
{
  "elements": [
    {
      "name": "myDraggable",
      "type": ["draggable"],
      "selector": { "css": ".foo" }
    },
    {
      "name": "dropTarget",
      "selector": {
        "css": "target[class='%s']",
        "args": [
          {
            "name": "classStr",
            "type": "string"
          }
        ]
      }
    }
  ],
  "methods": [
    {
      "name": "dragAndDropAtTarget",
      "compose": [
        {
          "element": "myDraggable",
          "apply": "dragAndDrop",
          "args": [
            {
              "type": "elementReference",
              "value": "dropTarget",
              "args": [{ "value": "myClass" }]
            }
          ]
        }
      ]
    }
  ]
}
```

If we omitted the `"value" : "myClass"` hardcoded value for the `dropTarget` element, it would be inferred and added to the method parameters.

JavaScript example:

```js
dragAndDropAtTarget(classStr: string): Promise<unknown>;
```

Java example:

```java
public void dragAndDropAtTarget(String classStr);
```

## Drop by offset inside a frame

It's always more reliable to `dragAndDrop` with a target element as shown in the previous section. However, that's not possible if the target element is inside a frame. Here's an example for Java:

```java
// get source element coordinates
ElementRectangle source = sourceElement.getRect();

// enter frame and get target coordinates
MyPageObject targetPageObjectInsideFrame = utam.enterFrameAndLoad(frameElement, MyPageObject.class);
ElementRectangle target = targetPageObjectInsideFrame.getTargetElement().getRect();
utam.exitFrame();

// offset is a difference between element centers
int xOffset = (target.getX() + target.getWidth()/2) - (source.getX() + source.getWidth()/2);
int yOffset = (target.getY() + target.getHeight()/2) - (source.getY() + source.getHeight()/2);

// drag and drop with a 5 second pause
source.dragAndDropByOffset(xOffset, yOffset, 5);
```

We don't show JavaScript code here but it's similar and uses the same methods.

<!-- document id=ea7dfc777aa41e126e01594c16c4260bfe4f043bc5227841cd1bd3830fe16497 url=/developer/current/en-us/lwc/lwc/guides/events/events-dynamic-considerations.md -->

# Dynamic Event Listeners Considerations

Consider these guidelines when using `lwc:on`.

- Mutating the object referenced by the variable that's passed to `lwc:on` is not allowed. To modify a property on the object, pass a new object instead. Reusing the same object with modified properties throws an error.
- Reassigning the variable that's passed to `lwc:on` to a new object is allowed.
  - If a property was in the previous object but ommited in the new object, then the corresponding event listener is removed.
  - If a property was not in the previous object but present in the new object, then the corresponding event listener is added.
  - If a property is present in both objects, then the corresponding event listener is updated.
- We recommend that you use the `lwc:on` directive instead of `lwc:spread` for dynamically adding event listeners.
- Using `lwc:on` and an `onevent` listener for the same event type in the HTML template throws an error.
- Using both `lwc:on` and `lwc:spread` to specify listeners for the same event type results in both event listeners getting added to the element.

To set properties and attach event listeners based on which component is dynamically loaded, use these template directives on your component.

- Load components dynamically using `lwc:component` and `lwc:is`
- Specify which properties to pass using `lwc:spread`
- Specify which event listeners to attach to the components using `lwc:on`

**See Also**

- [Attach Event Listeners Declaratively and Dynamically](https://developer.salesforce.com/docs/platform/lwc/guide/events-handling.md#attach-event-listeners-declaratively-and-dynamically)
- [Attach Event Listeners and Pass Properties to Dynamic Components](https://developer.salesforce.com/docs/platform/lwc/js/js-dynamic-components.md)

<!-- document id=72a69aa684c2998caba9a2eba6425912611c3283306f482f6328162e39d1d3af url=/developer/current/en-us/lwc/lwc/guides/js/js-dynamic-components.md -->

# Dynamically Instantiate Components

Dynamic component instantiation can help you to avoid loading large modules that you don’t always need. Also, you can instantiate a component instance when the underlying component constructor isn’t known until runtime. Dynamic import is a convenient solution to make a component more customizable. However, it isn’t always the best solution because of the runtime performance overhead it introduces, so don’t overuse it.

::video{src="https://youtube.com/embed/df7P22seEL8" title="How to Work with Dynamic Lightning Web Components" type="youtube" }

## Environment Setup and Caching

Before developing with dynamic components, ensure that your org is configured to immediately reflect your code changes.

1. **Enable Lightning Web Security**. To dynamically import and instantiate Lightning web components, you must [enable Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-enable.html).
2. **Disable persistent caching**. To avoid issues where dynamic imports fail to update during development, navigate to **Setup > Session Settings** and uncheck **Enable secure and persistent browser caching to improve performance**. You should re-enable this feature in production for optimal performance.

## Configure the Dynamic Component Capability

To instantiate a dynamic component, a component's configuration file must include the `lightning__dynamicComponent` capability. For example:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>59.0</apiVersion>
  <capabilities>
    <capability>lightning__dynamicComponent</capability>
  </capabilities>
</LightningComponentBundle>
```

To use this capability, you must set the `apiVersion` property to 55.0 or later.

For more information on a component's configuration file, see [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md).

## Dynamic Component Syntax

To instantiate a component dynamically, use the `<lwc:component>` managed element with the `lwc:is` directive in a component's HTML file. When building component names dynamically, make sure that you include the namespace. The syntax for the component name is `c/componentName`, where `c` is the default namespace.

Here's an HTML template that uses `<lwc:component>`.

<!-- prettier-ignore -->
```html
<template>
    <div class="container">
        <lwc:component lwc:is={componentConstructor}></lwc:component>
    </div>
</template>
```

`<lwc:component>` serves as a placeholder in the DOM that renders the specified dynamic component. You must use `<lwc:component>` with the `lwc:is` directive.

The `lwc:is` directive provides an imported constructor at runtime to the `<lwc:component>` managed element. `lwc:is` accepts an expression that resolves to a `LightningElement` constructor at runtime.

If the constructor is [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), the `<lwc:component>` tag along with all of its children aren't rendered.

If the expression value is defined but not a `LightningElement` constructor, an error is thrown.

In the component's JavaScript file, import the custom element using the [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) dynamic import syntax.

```javascript
import { LightningElement } from "lwc";
export default class extends LightningElement {
  componentConstructor;
  // Use connectedCallback() on the dynamic component
  // to signal when it's attached to the DOM
  connectedCallback() {
    import("c/concreteComponent")
      .then(({ default: ctor }) => (this.componentConstructor = ctor))
      .catch((err) => console.log("Error importing component"));
  }
}
```

The `import()` call returns a promise that resolves to a `LightningElement` constructor. The element is then rendered instead of the `lwc:component` placeholder. The tag name used for the dynamic component is the value that's returned for the given constructor.

Similar to a regular component, the dynamic component is instantiated and attached to the DOM. If the dynamic component's constructor changes, the existing element is removed from the DOM.

In this example, the following HTML is rendered after the import completes.

```html
<div class="container">
  <c-concrete-component></c-concrete-component>
</div>
```

Instead of using the [`then()` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then), you can use the operators `async/await` with `try/catch` to return the component constructor and handle network failures or invalid metadata. Because `connectedCallback()` is synchronous, call the async helper from `connectedCallback()` instead of marking the callback itself as `async`. For details, see [Don't mark lifecycle hooks as `async`](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-dom.md).

```javascript
import { LightningElement } from "lwc";
export default class App extends LightningElement {
  componentConstructor;
  connectedCallback() {
    this.loadComponent();
  }
  async loadComponent() {
    try {
      const { default: ctor } = await import("c/myComponent");
      this.componentConstructor = ctor;
    } catch (err) {
      console.error("Error importing component", err);
    }
  }
}
```

## Select a Dynamic Component

A custom element must be attached to the DOM before you can select it. To select a dynamic component, use the `lwc:ref` directive or use an attribute that's assigned to the component, such as a class name.

<!-- prettier-ignore -->
```html
<template>
    <lwc:component lwc:is={componentConstructor}
                   lwc:ref="myCmp">
    </lwc:component>
</template>
```

To identify if a dynamic component is attached to the DOM:

- Use `connectedCallback` in the dynamic component to signal when it's attached to the DOM.
- Use `renderedCallback` on the parent component to detect when the dynamic component has rendered to the DOM.

```javascript
import { LightningElement } from "lwc";
export default class extends LightningElement {
  componentConstructor;

  connectedCallback() {
    import("lightning/concreteComponent")
      .then(({ default: ctor }) => (this.componentConstructor = ctor))
      .catch((err) => console.log("Error importing component"));
  }

  renderedCallback() {
    // this.refs.myCmp will be available on the next rendering cycle after the constructor is set
    if (this.refs.myCmp) {
      // this.refs.myCmp will contain a reference to the DOM node
      console.log(this.refs.myCmp);
    }
  }
}
```

In Jest tests, the component's tag name for a dynamic component is an internal default value. To select the dynamic component in a Jest test, we recommend that you use a different selector by appending a [custom data attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*).

<!-- prettier-ignore -->
```html
<lwc:component
    lwc:is={componentConstructor}
    contact={contact}
    data-id-dynamic-cmp="c-dynamic-component"
></lwc:component>
```

In the Jest test, select the component using this syntax.

```javascript
const dynamicCmpEl = element.shadowRoot.querySelector(
  '[data-id-dynamic-cmp="c-dynamic-component"]',
);
```

For more information, see [Write Jest Tests for Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md).

## Assign Attributes and Template Directives

All supported HTML attributes that can be applied to an `HTMLElement` can also be applied to `lwc:component`.

Some examples include:

- Standard [global HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes)
- Custom HTML attributes, such as `data-*`
- Event listeners

Dynamic components behave like standard Lightning web components. `lwc:component` supports [the directives for HTML elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md), except for `lwc:external`.

## Dynamic Component's Children Elements

You can include child elements on the dynamic component. `<lwc:component>` first renders the dynamic component and then its children. Each time the dynamic component changes, the existing element is removed from the DOM along with all of its children. The new dynamic component is then rendered along with its children.

<!-- prettier-ignore -->
```html
<template>
    <lwc:component lwc:is={ctor}>
        <span>child</span>
    </lwc:component>
</template>
```

## Pass Properties in Markup

Passing a property to a dynamic component is similar to [passing a property to a child component](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md). In the dynamic component, annotate the property with `@api` and use it in the template.

```javascript
// dynamicCmp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  @api text;
}
```

In the placeholder component, import your custom element.

```javascript
// myApp.js
import { LightningElement } from "lwc";
import DynamicCmp from "c/dynamicCmp";

export default class extends LightningElement {
  componentConstructor = DynamicCmp;
}
```

Pass in the value for the `text` property.

<!-- prettier-ignore -->
```html
<!-- myApp.html -->
<template>
  <lwc:component lwc:is={componentConstructor} text="I love dynamic components!"></lwc:component>
</template>
```

In certain cases, it might not be possible to set all the potential properties a dynamic component can accept via the standard markup syntax. For example, when the component to be instantiated isn't known in advance, or the components to be instantiated accept a different set of public properties.

In those specific cases, the [`lwc:spread` directive](https://developer.salesforce.com/docs/platform/lwc/create/create-components-spread-properties.md) can be used to dynamically set to dynamic component properties at runtime. `lwc:spread` also enables elements to accept an object that's bound as properties at runtime.

Make the properties public by annotating them with `@api`.

```javascript
// dynamicCmp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  @api city;
  @api state;
}
```

Use the properties in your template.

```html
<!-- dynamicCmp.html -->
<template>
  <p>{city}, {state}</p>
</template>
```

Import your custom element as usual, and create a `childProps` object with the property name and values.

```javascript
// myApp.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  componentConstructor;
  childProps = { city: "San Francisco", state: "CA" };

  connectedCallback() {
    // import your custom element
  }
}
```

Use `lwc:spread` to pass in your properties, which then renders "San Francisco, CA" on the dynamic component.

<!-- prettier-ignore-->
```html
<!-- myApp.html-->
<template>
  <lwc:component lwc:is={componentConstructor} lwc:spread={childProps}></lwc:component>
</template>
```

## Attach Event Listeners and Pass Properties to Dynamic Components

In most cases, you want to set the properties and attach the event listeners based on which component is dynamically loaded. By using `lwc:component` with `lwc:is`, you can load components dynamically. Additionally, use the `lwc:spread` directive to set which properties to pass. Use `lwc:on` to dynamically set which event listeners to attach to the components.

The example shows how you can use all four directives to load components dynamically while passing properties to them and attaching event handlers for them.

The example includes 3 components

- `dynamic`: Loads either `childA` or `childB` dynamically
- `childA` : Dispatches the `customEventA` event with data
- `childB` : Dispatches the `customEventB` event with data

The `dynamic` component defines the properties and an event handler, passing it to the `childA` and `childB` components.

<!-- prettier-ignore -->
```html
<!-- dynamic -->
<template>
  <lightning-button onclick={switchComponent} label="Switch Component"> </lightning-button>

  <!-- Dynamically loads childA or childB -->
  <lwc:component lwc:is={dynamicCtor} lwc:spread={childProps} lwc:on={eventHandlers}>
  </lwc:component>

  <!-- Displays the event detail from childA or childB -->
  <p>Custom event received: {customEvent}</p>
</template>
```

When the button on `dynamic` is clicked, it creates either the `childA` or `childB` component dynamically with the passed in properties and event handler.

```javascript
// dynamic.js
import { LightningElement } from "lwc";
import ChildA from "c/childA";
import ChildB from "c/childB";

export default class DynamicComponent extends LightningElement {
  customEvent = "";
  dynamicCtor = ChildA; // Start with ChildA

  get childProps() {
    return this.dynamicCtor === ChildA
      ? { name: "Child A Name", age: 30 }
      : { name: "Child B Name", age: 5 };
  }

  get eventHandlers() {
    return this.dynamicCtor === ChildA
      ? { customEventA: this.handleCustomEventA }
      : { customEventB: this.handleCustomEventB };
  }

  handleCustomEventA(event) {
    this.customEvent = `Hello from ${event.detail}`;
  }

  handleCustomEventB(event) {
    this.customEvent = `Hello from ${event.detail}`;
  }

  switchComponent() {
    this.dynamicCtor = this.dynamicCtor === ChildA ? ChildB : ChildA;
  }
}
```

`childA` and `childB` are similar components that differ only for the custom events they dispatch.

```html
<!-- childA -->
<template>
  <div>Child A Component</div>
  <p>Name: {name}</p>
  <p>Age: {age}</p>
</template>
```

When you click the **Switch Component** button, the custom event on `childA` or `childB` is dispatched, depending on which child component is loaded.

```javascript
import { LightningElement, api } from "lwc";

export default class ChildA extends LightningElement {
  @api name;
  @api age;

  connectedCallback() {
    this.dispatchEvent(new CustomEvent("customEventA", { detail: "Child A" }));
  }
}
```

## Pass Record ID to a Dynamic Component

A dynamic component can load data based on [record context](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md). To retrieve the record ID on a page, pass the record ID value to the dynamic component. Passing the record ID to a dynamic component is similar to [passing a property to a child component](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md).

<!-- prettier-ignore -->
```html
<!-- myApp.html -->
<template>
    <lwc:component record-id={recordId} lwc:is={componentConstructor} > </lwc:component>
</template>
```

Retrieve the component module at runtime.

```javascript
// myApp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  componentConstructor;
  @api recordId;

  connectedCallback() {
    this.loadComponent();
  }

  async loadComponent() {
    const { default: ctor } = await import("c/myComponent");
    this.componentConstructor = ctor;
  }
}
```

The record ID is passed to the dynamic component and you can use it to retrieve record data based on the ID.

## Attach Event Listeners with Dynamic Component Loading

To dynamically load components and attach event listeners to them, use [`lwc:on`](https://developer.salesforce.com/docs/platform/lwc/events/events-handling.md) with `lwc:component`. The `lwc:component` element works together with the `lwc:is` directive to load a child component dynamically.

<!-- prettier-ignore -->
```html
<template>
  <lwc:component lwc:is={childComponent} lwc:on={eventHandlers}></lwc:component>
</template>
```

Define your event handlers for the child component.

```javascript
import { LightningElement } from "lwc";
import ChildComponent from "c/childComponent";

export default class ParentComponent extends LightningElement {
  childComponent = ChildComponent;

  eventHandlers = {
    customEvent: this.handleCustomEvent,
  };

  handleCustomEvent(event) {
    console.log("Custom event received:", event.detail);
  }
}
```

The child component contains a button that dispatches the custom event when clicked.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button onclick={dispatchCustomEvent} label="Click Me"> </lightning-button>
</template>
```

Dispatch the custom event in the child component, which is then handled by the parent component.

```javascript
import { LightningElement } from "lwc";

export default class ChildComponent extends LightningElement {
  dispatchCustomEvent() {
    const event = new CustomEvent("customEvent", {
      detail: { message: "Hello from Child Component!" },
    });
    this.dispatchEvent(event);
  }
}
```

## Dynamic Components in Packages

You can use dynamic components in managed packages only. Dynamic components in unlocked packages aren't supported.

## Performance Considerations

Since dynamic imports are “dynamic” by nature, the framework doesn’t prefetch those modules in advance, which can sometimes be detrimental to user experience.

When you use a static import statement, the framework delivers the component and all its dependencies in a single JavaScript file at runtime. To fetch a component that is dynamically imported, the framework has to do a network roundtrip if the content isn’t already stored in the browser HTTP cache.

In this example, the `BundleExample` component class is served with the `StaticImport` component class to the browser as a single JavaScript module. The `DynamicImport` component class is retrieved at runtime when the `loadModule` function is invoked.

```javascript
import { LightningElement } from "lwc";
import StaticImport from "c/static-import";

export default class BundleExample extends LightningElement {
  async loadModule() {
    const { default: DynamicImport } = await import("c/dynamic-import");
    return DynamicImport;
  }
}
```

Consider these recommendations when working with dynamic components.

### Make the dynamic imports statically analyzable

While not currently implemented, future framework optimizations can optimize code where dynamic imports are statically analyzable. Pass a JavaScript string literal to the `import()` function:

```javascript
import("c/analyzable"); // 👍: Statically analyzable
import("c/" + "analyzable"); // 👎: Not statically analyzable
import("c/" + componentName); // 👎: Not statically analyzable
```

There are always cases where dynamic imports can’t be statically analyzed. This scenario is especially true when the component name is defined via metadata. For all other cases, we strongly recommend making all your dynamic imports statically analyzable to avail of future framework optimizations.

### Don’t overuse dynamic imports

Dynamic import is a convenient solution to make a component more customizable. However, it isn’t always the best solution because of the runtime performance overhead it introduces. Let's illustrate the potential pitfalls with some examples.

In this first example, we create a chart component, `c/chart`. It accepts chart type as a public property that can be set to either be bar, pie, or line. Internally, the component uses one of the c/barChart, c/pieChart, or c/lineChart components to render the chart based on the type.

```javascript
// 👎 DON'T USE THIS
// Example with non statically analyzable dynamic import:
import { LightningElement, api } from "lwc";

const KNOWN_TYPE = new Set(["bar", "pie", "line"]);

export default class App extends LightningElement {
  chartCtor;

  _type = "line";

  @api
  get type() {
    return this._type;
  }
  set type(val) {
    if (!KNOWN_TYPE.has(val)) {
      console.warn(`Unknown chart type: ${val}`);
    }

    this._type = val;

    const chartComponentName = `c/${val}Chart`;
    import(chartComponentName).then(({ default: ChartCtor }) => {
      this.chartCtor = ChartCtor;
    });
  }
}
```

If the total bundle size of `c/barChart`, `c/pieChart`, and `c/lineChart` is small, it's preferable to update the `c/chart` component to use static imports to avoid the network roundtrip at runtime. Generally, we recommend that you start with static import and use dynamic import if performance becomes an issue due to import of components that aren't strictly needed.

```javascript
// 👍 USE THIS
// Example with static imports:
import { LightningElement, api } from "lwc";

import BarChart from "c/barChart";
import PieChart from "c/pieChart";
import LineChart from "c/lineChart";

const KNOWN_TYPE = new Set(["bar", "pie", "line"]);
const CHART_MAPPING = {
  bar: BarChart,
  pie: PieChart,
  line: LineChart,
};

export default class App extends LightningElement {
  chartCtor;

  _type = "line";

  @api
  get type() {
    return this._type;
  }
  set type(val) {
    if (!KNOWN_TYPE.has(val)) {
      console.warn(`Unknown chart type: ${val}`);
    }

    this._type = val;
    this.chartCtor = CHART_MAPPING[val];
  }
}
```

If statically importing all three modules negatively impacts runtime performance due to the bundle size increase, it’s still possible to update the example to turn the non-statically analyzable dynamic import into a statically analyzable one.

```javascript
// 👍 USE THIS
// Example with statically analyzable dynamic import:
import { LightningElement, api } from "lwc";

const KNOWN_TYPE = new Set(["bar", "pie", "line"]);
const CHART_MAPPING = {
  bar: () => import("c/barChart"),
  pie: () => import("c/pieChart"),
  line: () => import("c/lineChart"),
};

export default class App extends LightningElement {
  chartCtor;

  _type = "line";

  @api
  get type() {
    return this._type;
  }
  set type(val) {
    if (!KNOWN_TYPE.has(val)) {
      console.warn(`Unknown chart type: ${val}`);
    }

    this._type = val;
    CHART_MAPPING[val]().then(({ default: ChartCtor }) => {
      this.chartCtor = ChartCtor;
    });
  }
}
```

Here's another example illustrating this principle. In the example, we create a `c/field` component that is in charge of rendering an entity field value. Since it's a generic component, it accepts a renderer public property that is the name of the component to use to render this field. Unlike in the previous example, the list of known renderers isn’t known in advance because the `c/field` component potentially accepts any component name.

```javascript
// 👎 DON'T USE THIS
// Example with component name as prop:
import { LightningElement, api } from "lwc";

export default class Field extends LightningElement {
  rendererCtor;

  _renderer;

  @api
  get renderer() {
    return this._renderer;
  }
  set renderer(val) {
    this._renderer = val;

    import(val).then(({ default: rendererCtor }) => {
      this.rendererCtor = rendererCtor;
    });
  }
}
```

A more performant approach would be for the `c/field` component to accept the renderer constructor as a public property instead of the renderer component name. This only works if the component isn’t exposed to a builder, such as the Lightning App Builder.

```javascript
// 👍 USE THIS
// Example with component constructor as prop:
import { LightningElement, api } from "lwc";

export default class Field extends LightningElement {
  @api rendererCtor;
}
```

In this alternative design, the field component delegates to its parent the loading of the renderer component class. The parent component can now use either a static or a dynamic import depending on its requirements.

### Use String Interpolation

If you must drive the UI from Custom Metadata or Apex where the component name is only known at runtime, use string interpolation with backticks. Note that you must explicitly include the namespace (for example, `c/`) within the import string.

```
import(`c/${this.metaDataValue}`)
```

Interpolated strings can’t be evaluated during the build process, which prevents the framework from pre-bundling your dependencies. This adds unnecessary runtime overhead. Stick to static mapping unless you absolutely need dynamic values.

## Tooling and Debugging

To confirm that a dynamic component has been swapped (and not just hidden), use your browser developer tools to inspect the DOM. The custom element tag should be removed and replaced when the `componentConstructor` changes.

**See Also**

- [_Security for Lightning Components_: Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-intro.html)
- [_Salesforce Developers' Blog_: Dynamic Components for Lightning Web Components Is Now GA](https://developer.salesforce.com/blogs/2023/10/dynamic-components-for-lightning-web-components-is-now-ga)

<!-- document id=7a16597c56ace9e2170b37e7ed1ba10bc8540424cde0b2cb0008d722131078df url=/developer/current/en-us/lwc/lwc/guides/data/data-edit-record.md -->

# Edit a Record

The simplest way to create a form that enables you to edit a record is to use `lightning-record-form`. To customize the form layout or preload custom values, use `lightning-record-edit-form`.

**tip:** If you need more flexibility than these components provide, see [Build Custom UI to Create and Edit Records](https://developer.salesforce.com/docs/platform/lwc/data/data-salesforce-write.md).

## Edit a Record with Fields from a Layout Using `lightning-record-form`

To edit a record, use the `record-id` and `object-api-name` attributes. When you provide a record ID, the component uses view mode by default, which displays output fields with edit icons. If you click an edit icon, all updateable fields in the form become editable. The editable form displays a Save button that updates the record, and a Cancel button that reverts changes.

The component provides default submit and error handlers. Errors are automatically displayed at the top of the form.

This example creates a form that lets users update fields from the compact layout on an account record. It displays the fields in a two-column layout.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-form
    record-id={recordId}
    object-api-name={objectApiName}
    columns="2"
    mode="edit"
    layout-type="Compact"
  >
  </lightning-record-form>
</template>
```

**note:** To improve performance, specify fields instead of a layout whenever possible. Specify a layout only when you want the administrator, not the component, to control the fields that are provisioned. The component must handle receiving every field that is assigned to the layout for the context user.

Place this example on a record page to inherit its `record-id` and `object-api-name` properties.

```javascript
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  @api recordId;
  @api objectApiName;
}
```

You can override the default form behavior using custom events, such as displaying a toast when the submission succeeds or fails. For more information, see the [`lightning-record-form` reference documentation.](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-form)

## Edit a Record with Specific Fields Using `lightning-record-form`

You can specify which fields appear on the editable form, either by providing an array of field names or importing references to the fields.

**note:** Passing in the object and fields using strings doesn’t provide compile-time validation. You don’t know if the fields are valid until runtime. We recommend importing references to objects and fields from `@salesforce/schema`.

This example uses the `recordFormStaticContact` component in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. It displays an editable form for a record using a static schema definition.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-form
    object-api-name={objectApiName}
    record-id={recordId}
    fields={fields}
  ></lightning-record-form>
</template>
```

Import the field references in your JavaScript file.

```javascript
import { LightningElement, api } from "lwc";

import ACCOUNT_FIELD from "@salesforce/schema/Contact.AccountId";
import NAME_FIELD from "@salesforce/schema/Contact.Name";
import TITLE_FIELD from "@salesforce/schema/Contact.Title";
import PHONE_FIELD from "@salesforce/schema/Contact.Phone";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";

export default class RecordFormStaticContact extends LightningElement {
  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;

  fields = [ACCOUNT_FIELD, NAME_FIELD, TITLE_FIELD, PHONE_FIELD, EMAIL_FIELD];
}
```

## Edit a Record with a Custom Layout Using `lightning-record-edit-form`

To provide a custom layout for your form fields, use the `lightning-record-edit-form` component. Pass in the fields to `lightning-input-field`, which displays an input control based on the record field type. This example displays several fields using a custom layout. Add this example component to a contact record page to inherit its `record-id` and `object-api-name` properties.

```html
<template>
  <lightning-record-edit-form object-api-name="{objectApiName}" record-id="{recordId}">
    <lightning-messages></lightning-messages>
    <div class="slds-grid">
      <div class="slds-col slds-size_1-of-2">
        <lightning-input-field field-name="Name"></lightning-input-field>
        <lightning-input-field field-name="Title"></lightning-input-field>
      </div>
      <div class="slds-col slds-size_1-of-2">
        <lightning-input-field field-name="Phone"></lightning-input-field>
        <lightning-input-field field-name="Email"></lightning-input-field>
      </div>
    </div>
    <div class="slds-m-top_medium">
      <lightning-button type="submit" variant="brand" label="Edit Contact"></lightning-button>
    </div>
  </lightning-record-edit-form>
</template>
```

`lightning-record-edit-form` handles form submission and errors automatically. To display an error message above or below the form fields automatically, include `lightning-messages` before or after your `lightning-input-field` components.

## Reset the Form to the Original Field Values

`lightning-record-edit-form` doesn’t provide its own **Cancel** and **Save** buttons like `lightning-record-form` does. To create your own **Cancel** button that reverts the field values, include a `lightning-button` component that calls the `reset()` method. Replace the `record-id` with your own, or place this example on a contact record page to inherit its `record-id` property.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-edit-form record-id={recordId} object-api-name="Contact">
    <lightning-messages></lightning-messages>
    <lightning-input-field field-name="FirstName"></lightning-input-field>
    <lightning-input-field field-name="LastName"></lightning-input-field>
    <lightning-input-field field-name="Email"></lightning-input-field>
    <lightning-input-field field-name="Phone"></lightning-input-field>
    <div class="slds-align_absolute-center slds-p-around_medium">
      <lightning-button
        class="slds-m-around_xx-small"
        label="Cancel"
        onclick={handleReset}
      ></lightning-button>
      <lightning-button
        class="slds-m-around_xx-small"
        label="Create Contact"
        type="submit"
        variant="brand"
      ></lightning-button>
    </div>
  </lightning-record-edit-form>
</template>
```

Call the `reset()` method on the `lightning-input-field` component.

```javascript
import { LightningElement, api } from "lwc";

export default class FormResetExample extends LightningElement {
  @api recordId;

  handleReset(event) {
    const inputFields = this.template.querySelectorAll("lightning-input-field");
    if (inputFields) {
      inputFields.forEach((field) => {
        field.reset();
      });
    }
  }
}
```

## Override Default Behaviors Using Custom Events

`lightning-record-edit-form` handles form submission and errors automatically. To display an error message above or below the form fields automatically, include `lightning-messages` before or after your `lightning-input-field` components.

`lightning-record-edit-form` enables you to handle the following custom events.

- `error`—Fired when the form returns a server-side error.
- `load`—Fired when the form loads record data.
- `submit`—Fired when the form is submitted.
- `success`—Fired when the form data saves successfully.

This example displays a toast when an error occurs on form submission. Common errors include no network access or a required field is missing from the form. Use your own record ID or place the example on a contact record page to inherit its record ID.

<!-- prettier-ignore -->
```html
<template>
  <lightning-record-edit-form
    record-id={recordId}
    object-api-name="Contact"
    onerror={handleError}
  >
    <!--lightning-messages not needed here
                since we’re displaying a toast with the error message -->
    <!--<lightning-messages></lightning-messages>-->
    <lightning-input-field field-name="FirstName"></lightning-input-field>
    <lightning-input-field field-name="LastName"></lightning-input-field>
    <lightning-input-field field-name="Email"></lightning-input-field>
    <lightning-input-field field-name="Phone"></lightning-input-field>
    <lightning-button type="submit" variant="brand" label="Create Contact"></lightning-button>
  </lightning-record-edit-form>
</template>
```

To display a toast, import the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class FormErrorExample extends LightningElement {
  @api recordId;

  handleError(event) {
    console.log(event.detail);
    this.dispatchEvent(
      new ShowToastEvent({
        title: "Error creating record",
        message: event.detail.message,
        variant: "error",
      }),
    );
  }
}
```

`event.detail.message` returns a general description of the error. To return field-specific errors such as an error from a validation rule, use `event.detail.output.fieldErrors`, which provides a list of fields and [record exception errors](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_exception_error.htm).

Let’s say you encounter validation rule errors in the `FirstName`, `LastName`, and `Email` fields, `event.detail.output.fieldErrors` can return something like this.

```javascript
{
  "Email": [
    {
      "constituentField": null,
      "duplicateRecordError": null,
      "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
      "field": "Email",
      "fieldLabel": "Email",
      "message": "Enter a Salesforce email"
    }
  ],
  "Name": [
    {
      "constituentField": "FirstName",
      "duplicateRecordError": null,
      "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
      "field": "Name",
      "fieldLabel": "First Name",
      "message": "Your first name should contain at least 2 characters"
    },
    {
      "constituentField": "LastName",
      "duplicateRecordError": null,
      "errorCode": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
      "field": "Name",
      "fieldLabel": "Last Name",
      "message": "Your last name should contain at least 2 characters"
    }
  ]
}
```

For more information, see the [`lightning-record-edit-form` reference documentation.](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-record-edit-form)

## Edit a Record with Custom Validation Using `lightning-record-edit-form`

We recommend that you create validation rule errors to enforce field validation using `lightning-input-field` nested in `lightning-record-edit-form`, as discussed in **Override Default Behaviors Using Custom Events**.

`lightning-input-field` doesn’t support client-side custom validation. If you want to implement your own client-side validation, consider using `lightning-input` nested in `lightning-record-edit-form` instead.

Place this example on an account record page. This example wires up a `lightning-input` component to the Name field for editing.

<!-- prettier-ignore -->
```html
<!-- recordEditFormStaticAccount.html -->
<template lwc:if={account.data}>
  <lightning-record-edit-form
    object-api-name={objectApiName}
    record-id={recordId}
    onsubmit={handleSubmit}
  >
    <lightning-input
      label="Name"
      value={name}
      onchange={handleChange}
      class="slds-m-bottom_x-small"
    ></lightning-input>

    <lightning-button class="slds-m-top_small" type="submit" label="Update Account Name">
    </lightning-button>
  </lightning-record-edit-form>
</template>
```

Wire up the `lightning-input` component to the Salesforce field using the `getRecord` wire adapter and provide your own label. The wiring is done automatically when you use `lightning-input-field`, but not when you use `lightning-input`. Submit the record data using the `onsubmit` event handler on `lightning-record-edit-form`. In the event handler, perform the validation check using `setCustomValidity()` and update the fields with the user input value.

```javascript
// recordEditFormStaticAccount.js
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

const FIELDS = ["Account.Name"];

export default class RecordEditFormStaticAccount extends LightningElement {
  @api recordId;
  @api objectApiName;
  inputVal = "";

  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  account;

  get name() {
    return this.account.data.fields.Name.value;
  }

  handleChange(event) {
    this.inputVal = event.target.value;
  }

  handleSubmit(event) {
    event.preventDefault();
    const inputCmp = this.template.querySelector("lightning-input");
    const value = inputCmp.value;
    // perform validation check
    if (!value.includes("Burlington")) {
      inputCmp.setCustomValidity("The account name must include 'Burlington'");
    } else {
      // if there was a custom error before, reset it
      inputCmp.setCustomValidity("");
      const fields = event.detail.fields;
      fields.Name = this.inputVal;
      this.template.querySelector("lightning-record-edit-form").submit(fields);
    }
    // shows the error right away without user interaction
    inputCmp.reportValidity();
  }
}
```

`lightning-input` provides attributes for custom validation, such as `min`, `max`, and `pattern`. For more information, see the [`lightning-input` reference documentation.](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input)

**note:** `lightning-input-field` is the preferred component to use with `lightning-record-edit-form`. Use `lightning-input` with `lightning-record-edit-form` only if validation rule errors don’t meet your requirements.

<!-- document id=174ea63bd0105dc642d481059199f0633bc101fae676ea682defa41c619ed7e5 url=/developer/current/en-us/lwc/lwc/guides/data/data-table-custom-types-editable-example.md -->

# Edit Template Example for Custom Data Types

This example shows a custom data type with templates containing components rather than simple markup.

**note:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has several components that demonstrate inline editing with Apex and the `lightning/uiRecordApi` module. Look for components whose names start with `datatableInline`.

This example creates a datatable with a custom datatype for the Amount.

Here’s the datatable on initial load.

![Datatable with custom type that's editable](https://developer.salesforce.com/media/datable_custom_datatype_editable_initial.png)

The `myDatatableWrapper` component contains the extended datatable component that defines the custom type.

<!-- prettier-ignore -->
```html
/* myDatatableWrapper.html */

<template>
  <c-my-custom-type-datatable columns={COLS} key-field="id" data={data}>
  </c-my-custom-type-datatable>
</template>
```

```javascript
// myDatatableWrapper.js

import { LightningElement } from 'lwc';
export default class MyDatatableWrapper extends LightningElement {
    COLS = [
        { label: 'Account', type: 'text', fieldName: 'account', editable: false, displayReadOnlyIcon: true},
        { label: 'Stage', type: 'text', fieldName: 'stage', editable: false, displayReadOnlyIcon: true},
        { label: 'Amount', type: 'customNumber', fieldName: 'amount', editable: true,
            typeAttributes: {
                status: {fieldName: 'status'},
                step: {fieldName: 'step'}
            }
        },
        { label: 'Due Date', type: 'date', fieldName: 'date', editable: false, displayReadOnlyIcon: true}
    ];

    data = [
        {account: 'Acme Corp.', amount: '200.00', status: 'action:user',
            step: '0.01', stage:'Value Proposition', date: '2022-02-10T00:00:00Z'},
        {account: 'Norwood Inc.', amount: '500000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-01-20T00:00:00Z'},
        {account: 'Edge Communications', amount: '800000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-02-18T00:00:00Z'},
        {account: 'Pyramid Construction Inc.', amount: '50000.00', status: 'action:user',
            step: '0.01', stage:'Closed ', date: '2022-03-10T00:00:00Z'},
        {account: 'GenePoint', amount: '30000', status: 'action:user',
            step: '0.01', stage:'Negotiation/Review	', date: '2022-05-28T00:00:00Z'},
        {account: 'Dickenson plc', amount: '1550000.00', status: 'action:user',
            step: '0.01', stage:'Closed Won', date: '2022-03-16T00:00:00Z'}
    ]
```

Here's the folder for the extended datatable with an editable custom type.

```asciidoc
myCustomTypeDatatable
   ├──customNumber.html
   ├──customNumberEdit.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml

```

Define the custom type and import the display and edit templates in the extended datatable.

```javascript
// myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNumberTemplate from "./customNumber.html";
import customNumberEditTemplate from "./customNumberEdit.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customNumber: {
      template: customNumberTemplate, // display mode
      editTemplate: customNumberEditTemplate, // edit mode
      standardCellLayout: true,
      typeAttributes: ["status", "step"],
    },
  };
}
```

:**note:** - You import HTML templates into the extended datatable’s JavaScript file as shown above.
- Child components used inside a custom cell (for example, `c-my-fancy-number` in `customNumber.html`) are referenced directly in the template. Don’t import them in the datatable’s JavaScript file.:

The display template uses a child component to render the value.

<!-- prettier-ignore -->
```html
/*customNumber.html*/
<template>
  <c-my-fancy-number value={value}> </c-my-fancy-number>
</template>
```

The child component defines the data type’s display and includes logic to determine the styling that’s applied to the data.

The `myFancyNumber` component evaluates the data to apply classes, icons, and icon styling.

<!-- prettier-ignore -->
```html
/* myFancyNumber.html */

<template>
  <div class={computedClass}>
    <lightning-formatted-number format-style="currency" value={value}>
    </lightning-formatted-number>
    <lightning-icon
      class="slds-p-horizontal_xx-small"
      icon-name={computedIcon}
      size="xx-small"
      variant={iconVariant}
    >
    </lightning-icon>
    ({range})
  </div>
</template>
```

```javascript
// myFancyNumber.js

import { LightningElement, api, track, wire } from "lwc";

export default class MyFancyNumber extends LightningElement {
  @api value;
  get range() {
    return this.value > 50000 ? "High" : "Low";
  }
  get computedClass() {
    return this.value > 50000 ? "slds-text-color_success" : "slds-text-color_error";
  }

  get computedIcon() {
    return this.value > 50000 ? "utility:arrowup" : "utility:arrowdown";
  }

  get iconVariant() {
    return this.value > 50000 ? "success" : "error";
  }
}
```

The `customNumberEdit.html` template uses the `lightning-input` component with `type="number"`.

<!-- prettier-ignore -->
```html
/* customNumberEdit.html */
<template>
  <lightning-input
    type="number"
    value={editedValue}
    label={columnLabel}
    required={required}
    step={typeAttributes.step}
    data-inputable="true"
  >
  </lightning-input>
</template>
```

Here’s the datatable after a custom number type field has been edited before the table is saved. The edited field is highlighted in yellow.

![Datatable with an edited custom type field](https://developer.salesforce.com/media/datable_custom_datatype_edited.png)

### How a Custom Component Affects Editing

- **Inline edit flow**: Unchanged. Set `editable: true` on the column. Edited values appear in `editedValue`, and the table emits `onsave` with `draft-values`.
- **Keyboard and a11y**: Unchanged when `standardCellLayout: true` and the input in the edit template has `data-inputable="true"`.
- **Other behaviors**: Sorting, selection, pagination, and save handling work the same as with standard types.

For information about saving changed data, see [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/data/data-table-inline-edit.md).

<!-- document id=925bc8c49c7f174c382bc85fbf38a0f385f1a4246692fe5d8b74c77a565277d3 url=/developer/current/en-us/lwc/utam/references/element-filters.md -->

# Element Filters

To pick an element or a list of elements based on a condition at run time, add a filter inside an element node. An element with a `filter` must have a `selector` with `returnAll` set to `true`.

## Filter Properties

A `filter` object inside an element has these properties:

- `apply` (Required) String. The method called on the element, which must return a value of the type expected by `matcher`.
  - For a custom element: the method name declared inside the page object.
  - For a basic element: one of the [supported actions](/grammar/basic-actions).
- `findFirst` (Optional, default is `false`) Boolean. If `true`, returns the first element that matches the filter. If `false`, returns a list of elements. If the element is marked as `nullable`, the filter can return `null` if no match is found.
- `matcher` (Required) Object. Defines the filter criteria for the data returned by the `apply` method.
  - `type` (Required) String. The matcher type for filtering data. For supported types, see [Matchers](#matchers).
  - `args` (Optional) Array. If the matcher type requires arguments, pass them in this array.

This example uses a filter to pick one of the `lightning-menu-item` instances inside a `lightning-button-menu` based on the item text.

```json
{
  "elements": [
    {
      "name": "menuItemByText",
      "type": "utam-lightning/pageObjects/lightning/menuItem",
      "selector": {
        "css": "lightning-menu-item",
        "returnAll": true
      },
      "filter": {
        "apply": "getItemText",
        "findFirst": true,
        "matcher": {
          "type": "stringContains",
          "args": [
            {
              "name": "itemText",
              "type": "string"
            }
          ]
        }
      },
      "public": true
    }
  ]
}
```

For the example to work, the `lightning-menu-item` page object must declare a public method `getItemText` that returns menu item text.

The generated method finds all `lightning-menu-item` instances inside a `lightning-button-menu` based on the item text. For each item, `getItemText` executes and picks the first item that contains the parameter value as a substring. If no match is found, it returns null.

```java
public MenuItem getMenuItemByText(String itemText) {
    // find all available menu items
    // get text for each item
    // pick first item that contains value provided in parameter
}
```

Example of a basic element filter that returns a list:

```json
{
  "elements": [
    {
      "name": "myElement",
      "selector": {
        "css": ".myClass",
        "returnAll": true
      },
      "filter": {
        "apply": "getText",
        "matcher": {
          "type": "stringContains",
          "args": [
            {
              "name": "matcherArg",
              "type": "string"
            }
          ]
        }
      },
      "public": true
    }
  ]
}
```

UTAM generates this compiled type:

```js
getMyElement(matcherArg: string): Promise<_ActionableUtamElement[]>;
```

UTAM generates this compiled JavaScript:

```js
async getMyElement(matcherArg) {
    const driver = this.driver;
    const root = await this.getRootElement();
    let elements = await _utam_get_myElements(driver, root, );
    elements = elements.map(function _createUtamElement(element) {
        return new _ActionableUtamElement(driver, element);
    });
    const appliedFilter = await Promise.all(elements.map(el => _utam_filter_myElement(el, matcherArg)));
    elements = elements.filter((_, i) => appliedFilter[i]);
    return elements;
}
```

## Matchers

Use a matcher to apply a condition at run time:

- To pick an element or a list of elements in an element filter.
- To transform the return value of a compose statement. For an example, see [Methods](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/methods.md#matchers).

A matcher is an object with these properties.

- `type` (Required) String. The matcher type to filter data returned by an `apply` method or an element's getter method. These types are supported:
  - `isFalse` Matches `false` values.
  - `isTrue` Matches `true` values.
  - `notNull` Matches values that are not null.
  - `stringContains` Matches values containing the string passed to the matcher's `args` array.
  - `stringEquals` Matches values that equal the string passed to the matcher's `args` array.
- `args` (Optional) Array. If the matcher type requires arguments, pass them in this array.

This matcher uses the `stringContains` matcher type.

```json
"matcher": {
    "type": "stringContains",
    "args": [
        {
            "name": "itemText",
            "type": "string"
        }
    ]
}
```

## Nested elements inside filtered parent

Element with filter can have nested elements.

### Element with `findFirst` set to true (filtered element returns single element)

For example UTAM page object that has `"child"` element nested inside filtered `"parent"` that returns single element (`"findFirst": true`):

```json
{
  "name": "parent",
  "selector": {
    "css": "div",
    "returnAll": true
  },
  "filter": {
    "apply": "isVisible",
    "findFirst": true,
    "matcher": {
      "type": "isTrue"
    }
  },
  "elements": [
    {
      "name": "child",
      "selector": {
        "css": "button"
      },
      "public": true
    }
  ]
}
```

Generated code:

1. Type definition for JavaScript

```js
getChild(): Promise<_BaseUtamElement>;
```

2. Java interface

```java
BasicElement getChild();
```

### Element with `findFirst` is set to false (filtered element returns list, default)

UTAM compiler will add additional index parameter to nested element's gettter.
For example UTAM page object that has `"listField"` element nested inside filtered list `"visibleTableCells"`: true`):

```json
{
  "name": "visibleTableCells",
  "selector": {
    "css": "td",
    "returnAll": true
  },
  "filter": {
    "apply": "isVisible",
    "matcher": {
      "type": "isTrue"
    }
  },
  "elements": [
    {
      "name": "listField",
      "selector": {
        "css": "lst-template-list-field"
      },
      "type": "utam-lst/pageObjects/templateListField",
      "public": true
    }
  ]
}
```

Generated code:

1. Type definition for JavaScript

```javascript
/**
* @param _visibleTableCellsIndex index of parent element
*/
getListField(_visibleTableCellsIndex: number): Promise<(_TemplateListField)>;
```

2. Java interface

```java
/**
* @param _visibleTableCellsIndex index of parent element
*/
TemplateListField getListField(_visibleTableCellsIndex: integer);
```

<!-- document id=b701c8f9f2ec7fe120b3417f6bcc1a220a007166738c089b156f02dd43f1ea7a url=/developer/current/en-us/lwc/utam/references/element-lists.md -->

# Element Lists

## Multiple elements

When a `selector` includes `"returnAll": true`, the generated method returns a list.

In the DOM, a parent can contain multiple instances of a nested element, like `lightning-tab` components inside a `lightning-tabset`. If the `selector` has a `returnAll` property set to `true`, the method returns a list of instances found at run time.

```json
{
  "elements": [
    {
      "name": "allTabs",
      "type": "utam-lightning/pageObjects/lightning/tab",
      "selector": {
        "css": "lightning-tab",
        "returnAll": true
      },
      "public": true
    }
  ]
}
```

From the previous JSON, UTAM generates this public method, which returns a list of the page objects of the given type.

```java
public List<Tab> getAllTabs() {
    // return list of instances found in runtime
    // throw exception if nothing found
}
```

## Indexes

To get one of the instances by its index, add `:nth-of-type(%d)` to the injected selector and the `args` property with an `index` parameter. `:nth-of-type(%d)` is 1-based, not 0-based.

```json
{
  "elements": [
    {
      "name": "myComponent",
      "type": "utam-lightning/pageObjects/lightning/myComponent",
      "selector": {
        "css": "lightning-my-component:nth-of-type(%d)",
        "args": [
          {
            "name": "index",
            "type": "number"
          }
        ]
      },
      "public": true
    }
  ]
}
```

The generated method finds all the custom elements inside the parent and returns one by `index`.

```java
public MyComponent getMyComponent(int index) {
    // return nth instance
    // if nothing found, or index is out of bounds, throw exception
}
```

## Elements nested inside lists

Sometimes a list element can have nested element, in the example below it's `<lst-template-list-field>` inside `<dd>`:

```html
<template for:each="{fields}" for:item="field">
  <dd key="{field.key}" class="record__card-field">
    <lst-template-list-field field="{field}"></lst-template-list-field>
  </dd>
</template>
```

The UTAM grammar allows you to include nested elements within lists:

```json
{
    "name": "recordCardField",
    "selector": {
        "css": "dd.record__card-field",
        "returnAll": true
    }
    "elements": [
        {
            "name": "listField",
            "selector": {
                "css": "lst-template-list-field"
            },
            "type": "utam-lst/pageObjects/templateListField",
            "public": true
        }
    ]
}
```

Because `"recordCardField"` is a list, the UTAM compiler will automatically generate a getter method with an index parameter in order to access the `"listField"` nested element.

Here's what the generated code might look like:

1. For JavaScript:

```javascript
/**
* @param _recordCardFieldIndex index of parent element
*/
getListField(_recordCardFieldIndex: number): Promise<(_TemplateListField)>;
```

2. For Java:

```java
/**
* @param _recordCardFieldIndex index of parent element
*/
TemplateListField getListField(_recordCardFieldIndex: integer);
```

<!-- document id=9c7ab56c199e9d4ccac6d4f2f6c9443988a2fe4e4bd44493d51399e835fc4f3d url=/developer/current/en-us/lwc/utam/references/element-selectors.md -->

# Element Selectors

Every basic element and custom element requires a `selector` object that locates the element at run time. A container element doesn't require a `selector`, because it has a default.

When a selector is used for a custom element, the `selector` is reserved for the custom element’s type and can’t be reused for any other type.

UTAM supports all valid CSS selectors.

## Selector Properties

A `selector` object has these properties:

- `css` (Required) String. A [standard CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors#reference_table_of_selectors), which can also include special [selector parameters](#selector-parameters). UTAM supports all valid CSS selectors.
- `args` (Optional) Array. Parameters to add to the methods that access this element or its nested elements. Each element in the array has these properties:
  - `name` (Required) String. A parameter name that is unique in the scope of the `args` array.
  - `type` (Required) String. A primitive type, either `string`, `number` or `boolean`.
- `returnAll` (Optional, default is `false`) Boolean. To get a list of elements, set `returnAll` to `true`.

```json
{
  "elements": [
    {
      "name": "myDiv",
      "selector": {
        "css": ".myDiv"
      }
    },
    {
      "name": "listItems",
      "selector": {
        "css": "li a",
        "returnAll": true
      }
    }
  ]
}
```

## Selector Parameters

A `selector` can depend on run-time information from the test, like a label or an index. To access this run-time information, use these format indicators inside a CSS selector. At run time, they’re replaced by values passed as parameters to the element’s public method.

- String (`%s`)
- Integer (`%d`)

```json
{
  "elements": [
    {
      "name": "listItemWithTitle",
      "selector": {
        "css": "li a[title='%s']",
        "args": [
          {
            "name": "titleString",
            "type": "string"
          }
        ]
      },
      "public": true
    }
  ]
}
```

UTAM generates this code from the JSON.

```java
  public Actionable getListItemWithTitle(String titleString) {
    // return instance of the element using selector with replaced parameter
  }
```

A nested element can inherit parameters from its parents. In this example, the nested input needs two integer parameters for the enclosing table cell.

```json
{
  "elements": [
    {
      "name": "tableCell",
      "selector": {
        "css": "tr:nth-of-type(%d) td:nth-of-type(%d)",
        "args": [
          {
            "name": "rowIndex",
            "type": "number"
          },
          {
            "name": "colIndex",
            "type": "number"
          }
        ]
      },
      "elements": [
        {
          "name": "inputInsideCell",
          "selector": {
            "css": "input"
          },
          "type": ["editable"],
          "public": true
        }
      ]
    }
  ]
}
```

UTAM collects parameter names for every element from root that leads to the current element and adds them in order of appearance.

```java
  public Editable getInputInsideCell(int rowIndex, int colIndex) {
    // Apply the provided parameters,
    // then find an input element inside a table cell.
  }
```

## Mobile Selectors

The Salesforce mobile app is a mobile hybrid application. Some pages are WebView pages, and some pages are native pages. For a native page, CSS selectors aren't sufficient. To find elements in a mobile environment, Appium implements a number of locator strategies for specific mobile devices. For more information, see [appium.io: Find Elements](https://appium.io/docs/en/2.0/reference/interfaces/appium_types.Driver/#findelement).

Appium is an open-source tool for automating native, mobile web, and hybrid applications. Appium allows you to write tests against multiple platforms, such as iOS and Android, using the same API.

### Accessibility ID Selector

**important:** This selector is supported for Mobile Platform only.

Use the accessibility ID selector, which is a unique identifier for a UI element. This example uses an accessibility ID selector of `searchCell.ViewAllCell`.

```json
{
  ...
  	"name": "searchCell",
    "selector": {
        "accessid": "searchCell.ViewAllCell"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(accessid = "searchCell.ViewAllCell")
private ElementLocation searchCell;
```

### iOS Class Chain Selector

**important:** This selector is for iOS Platform only.

The iOS class chain selector finds a window element from the root of the page:

Page object JSON:

```json
{
  ...
    "name": "appWindow",
    "selector": {
        "classchain": "XCUIElementTypeWindow"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(classchain = "XCUIElementTypeWindow")
private ElementLocation appWindow;
```

You can use double star and slash (\*\*/) to define the next item descendant from the root. This strategy makes the configured locator not sensitive to the hierarchy of the page.

Page object json:

```json
{
  ...
    "name": "button",
    "selector": {
        "classchain": "**/XCUIElementTypeButton"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(classchain = "**/XCUIElementTypeButton")
private ElementLocation button;
```

Sometimes, the element type isn't unique enough to identify a specific element. In those scenarios, you can combine the element type with an attribute using a predicate. The predicate string should always be enclosed in \` marks or `$` characters inside square brackets. Use \`\` or \$\$ to escape a single \`or`\$` character inside a predicate expression.

A single backtick means the predicate expression is applied to the current children. A single dollar sign means the predicate expression is applied to all the descendants of the current element(s). String values, not the key words, can be enclosed by \' or \".

Page object JSON:

```json
{
  ...
    "name": "newButton",
    "selector": {
        "classchain": "**/XCUIElementTypeButton[`name BEGINSWITH 'New'`]",
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(classchain = "**/XCUIElementTypeButton[`name BEGINSWITH 'New'`])
private ElementLocation newButton;
```

This selector uses the `$` character to apply the attribute to all the descendants of the current element(s).

Page object JSON:

```json
{
  ...
    "name": "newButton",
    "selector": {
        "classchain": "**/XCUIElementTypeCell[$name == \"My Accounts\"$]",
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(classchain = "**/XCUIElementTypeCell[$name == \"My Accounts\"$])
private ElementLocation newButton;
```

The following attributes are supported:

- `name`
- `visible`
- `value`
- `enabled`

The following comparison types for an attribute are supported:

- `EQUALS` or `==`
- `BEGINSWITH`
- `ENDSWITH`
- `CONTAINS`

You can use the following operators to set conditions for multiple attributes in one expression.

- `AND`
- `OR`

For example:

```json
{
  ...
    "name": "newButton",
    "selector": {
        "classchain": "**/XCUIElementTypeBotton[`name BEGINSWITH 'New' AND visible == true`]",
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(
    classchain = "**/XCUIElementTypeBotton[`name BEGINSWITH 'New' AND visible == true`]"
)
private ElementLocation newButton;
```

Similarly to CSS selectors, you can use string or integer parameters. This example uses a string parameter.

```json
{
  ...
    "name": "tabBarBtn",
    "selector": {
        "classchain": "**/XCUIElementTypeButton[`name == '%s'`]",
        "args": [
            {
                "name": "item",
                "type": "string"
            }
        ]
    }
}
```

Generated Java code:

```java
@ElementMarker.Find(classchain = "**/XCUIElementTypeButton[`name == '%s'`]")
private ElementLocation tabBarBtn;

@Override
final TabBarBtnElement getTabBarBtnElement(String item) {
  return element(this.tabBarBtn).build(TabBarBtnElement.class, TabBarBtnElementImpl.class, item);
}
```

Here's more detailed examples for [iOS Class Chain](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules).

### Android UIAutomator Selector

**important:** This selector is for Android Platform only.

Appium uses the UIAutomator selector to enable searching using UiSelectors. We support the following methods only from `UiSelector` to find elements:

- `checkable(boolean val)`
- `checked(boolean val)`
- `className(String className)`
- `clickable(boolean val)`
- `description(String desc)`
- `descriptionContains(String desc)`
- `descriptionStartsWith(String desc)`
- `enabled(boolean val)`
- `selected(boolean val)`
- `resourceId (String id)`
- `resourceIdMatches(String regex)`

This example uses the `clickable` method:

```json
{
  ...
    "name": "acceptButton",
    "selector": {
        "uiautomator": "new UiSelector().clickable(true)"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(uiautomator = "new UiSelector().clickable(true)")
private ElementLocation acceptButton;
```

This example uses the `className` method:

```json
{
  ...
  	"name": "newButton",
    "selector": {
        "uiautomator": "new UiSelector().className(\"android.widget.TextView\")"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(
    uiautomator = "new UiSelector().className(\"android.widget.TextView\")"
)
private ElementLocation newButton;
```

This example uses the `descriptionContains` method:

```json
{
  ...
    "name": "vfLink",
    "selector": {
        "uiautomator": "new UiSelector().descriptionContains(\"VfPage Link\")"
    },
  ...
}
```

Generated Java code:

```java
@Selector.Find(
    uiautomator = "new UiSelector().descriptionContains(\"VfPage Link\")"
)
private ElementLocation vfLink;
```

`UIScrollable` is a powerful Android class that performs element lookups in scrollable layouts. In most cases, you should use the `scrollIntoView` method, which performs a scroll action until the destination element is found on the screen. You can use `UIScrollable` swipe to:

- search elements in a list (for example in a country list)
- search elements outside of the screen (for example, an input field, text, or button)

The `scrollIntoView` method has UiSelector as search criteria input to allow you to find elements by supported methods. For example:

```json
{
    "implements": "utam-salesforceapp/pageObjects/navigation/navItemsList",
    "elements": [
        {
            "name": "navItemWithLabel",
            "selector": {
                "uiautomator": "new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(className(\"android.widget.TextView\").text(\"%s\"))",
                "args": [
                    {
                        "name": "item",
                        "type": "string"
                    }
                ]
            }
        }
```

The generated Java code is:

```java
  @ElementMarker.Find(
    uiautomator =
        "new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(className(\"android.widget.TextView\").text(\"%s\"))",
    nullable = true
  )
  private ElementLocation navItemWithLabel;
```

Here's more details for UIAutomator [UiSelector](https://developer.android.com/reference/androidx/test/uiautomator/UiSelector) and [UiScrollable](https://developer.android.com/reference/android/support/test/uiautomator/UiScrollable).

<!-- document id=b486e3a09bb9e721916bb0a67311d6835cd9b1c632f81124be9eaad81d4e330f url=/developer/current/en-us/lwc/utam/guide/frames.md -->

# Elements in Frames

Let's write a UI test for a `playground-app` element inside an iframe.

![iframe](https://developer.salesforce.com/docs/media/utam/iframe.png)

## Add a frame element

First, we need to create a root `Home` page object and add a [frame element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#frame-elements):

```json
{
  "root": true,
  "selector": {
    "css": "componentreference-playground"
  },
  "shadow": {
    "elements": [
      {
        "name": "previewFrame",
        "public": true,
        "type": "frame",
        "selector": {
          "css": "[name='preview']"
        }
      }
    ]
  }
}
```

## Enter the frame from a test

Use `enterFrame()` in this JavaScript test to enter the frame.

```js
const home = await utam.load(Home);
const frame = await home.getPreviewFrame();
await utam.enterFrame(frame);
```

## Load the page object inside the frame

The Playground page object for our `playground-app`, which is in the iframe, should be marked as root.

```json
{
  "root": true,
  "selector": {
    "css": "playground-app"
  },
  "methods": [
    {
      "name": "play",
      "compose": []
    }
  ]
}
```

Now, when the JavaScript test enters the frame, we can load the Playground page object from the UTAM loader:

```js
// shortcut to enter frame and load:
// utam.enterFrameAndLoad(frame, Playground);
const playground = await utam.load(Playground);
await playground.play();
```

## Exit frame

When the test is done interacting with the Playground page object inside the frame, call `exitFrame`:

```js
await utam.exitFrame();
```

**note:** If the frame is nested, a test can use `utam.exitParentFrame()` to pass the control to the parent frame of the current frame.

<!-- document id=537f89c8ff05896c76cd09acae02ddefc1791fa5f4d2111fde4ed944a5b904d6 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-component.md -->

# Embed a Flow in a Custom Lightning Web Component

Embed a screen flow from any Lightning web component to customize the finish behavior, set custom styling, or launch flows from your Lightning web components.

In this section, learn how to:

- [Create and Start a Flow in a Custom Lightning Web Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-create-start.md)
- [Set Flow Input Variables](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-input-variables-example.md)
- [Get Values from Flow Output Variables](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-output-variables-example.md)
- [Control What Happens When a Flow Interview Finishes](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-control-finish-example.md)
- [Resume a Flow Interview](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-embed-resume-example.md)

**See Also**

- [_Salesforce Help_: Flow Builder](https://help.salesforce.com/articleView?id=platform.flow_builder.htm&type=5)
- [_Salesforce Help_: Considerations for Using Flows in the Field Service Mobile App](https://help.salesforce.com/s/articleView?id=service.mfs_flow_considerations.htm)
- [Component Reference: lightning-flow](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow)

<!-- document id=2321e7e5943d9932d597d544ed18e7e5cc06620ef6d07a7c6d7057ad72159b8a url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-enable-scratch-orgs.md -->

# Enable and Disable Lightning Web Security in Scratch Orgs

New orgs have Lightning Web Security (LWS) for Lightning web components and Aura components enabled by default. New scratch orgs also have LWS enabled.

To enable and disable LWS in your scratch orgs, you can use [scratch org definition files](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm). For example, to disable LWS in your scratch org, set the `lockerServiceNext` setting to `false`.

```json
"settings": {
     "securitySettings": {
         "sessionSettings": {
            "lockerServiceNext": false
           }
      }
}
```

**important:** The boolean `lockerServiceNext` enables and disables LWS, not [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md).

When LWS is disabled in your scratch org, Lightning Locker is automatically enabled for Lightning web components and Aura components.

**See Also**

- [Salesforce CLI Command Reference](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/)
- [Salesforce DX Developer Guide: Scratch Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs.htm)

<!-- document id=19c83e7760b786b2e1be88c895281e2b2f7dd003af7349b3e869433e65f1d483 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-third-party-cookies.md -->

# Enable Browser Third-Party Cookies for Lightning Out (Beta)

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

Lightning components set cookies in a user’s browser. Because Lightning Out (beta) runs Lightning components _outside_ of Salesforce, these cookies are “third-party” cookies. There are a few alternatives to make these third-party cookies functional for Lightning Out (beta).

## Enable Token-Based Authentication

Salesforce uses a cookie for authentication. For Lightning Out (beta) apps, we recommend that you enable the setting that replaces the authentication cookie with a session token when a Lightning app is in a third-party context.

From Setup, in the Quick Find box, enter _Session_, and then select **Session Settings**. On the Session Settings page, select **When embedding a Lightning application in a third-party site, use a session token instead of a session cookie**.

If you don’t enable this setting, your users must allow third-party cookies in their browser settings.

## Enable Cross-Site Tracking in Safari

Salesforce uses cookies other than the authentication cookie. For these third-party cookies from Salesforce to work, your users must allow third-party cookies in their browser settings.

The Prevent cross-site tracking setting is enabled by default in iOS and iPadOS 13.4 and Safari 13.1 and later. To allow third-party cookies and use Lightning Out (beta), this setting must be disabled.

To see the Prevent cross-site tracking setting:

- In the Safari app on a Mac desktop, go to **Safari** | **Preferences**, and click Privacy.
- In iOS and iPadOS, go to **Settings** | **Safari**.

## Set Up a Custom Domain

An alternative to requiring all Safari users to change their cross-site tracking browser setting is to set up a custom domain. The custom domain matches the first-level domain of the external server that calls the Lightning Out (beta) app. This approach causes the browser to see the external server and the Lightning Out (beta) app as part of the same domain so cookies can be shared between the two sites.

For example, to call a Lightning Out (beta) app from an `external.example.com` server, add a custom domain, such as `lightningout.example.com`, in Salesforce. You must set up a DNS record to map the fully qualified domain name (FQDN), `lightningout.example.com`, to the custom domain URL in Salesforce.

1.  Decide on the custom domain name, for example, `lightningout.example.com`. The custom domain must resolve to the same parent domain as the third-party site that calls the Lightning Out (beta) app.
2.  Find your 18-character org ID from Setup by entering `Domains` in the Quick Find box, then select **Domains**. Click **Add a Domain** and note the org ID listed at the top of the page.
3.  Set up a CNAME record with your DNS provider to map the custom domain name, such as `lightningout.example.com`, to the custom domain in Salesforce. The target of the CNAME record uses the format `YourFQDN.Your18charOrgId.live.siteforce.com`, where `YourFQDN` is the custom domain name that you chose in the first step.
4.  Create a [custom domain](https://help.salesforce.com/s/articleView?id=platform.domain_mgmt_add.htm) by completing the Add a Domain page.
    1.  For the Domain Name, enter the custom domain name, such as `lightningout.example.com`, that you chose in the first step.
    2.  For the HTTPS Option, choose Salesforce serves the domain over HTTPS, on Salesforce's servers, using your HTTPS certificate.
5.  Configure the [Lightning Out (Beta) Markup](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-markup.md) on the external server's page to use the FQDN of the CNAME record, such as `lightningout.example.com`, which you set up with your DNS provider. The `src` attribute in the `script` tag and the `lightningEndPointURI` argument in the `$Lightning.use()` function must both use the FQDN of the CNAME record.
6.  If your app uses authentication, see [Authentication from Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-authentication.md).

**See Also**

- [Lightning Out (Beta) Requirements](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-requirements.md)

<!-- document id=f23db37729182074b5159d657bae9f36a6c01c0b3c38b8165f7d6fa90dcb689d url=/developer/current/en-us/lwc/lwc/guides/perf/perf-cdn.md -->

# Enable CDN to Load Applications Faster

Load Lightning Experience and other apps faster by enabling Akamai’s content delivery network (CDN) to serve the static content for Lightning Component framework. A CDN generally speeds up page load time, but it also changes the source domain that serves the files. If your company has IP range restrictions for content served from Salesforce, test thoroughly before enabling this setting.

CDNs improve the load time of static content by storing cached versions in multiple geographic locations. This setting turns on CDN delivery for the static JavaScript and CSS in the Lightning Component framework. It doesn’t distribute your Salesforce data or metadata in a CDN.

This setting is disabled by default for orgs created before the Winter ’19 release, and enabled by default for new orgs and all new and existing Experience Builder sites. Lightning CDN for Experience Builder sites can’t be turned off and isn’t configurable.

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.

2.  Select the checkbox for “Enable Content Delivery Network (CDN) for Lightning Component framework”.

3.  Click **Save**.

    If you experience any issues, ask your network administrator if your company’s firewall blocks any Akamai CDN content. Ensure that `https://static.lightning.force.com` is added to any allowlist or firewall that your company operates. You can ping `static.lightning.force.com` but you can’t browse directly to the root URL at `https://static.lightning.force.com`.

    **important:** Don’t use IP addresses for network filtering because that can cause connection issues with `https://static.lightning.force.com`. IP addresses for `https://static.lightning.force.com` are dynamic and aren’t maintained in Salesforce’s list of allowed IP addresses.

**See Also**

- [_Salesforce Developers Blog:_ Enable CDN to Load Lightning Experience Faster](https://developer.salesforce.com/blogs/2023/03/enable-cdn-to-load-lightning-experience-faster)
- [_Knowledge Article:_ Salesforce IP Addresses and Domains to Allow](https://help.salesforce.com/articleView?id=000003652&type=1)

<!-- document id=d9ae5fc932e9ede51665a05ad9f20b9bc694e0ebd8ba2847b5a24d8ffb6ff056 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-mode-enable.md -->

# Enable Debug Mode in Salesforce

Enable debug mode to make it easier to debug JavaScript code. Only enable debug mode for users who are actively debugging JavaScript. Salesforce is slower for users who have debug mode enabled.

To enable debug mode for users in your org:

1.  In Salesforce, from Setup, enter `Debug Mode` in the Quick Find box, then select **Debug Mode Users**.

    Users with debug mode enabled have a check mark in the Debug Mode column.

2.  In the user list, locate any users who need debug mode enabled. If necessary, use the standard list view controls to filter your org’s users.

3.  Select the checkbox next to users for whom you want to enable debug mode.

4.  Click **Enable**.

**tip:** If you see only a few lines of code in a JavaScript file, then debug mode is not enabled. If enabling debug mode doesn’t reset the code in the code editor, do a hard reload. With DevTools open, right-click the browser Reload button and then click **Hard Reload**.

To disable debug mode for a user, follow the preceding steps and click **Disable** instead of **Enable**.

**See Also**

- [Debug Mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-debug-mode.md)

<!-- document id=4c51d0d2a44d0083879c31806bb7bb0d6749957f265a629037b64b0a80cf4022 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-enable.md -->

# Enable Lightning Web Security in an Org

To determine whether to enable Lightning Web Security (LWS) in your production org, see [When to Enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-when.md). First test LWS in a sandbox environment, and then in production.

**important:** New orgs have Lightning Web Security for Lightning web components and Aura components enabled by default. If you create an org from a template, then that org inherits the LWS setting of the template.

If you plan to populate a new org with preexisting or packaged Lightning components, be sure to first test in a sandbox environment with LWS enabled. See [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md).

If your org contains Experience Cloud sites, see [Experience Builder Sites and LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-lms-ec.md) before enabling LWS.

To use Lightning Web Security in an org:

1.  From Setup, in the Quick Find box, enter `Session`, and then select **Session Settings**.
2.  On the Session Settings page, select **Use Lightning Web Security for Lightning web components and Aura components** and save.
3.  To ensure the correct files are loaded in the browser, clear your browser cache after enabling or disabling Lightning Web Security. If you suspect that the correct security architecture is not in effect, see [Delayed Enabling or Disabling of LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-caching.md).

![Session Settings page with Lightning Web Security selected](https://developer.salesforce.com/media/setup_lwsec_enable.png)

To report issues, give feedback, or ask questions about Lightning Web Security, go to the [Lightning Components Development group](https://sfdc.co/NextGenWebSecurity) on Trailhead.

**important:** LWS relies on [Stricter CSP](https://developer.salesforce.com/docs/platform/lightning-components-security/content-security-policy/content-security-policy-stricter.md) to fully implement its security measures. When LWS is enabled, we strongly advise that you keep the Enable Stricter Content Security Policy setting enabled.

**See Also**

- [Enable and Disable LWS in Scratch Orgs](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable-scratch-orgs.md)
- [Salesforce Help: Lightning Web Security FAQ](https://help.salesforce.com/s/articleView?id=000363550&type=1)

<!-- document id=d70a7acd3f94ecc7a5bef9b4a2ce1ff921edcf20c552dcf510cceb1b94cb0731 url=/developer/current/en-us/lwc/lwc/guides/perf/perf-secure-browser-caching.md -->

# Enable Secure Browser Caching

Enable secure data caching in the browser to improve page reload performance by avoiding extra round trips to the server.

This setting is selected by default.

**important:** Disabling secure and persistent browser caching has a significant negative performance impact on Lightning Experience. Only disable in these scenarios.

- Your company’s policy doesn’t allow browser caching, even if the data is encrypted.
- During development in a sandbox or Developer Edition, you want to see the effect of any code changes without emptying the secure cache.

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.

2.  Select the checkbox for “Enable secure and persistent browser caching to improve performance”.

3.  Click **Save**.

**note:** Enabling secure and persistent data caching impacts record pages in Experience Cloud. Updates on fields aren’t observed immediately. To see the latest changes immediately, log out and log back in. Other users don't see the change until the cache is deleted or invalidated.

**See Also**

- [Disable Caching During Development](https://developer.salesforce.com/docs/platform/lwc/debug/debug-disable-caching.md)

<!-- document id=3961f0ea86fe299d6eaf7f75c7ce798c534fe9e674efc481afcb38a23ddba77a url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-endcapture.md -->

# `endCapture()` (Legacy)

Use this function to end a scanning session, close the mobile OS scanning interface, and dispose of resources.

**note:** We recommend using the modern [`scan()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-scan.md) and [`dismiss()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-dismiss.md) APIs in your LWC’s scanning code to streamline your development experience. The legacy APIs `beginCapture()`, `resumeCapture()`, and `endCapture()` are still available, but will be retired in a future release.

## Syntax

```javascript
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
endCapture(): void
```

## Parameters

None.

## Returns

None.

## Usage

```javascript
myScanner
  .beginCapture(scanningOptions)
  .then((result) => {
    console.log(result);
    this.scannedBarcode = result.value;
  })
  .catch((error) => {
    console.error(error);
  })
  .finally(() => {
    // Handle final cleanup
    myScanner.endCapture();
  });
```

After calling `endCapture()`, you can call `beginCapture()` on an existing or new `BarcodeScanner` instance to start a new scanning session.

**See Also**

- [BarcodeScanner Example—Single Scan (Legacy)](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_example.htm)
- [beginCapture(options) (Legacy)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-begincapture.md)

<!-- document id=ae168500dd9bf813d530c2d7eb9d74c5021b57eecde579aea52ce5f4ae1daf83 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-entityextraction.md -->

# Entity Extraction

Using Google’s entity extraction APIs, DocumentScanner can identify and enable the appropriate action for entities such as addresses, phone numbers, and more.

## `extractEntities`

To enable entity extraction, set the `extractEntities` boolean to true.

## `entityExtractionLanguageCode`

To specify the language, identify one of the supported languages in Google’s [Entity Extraction ML Kit](https://developers.google.com/ml-kit/language/entity-extraction). Then, set `entityExtractionLanguageCode` to the corresponding language code in the [ML Kit language identification doc](https://developers.google.com/ml-kit/language/identification/langid-support). By default, the language is set to `"en"` for English.

## Sample Configuration

```js
    const myScanner = getDocumentScanner();
    if (myScanner.isAvailable()) {
      const options = {
        imageSource: imageSource,
        scriptHint: "LATIN",
        returnImageBytes: true,
        extractEntities: true,
        entityExtractionLanguageCode: "NL",
      };
```

<!-- document id=aed194c2495d114086b2cd2a8aec0607f5f6cff46247049cdb063445a5a70e26 url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-erase.md -->

# `erase(options)`

Erase the contents of an NFC tag.

**warning:** Using `erase()` is an inherently dangerous action, as it allows data to be irreversibly deleted. Use caution when using this functionality in your component. At an absolute minimum, consider adding a confirmation window for your users that clearly states the outcome of the action, with an option for them to cancel if they wish.

**note:** The `erase()` function can only be performed on writable NFC tags. Attempting this function on a read-only NFC tag will result in an error.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
erase(options?: NFCServiceOptions): Promise<Object>;
```

## Parameters

- `options`—(Required) An [`NFCServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md#nfcserviceoptions) object to configure the NFCService request.

## Returns

If successful, the OS returns a `Promise` object that resolves to null. If unsuccessful, the OS returns a `Promise` object that rejects to `NFCServiceFailure`.

## Usage

Use this function to erase data from an NFC tag.

```javascript
myNFCService
  .erase(options)
  .then(() => {
    console.log("Data erased successfully!");
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels the operation, the promise is rejected with a `NFCServiceFailure.code` value of USER_DISMISSED.

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)

<!-- document id=4615d7a7f621e8de20ea86d9d948e74acdb11c2763035de33abadbe9ee43ead5 url=/developer/current/en-us/lwc/utam/references/error-codes.md -->

# Error Codes

The UTAM compiler generates Java or JavaScript page objects from source JSON page objects. If the compiler encounters an error in a JSON page object, it emits an error code and an error message.

To combine all compilation errors into one report and throw an error at the end, set the `interruptCompilerOnError` option to `false` in the compiler configuration file. For information about the compiler configuration options, see:

- [JavaScript compiler configuration file](/docs/platform/guide/js-guide.html#compiler-setup)
- [Java compiler configuration file](/docs/platform/guide/java-guide.html#compiler-setup)

Here's the list of error codes.

## Error Code 7

This property isn't supported. For a list of supported page object properties, see the [JSON Grammar](/docs/platform/utam/references/utam-grammar/grammar.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "testNestedArgs",
      "compose": [
        {
          "element": "self",
          "apply": "unknownMethod",
          "args": [
            {
              "value": "string",
              "args": [
                {
                  "value": "not allowed"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 7: method "testNestedArgs" statement "unknownMethod": property "args" is not supported
```

## Error Code 8

This property isn't supported. The set of supported properties is listed in the error message.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": { "css": "css" },
      "type": "frame",
      "nullable": true
    }
  ]
}
```

**Error message**:

```text
error 8: element "test": property "nullable" is not supported, supported are: name, public, selector, type
```

## Error Code 9

A required property is missing.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test"
    }
  ]
}
```

**Error message**:

```text
error 9: element "test": property "selector" is required
```

## Error Code 10

This property isn't supported. An alternative property is suggested in the error message.

**Incorrect JSON example**:

```json
{
  "description": ""
}
```

**Error message**:

```text
error 10: page object description: property "text" should be a non-empty string, instead found empty
```

## Error Code 11

This array can't contain a member with an empty string.

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "name": [1]
    }
  ]
}
```

**Error message**:

```text
error 11: profile "name": array member should be a non-empty string, instead found number
```

## Error Code 12

This property must be set to a non-empty array.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": []
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 12: method "test": property "args" should be a not empty array
```

## Error Code 13

This object can't be empty.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [true]
    }
  ]
}
```

**Error message**:

```text
error 13: method "test": compose statement should be a non-empty object
```

## Error Code 100

The arguments are incorrectly formatted. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "value": true,
              "type": "string"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 100: method "test" arguments: incorrect argument format
```

## Error Code 101

An unknown element is referenced as an argument. Check that the `elementReference` in the `args` array corresponds to a defined element.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "value": "argName",
              "type": "elementReference"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 101: method "test" arguments: unknown element with name "argName" is referenced
```

## Error Code 102

An argument is using an unsupported literal argument type. This example uses a number (1.024) but only integers are supported. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "value": 1.024
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 102: method "test" arguments: unsupported literal argument type "1.024"
```

## Error Code 103

An argument is using an unsupported argument type. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "type": "elementReference"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 103: method "test" arguments: unsupported argument type "elementReference"
```

## Error Code 104

A function argument type requires a `predicate` property and it's missing or incorrectly formatted. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "name": "name",
              "type": "function"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 104: method "test" arguments: incorrect predicate format
```

## Error Code 105

Literal arguments aren't allowed in this context. Use a `name` property instead of a `value` property. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "args": [
        {
          "value": "string literal"
        }
      ],
      "compose": [
        {
          "element": "root"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 105: method "test" arguments: literal arguments are not allowed
```

## Error Code 106

An argument is using an incorrect `elementReference` format. See [Element Reference](/docs/platform/utam/references/utam-grammar/methods.html#element-reference).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "value": "myElement",
              "type": "elementReference",
              "predicate": []
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 106: method "test" arguments: incorrect format of elementReference argument
```

## Error Code 107

A duplicate argument name is defined. Look for duplicate argument names.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "element",
      "selector": {
        "css": "selector %s",
        "returnAll": true,
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ]
      },
      "filter": {
        "apply": "getAttribute",
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ],
        "matcher": {
          "type": "stringContains",
          "args": [
            {
              "name": "arg1",
              "type": "string"
            }
          ]
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 107: element "element" arguments: argument with name "arg1" is already declared
```

## Error Code 108

There's a mismatch in the expected number of arguments.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "selector",
        "returnAll": true
      },
      "type": "my/page/object",
      "filter": {
        "apply": "getText",
        "matcher": {
          "type": "isTrue",
          "args": [
            {
              "name": "arg",
              "type": "string"
            }
          ]
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 108: element "test" filter matcher arguments: expected number of arguments is 0, found 1
```

## Error Code 109

An argument has an incorrect type. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "root",
                  "apply": "isPresent"
                }
              ]
            },
            {
              "value": true
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 109: method "test" arguments: argument "true" has incorrect type, expected "literal string", found "Boolean"
```

## Error Code 110

A selector has an unknown parameter type. See [Selector Parameters](/docs/platform/utam/references/utam-grammar/element-selectors.html#selector-parameters).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "public": true,
      "selector": {
        "css": "str[%f]",
        "args": [
          {
            "name": "num",
            "type": "number"
          }
        ]
      }
    }
  ]
}
```

**Error message**:

```text
error 110: element "test" selector arguments: unknown selector parameter type "%f", only string and number are supported
```

## Error Code 111

An argument can only define either a "name" or "value" property. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).
**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [{ "value": "true", "name": "name" }]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 111: method "test" arguments: either "name" or "value" is supported for an argument, not both
```

## Error Code 112

An argument with a "name" property also requires a "type" property. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "name": "name"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 112: method "test" arguments: "type" is required for an argument "name"
```

## Error Code 113

An argument must have either a "name" or "value" property. See [Supported Argument Types](/docs/platform/utam/references/utam-grammar/arguments.html#argument-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "world",
          "apply": "setText",
          "args": [
            {
              "type": "string"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 113: method "test" arguments: either "name" or "value" is required for an argument
```

## Error Code 114

A literal or function argument doesn't support a `description` property.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "description": "redundant",
              "predicate": [
                {
                  "element": "root"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 114: method "test" arguments: property "description" is not supported for literal or function argument
```

## Error Code 115

An invalid basic element type is defined. See [Basic Element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#basic-elements).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "type": ["wrong"],
      "selector": {
        "css": "css"
      }
    }
  ]
}
```

**Error message**:

```text
error 115: element "test" type: basic type "wrong" is not supported, valid values are: actionable, clickable, draggable, editable, touchable
```

## Error Code 116

A duplicate basic type is defined.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "type": ["clickable", "clickable"],
      "selector": {
        "css": "css"
      }
    }
  ]
}
```

**Error message**:

```text
error 116: element "test" type: duplicate basic type "clickable", basic type values must be unique
```

## Error Code 200

An element is incorrectly formatted. See [Basic Element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#basic-elements).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "wrong": "test",
      "type": "container"
    }
  ]
}
```

**Error message**:

```text
error 200: root elements: incorrect format of elements
```

## Error Code 201

An incorrect element type is defined. A custom type must contain alphanumeric characters only with the schema `[package-name]/[custom/path]/pageObject`.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "type": "wrong",
      "selector": {
        "css": "css"
      }
    }
  ]
}
```

**Error message**:

```text
error 201: element "test": type "wrong" is not supported, valid values are: custom, container, frame, actionable, clickable, draggable, editable, touchable
```

## Error Code 202

A duplicate element with the same name is defined.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "dupElement",
      "selector": {
        "css": "css"
      }
    },
    {
      "name": "dupElement",
      "selector": {
        "css": "css"
      }
    }
  ]
}
```

**Error message**:

```text
error 202: element "dupElement": element with same name was already declared
```

## Error Code 204

A frame selector can't set a `returnAll` property to `true`.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "css",
        "returnAll": true
      },
      "type": "frame"
    }
  ]
}
```

**Error message**:

```text
error 204: element "test": frame selector cannot have "returnAll" set to true
```

## Error Code 205

Only a basic element can have nested elements or a shadow root.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "one",
      "selector": {
        "css": ".one"
      },
      "elements": [
        {
          "name": "nestedCustom",
          "selector": {
            "css": ".nestedCustom"
          },
          "type": "utam-test/pageObjects/test/componentType",
          "public": true
        }
      ],
      "shadow": {
        "elements": [
          {
            "name": "nestedInsideShadow",
            "selector": {
              "css": ".css"
            }
          }
        ]
      }
    }
  ]
}
```

**Error message**:

```text
error 205: element "test": only basic element can have nested elements or shadow root
```

## Error Code 206

The `load` property is not supported for elements with arguments or container type elements.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "test[%s]",
        "args": [
          {
            "name": "selectorArgs",
            "type": "string"
          }
        ]
      },
      "load": true
    }
  ]
}
```

**Error message**:

```text
error 206: element "test": property "load" is not supported for element with arguments, filter or for container element
```

## Error Code 300

An element filter is incorrectly defined. See [Element Filter](/docs/platform/utam/references/utam-grammar/element-filters.html).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "selector %s",
        "returnAll": true,
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ]
      },
      "filter": {
        "apply": "wrong",
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ]
      }
    }
  ]
}
```

**Error message**:

```text
error 300: element "test" filter: incorrect format of element filter
```

## Error Code 301

An unknown action is defined for a basic element.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "selector %s",
        "returnAll": true,
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ]
      },
      "filter": {
        "apply": "wrong",
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ],
        "matcher": {
          "type": "isTrue"
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 301: element "test" filter: unknown action "wrong" for basic element
```

## Error Code 302

A filter can only be set for a list element. See [List and Index](/docs/platform/utam/references/utam-grammar/element-lists.html).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "css"
      },
      "filter": {
        "apply": "isVisible",
        "matcher": {
          "type": "isTrue"
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 302: element "test" filter: filter can only be set for list
```

## Error Code 303

An unsupported action is defined for this element type. See [Basic Element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#basic-elements).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "type": "touchable",
      "selector": {
        "css": "selector %s",
        "returnAll": true,
        "args": [
          {
            "name": "arg1",
            "type": "string"
          }
        ]
      },
      "filter": {
        "apply": "click",
        "matcher": {
          "type": "isTrue"
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 303: element "test" filter: unsupported action "click" for type "touchable"
```

## Error Code 400

An interface is incorrectly defined. Declare an interface's API as an array of objects in the `methods` property. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "interface": true,
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "apply": "getText"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 400: method "test": incorrect format of abstract method
```

## Error Code 401

Reserved for future use.

## Error Code 402

A `returnAll` property can't be set in an interface without setting a `returnType` property. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "interface": true,
  "methods": [
    {
      "name": "test",
      "returnAll": true
    }
  ]
}
```

**Error message**:

```text
error 402: abstract method "test": "returnAll" property can't be set without setting return type
```

## Error Code 403

An unsupported `returnType` property for an interface was defined. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "interface": true,
  "methods": [
    {
      "name": "test",
      "returnType": "container"
    }
  ]
}
```

**Error message**:

```text
error 403: abstract method "test": return type "container" is not supported
```

## Error Code 500

The compose method is incorrectly formatted. See [Compose Method](/docs/platform/utam/references/utam-grammar/methods.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "unsupportedProperty": "value",
      "compose": [
        {
          "element": "root"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 500: method "test": incorrect format of compose method
```

## Error Code 501

An argument at the method level can't have an `argumentReference` type. See [Argument Reference](/docs/platform/utam/references/utam-grammar/arguments.html#argument-reference).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "args": [
        {
          "name": "arg1",
          "type": "argumentReference"
        }
      ],
      "name": "test",
      "compose": [
        {
          "apply": "something"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 501: method "test" arguments: parameter "arg1" at method level can't have type "argumentReference"
```

## Error Code 502

An `argumentReference` is used but there's no matching argument defined at the method level. See [Argument Reference](/docs/platform/utam/references/utam-grammar/arguments.html#argument-reference).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "something",
          "args": [
            {
              "name": "arg1",
              "type": "argumentReference"
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 502: method "test": statement declares a reference to an "arg1" argument, but there is no matching argument at the method level
```

## Error Code 503

A declared argument is never used.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "args": [
        {
          "type": "string",
          "name": "arg"
        }
      ],
      "name": "test",
      "compose": [
        {
          "apply": "someMethod"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 503: method "test": declared parameter "arg" is never used
```

## Error Code 504

A duplicate method name is declared. This can be fixed by renaming one of the methods.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "method1",
      "compose": [
        {
          "apply": "someMethod1"
        }
      ]
    },
    {
      "name": "method1",
      "compose": [
        {
          "apply": "someMethod2"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 504: method "method1": method with the same name was already declared
```

## Error Code 505

The name of a method will duplicate the name of a generated method.

In the example below, the compiler will generate a helper function for the `test` element named `waitForTest`.
Because there is a declared method with the same name, an error is thrown.
To fix this, rename the element or the method.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": "div"
      },
      "wait": true,
      "public": true
    }
  ],
  "methods": [
    {
      "name": "waitForTest",
      "compose": [
        {
          "element": "test"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 505: method "waitForTest": the given method name would duplicate the name of a generated helper function for element "test"
```

## Error Code 600

The compose statement is incorrectly formatted. See [Compose Method](/docs/platform/utam/references/utam-grammar/methods.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "returnSelf",
          "element": "document"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 600: method "test" statement: incorrect compose statement format
```

## Error Code 601

A compose statement references an unknown element.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "test"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 601: method "test" statement: unknown element with name "test" is referenced in a compose statement
```

## Error Code 602

A compose statement is using an unsupported `returnType` property. See [Method Return Types](/docs/platform/utam/references/utam-grammar/method-return-types.html#supported-return-types).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "returnType": "container"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 602: method "test" statement: return type "container" is not supported in a compose statement
```

## Error Code 603

A compose statement with a `returnAll` property must also have a `returnType` property. See [Compose Method](/docs/platform/utam/references/utam-grammar/methods.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "returnAll": true
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 603: method "test" statement: "returnAll" property can't be set without setting return type in a compose statement
```

## Error Code 605

The return type for `element` can't be inferred. Please add a `returnType` property.

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "element",
      "type": "my/pageobject/foo",
      "selector": {
        "css": "css"
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "element"
        },
        {
          "chain": true,
          "element": "element"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 605: method "test" statement: can't infer return type for "element", please provide a "returnType"
```

## Error Code 606

An `element` property is redundant because it's a chain statement. See [Chain Compose Statements](/docs/platform/utam/references/utam-grammar/methods.html#chain-compose-statements).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "element",
      "type": "my/custom/type",
      "selector": {
        "css": "css"
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "element"
        },
        {
          "chain": true,
          "element": "element",
          "apply": "method"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 606: method "test" statement: "element" property is redundant because statement is marked as a chain
```

## Error Code 607

Only a `document` or `root` element is allowed in a `beforeLoad` statement. See [beforeLoad](/docs/platform/utam/references/utam-grammar/explicit-waits.html#beforeload).

**Incorrect JSON example**:

```json
{
  "beforeLoad": [
    {
      "element": "test",
      "apply": "getAttribute"
    }
  ]
}
```

**Error message**:

```text
error 607: method "beforeLoad" statement: only "document" or "root" elements are allowed
```

## Error Code 608

A "returnSelf" statement can only be invoked from the last statement. See [returnSelf statement](/docs/platform/utam/references/utam-grammar/methods.html#returnself-statement).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "returnSelf"
        },
        {
          "apply": "someMethod"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 608: method "test" statement: "returnSelf" can only be invoked from the last statement
```

## Error Code 609

A compose method must define either an `element`, `apply`, or `applyExternal` property. See [Compose Method](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/methods.md) and [Imperative Extensions](/docs/platform/guide/imperatives.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [{}]
    }
  ]
}
```

**Error message**:

```text
error 609: method "test" statement: either "element" or "apply" or "applyExternal" should be defined
```

## Error Code 610

A compose method can define either an `apply` or `applyExternal` property, but not both. See [Compose Method](/docs/platform/utam/references/utam-grammar/methods.html) and [Imperative Extensions](/docs/platform/guide/imperatives.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "apply": "getText",
          "applyExternal": {}
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 610: method "test" statement: either "apply" or "applyExternal" should be defined"
```

## Error Code 611

A compose statement that uses an `applyExternal` property can't also use `element` or `apply` properties.

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "applyExternal": {}
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 611: method "test" utility statement: "element" property is redundant
```

## Error Code 612

This method isn't supported for this basic element type. See [Basic Actions](/docs/platform/utam/references/utam-grammar/basic-actions.html).

**Incorrect JSON example**:

```json
{
  "exposeRootElement": true,
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "click",
          "element": "root"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 612: method "test" statement: unknown method "click" for basic element
```

## Error Code 613

The compose statement has an unexpected `returnType` property. See [Method Return Types](/docs/platform/utam/references/utam-grammar/method-return-types.html#supported-return-types).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "element",
      "selector": {
        "css": "css"
      },
      "type": ["actionable"]
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "returnType": "string",
          "element": "element"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 613: method "test" statement: incorrect return type; expected "ElementElement", provided is "String"
```

## Error Code 614

Chains are supported only if the previous statement returns a custom type (another page object). See [Chain Compose Statements](/docs/platform/utam/references/utam-grammar/methods.html#chain-compose-statements).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "element",
      "selector": {
        "css": "css"
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "element"
        },
        {
          "chain": true,
          "element": "element"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 614: method "test" statement: to use chain, previous statement should return custom type, but it returns "BasicElement"
```

## Error Code 615

A nested `waitFor` statement isn't supported. See [Explicit Waits](/docs/platform/utam/references/utam-grammar/explicit-waits.html).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "apply": "waitFor",
                  "args": [
                    {
                      "type": "function",
                      "predicate": [
                        {
                          "apply": "invoke"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 615: method "test" statement: nested waitFor is not supported
```

## Error Code 616

The first statement in a compose method can't set `chain` to `true`. See [Chain Compose Statements](/docs/platform/utam/references/utam-grammar/methods.html#chain-compose-statements).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "root",
          "chain": true
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 616: method "test" statement: first statement can't be marked as chain
```

## Error Code 617

This method isn't supported for this element type. See [Basic Actions](/docs/platform/utam/references/utam-grammar/basic-actions.html).

**Incorrect JSON example**:

```json
{
  "type": ["editable"],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "apply": "click",
          "element": "root"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 617: method "test" statement: unsupported action "click" for type "Editable"
```

## Error Code 700

The `description` property is incorrectly formatted. See [Page Object Description](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html#page-object-description).

**Incorrect JSON example**:

```json
{
    "elements",
        [
          {
            "name": "test",
            "description": true,
            "selector": {
                "css": "css"
            }
          }
        ]
}
```

**Error message**:

```text
error 700: element "test" description: format of the description is incorrect
```

## Error Code 800

The `profile` property is incorrectly formatted. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [{}],
  "implements": "my/pageobjects/type"
}
```

**Error message**:

```text
error 800: profile format is incorrect
```

## Error Code 801

The profile name is a duplicate. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "name": "value"
    },
    {
      "name": "value"
    }
  ],
  "implements": "my/pageobjects/type"
}
```

**Error message**:

```text
error 801: "profile": duplicate profile name "name"
```

## Error Code 802

The profile has a duplicate value. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
    "profile": [
        {
            "name":
            ["same", "same"]
        }
    ]
    "implements", "my/pageobjects/type"
}
```

**Error message**:

```text
error 802: profile "name": duplicate profile value "same"
```

## Error Code 803

The profile isn't configured. Make sure that the profile is in the compiler configuration file. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "name": "error"
    }
  ],
  "implements": "my/pageobjects/type"
}
```

**Error message**:

```text
error 803: profile { "name": "error" } is not configured, make sure it's in compiler config
```

## Error Code 804

A profile with this name isn't configured. Make sure that the profile is in the compiler configuration file. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "name1": "value1"
    }
  ],
  "implements": "my/pageobjects/type"
}
```

**Error message**:

```text
error 804: profile with name "name1" is not configured, make sure it's in compiler config
```

## Error Code 805

A profile can only be set for a page object that also sets the `implements` property. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "profile": "test"
    }
  ]
}
```

**Error message**:

```text
error 805: "profile" can only be set for a page object that implements an interface
```

## Error Code 806

A profile value can either be a string or a non-empty string array. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "profile": [
    {
      "name": {}
    }
  ],
  "implements": "my/pageobjects/type"
}
```

**Error message**:

```text
error 806: profile "name": values can either be string or non-empty string array
```

## Error Code 900

The page object is incorrectly formatted.

**Incorrect JSON example**:

```json
{
  "error": true
}
```

**Error message**:

```text
error 900: incorrect format of the page object. Unrecognized field "error".
```

## Error Code 901

A non-root page object can't have a `selector` property. Either remove the `selector` property or add `"root": true`. See [Root Element](/docs/platform/utam/references/utam-grammar/root-elements.html).

**Incorrect JSON example**:

```json
{
  "selector": {
    "css": "rootSelector"
  }
}
```

**Error message**:

```text
error 901: non-root page object can't have selector
```

## Error Code 902

A root page object requires a `selector` property. Either add a `selector` property or remove `"root": true`. See [Root Element](/docs/platform/utam/references/utam-grammar/root-elements.html).

**Incorrect JSON example**:

```json
{
  "root": true
}
```

**Error message**:

```text
error 902: root page object requires "selector" property
```

## Error Code 903

The `platform` property value must be either `web` or `native`. See [Interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**Incorrect JSON example**:

```json
{
  "platform": "wibblywobblywonder"
}
```

**Error message**:

```text
error 903: "platform" property: platform should be a string with "web" or "native" value, instead found "wibblywobblywonder"
```

## Error Code 904

The `beforeLoad` property can't have arguments. See [beforeLoad](/docs/platform/utam/references/utam-grammar/explicit-waits.html#beforeload).

**Incorrect JSON example**:

```json
{
  "beforeLoad": [
    {
      "element": "root",
      "apply": "getAttribute",
      "args": [
        {
          "type": "string",
          "name": "str"
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 904: method "beforeLoad" cannot have parameters
```

## Error Code 905

The root `description` property is incorrectly formatted. See [Page Object Description](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html#page-object-description).

**Incorrect JSON example**:

```json
{
  "description": true
}
```

**Error message**:

```text
error 905: format of the root description is incorrect
```

## Error Code 1000

The `selector` property is incorrectly formatted. See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": "selector"
    }
  ]
}
```

**Error message**:

```text
error 1000: element "test": format of selector is incorrect
```

## Error Code 1002

The `selector` must contain `css`, `accessid`, `uiautomator`, or `classchain` properties. See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "root": true,
  "selector": {}
}
```

**Error message**:

```text
error 1002: element "root" selector: one of "css", "accessid", "uiautomator" or "classchain" should be set"
```

## Error Code 1003

The root `selector` can only be one of "css", "accessid", "uiautomator", or "classchain". See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "root": true,
  "selector": {
    "css": "css",
    "accessid": "accessid"
  }
}
```

**Error message**:

```text
error 1003: element "root" selector: only one of "css", "accessid", "uiautomator" or "classchain" can be set
```

## Error Code 1004

The `selector` is using an invalid `UiSelector` method. See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "uiautomator": "new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().unsupported())"
      }
    }
  ]
}
```

**Error message**:

```text
error 1004: element "test" selector: unsupported UiSelector method "unsupported", supported methods are checkable, checked, classname, description, descriptioncontains, descriptionstartswith, enabled, selected, resourceid, resourceidmatches
```

## Error Code 1005

The `classchain` property in the selector is using unsupported quotes. See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "selector": {
    "classchain": "**/XCUIElementTypeStaticText[\"label == 'something'\"]"
  },
  "root": true
}
```

**Error message**:

```text
error 1005: element "root" selector "label == 'something'": for class chain only one of supported quotes can be set, supported are $,`
```

## Error Code 1006

The `classchain` property in the selector can set only one of the supported operators. See [Element Selector](/docs/platform/utam/references/utam-grammar/element-selectors.html).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "classchain": "**/XCUIElementTypeStaticText[`label=='something'`]"
      }
    }
  ]
}
```

**Error message**:

```text
error 1006: element "test" selector "`label=='something'`": for class chain only one of supported operators can be set, supported are ==,BEGINSWITH,ENDSWITH,CONTAINS,OR,AND
```

## Error Code 1100

The `elements` property inside `shadow` is incorrectly formatted. See [Root Element](/docs/platform/utam/references/utam-grammar/root-elements.html).

**Incorrect JSON example**:

```json
{
  "shadow": {
    "elements": [{}]
  }
}
```

**Error message**:

```text
error 1100: root shadow: incorrect format of elements inside shadow
```

## Error Code 1200

The `matcher` property is incorrectly formatted. See [Matchers](/docs/platform/utam/references/utam-grammar/element-filters.html#matchers).

**Incorrect JSON example**:

```json
{
  "name": "test",
  "selector": {
    "css": ".css",
    "returnAll": true
  },
  "filter": {
    "apply": "getText",
    "matcher": {
      "typemisprinted": "stringEquals"
    }
  }
}
```

**Error message**:

```text
error 1200: element "test" filter: incorrect format of matcher
```

## Error Code 1201

The filter matcher type isn't supported. See [Matchers](/docs/platform/utam/references/utam-grammar/element-filters.html#matchers).

**Incorrect JSON example**:

```json
{
  "elements": [
    {
      "name": "test",
      "selector": {
        "css": ".helloworld",
        "returnAll": true
      },
      "type": "vanilla-js/pageObjects/counter",
      "filter": {
        "apply": "getText",
        "matcher": {
          "type": "invalid"
        }
      }
    }
  ]
}
```

**Error message**:

```text
error 1201: element "test" filter matcher: unsupported matcher type "invalid", supported are isTrue, isFalse, notNull, stringContains, stringEquals
```

## Error Code 1202

The `apply` method returns a type that's incompatible with the `matcher`. See [Matchers](/docs/platform/utam/references/utam-grammar/element-filters.html#matchers).

**Incorrect JSON example**:

```json
{
  "methods": [
    {
      "name": "matcherThrows",
      "compose": [
        {
          "element": "root",
          "apply": "getText",
          "matcher": {
            "type": "isTrue"
          }
        }
      ]
    }
  ]
}
```

**Error message**:

```text
error 1202: method "matcherThrows" statement matcher: applied method returns type "String", which is only compatible with the following matchers - stringContains, stringEquals, notNull
```

<!-- document id=93d8c0480ef05fe4779945674dcfc35514cdab8e9e9c8598c9dbbdc656ef8cd1 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-escape-xml-characters.md -->

# Escape Special XML Characters in Default Values

The `default` attribute of a property type lets you set a value for the property before an end user has a chance to change the input. Setting the default value of a custom property type from the `js-meta.xml` file requires you to escape any special characters in that value.

It's standard practice in XML documents to ensure that special characters in a value don't affect the validity of the whole XML document. (This consideration generally doesn't apply to primitive types.) For properties that directly or indirectly reference a custom property type that's defined in its schema as `lightning__objectType`, `lightning__dateTimeType`, or `lightning__richTextType`, you may need to escape special characters in those values.

For example, if a component has a property tag that uses `lightning__richTextType`, this is how to specify any HTML or XML usage in the `default` attribute that you'd have to escape, such as "\<strong\>bold text\</strong\>."

```xml
<property name="richTextProperty" type="lightning__richTextType" default="&gt;&lt;strong&gt;bold text&lt;/strong&gt;" />
```

Similarly, if a component has a property type reference that uses the `lightning__objectType`, this is how to specify a default object value such as "{"state":"California", "city":"San Francisco"}".

```xml
<property name="addressProperty" type="c__addressType" default="{&quot;state&quot;:&quot;California&quot;,&quot;city&quot;:&quot;San Francisco&quot;}" />
```

<!-- document id=b19c7f601f5ba54e8f22915bf48a9e1d3ad90f61027ed25942218efb4a2f2d66 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-js-eval.md -->

# eval() Function Is Limited by Lightning Locker

In Lightning Locker, use of the `eval()` function is supported to enable use of third-party libraries that evaluate code dynamically. However, it’s limited to work only in the global scope of the namespace. The `eval()` function can’t access the local variables within the scope in which it’s called.

Normally, `eval()` has two modes of execution. When you invoke `eval()` directly, it works in the local scope. When you invoke it via a reference, it works in the global scope. Lightning Locker only supports the latter.

For example, suppose that you execute this code:

```javascript
window.foo = 1;
function bar() {
  var foo = 2;
  return eval("foo");
}
```

A call to `bar()` returns 2 when evaluation is performed in the local scope, and returns 1 when it’s performed in the global scope. If you must use variables from the local scope, refactor your code. Use a `Function()`, declare the local variables as parameters, pass them as arguments, and add a return statement:

```javascript
window.foo = 1;
function bar() {
  var foo = 2;
  return Function("foo", "return foo")(foo);
}
```

**tip:** Lightning Web Security doesn’t limit `eval()` to the global scope because the code executes in a sandbox. However, invoking `eval()` directly in local scope is still not recommended.

<!-- document id=fc3694b8369b4cfeba32790148e5a25951fba4dc3e3f64e77d60f85154804151 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-console-evaluate.md -->

# Evaluate JavaScript Code Compatibility with Lightning Locker

Ensure that your code is compatible with Lightning Locker by running the code with Locker enabled. Run the code a second time with Locker disabled to see if any errors are due to Lightning Locker restrictions.

Let's look at an example that uses a prohibited DOM API.

1. Paste this code into the console.

   ```javascript
   var controller = new AbortController();
   controller;
   ```

2. Click **Evaluate**.

   Note the error in the LOCKER ON column of the results window.

   ```
   Error: AbortController is not a constructor
   ```

   You get this error because `AbortController` is an experimental interface in the DOM API and is not allowed by Lightning Locker.

   The LOCKER OFF column shows N/A as this column isn't relevant when the Locker toggle is enabled.

3. Click the **Locker** toggle to disable Lightning Locker.

4. Click **Evaluate** to rerun the code sample with Lightning Locker disabled.

   The second row of the results window shows there's no longer an error when Lightning Locker is disabled. The LOCKER OFF column shows [object AbortController], which is the return value of the sample code.

   ![Locker Console Example with prohibited DOM API.](https://developer.salesforce.com/media/locker_console_evaluate.png '{"class": "image-framed", "title": "Locker Console Example with prohibited DOM API"}')

Use the Locker API Viewer to see the DOM APIs exposed by Lightning Locker versus the standard DOM APIs for the most complex wrappers: `SecureDocument`, `SecureElement`, and `SecureWindow`.

**See Also**

- [Locker Console Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console.md)
- [Lightning Locker API Viewer Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-api-viewer.md)

<!-- document id=2e15f5f41a01764f7400dcc2e5e5f159211aff60c5b43ce5eb32d5f247caf964 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-tools-console.md -->

# Evaluate JavaScript in Lightning Web Security Console

Evaluate your code in Lightning Web Security (LWS) Console as it runs with LWS enabled and disabled. This tool can help you determine if a problem with your JavaScript code is related to its interaction with LWS.

Lightning Web Security Console is available in the Tools area of the [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience) and the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components).

Here’s a direct link to the tool: [https://developer.salesforce.com/tools/lws-console](https://developer.salesforce.com/tools/lws-console)

## Explore LWS Console

Here’s an overview of the LWS Console user interface.

![Lightning Web Security Console functionality](https://developer.salesforce.com/media/lws-console-callouts.png '{"class": "image-framed"}')

- Code console (1)

  - : To evaluate your JavaScript code, paste or type code into the code console.

- Actions (2)

  - :
    - Enable or disable LWS.
    - To run the code that’s displayed in the code console, click **Evaluate**.
    - To clear the results, but not the code in the code console, click **Clear**.
    - Select **LWC** or **Aura**, depending on which type of component is using your JavaScript. LWS applies similar distortions to Lightning web components (LWC) and Aura components. However, the runtime environment is different for the component types, which can cause LWS to block some properties in Aura components that are allowed in LWC.

- Results of evaluation (3)

  - : Shows the results of the LWS evaluation, including error messages returned from distortions.

- Linting results (4)

  - : Shows the [LWS ESLint rules](https://github.com/salesforce/lwsec-docs-mirror/tree/main/packages/%40locker/eslint-plugin-locker/docs/rules) that were triggered during the evaluation.

When you click **Evaluate**, Lightning Web Security Console sets up the execution environment, and then runs the code in a JavaScript sandbox environment in your browser. Any errors from running the code are displayed in the upper right panel. Otherwise the tool reports Success.

**tip:** If a distortion’s effect is to enable the code to run safely in the sandbox, the tool reports Success, and doesn’t indicate that a distortion was applied. If a distortion prevents the code from executing, the tool reports the error generated by the distortion.

## Considerations for Using LWS Console

LWS Console simulates the behavior of LWS running in a Salesforce org. The console provides an environment to execute your code with LWS so you can do a quick check while developing your components’ JavaScript. The console can’t create the complete execution environment of an org, so you **must** still perform functional testing within a sandbox before using the components in production.

LWS Console doesn’t evaluate JavaScript modules containing `import` or `export` statements or Lightning web component decorators such as `@api` and `@wire`. The tool is designed to evaluate pure JavaScript only, and it only evaluates JavaScript pasted into the code console.

**See Also**

- [Troubleshoot Issues Related to Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-troubleshoot.md)
- [_Lightning Web Components Developer Guide_: Debug Lightning Web Components](/docs/platform/lwc/guide/debug-intro.html)
- [_Lightning Aura Components Developer Guide_: Debugging](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/debug_intro.htm)

<!-- document id=2fce48ffab58d7038b85b881b8e8374f66c492532cfe1026ebb32a958ea5f646 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-evaluate-learning-item.md -->

# `evaluateLearningItem`

Use this wire adapter to check whether the criteria for completing a custom exercise in an Enablement program are satisfied.

## Syntax

```javascript
import { evaluateLearningItem } from 'lightning/uiLearningPlatformApi';

evaluateLearningItem({
    learningItemId: "04Qxx00000003AnEAI",
    details: {
        customComponent: "customComponent"
    }
}): Promise<LearningItemProgress>
```

<!-- no API Resource section included because the corresponding Connect API isn't public yet -->

## Parameters

| Parameter Name   | Type   | Description                                                                                                                                                                                                  | Required?                               |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `learningItemId` | String | The ID of the LearningItem record to evaluate.                                                                                                                                                               | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `details`        | Object | An optional `Map<String, Object>` that includes any additional information required for evaluating the learning item. The LearningItemType record that represents the custom exercise defines this criteria. |                                         |

## Returns

- A Promise object that resolves when the custom exercise's corresponding LearningItemProgress response is returned. The response includes:
  - `id`—The ID of the LearningItemProgress record.
  - `learningItemId`—The ID of the LearningItem record that was evaluated.
  - `completedPercent`—Percentage of the learning item that’s complete.
  - `completedDate`—The date when the user completed the learning item.
  - `isCompleted`—Whether the learning item is complete. The default value is false.
- `error`—A validation error for invalid fields.

## Usage

This example passes only the required `learningItemId`.

```javascript
import { evaluateLearningItem } from 'lightning/uiLearningPlatformApi';

class Example extends LightningElement {
   evaluateLearningItem({
        learningItemId: "04Qxx00000003AnEAI"
    }).then(() => {
        //handle success
    })
}
```

This example evaluates a user's progress through a custom exercise that uses a screen flow. The optional `details` parameter includes information about the user's current screen and the screens that the user has navigated already.

```javascript
import getScreenNames from '@salesforce/apex/ResourceController.getScreenNames';
import { evaluateLearningItem } from 'lightning/uiLearningPlatformApi';

class Example extends LightningElement {
    screenNames;
    evaluateLearningItem({
        learningItemId: "04Qxx00000003AnEAI",
        details: {
            status: event.detail.status,
            currentScreen: event.detail.locationName,
            allScreens: this.screenNames.join(',')
          }
    }).then(() => {
        //handle success
    })
}
```

**See Also**

- _Object Reference for the Salesforce Platform_: [LearningItem](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_learningitem.htm)
- _Object Reference for the Salesforce Platform_: [LearningItemProgress](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_learningitemprogress.htm)
<!-- 
These links won't work until 252 content is live.


- _Object Reference for the Salesforce Platform_: [LearningItemType](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_learningitemtype.htm)
- _Sales Programs and Partner Tracks with Enablement Developer Guide_: [Create Custom Exercises for Enablement Programs](https://developer.salesforce.com/docs/sales/enablement/guide/custom-exercises-intro.html)

-->

<!-- document id=a7dcaf9ee55997921fb516d4dd71634b53cbe089cf9fb6b52d3cccda36880ea5 url=/developer/current/en-us/lwc/lwc/guides/events/events-best-practices.md -->

# Events Best Practices

We recommend following these best practices when working with events.

- `CustomEvent.detail`

  - : To communicate data to elements in the same shadow tree, don’t add `myProperty` into `event.detail`. The consumer of the event can use the `event.target.myProperty`.

    To communicate data to elements that aren’t in the same shadow tree, use `event.detail`. In these cases, `event.target.*` doesn’t work because the real target isn’t visible to the listener. (When an event bubbles up the DOM, if it crosses the shadow boundary, the value of `Event.target` changes to match the scope of the listener. The event is retargeted so the listener can’t see into the shadow tree of the component that dispatched the event.)

    If you do use `detail`, use [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) types. JavaScript passes all data types by reference except for primitives. If a component includes an object in its `detail` property, any listener can mutate that object without the component’s knowledge, which is a bad thing!

    It is possible to avoid leaking internal state when using a non-primitive type. Before you add data to the `detail` property, copy it to a new object or array. Copying the data to a new object ensures that you’re sending only the data you want, and that the receiver can’t mutate your data.

    Don’t include the non-primitive from `@api` or `@wire` in `detail`. These values are wrapped in a read-only membrane. [In IE 11](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md), when crossing the LWC to Aura bridge, the read-only membrane is lost, which means that mutation can occur.

- Event Propagation

  - : Use events configured with `bubbles: false` and `composed: false` because they're the least disruptive. These events don’t bubble up through the DOM and don’t cross the shadow boundary.

    Bubbling and composed events are not recommended because they bubble up the entire DOM tree, across shadow boundaries, and through parent components (unless stopped). If you configure an event with `bubbles: true` and `composed: true`, the event type becomes part of the component’s public API. It also forces the consuming component and all of its ancestors to include the event as part of their APIs. It's a big API contract to sign up for. If you do use this configuration, the event type should be globally unique.

**See Also**

- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/events/events-create-dispatch.md)
- [Configure Event Propagation](https://developer.salesforce.com/docs/platform/lwc/events/events-propagation.md)
- [_MDN web docs_: CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail)

<!-- document id=def0df20723a4562135a9515fddbc38d5e1210f3ace57184915794757033dc61 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-to-custom-reactive-example.md -->

# Example: Custom Lightning Web Component to Custom Lightning Web Component

Make a custom lightning web component react to another custom component.

This example assumes both the `customText` component and the `colorName`component have been added to the Flow Builder. The `customText`component is used to control `colorName` component.

1.  Add the `customText` component and the `colorName` component and provide labels for each.
2.  In the `colorName` component’s Name of Color field, choose the `customText` component as the source.

Any changes made to the `customText` component are automatically reflected in the color public field inside of `colorName`. For example, entering `magenta` into the `customText` input results in the `colorName` displaying the color name styled with the same color, magenta.

<!-- document id=3e34e8c7b789ded83db666ce010f74318213381c6b7ad0e2729f33931a33d742 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-to-standard-reactive-example.md -->

# Example: Custom Lightning Web Component to Standard Flow Component

Make your custom text component react to a standard Flow component.

1.  Create a public field with the `@api` decorator as referenced in `customText.js` example.
2.  Add the target configuration in the `.js-meta.xml` file with the appropriate type as referenced in the `customText.js-meta.xml` example.
3.  Add an input field attached with an event handler to store the user input.
4.  In the event handler, fire a `FlowAttributeChange` event defined in the [`flow-support` component](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow-support). The `FlowAttributeChange` event name must match the name of the public field in order for reactivity to work. Due to the nature of the Flow Runtime, the setter method is called after the `FlowAttributeChange` event is fired and it is invoked when reactivity leads to a change to the public field.
5.  After you create the custom component, add the component to the Flow builder with a label.
6.  To make the Text component react to the custom component, configure the default value’s source on the Text component to the custom component’s public property.

<!-- prettier-ignore -->
```html
<!-- customText.html -->
<template>
  <lightning-input type="text" label="This is custom text" onchange={handleInputChange}>
  </lightning-input>
</template>
```

```javascript
// customText.js
import { LightningElement, api, track } from "lwc";
import { FlowAttributeChangeEvent } from "lightning/flowSupport";

export default class customText extends LightningElement {
  @track _input;

  @api
  set customTextValue(input) {
    if (input) {
      this._input = input;
    }
  }
  get customTextValue() {
    return this._input;
  }

  handleInputChange(event) {
    const attributeChangeEvent = new FlowAttributeChangeEvent(
      "customTextValue",
      event.target.value,
    );
    this.dispatchEvent(attributeChangeEvent);
  }
}
```

```xml
// customText.js-meta.xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
 <apiVersion>52.0</apiVersion>
 <isExposed>true</isExposed>
 <masterLabel>Custom Text</masterLabel>
 <description>Custom Text Example</description>
 <targets>
     <target>lightning__FlowScreen</target>
 </targets>
<targetConfigs>
      <targetConfig targets="lightning__FlowScreen">
          <property name="customTextValue" label="Custom Text Value" type="String" />
      </targetConfig>
</targetConfigs>
</LightningComponentBundle>
```

**See Also**

- [Runtime Considerations for Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-runtime-considerations.md)

<!-- document id=6a876463c6ec0a287cfc50e5a3f3140f927b556b09c1f835095e5d4ff7de298c url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-lwc-example.md -->

# Example: Custom Property Editor for a Screen Component

This example creates a custom property editor for a custom flow screen component that displays a volume. The admin sets the volume using a slider in the volume component’s custom property editor. When users run the flow, the flow screen shows the volume level that the admin set.

![Flow screen at run time.](https://developer.salesforce.com/media/flow_custom_property_editor_screen_runtime.png)

The following HTML, JavaScript, and configuration files define the `volume` custom flow screen component.

<!-- prettier-ignore -->
```html
<!--volume.html-->
<template>
  <div>
    <h1 class="slds-text-heading_medium">Volume</h1>
  </div>

  <div class="slds-p-top_xxx-small">
    <p>
      Your selected volume is:
      <lightning-formatted-number value={volume}></lightning-formatted-number>
    </p>
  </div>
</template>
```

The JavaScript class defines a `volume` public property.

```javascript
// volume.js
import { LightningElement, api } from "lwc";

export default class Volume extends LightningElement {
  @api volume;
}
```

To expose the `volume` public property in Flow Builder, define it in the configuration file: `<property name="volume" type="Integer"/>`. The `role` attribute determines whether the property can receive input from the flow or not. The default value, which is used in this example, is `inputAndOutput`. To make a property available for input or output only, set the `role` attribute to `inputOnly` or `outputOnly`.

In the configuration file, use the `configurationEditor` attribute to register the custom property editor: `<targetConfig targets="lightning__FlowScreen" configurationEditor="c-volume-editor">`. Use the `c` namespace unless the org has a custom namespace. If the org has a custom namespace, use that namespace.

```xml
<!-- volume.js-meta.xml-->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>49.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__FlowScreen</target>
  </targets>
  <masterLabel>Volume</masterLabel>
  <targetConfigs>
    <targetConfig targets="lightning__FlowScreen" configurationEditor="c-volume-editor">
      <property name="volume" type="Integer"/>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

The following HTML, JavaScript, and configuration files define the custom property editor for the `volume` component.

![Custom property editor that uses a slider component to set an input value](https://developer.salesforce.com/media/flow_custom_property_editor_volume.png)

The custom property editor’s HTML template defines the UI, which uses a slider Lightning base component.

<!-- prettier-ignore -->
```html
<!--volumeEditor.html-->
<template>
  <div class="slds-p-around_xx-small">
    <lightning-slider label="Volume" step="10" value={volume} onchange={handleChange}>
    </lightning-slider>
  </div>
</template>
```

When the custom property editor is initialized, its JavaScript class receives a copy of the flow metadata from Flow Builder. When the admin makes an update in the custom property editor, it dispatches an event to propagate the change back to Flow Builder.

**note:** Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```javascript
// volumeEditor.js
import { LightningElement, api } from "lwc";

export default class VolumeEditor extends LightningElement {
  _inputVariables = [];

  @api
  get inputVariables() {
    return this._inputVariables;
  }

  // Set a field with the data that was stored from the flow.
  // This data includes the public volume property of the custom volume
  // component.
  set inputVariables(variables) {
    this._inputVariables = variables || [];
  }

  // Get the value of the volume input variable.
  get volume() {
    const param = this.inputVariables.find(({ name }) => name === "volume");
    return param && param.value;
  }

  @api
  validate() {
    const volumeCmp = this.template.querySelector("lightning-slider");
    const validity = [];
    if (this.volume < 0 || this.volume > 100) {
      volumeCmp.setCustomValidity("The slider range is between 0 and 100.");
      validity.push({
        key: "Slider Range",
        errorString: "The slider range is between 0 and 100.",
      });
    } else {
      volumeCmp.setCustomValidity("");
    }
    volumeCmp.reportValidity();
    return validity;
  }

  handleChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
          name: "volume",
          newValue,
          newValueDataType: "Number",
        },
      });
      this.dispatchEvent(valueChangedEvent);
    }
  }
}
```

Flow Builder has a [JavaScript interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md) for communicating with a custom property editor. This JavaScript class uses the `inputVariables` and `validate` interfaces.

This example defines the getter and setter for `inputVariables`. When the custom property editor is initialized, the setter for `inputVariables` receives the values of the public properties in the screen component from Flow Builder. In this example, we use a convention of storing the flow metadata in an `_inputVariables` field, but you can name the field whatever you like.

The data structure in `_inputVariables` includes the name, value, and data type for each input variable.

```javascript
[
  {
    name: "volume",
    value: "10",
    valueDataType: "Number",
  },
];
```

The `volume` method gets the `value` for the `volume` property for use in the volume UI.

When an admin clicks **Done** in Flow Builder’s screen editor UI, Flow Builder evaluates the `validate` function in each custom property editor. If the function returns the `key` and `errorString` data structure, Flow Builder shows the number of errors and prevents the admin from saving changes in the screen editor.

**note:** Flow Builder shows only the number of errors. To show error strings, write code. This example uses the `lightning-slider` component’s `setCustomValidity()` function to display a custom error message. Use the `validate` interface method.

When an admin enters a value for volume in the custom property editor, the `handleChange` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

This is the configuration file for `volumeEditor`.

```xml
<!--volumeEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>49.0</apiVersion>
  <!--isExposed can be true or false-->
  <isExposed>true</isExposed>
</LightningComponentBundle>
```

<!-- document id=7f1004328b369666d8307a0c356acd051df9dbcd42cd76c4ebc0ea6c4e60d961 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-action-example.md -->

# Example: Custom Property Editor for an Invocable Action

This example creates an invocable action and its custom property editor. In Flow Builder, an admin sets input values for the Send HTML Email invocable action. When users run the flow, the invocable action sends the email.

This Apex class file defines the `sendEmails` method that can run as an invocable action and its input variables. The `@InvocableMethod` annotation identifies the invocable method that can run as an invocable action. The `@InputVariable` annotation identifies variables used by the invocable method.

The invocable method registers the custom property editor in the `configurationEditor` modifier. The namespace is `c` unless the org has a custom namespace. If the org has a custom namespace, use that namespace to register the custom property editor. For this example, the name of the custom property editor is `c-html-email-editor`.

```apex
// HtmlEmailAction.cls
global class HtmlEmailAction {
    global class EmailActionRequest {
        @InvocableVariable
        global String senderName;

        @InvocableVariable
        global String replyToEmail;

        @InvocableVariable
        global String recipientName;

        @InvocableVariable
        global String sendToEmail;

        @InvocableVariable
        global String subject;

        @InvocableVariable
        global String htmlBody;
    }

    global class EmailActionResult {
        @InvocableVariable
        global Boolean isSuccess;

        @InvocableVariable
        global String errorMessage;
    }

    @InvocableMethod(label='Send HTML Email' configurationEditor='c-html-email-editor')
    global static List<EmailActionResult> sendEmails(List<EmailActionRequest> requests) {
        List<EmailActionResult> results = new List<EmailActionResult>();

        for(EmailActionRequest request : requests){
            results.add(sendEmail(request));
        }

        return results;
    }

    public static EmailActionResult sendEmail(EmailActionRequest request) {
        Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();

        String[] sendToEmail = new String[]{ request.sendToEmail };
        mail.setToAddresses(sendToEmail);
        mail.setSenderDisplayName(request.senderName);
        mail.setReplyTo(request.replyToEmail);
        mail.setSubject(request.subject);
        mail.setHtmlBody(request.htmlBody);
        mail.setOptOutPolicy('FILTER');

        Messaging.SingleEmailMessage[] messages = new List<Messaging.SingleEmailMessage>();
        messages.add(mail);

        Messaging.SendEmailResult[] results = Messaging.sendEmail(messages);
        EmailActionResult emailActionResult = new EmailActionResult();

        for(Messaging.SendEmailResult result :results) {
            if(result.IsSuccess()) {
                emailActionResult.isSuccess = true;
            } else {
                emailActionResult.isSuccess = false;
                Messaging.SendEmailError[] errors = result.getErrors();
                if (errors.size() > 0 ){
                    emailActionResult.errorMessage = errors[0].getMessage();
                }
            }
        }

        return emailActionResult;
    }
}
```

These HTML, CSS, JavaScript, and configuration files define the custom property editor for the action.

The HTML template defines the UI for the custom property editor in Flow Builder.

<!-- prettier-ignore -->
```html
<!--htmlEmailEditor.html-->
<template>
  <div class="slds-m-bottom_x-small">
    <h2 class="slds-text-heading_medium slds-p-around_xx-small lgc-bg-inverse">
      Sender Information
    </h2>

    <div class="slds-p-around_xx-small lgc-bg">
      <lightning-input
        type="text"
        label="Sender Name"
        placeholder="Enter sender name here..."
        value={senderName}
        onchange={handleSenderNameChange}
      >
      </lightning-input>

      <lightning-input
        type="email"
        label="Reply-To Email Address"
        placeholder="Enter reply-to email address here..."
        value={replyToEmail}
        onchange={handleReplyToEmailChange}
      >
      </lightning-input>
    </div>
  </div>

  <div class="slds-m-bottom_x-small">
    <h2 class="slds-text-heading_medium slds-p-around_xx-small lgc-bg-inverse">
      Recipient Information
    </h2>

    <div class="slds-p-around_xx-small lgc-bg">
      <lightning-input
        type="text"
        label="Recipient Name"
        placeholder="Enter recipient name here..."
        value={recipientName}
        onchange={handleRecipientNameChange}
      >
      </lightning-input>

      <lightning-input
        type="email"
        label="Send-To Email Address"
        placeholder="Enter send-to email address here..."
        value={sendToEmail}
        onchange={handleSendToEmailChange}
        required
      >
      </lightning-input>
    </div>
  </div>

  <div class="slds-m-top_small">
    <h2 class="slds-text-heading_medium slds-p-around_xx-small lgc-bg-inverse">Subject and Body</h2>

    <div class="slds-p-around_xx-small lgc-bg">
      <lightning-input
        type="text"
        label="Subject"
        placeholder="Enter subject here..."
        value={subject}
        onchange={handleSubjectChange}
      >
      </lightning-input>

      <div class="row">
        <lightning-textarea
          name="body"
          label="HTML Body"
          placeholder="Enter html body here..."
          value={htmlBody}
          onchange={handleHtmlBodyChange}
        >
        </lightning-textarea>
      </div>
    </div>
  </div>
</template>
```

This example shows the custom property editor UI.

![Custom action that uses a custom property editor](https://developer.salesforce.com/media/flow_custom_property_editor_for_action.png)

When the custom property editor is initialized, the JavaScript class receives a copy of the flow metadata from Flow Builder. When the admin changes a value in the custom property editor, the custom property editor dispatches an event to propagate the change back to Flow Builder.

**note:** Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```javascript
// htmlEmailEditor.js
import { LightningElement, api } from "lwc";
export default class HtmlEmailEditor extends LightningElement {
  @api
  inputVariables;

  get senderName() {
    const param = this.inputVariables.find(({ name }) => name === "senderName");
    return param && param.value;
  }

  get replyToEmail() {
    const param = this.inputVariables.find(({ name }) => name === "replyToEmail");
    return param && param.value;
  }

  get recipientName() {
    const param = this.inputVariables.find(({ name }) => name === "recipientName");
    return param && param.value;
  }

  get sendToEmail() {
    const param = this.inputVariables.find(({ name }) => name === "sendToEmail");
    return param && param.value;
  }

  get subject() {
    const param = this.inputVariables.find(({ name }) => name === "subject");
    return param && param.value;
  }

  get htmlBody() {
    const param = this.inputVariables.find(({ name }) => name === "htmlBody");
    return param && param.value;
  }

  @api validate() {
    const validity = [];
    if (
      !this.isValidEmailAddress(this.sendToEmail) ||
      !this.isValidEmailAddress(this.replyToEmail)
    ) {
      validity.push({
        key: "SendToAddress",
        errorString: "You have entered an invalid email format.",
      });
    }
    return validity;
  }

  isValidEmailAddress(email) {
    const emailRegex = /^\w+([\.-]?\w+)+@\w+([\.:]?\w+)+(\.[a-zA-Z0-9]{2,3})+$/;
    return emailRegex.test(email);
  }

  handleSenderNameChange(event) {
    this.handleChange(event, "senderName");
  }

  handleReplyToEmailChange(event) {
    this.handleChange(event, "replyToEmail");
  }

  handleRecipientNameChange(event) {
    this.handleChange(event, "recipientName");
  }

  handleSendToEmailChange(event) {
    this.handleChange(event, "sendToEmail");
  }

  handleSubjectChange(event) {
    this.handleChange(event, "subject");
  }

  handleHtmlBodyChange(event) {
    this.handleChange(event, "htmlBody");
  }

  handleChange(event, name) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
          name,
          newValue,
          newValueDataType: "String",
        },
      });
      this.dispatchEvent(valueChangedEvent);
    }
  }
}
```

Flow Builder has a [JavaScript interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md) for communicating with a custom property editor. This JavaScript class uses the `inputVariables` and `validate` interfaces.

When the custom property editor is initialized, `inputVariables` receives the values of the input variables in the invocable action from Flow Builder.

The `inputVariables` data structure includes the name, value, and data type for each input variable.

```javascript
[
  {
    name: "senderName",
    value: "Test Inc",
    valueDataType: "String",
  },
];
```

The `get` methods, such as `get senderName()` and `get replyToEmail()`, get the `value` for each input variable for use in the custom property editor.

When an admin clicks **Done** in Flow Builder’s screen editor UI, Flow Builder evaluates the `validate` function in the custom property editor. If the function returns the `key` and `errorString` data structure, the screen editor shows the number of errors and prevents the admin from saving changes in the screen editor.

**note:** Flow Builder shows only the number of errors. To show error strings, write code in the `validate` method. For more information, see [Custom Property Editor JavaScript Interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md).

When an admin enters a value for an input in the custom property editor, the `handleChange` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

Here’s the configuration file for `htmlEmailEditor`.

```xml
<!--htmlEmailEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>49.0</apiVersion>
    <!--isExposed can be true or false-->
    <isExposed>true</isExposed>
</LightningComponentBundle>
```

<!-- document id=ee03cc65f95dd0e0a745f4f6db03013ef9ad3027a05a17042070c2801ae83e72 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-validate-external-internal-example.md -->

# Example: Custom Validation for Components in Flows

Create a custom Lightning web component for a single input on a Screen element in a flow built with Flow Bulder. The component contains custom validation.

The `c-number-of-students` component contains a `lightning-input` component that supports number values. The flow contains validation to check whether the component’s value is equal to another value in the flow. When an invalid value is entered, the flow sends the input validation error message to the component to be stored. The component also validates the input using the `@api` validate method and displays an error message if the value is greater than 30. You can customize the error message to display above the component and to show the error message from the `numStudentsErrorLabel` resource.

The HTML file defines a `lightning-input` field for entering the number of students. It binds the input value to `numberOfStudents`. The `lightning-input` field listens for changes to trigger validation where the error message is displayed above the input component:

<!-- prettier-ignore-->
```html
<!-- numberOfStudents.html -->
<template>
  <div if:true={internalErrorToRender} class="slds-text-color_error slds-m-bottom_small">
    {internalErrorToRender}
  </div>

  <lightning-input
    label="Number of Students"
    type="number"
    value={_numberOfStudents}
    onchange={handleInputChange}
  >
  </lightning-input>

  <div if:true={externalErrorToRender} class="slds-m-bottom_small">
  <!-- This code renders the message while keeping existing styles intact-->

        <lightning-formatted-rich-text disable-linkify value={externalErrorToRender} />
  </div>
</template>
```

The JavaScript controller file manages the component's state and handles user interactions. The controller uses the `numberOfStudents(updatedNumberOfStudents)` setter method to perform validation inside the component if the component’s value changes due to user input or reactivity. If the value is invalid, it sets `internalErrorToRender` to the appropriate error message. The `hasUserInteracted` property tracks whether the user has interacted with the component. Checking the `hasUserInteracted` property prevents the component from showing an error until the user interacts with the component at least once.

The `handleInputChange(event)` method is triggered when the user changes the input value for the component. It then creates a `FlowAttributeChangeEvent` to notify the flow of the new value and dispatches this event. The `getInternalErrorMessageIfInvalid()` method checks if the number of students exceeds 30. If the value is invalid, it returns the error message from `numStudentsErrorLabel`. If the value is valid, it returns null.

The `validate()` method validates the input when the flow attempts to move forward. It calls `getInternalErrorMessageIfInvalid()` to get the internal error message. It returns an object with `isValid` set to true if there is no internal error or set to false if an internal message exists. The `errorMessage` property is set to null if there is no internal error message or set to the internal error message if one exists.

The flow calls the `setCustomValidity(externalErrorMessage)` method to pass in an external error message. If an external error is currently being rendered, it updates `externalErrorToRender` with the new message. It also stores the new message in `cachedExternalErrorMessage`.

The flow calls the `reportValidity()` method that requests the component to show all error messages. It sets `externalErrorToRender` to the value stored in `cachedExternalErrorMessage` and updates `internalErrorToRender` with the result of `getInternalErrorMessageIfInvalid()`.

```javascript
// numberOfStudents.js
import { LightningElement, api } from "lwc";
import { FlowAttributeChangeEvent } from "lightning/flowSupport";
import numStudentsErrorLabel from "@salesforce/label/numStudentsErrorLabel";

export default class NumberOfStudents extends LightningElement {
  _numberOfStudents = 0;
  internalErrorToRender = ""; // '' is falsy
  externalErrorToRender = ""; // '' is falsy
  cachedExternalErrorMessage = ""; // '' is falsy
  hasUserInteracted = false;

  @api
  get numberOfStudents() {
    return this._numberOfStudents;
  }
  set numberOfStudents(updatedNumberOfStudents) {
    this._numberOfStudents = updatedNumberOfStudents;

    if (this.hasUserInteracted) {
      this.internalErrorToRender = this.getInternalErrorMessageIfInvalid();
    }
  }

  handleInputChange(event) {
    this.hasUserInteracted = true;

    const attributeChangeEvent = new FlowAttributeChangeEvent(
      "numberOfStudents",
      event.detail.value,
    );
    this.dispatchEvent(attributeChangeEvent);
  }

  getInternalErrorMessageIfInvalid() {
    return this.numberOfStudents > 30 ? numStudentsErrorLabel : null;
  }

  @api
  validate() {
    const internalError = this.getInternalErrorMessageIfInvalid();
    return {
      isValid: internalError === null,

      errorMessage: internalError,
    };
  }

  @api
  setCustomValidity(externalErrorMessage) {
    if (this.externalErrorToRender) {
      this.externalErrorToRender = externalErrorMessage;
    }

    this.cachedExternalErrorMessage = externalErrorMessage;
  }

  @api reportValidity() {
    this.externalErrorToRender = this.cachedExternalErrorMessage;
    this.internalErrorToRender = this.getInternalErrorMessageIfInvalid();
  }
}
```

The XML configuration file exposes the component to flow screens by specifying `lightning\_\_FlowScreen` as a target. It also defines the `numberofStudents` property for the flow to interact with.

```xml
<!-- numberOfStudents.js-meta.xml -->
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="c:numberOfStudents">
    <apiVersion>63.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__FlowScreen</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__FlowScreen">
            <property name="numberOfStudents" type="Integer" label="Number of Students"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

**See Also**

- [Validation Methods for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-methods.md)
- [Customize Input Validation Errors for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-input.md)

<!-- document id=3c935f26bbfa41b01ce23c24e7d84ed1c022ca7d714bc4afdc4d8cd2486da9cf url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-sobject-action-example.md -->

# Example: Generic SObject Input for Invocable Actions

This example creates a custom property editor for an invocable action that uses a generic sObject input parameter. An invocable action is an Apex method that you can add to your flow. In Flow Builder, an admin uses picklist fields to set the invocable action’s input parameters: the object of the record variable, the record variable, and the object for storing the output. When users run a flow for this example, the invocable action stores the first record from a collection of records.

This Apex class file defines the `selectRecord` method that can run as an invocable action and its input variables. The `@InvocableMethod` annotation identifies the method that can run as an invocable action. The `@InvocableVariable` annotation identifies the variables used by the invocable method.

The invocable method registers the custom property editor in the `configurationEditor` modifier. The namespace is `c` unless the org has a custom namespace. If the org has a custom namespace, use that namespace to register the custom property editor. For this example, the name of the custom property editor is `c-select-record-editor`.

```apex
// SelectRecordAction.cls
public with sharing class SelectRecordAction {
    @InvocableMethod(configurationEditor='c-select-record-editor')
    public static List <Results> selectRecord(List<Requests> requestList) {
        List<SObject> inputCollection = requestList[0].inputCollection;
        //Store the first input record for output
        SObject outputMember = inputCollection[0];
        Results response = new Results();
        response.outputMember = outputMember;
        List<Results> responseWrapper= new List<Results>();
        responseWrapper.add(response);
        return responseWrapper;
    }

public class Requests {
    @InvocableVariable(label='Object for Input' description='Records for Input')
    public List<SObject> inputCollection;
    }

public class Results {
    @InvocableVariable(label='Object for Storing Output' description='Records for Output')
    public SObject outputMember;
    }
}
```

These HTML, CSS, JavaScript, and configuration files define the custom property editor for the action.

The HTML template defines the UI for the custom property editor in Flow Builder.

<!-- prettier-ignore -->
```html
<!--selectRecordEditor.html-->
<template>
  <lightning-combobox
    name="inputType"
    label="Object for Record Variable"
    value={inputType}
    placeholder="Select object..."
    options={typeOptions}
    onchange={handleInputTypeChange}
  >
  </lightning-combobox>

  <lightning-combobox
    name="outputType"
    label="Object for Storing Output"
    value={outputType}
    placeholder="Select object..."
    options={typeOptions}
    onchange={handleOutputTypeChange}
  >
  </lightning-combobox>

  <lightning-combobox
    name="inputValue"
    label="Record Variable"
    value={inputValue}
    placeholder="Select record variable..."
    options={valueOptions}
    onchange={handleValueChange}
  >
  </lightning-combobox>

  <div class="slds-p-bottom_medium"></div>
</template>
```

This example shows the custom property editor UI.

![Custom property editor for the Select Record action](https://developer.salesforce.com/media/flow_custom_property_editor_selectRecordFB.png)

When the custom property editor is initialized, the JavaScript class receives a copy of the flow metadata from Flow Builder. When the admin changes a value in the custom property editor, the custom property editor dispatches an event to propagate the change back to Flow Builder.

**note:** Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```javascript
// selectRecordEditor.js
import { LightningElement, api } from "lwc";

export default class SelectRecordEditor extends LightningElement {
  @api
  inputVariables;

  @api
  genericTypeMappings;

  @api
  builderContext;

  get inputValue() {
    const param = this.inputVariables.find(({ name }) => name === "inputCollection");
    return param && param.value;
  }

  get inputType() {
    const type = this.genericTypeMappings.find(({ typeName }) => typeName === "T__inputCollection");
    return type && type.typeValue;
  }

  get outputType() {
    const type = this.genericTypeMappings.find(({ typeName }) => typeName === "U__outputMember");
    return type && type.typeValue;
  }

  get typeOptions() {
    return [
      { label: "Account", value: "Account" },
      { label: "Case", value: "Case" },
      { label: "Lead", value: "Lead" },
    ];
  }

  get valueOptions() {
    const variables = this.builderContext.variables;
    return variables.map(({ name }) => ({
      label: name,
      value: name,
    }));
  }

  handleInputTypeChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const typeChangedEvent = new CustomEvent(
        "configuration_editor_generic_type_mapping_changed",
        {
          bubbles: true,
          cancelable: false,
          composed: true,
          detail: {
            typeName: "T__inputCollection",
            typeValue: newValue,
          },
        },
      );
      this.dispatchEvent(typeChangedEvent);
    }
  }

  handleOutputTypeChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const typeChangedEvent = new CustomEvent(
        "configuration_editor_generic_type_mapping_changed",
        {
          bubbles: true,
          cancelable: false,
          composed: true,
          detail: {
            typeName: "U__outputMember",
            typeValue: newValue,
          },
        },
      );
      this.dispatchEvent(typeChangedEvent);
    }
  }

  handleValueChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
          name: "inputCollection",
          newValue,
          newValueDataType: "reference",
        },
      });
      this.dispatchEvent(valueChangedEvent);
    }
  }
}
```

Flow Builder has a [JavaScript interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md) for communicating with a custom property editor. This JavaScript class uses the `inputVariables`, `builderContext`, and `genericTypeMappings` interfaces.

When the custom property editor is initialized, `inputVariables` receives the values of the input variables in the invocable action from Flow Builder.

The `inputVariables` data structure includes the name, value, and data type for each input variable.

```javascript
[
  {
    name: "inputType",
    value: "Account",
    valueDataType: "Account",
  },
];
```

The `get inputValue()` method gets the value for each input variable for use in the custom property editor.

The `genericTypeMappings` interface receives the values of the input variables that are generic sObject data types in the invocable action from Flow Builder.

The data structure includes the name and value for each input. The `typeName` must match the name of the generic sObject input that is defined with the `@InvocableVariable` annotation in the method for example `’T__inputCollection’`. `T__` is prepended to input names and `U__` is prepended to output names automatically . The `typeValue` is the specific value for the generic sObject input for example `Account`.

```javascript
[
  {
    typeName: "T__inputCollection",
    typeValue: "Account",
  },
];
```

The `get inputType()` and `get outputType()` methods get the value for each input parameter that is a generic sObject data type for use in the custom property editor.

The `get typeOptions()` method gets the labels and values for each object input option for use in the custom property editor.

The `builderContext` interface provides data about the elements and resources in the flow.

The `builderContext` data structure includes the elements and resources in the flow.

The `get valueOptions()` method uses the data from variables as options for input values on the custom property editor for the invocable action’s input parameters.

When an admin enters a value for **Object for Record Variable** in the custom property editor, the `handleInputTypeChange` method dispatches a `configuration_editor_generic_type_mapping_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

When an admin enters a value for **Object for Storing Output** in the custom property editor, the `handleOutputTypeChange` method dispatches a `configuration_editor_generic_type_mapping_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

When an admin enters a value for **Record Variable** in the custom property editor, the `handleValueChange` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

Here’s the configuration file for `selectRecordEditor`.

```xml
<!--selectRecordEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>50.0</apiVersion>
    <!--isExposed can be true or false-->
    <isExposed>true</isExposed>
</LightningComponentBundle>
```

**See Also**

- [Custom Property Editor JavaScript Interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=a76c1c089ba5c5fbe201d268ca91680338ba2fba3f45f7e821f775e5c6d3656c url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-sobject-lwc-example.md -->

# Example: Generic SObject Input for Screen Components

This example creates a custom property editor for a custom flow screen component that uses a generic `sObject` input value. The admin uses picklist fields to set the screen component’s input values for the object of the record variable and the record variable. When users run a flow for this example, the screen component displays the first record from a collection of records.

![Flow screen at run time](https://developer.salesforce.com/media/flow_custom_property_editor_displayRecordRun.png)

The following HTML, JavaScript, and configuration files define the `displayRecord` custom flow screen component.

<!-- prettier-ignore -->
```html
<!--displayRecord.html-->
<template>
  <p>Record Name: {inputValue.Name}</p>
</template>
```

The JavaScript class defines an `inputValue` public property.

```javascript
// displayRecord.js
import { LightningElement, api } from "lwc";

export default class DisplayRecord extends LightningElement {
  @api
  inputValue;
}
```

To expose the `inputValue` public property in Flow Builder, define it in the configuration file. To define the property as a generic `sObject` data type, define the `propertyType` subtag. The subtag extends the generic `sObject` data type. The `type` attribute of `inputValue` references the `name` attribute of the `propertyType` subtag. For example, if `propertyType name="T"`, then `property type="{T}"`. The `type` attribute of the `property` subtag must be inside curly braces. To define the property as a generic `sObject` collection data type, append `[]`, for example `property type="{T[]}"`.

The `role` attribute determines whether the property can receive input from the flow or not. The default value is `inputAndOutput`. To make a property available for input or output only, set the `role` attribute to `inputOnly` or `outputOnly`.

In the configuration file, use the `configurationEditor` attribute to register the custom property editor.

Use the `c` namespace unless the org has a custom namespace. If the org has a custom namespace, use that namespace.

```xml
<!-- displayRecord.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>50.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__FlowScreen</target>
  </targets>
  <masterLabel>Display Record</masterLabel>
  <targetConfigs>
    <targetConfig targets="lightning__FlowScreen" configurationEditor="c-display-record-editor">
      <propertyType name="T" extends="SObject" label="Input Type" description="Generic sObject data type used for input sObject properties" />
      <property name="inputValue" type={T} label="input value" role="inputOnly" />
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

The following HTML, JavaScript, and configuration files define the custom property editor for the `displayRecord` component.

![Custom property editor for the Display Record component](https://developer.salesforce.com/media/flow_custom_property_editor_displayRecordFB.png)

The custom property editor’s HTML template defines the UI, which uses a combo box Lightning base component.

<!-- prettier-ignore -->
```html
<!--displayRecordEditor.html-->
<template>
  <lightning-combobox
    name="inputType"
    label="Object for Record Variable"
    value={inputType}
    placeholder="Select object..."
    options={typeOptions}
    onchange={handleInputTypeChange}
  >
  </lightning-combobox>

  <lightning-combobox
    name="inputValue"
    label="Record Variable"
    value={inputValue}
    placeholder="Select record variable..."
    options={valueOptions}
    onchange={handleValueChange}
  >
  </lightning-combobox>
</template>
```

When the custom property editor is initialized, its JavaScript class receives a copy of the flow metadata from Flow Builder. When the admin makes an update in the custom property editor, it dispatches an event to propagate the change back to Flow Builder.

**note:** Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```
// displayRecordEditor.js
import { LightningElement, api } from 'lwc';

export default class DisplayRecordEditor extends LightningElement {
  @api
  inputVariables;

  @api
  genericTypeMappings;

  @api
  builderContext;

  get inputValue() {
    const param = this.inputVariables.find(({ name }) => name === 'inputValue');
    return param && param.value;
  }

  get inputType() {
    const type = this.genericTypeMappings.find(
      ({ typeName }) => typeName === 'T'
    );
    return type && type.typeValue;
  }

  get typeOptions() {
    return [
      { label: 'Account', value: 'Account' },
      { label: 'Case', value: 'Case' },
      { label: 'Lead', value: 'Lead' },
    ];
  }

  get valueOptions() {
    const variables = this.builderContext.variables;
    return variables.map(({ name }) => ({
      label: name,
      value: name,
    }));
  }

  handleInputTypeChange(event) {
    if (event && event.detail) {
    const newValue = event.detail.value;
    const typeChangedEvent = new CustomEvent(
      'configuration_editor_generic_type_mapping_changed',
      {
        bubbles: true,
        cancelable: false,
        composed: true,
        detail: {
          typeName: 'T',
          typeValue: newValue
        },
      }
    );
    this.dispatchEvent(typeChangedEvent);
    }
  }

  handleValueChange(event) {
    if (event && event.detail) {
      const newValue = event.detail.value;
      const valueChangedEvent = new CustomEvent(
        'configuration_editor_input_value_changed',
        {
          bubbles: true,
          cancelable: false,
          composed: true,
          detail: {
            name: 'inputValue',
            newValue,
            newValueDataType: 'reference',
          },
        }
      );
    this.dispatchEvent(valueChangedEvent);
    }
  }
}
```

Flow Builder has a [JavaScript interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md) for communicating with a custom property editor. This JavaScript class uses the `inputVariables`, `builderContext`, and `genericTypeMappings` interfaces.

When the custom property editor is initialized, `inputVariables` receives the values of the public properties in the screen component from Flow Builder.

The `inputVariables` data structure includes the name, value, and data type for each input variable.

```javascript
[
  {
    name: "inputType",
    value: "Account",
    valueDataType: "Account",
  },
];
```

The `get inputValue()` gets the value of the `inputValue` property for use in the custom property editor.

The `genericTypeMappings` interface receives the values of the input variables that are generic `sObject` data types in the screen component from Flow Builder.

The data structure includes the name and value for each input. The `typeName` is the name of the generic `sObject` input; for example, `'T'`. The `typeValue` is the specific value for the generic `sObject` input; for example, `Account`.

```javascript
[
  {
    typeName: "T",
    typeValue: "Account",
  },
];
```

The `get inputType()` gets the data type of the `inputValue` property for use in the custom property editor.

The `get typeOptions()` method gets the labels and values for each object input option for use in the custom property editor.

The `builderContext` interface provides data about the elements and resources in the flow.

```javascript
{
  actionCalls: [],
  apexPluginCalls: [],
  constants: [],
  formulas: [],
  recordCreates: [],
  recordDeletes: [],
  recordLookups: [],
  recordUpdates: [],
  screens: [],
  stages: [],
  textTemplates: [],
  variables: []
}
```

The `get valueOptions()` method uses the data from `variables` as options for input values on the custom property editor for the screen component’s inputs.

When an admin enters a value for **Object for Record Variable** in the custom property editor, the `handleInputTypeChange` method dispatches a `configuration_editor_generic_type_mapping_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

When an admin enters a value for **Record Variable** in the custom property editor, the `handleValueChange` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

This is the configuration file for `displayRecordEditor`.

```xml
<!--displayRecordEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>50.0</apiVersion>
  <!--isExposed can be true or false-->
  <isExposed>true</isExposed>
</LightningComponentBundle>
```

**See Also**

- [Custom Property Editor JavaScript Interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=c14f50c433ec1cdda6e6fafe3b0ccaab928701d34b57c5c12f4941d13caa17c4 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-example-user-input.md -->

# Example: Handle User Input with Complex Expressions

This component has an input field that asks for a name to greet. When the value of the input field changes, the component changes the value of the bound `name` property and uses complex expressions to format the output.

```html
<template>
  <input value="{name}" oninput="{handleInput}" placeholder="Enter your name" />
  <div>{name ? `Hello, ${name.trim().toUpperCase()}!` : 'Please enter your name'}</div>
  <div>{name ? `Your name has ${name.length} characters` : ''}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class UserInputComponent extends LightningElement {
  name = "";

  handleInput(event) {
    this.name = event.target.value;
  }
}
```

The `<input>` element uses the `oninput` event to listen for a change to its value. To bind the `handleInput` function to the template, we use the same syntax that we use to bind a property, `{...}`. The `handleInput` JavaScript function executes when the value of the `<input>` element changes.

When the value of the `name` property changes, the component re-renders and the following expression is evaluated.

```html
{name ? `Hello, ${name.toUpperCase()}!` : 'Please enter your name'}
```

Notice in the JavaScript class that `handleInput` is passed an `event` object. The `event` object contains information about the `input` event. The component uses the `event` object to get the value that the user enters into the input field.

<!-- document id=07549b85632d59814d303a50d99ee018b7895dfc7dad64c04b9037a361e147e1 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-example-lists-iterators.md -->

# Example: Render Lists with Template Expressions

To render a list of items, use the `for:each` directive or the `iterator` directive to iterate over an array, with support for complex expressions in the template.

Which should you use? The `iterator` directive has `first` and `last` properties that let you apply special behaviors to the first and last items in an array.

**note:** Regardless of which directive you use, you must use a `key` directive to assign a unique ID to each item. When an item changes, the framework uses the `key` to re-render only the item that changed.

The `key` in the template is used for performance optimization and isn't reflected in the HTML or DOM at runtime.

The code you write to render lists is standard HTML and JavaScript, except for the directives, which are specific to Lightning Web Components and template expressions.

## `for:each` with Template Expressions

To render an array, add the `for:each="{}"` directive to a nested `<template>` tag that encloses the HTML elements you want to repeat with quoted curly brackets. Inside the brackets, you can use an expression to return a valid array. To access the current item, use `for:item="_currentItem_"`. To access the current item's index, use `for:index="index"`. To assign a key to every element in the list, use the `key={_uniqueId_}` directive.

This example iterates over an array called `contacts`, defined in the component's JavaScript class, and uses template expressions to format the output.

```html
<template>
  <template for:each="{getContacts()}" for:item="contact">
    <div key="{contact.id}">
      <p>{`${contact.firstName} ${contact.lastName}`}</p>
      <p>{contact.email ? contact.email : 'No email provided'}</p>
      <p>{contact.age >= 18 ? 'Adult' : 'Minor'}</p>
    </div>
  </template>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ForEachComponent extends LightningElement {
  getContacts() {
    return [
      {
        id: 1,
        firstName: "John",
        lastName: "Doe",
        email: "john@example.com",
        age: 30,
      },
      {
        id: 2,
        firstName: "Jane",
        lastName: "Smith",
        email: null,
        age: 16,
      },
      {
        id: 3,
        firstName: "Bob",
        lastName: "Johnson",
        email: "bob@example.com",
        age: 25,
      },
    ];
  }
}
```

**important:** Every item in a list must have a `key`. When a list changes, the framework uses the `key` to identify each item so that it can re-render only the item that changed.

The `key` must be a string or a number; it can't be an object. You can't use `index` as a value for `key`. Use a natural key, like a record ID. Or, assign unique keys to an incoming data set. To add new items to a data set, use a private property to track and generate keys.

## `iterator` with Template Expressions

To apply a special behavior to the first or last item in a list, use the `iterator` directive, `iterator:_myiteratorname_={_someArray_}`. Add the `iterator` directive to a nested `<template>` tag that encloses the HTML elements you want to repeat. `_myiteratorname_` must be in lowercase.

Use `_myiteratorname_` to access these properties:

- `value` — The value of the item in the list. Use this property to access the properties of the array item. For example, `_myiteratorname_.value._aPropertyName_`.
- `index` — The index of the item in the list.
- `first` — A boolean value indicating whether this item is the first item in the list.
- `last` — A boolean value indicating whether this item is the last item in the list.

This sample code uses the same array as the previous example. To apply special rendering to the first and last items in the list, the code uses the `first` and `last` properties with the `if:true` directive and complex expressions.

```html
<template>
  <template iterator:it="{getActiveContacts()}">
    <div key="{it.value.id}" class="{it.first ? 'list-first' : it.last ? 'list-last' : ''}">
      <p>{`${it.value.firstName} ${it.value.lastName}`}</p>
      <p>{it.value.email || 'No email provided'}</p>
      <p>{it.value.age >= 18 ? 'Adult' : 'Minor'}</p>
    </div>
  </template>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class IteratorComponent extends LightningElement {
  allContacts = [
    {
      id: 1,
      firstName: "John",
      lastName: "Doe",
      email: "john@example.com",
      age: 30,
      active: true,
    },
    {
      id: 2,
      firstName: "Jane",
      lastName: "Smith",
      email: null,
      age: 16,
      active: true,
    },
    {
      id: 3,
      firstName: "Bob",
      lastName: "Johnson",
      email: "bob@example.com",
      age: 25,
      active: false,
    },
  ];

  getActiveContacts() {
    return this.allContacts.filter((contact) => contact.active);
  }
}
```

If the item is first in the list, the `<div>` tag renders with the styling defined in the CSS `list-first` class. If the item is last in the list, the `<div>` tag renders with the styling defined in the CSS `list-last` class.

**important:** To access a property of an item in the iteration, use the `value` property of the iteration. That is, `_myiteratorname_.value._propertyName_`, not `_myiteratorname_._propertyName_`. For example, in the template above, look at `{it.value.firstName}` and `{it.value.lastName}`.

<!-- document id=0e0653b08b754dcbc18e00f7c435a8db2f4ac1e1dff54154f5681d3bb881541e url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-sobject-collection-input-for-screen.md -->

# Example: SObject Collection Input for Invocable Actions

This example creates a custom property editor component named `CreateAccountActionEditor` for an invocable action that uses Account input parameters. In Flow Builder, an admin uses text fields to set the invocable action’s account input parameters. When users run a flow for this example, the invocable action creates a collection of accounts.

This Apex class file defines the `CreateAccountAction` method, which can run as an invocable action, and its input variables. The `@InvocableMethod` annotation identifies the method that can run as an invocable action. The `@InvocableVariable` annotation identifies the variables used by the invocable method.

The invocable method registers the custom property editor component in the `configurationEditor` modifier. For this example, the name of the component is `c-create-accounts-action-editor`.

**note:** The component namespace is `c` unless the org has a custom namespace. If the org has a custom namespace, use that namespace to register the custom property editor component.

```java
public with sharing class CreateAccountAction {
   @InvocableMethod(
       label='Create Accounts via Custom Property Editor'
       configurationEditor='c:accountEditor'
       category='Account'
   )
   public static void createAccounts(List<Request> requests) {
       for (Request request : requests) {
           insert request.accounts;
       }
   }

   // Nested class to hold invocable variables
   public class Request {
       @InvocableVariable(label='accounts' description='The accounts to create.')
       public Account[] accounts;
   }
}
```

Here’s the configuration file for `CreateAccountAction`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ApexClass xmlns="urn:metadata.tooling.soap.sforce.com" fqn="CreateAccountAction">
   <apiVersion>66.0</apiVersion>
   <status>Active</status>
</ApexClass>
```

These HTML, JavaScript, and configuration files define the custom property editor component `CreateAccountActionEditor` for the action.

The component’s HTML template defines the UI for the custom property editor in Flow Builder.

```html
<template>
  <lightning-card title="Create Account Action Editor">
    <!-- Button to add new row for Account -->
    <div class="slds-p-horizontal_small slds-p-vertical_x-small">
      <lightning-button
        label="Add Account"
        variant="brand"
        onclick="{handleAddRow}"
      ></lightning-button>
    </div>
    <!-- Inputs to display and edit the accounts' fields -->
    <div class="slds-p-horizontal_small slds-m-bottom_small">
      <template for:each="{accounts}" for:item="row" for:index="index">
        <div
          key="{row.key}"
          class="slds-grid slds-gutters slds-var-m-vertical_x-small slds-align_absolute-center"
        >
          <div class="slds-col slds-size_1-of-2">
            <lightning-input
              type="text"
              name="Name"
              label="Name"
              value="{row.Name}"
              data-index="{index}"
              onchange="{handleFieldChange}"
              required
            >
            </lightning-input>
          </div>
          <div class="slds-col slds-size_1-of-2">
            <lightning-input
              type="tel"
              name="Phone"
              label="Phone"
              value="{row.Phone}"
              data-index="{index}"
              onchange="{handleFieldChange}"
            >
            </lightning-input>
          </div>
        </div>
        <hr key="{row.key}" class="slds-m-vertical_x-small" />
      </template>
      <div>
        <lightning-button
          variant="brand"
          label="Save"
          data-index="{index}"
          onclick="{handleSaveAccountConfig}"
        >
        </lightning-button>
      </div>
    </div>
  </lightning-card>
</template>
```

This example shows the custom property editor UI.

![Custom property editor for the Create Accounts via Custom Property Editor action](https://developer.salesforce.com/media/flow_custom_property_editor_sobject_coll_input.png)

When the custom property editor component is initialized, the component instance receives a copy of the flow metadata from Flow Builder. When the admin changes a value in the custom property editor, the custom property editor component dispatches an event to propagate the change back to Flow Builder.

Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```javascript
//createAccountsActionEditor.js
import { LightningElement, api, track } from "lwc";

export default class CreateAccountsActionEditor extends LightningElement {
  @track _accounts = [];
  @track _inputVariables = [];

  @api
  get inputVariables() {
    return this._inputVariables;
  }

  set inputVariables(variables) {
    this._inputVariables = variables || [];
  }

  get accounts() {
    if (this._accounts.length === 0) {
      const param = this._inputVariables?.find(({ name }) => name === "accounts");
      this._accounts = this.populateAccountRows(Array.isArray(param?.value) ? param.value : []);
    }
    return this._accounts;
  }

  populateAccountRows(accounts) {
    const rows = accounts.map((r) => {
      return {
        Name: r.Name,
        Phone: r.Phone,
        key: "tmp-" + Date.now() + "-" + Math.random().toString(36).slice(2),
      };
    });
    return rows;
  }

  handleAddRow() {
    const key = "tmp-" + Date.now() + "-" + Math.random().toString(36).slice(2);
    this._accounts = [{ key, Name: "", Phone: "" }, ...this._accounts];
  }

  handleFieldChange(event) {
    const index = Number(event.currentTarget.dataset.index);
    const field = event.target.name; // 'Name' or 'Phone'
    const value = event.target.value;
    const next = [...this._accounts];
    next[index] = { ...next[index], [field]: value };
    this._accounts = next;
  }

  getAccountsFromRows() {
    let accs = [];
    this._accounts.map((r) => {
      accs.push({
        Name: r.Name,
        Phone: r.Phone,
        attributes: {
          type: "Account",
        },
      });
    });
    return JSON.stringify(accs);
  }

  @api
  validate() {
    const errors = [];
    if (!this._accounts.some((r) => r.Name)) {
      errors.push({
        message: "Name is required",
        severity: "error",
      });
    }
    return errors;
  }

  handleSaveAccountConfig(event) {
    const newValue = this.getAccountsFromRows();
    const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
      bubbles: true,
      cancelable: false,
      composed: true,
      detail: {
        name: "accounts",
        newValue,
        newValueDataType: "SObject",
      },
    });
    this.dispatchEvent(valueChangedEvent);
  }
}
```

Flow Builder has a JavaScript interface for communicating with a custom property editor. This JavaScript class uses the `inputVariables` interface.

When the custom property editor is initialized, `inputVariables` receives the value of the input variable in the invocable action from Flow Builder. When you use a literal value for an input that’s an sObject data type, specify the type value such as Account.

The `newValue` data structure includes the sObject type and field and value mappings in JSON format.

```json
[
  {
    "attributes": {
      "type": "Account"
    },
    "Name": "Acme",
    "Phone": 5555551234
  }
]
```

The `get accounts()` method gets the preexisting value for the input variable saved in flow metadata for use in the custom property editor.

When an admin enters a value for an input in the custom property editor, and clicks the Save button, the `handleSaveAccountConfig` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

Here’s the configuration file for `CreateAccountsActionEditor`.

```xml
<!---CreateAccountsActionEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>66.0</apiVersion>
   <isExposed>true</isExposed>
</LightningComponentBundle>
```

**See Also**

- [Custom Property Editor JavaScript Interface](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-custom-property-editor-interface.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens.md)

<!-- document id=c7c2bd283361620fa2e0297cf838c6d9a3f77d2ef11a0845417d25a247077813 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-custom-property-editor-literal-sobject-action-example.md -->

# Example: SObject Input for Invocable Actions

This example creates a custom property editor component named `createContactActionEditor` for an invocable action that uses a Contact object input parameter. An invocable action is an Apex method that you can add to your flow. In Flow Builder, an admin uses text fields to set the invocable action’s contact input parameter. When users run a flow for this example, the invocable action stores a new contact.

This Apex class file defines the `createContact` method that can run as an invocable action and its input variables. The `@InvocableMethod` annotation identifies the method that can run as an invocable action. The `@InvocableVariable` annotation identifies the variables used by the invocable method.

The invocable method registers the custom property editor component in the `configurationEditor` modifier. The component namespace is `c` unless the org has a custom namespace. If the org has a custom namespace, use that namespace to register the custom property editor component. For this example, the name of the component is `c-create-contact-action-editor`.

```apex
//CreateContactAction.cls
global class CreateContactAction {
    global class CreateContactRequest {

        @InvocableVariable
        global Contact contact;
    }

    global class CreateContactResult {
        @InvocableVariable
        global Boolean isSuccess;

        @InvocableVariable
        global String errorMessage;

        @InvocableVariable
        global String contactId;
   }

    @InvocableMethod(label='Create Contact' configurationEditor='c-create-contact-action-editor')
    global static List<CreateContactResult> createContact(List<CreateContactRequest> requests) {
        List<CreateContactResult> results = new List<CreateContactResult>();
            for(CreateContactRequest request : requests){
        results.add(insertContact(request));
        }
        return results;
    }

    public static CreateContactResult insertContact(CreateContactRequest request) {
        List<Contact> contactList = new List<Contact>();
        contactList.add(request.contact);

        Database.SaveResult[] srList = Database.insert(contactList, true);

        CreateContactResult contactResult = new CreateContactResult();
            for(Database.SaveResult sr: srList) {
                if (sr.isSuccess()) {
                    contactResult.isSuccess = sr.isSuccess();
                    contactResult.contactId = sr.getId();
                }
                else {
                    for(Database.Error err : sr.getErrors()) {
                        contactResult.errorMessage = err.getStatusCode() + ': ' + err.getMessage();
                    }
                }
            }

    return contactResult;
    }
}
```

Here’s the configuration file for `CreateContactAction`.

```xml
<!--CreateContactAction.cls-meta.xml-->

<?xml version="1.0" encoding="UTF-8"?>
<ApexClass xmlns="urn:metadata.tooling.soap.sforce.com" fqn="CreateContactAction">
    <apiVersion>53.0</apiVersion>
    <status>Active</status>
</ApexClass>

```

These HTML, CSS, JavaScript, and configuration files define the custom property editor component `createContactActionEditor` for the action.

The component’s HTML template defines the UI for the custom property editor in Flow Builder.

<!-- prettier-ignore -->
```html
<!--createContactActionEditor.html-->

<template>
  <div class="slds-m-top_small">
    <h2 class="slds-text-heading_medium slds-p-around_xx-small lgc-bg-inverse">
      Contact Primary Information
    </h2>

    <lightning-input
      label="First Name"
      value={defaultContact.FirstName}
      onchange={handleFirstNameChange}
    >
    </lightning-input>

    <lightning-input
      label="Last Name"
      value={defaultContact.LastName}
      onchange={handleLastNameChange}
    >
    </lightning-input>
  </div>

  <div class="slds-m-top_small">
    <h2 class="slds-text-heading_medium slds-p-around_xx-small lgc-bg-inverse">Contact Source</h2>

    <lightning-input
      label="European Country Code"
      value={defaultContact.European_Country_Code__c}
      onchange={handleCountryCodeChange}
    >
    </lightning-input>
  </div>
</template>
```

This example shows the custom property editor UI.

![Create Contact action's custom property editor in Flow Builder](https://developer.salesforce.com/media/flow_custom_property_editor_create_contact.png)

When the custom property editor component is initialized, its JavaScript class receives a copy of the flow metadata from Flow Builder. When the admin changes a value in the custom property editor, the custom property editor component dispatches an event to propagate the change back to Flow Builder.

**note:** Use `@api` properties to capture data from flows. Use events to report changes to flows at run time.

```javascript
//createContactActionEditor.js

import { LightningElement, api } from "lwc";

export default class CreateContactActionEditor extends LightningElement {
  @api
  inputVariables;

  defaultContact = {
    attributes: {
      type: "Contact",
    },
    European_Country_Code__c: "FRA",
  };

  get contact() {
    const param = this.inputVariables.find(({ name }) => name === "contact");
    return param && param.value;
  }

  handleFirstNameChange(event) {
    this.defaultContact["FirstName"] = event.detail.value;
    this.handleContact();
  }

  handleLastNameChange(event) {
    this.defaultContact["LastName"] = event.detail.value;
    this.handleContact();
  }

  handleCountryCodeChange(event) {
    this.defaultContact["European_Country_Code__c"] = event.detail.value;
    this.handleContact();
  }

  handleContact() {
    const newValue = JSON.stringify(this.defaultContact);
    const valueChangedEvent = new CustomEvent("configuration_editor_input_value_changed", {
      bubbles: true,
      cancelable: false,
      composed: true,
      detail: {
        name: "contact",
        newValue,
        newValueDataType: "SObject",
      },
    });
    this.dispatchEvent(valueChangedEvent);
  }
}
```

Flow Builder has a [JavaScript interface](https://developer.salesforce.com/docs/platform/lwc/use/use-flow-custom-property-editor-interface.md) for communicating with a custom property editor. This JavaScript class uses the `inputVariables` interface.

When the custom property editor is initialized, `inputVariables` receives the value of the input variable in the invocable action from Flow Builder. The default values are set for type and `European_Country_Code__c`. When you use a literal value for an input that’s an sObject data type, specify the `type` value such as `Contact`.

The `inputVariables` data structure includes the name, value, and data type for each input variable.

```javascript
[{
    name: 'contact',
    value: '{
        "attributes": {
            "type": "Contact"
        },
        "FirstName" : "",
        "LastName": "",
        "European_Country_Code__c" : "FRA"
    }',
    valueDataType: 'SObject'
}]

```

The `get contact()` method gets the value for the input variable for use in the custom property editor.

When an admin enters a value for an input in the custom property editor, the `handleContact` method dispatches a `configuration_editor_input_value_changed` event to Flow Builder. Flow Builder receives the event and updates the value in the flow.

Here’s the configuration file for `createContactActionEditor`.

```xml
<!---createContactActionEditor.js-meta.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>53.0</apiVersion>
    <!--isExposed can be true or false-->
    <isExposed>true</isExposed>
</LightningComponentBundle>
```

<!-- document id=bece0bcb87ffff95755e202c9af83be8bd891d93e9f95da93ed485c477e33dfe url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-standard-to-custom-reactive-example.md -->

# Example: Standard Flow Component to Custom Lightning Web Component

Make your custom component react to changes in a standard Flow component.

To create and add the `colorName` custom component into the Flow Builder:

1.  Add the Text component and custom component, `colorName` and provide the labels for each.
2.  In the colorName’s property, select the `Text` component as a source for the Name of Color field.

Any changes made to the Text input are automatically reflected in the color public field inside of the custom Lightning web component, `colorName`. For example, entering magenta into the Text input results in the LWC displaying the color name styled with the same color, magenta.

<!-- prettier-ignore -->
```html
<!-- colorName.html -->
<template>
  <p>
    Color name has the same color :
    <span style={colorStyle}>{color}</span>
  </p>
</template>
```

```javascript
// colorName.js
import { LightningElement, api } from "lwc";

export default class colorName extends LightningElement {
  @api color;

  get colorStyle() {
    return "color:" + this.color;
  }
}
```

```xml
// colorName.js-meta.xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
 <apiVersion>52.0</apiVersion>
 <isExposed>true</isExposed>
 <masterLabel>Color Name</masterLabel>
 <description>Reactive Color Name</description>
 <targets>
     <target>lightning__FlowScreen</target>
 </targets>
<targetConfigs>
      <targetConfig targets="lightning__FlowScreen">
          <property name="color" label="Name of Color" type="String" />
      </targetConfig>
</targetConfigs>
</LightningComponentBundle>
```

<!-- document id=516a4c8f2e289ef334e9b302406b5f17a6daccd36a29049c0db770e087023993 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-standard-to-standard-reactive-example.md -->

# Example: Standard Flow Component to Standard Flow Component

Using your standard Flow components is the simplest way to achieve reactivity.

With standard Flow components, you add the components, provide API names for each and a label (if required), identify the source and reactive component, then save and run the flow.

To make a Name component’s First Name field react to and display all text input from a Text component:

1.  From your flow, add the `Text` component and `Name` component and provide the labels for each.
2.  In the `Name` component’s First Name’s source field, choose the `Text` component as the source. The source can be any component of the same type, in this case, the Text component’s type and the Name component’s First Name field are of type String.
3.  Save and run the Flow, and in the `Text` component’s input, type, `This is Reactivity`. After each character is typed, the First Name field updates immediately.

<!-- document id=9de44ac693651a1b30419144d2831075779c85857bb841c2523859f7d7ea3086 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-managers-use-example.md -->

# Example: Use a Built-in State Manager

This example is intended to show the simplest possible use of a built-in state manager. The important concepts are the state manager lifecycle, and understanding how to access response values.

**important:** In practice, if your usage pattern is this simple, use the wire service instead. To clearly illustrate essential concepts here, we've over-simplified the example code in this topic. See [Best Practices for State Manager Design](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-design.md) for more guidance on how built-in state managers are intended to be used.

```javascript
import { LightningElement, wire } from 'lwc';
import { gql, graphql } from "lightning/graphql";
import smRecord from "lightning/stateManagerRecord";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import OWNER_NAME_FIELD from "@salesforce/schema/Account.Owner.Name";
import PHONE_FIELD from "@salesforce/schema/Account.Phone";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";
import { getFieldValue } from "lightning/uiRecordApi";

export default class AccountBrowserSimple extends LightningElement {

    // Create a state manager to retrieve account record data
    // This is deliberately simple to illustrate concepts, not
    // a recommended pattern.
    myRecMgr = smRecord({
        recordId: undefined,
        fields: [ NAME_FIELD, INDUSTRY_FIELD ],
        optionalFields: [PHONE_FIELD, OWNER_NAME_FIELD]
    });

    // UX: handle change to selected Account
    handleMenuSelect(event) {
        // Get the selected account record ID
        const accountId = event.detail.value;
        // Update the recordManager
        this.myRecMgr.value.setRecordId(accountId);
    }

    // What's the state of the state manager
    get accountAvailable() {
        return this.myRecMgr.value.status === "loaded";
    }

    // This property provides the record data in the state manager
    get accountData() {
        if (this.accountAvailable) {
            return this.myRecMgr.value.data;
        }
        return undefined;
    }

    // Record data fields for display
    // This is deliberately tedious; don't do this!
    get recName() {
        return getFieldValue(this.accountData, NAME_FIELD);
    }
    get recOwner() {
        return getFieldValue(this.accountData, OWNER_NAME_FIELD);
    }
    get recPhone() {
        return getFieldValue(this.accountData, PHONE_FIELD);
    }
    get recIndustry() {
        return getFieldValue(this.accountData, INDUSTRY_FIELD);
    }

    // UX: Show loading message in account selection menu while
    //     gql query is running
    get accountsLoading() {
        if (this.results) return false;
        return true;
    }

    // This GQL block is simply to get record IDs for some Accounts,
    // for display in a menu in the component. It's purely for the UX,
    // and has nothing to do with state managers
    results; // Account IDs and Names, for the selection menu only
    errors;
    @wire(graphql, {
        query: gql`
            query AccountWithName {
                uiapi {
                    query {
                        Account(first: 10) {
                            edges {
                                node {
                                    Id
                                    Name {
                                        value
                                    }
                                }
                            }
                        }
                    }
                }
            }
        `,
    })
    graphqlQueryResult({ data, errors }) {
        if (data) {
            this.results = data.uiapi.query.Account.edges.map((edge) => edge.node);
        }
        this.errors = errors;
    }

    get stateDump() {
        return JSON.stringify(this.myRecMgr.value, null, 2);
    }
}
```

```html
<template>
    <lightning-card title="Example: Account Browser">

        <!-- This section element is purely user interface, providing a
            simple menu of accounts to view details for. -->
        <section class="slds-p-around_small" title="Select an Account">
            <template lwc:if={results}>
                <lightning-button-menu
                    alternative-text="Select Account"
                    icon-name="utility:account"
                    onselect={handleMenuSelect}
                    loading-state-alternative-text="Loading accounts…"
                    is-loading={accountsLoading}
                >
                    <template for:each={results} for:item="account">
                        <lightning-menu-item
                            label={account.Name.value}
                            value={account.Id}
                            key={account.Id}
                            >
                        </lightning-menu-item>
                    </template>
                </lightning-button-menu>
            </template>
        </section>

        <!-- This section displays data using the `lightning/stateManagerRecord`
            built-in state manager. -->
        <section class="slds-p-around_small" title="Account Data">

            <!-- Important: verify state manager data is ready/loaded -->
            <template lwc:if={accountAvailable}>
                <!-- This is deliberately hideous. You can do better. -->
                Account name: {recName}<br/>
                Industry: {recIndustry}<br/>
                Phone: {recPhone}<br/>
                Account Manager: {recOwner}<br/>
            </template>

            <!-- Debugging and inspection of state manager -->
            <hr/>
            <section class="slds-p-around_small">
                <textarea rows="10" cols="40">{stateDump}</textarea>
            </section>
        </section>
    </lightning-card>
</template>
```

<!-- document id=c2b3676233f98dc42a88451a80ae89e9804646f491a67ad56c5caec5f5df8b64 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-mutation.md -->

# `executeMutation`

To work with mutation operations for record create, update, or delete, import `executeMutation` from `lightning/graphql`.
Use the `executeMutation` method imperatively. `executeMutation` isn't supported using the `@wire` annotation.

**note:** `lightning/graphql` doesn’t currently support Mobile Offline use cases. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md).

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { gql, executeMutation } from "lightning/graphql";

export default class MutationGQLComponent extends LightningElement {
  get mutationQuery() {
    return gql`
      mutation operationObjectName {
        // mutation query here
      }
    `;
  }

  async mutateObject() {
    const result = await executeMutation({
      query: mutationQuery,
      variables: {
        // variables here
      },
    });
    // do something with the result
  }
}
```

The mutation query includes an `input` argument.

```javascript
mutation operationObjectName {
  uiapi {
    ObjectNameOperation(input: {
      // For create and update operations only
      ObjectName: {
        // Input fields
      }
      Id: ... // ID for update and delete operations only
    }) {
      // For create and update operations only
      Record {
        }
        // Output fields
      Id: ... // ID for delete operations only
    }
  }
}
```

## GraphQL API Resource

```html
POST /graphql
```

Like the GraphQL wire adapter, `executeMutation` uses the Salesforce [GraphQL API resource](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=Graphql).

## Parameters

- `query`—(Required) Parsed GraphQL query. Parse the query using the `gql` JavaScript template literal function. `gql` parses the GraphQL query into a format that `executeMutation` can use. `gql` isn’t reactive.
- `variables`— An object that provides GraphQL Variables for the query.

  **note:** The value passed to `variables` must include an `input` argument with the record `Id` field and fields for the record create or update.

- `operationName`—The name of the mutation operation you want to perform. Use `operationName` to select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with `mutation operationName` instead of using the shorthand syntax `mutation` for improved server-side debugging to identify different GraphQL requests. For example, `mutation CreateCase` or `mutation UpdateContact`.

## Returns

- `data`—[GraphQL API response](https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html)
- `errors`—[GraphQL API errors](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=type%3AGraphQLErrorRepresentation)

**note:** To maintain compatibility with the [GraphQL response specification](https://graphql.org/learn/serving-over-http/#response), `executeMutation` also returns `errors` instead of `error`, unlike other imperative functions, like `updateRecord`.

## Usage

Consider these usage guidelines when running mutation operations.

**note:** Child relationships aren't supported and can't be queried as part of a mutation.

### Create a Record

When creating a record:

- Include all required fields
- Include only createable fields
- Assign IDs to fields with type `Reference` using their API name

To ensure that new records are available in query results, use the [`refresh` method](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-refresh.md).

This example creates a contact record using the `FirstName` and `LastName` fields.

```javascript
import { LightningElement } from "lwc";
import { gql, executeMutation } from "lightning/graphql";

export default class CreateRecordQuery extends LightningElement {
  get createMutation() {
    return gql`
      mutation ContactCreateExample {
        uiapi {
          ContactCreate(
            input: { Contact: { FirstName: "Astro", LastName: "Nomical", Title: "CEO" } }
          ) {
            Record {
              Id
              Name {
                value
              }
            }
          }
        }
      }
    `;
  }

  async handleCreateContact() {
    const result = await executeMutation({
      query: this.createQuery,
    });
  }
  catch(error) {
    console.error("Error creating contact", error);
  }
}
```

### Update a Record

When updating a record:

- Include the ID of the record you want to update
- Include only updateable fields
- Assign IDs to fields with type `Reference` using their API name
- The output field is `Record`

To ensure that updated records are available in query results, use the [`refresh` method](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-refresh.md).

This example updates the `Phone` field on a contact record.

```javascript
import { LightningElement } from "lwc";
import { gql, executeMutation } from "lightning/graphql";

export default class UpdateRecordQuery extends LightningElement {
  get updateMutation() {
    return gql`
      mutation UpdateContact($input: ContactUpdateInput!) {
        uiapi {
          ContactUpdate(input: $input) {
            success
          }
        }
      }
    `;
  }
  async handleUpdateContact() {
    const result = await executeMutation({
      query: this.updateQuery,
      variables: {
        input: {
          Id: "003Z6000001W5zXIAS",
          Contact: {
            Phone: "18888888888",
          },
        },
      },
    });
    console.log("result", result);
  }
  catch(error) {
    console.error("Error creating contact", error);
  }
}
```

### Delete a Record

When deleting a record, include only the ID of the record you want to delete.

This example deletes a contact record using the `Id` field.

```javascript
import { LightningElement } from "lwc";
import { gql, executeMutation } from "lightning/graphql";

export default class DeleteRecordQuery extends LightningElement {
  get deleteMutation() {
    return gql`
      mutation ContactDeleteExample {
        uiapi {
          ContactDelete(input: { Id: "003Z6000001W5yaIAC" }) {
            Id
          }
        }
      }
    `;
  }

  async handleDeleteContact() {
    const result = await executeMutation({
      query: this.deleteQuery,
    });
  }
  catch(error) {
    console.error("Error deleting contact", error);
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [`graphqlMutations`](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/graphqlMutations) example that saves record updates from inline editing using a `lightning-datatable` component.

**See Also**

- [_GraphQL API Developer Guide_: Mutations Schema](https://developer.salesforce.com/docs/platform/graphql/guide/mutations-schema.html)
- [_GraphQL API Developer Guide_: Mutations Limitations](https://developer.salesforce.com/docs/platform/graphql/guide/mutations-limitations.html)

<!-- document id=828bb4bd12b8f5886c17f5c0686b4a1d65b28fdf42b75b068d83221e5e982f5e url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-execute-query.md -->

# `executeQuery`

Executes a CRM Analytics query written in Salesforce Analytics Query Language (SAQL) or standard SQL.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { executeQuery } from 'lightning/analyticsWaveApi';

export default class ExecuteQuery extends LightningElement {
  query = '<YOUR SAQL QUERY>'; // or generate SAQL for dynamic query

  get computedQuery() {
    if (!this.query) { return undefined; }
      return {
        query: this.query;
      }
  }

  @wire(executeQuery, {
    query: '$computedQuery'
  })
  onExecuteQuery({data, error}) {
    if (error) {
      console.log(`executeQuery(${computedQuery}) ERROR:`, error);
    } else if (data) {
      console.log('executeQuery results RESPONSE:', data.results.records);
      console.log('executeQuery metadata RESPONSE:', data.results.metadata);
    }
  }
}
```

## CRM Analytics API Resource

```html
POST /wave/query
```

`executeQuery` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_query.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                    | Required?                                  |
| --------------- | ------ | ------------------------------------------------------------------------------ | ------------------------------------------ |
| `query`         | String | The query string to execute.                                                   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `queryLanguage` | String | The query language. The default is SAQL.<ul><li>`SAQL`</li><li>`SQL`</li></ul> |                                            |
| `timeZone`      | String | The timezone for the query.                                                    |                                            |

## Returns

- `data`—[Literal JSON](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_literal_json.htm) query results
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

**See Also**

- [_CRM Analytics REST API Developer Guide:_ Query CRM Analytics Data with the Query API](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_rest_api_query_data.htm)
- [_CRM Analytics REST API Developer Guide:_ Query Resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_query.htm)

<!-- document id=1424c9d1bdc68f6b02764f7146b698c8adf49513c72ebde639fd235c833d4802 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-execution-modes.md -->

# Execution Modes for Lightning Components

The Lightning Component framework executes in one of two modes: production and debug.

Let’s look at the differences between the execution modes.

<!-- document id=276b33634ea094a1f26e833fe658a973b0247c471068a543535e5f935983122f url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-lms-ec.md -->

# Experience Builder Sites and Lightning Web Security

If Lightning Web Security (LWS) is enabled in an org that contains Experience Builder Aura sites, LWS protects Lightning web components and Aura components in the Aura sites.

LWS protects Lightning web components and Aura components in Lightning Web Runtime (LWR) sites too. However, LWR sites have their own instance of LWS that isn’t affected by the org’s LWS setting.

For more information, see [Develop Secure Sites: CSP, LWS, and Lightning Locker](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_security_locker_csp.htm) in the _Experience Cloud Developer Guide_.

**See Also**

- [_Experience Cloud Developer Guide_](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_intro.htm)

<!-- document id=5357ecd98ab6212b10c4cb50776f423e40604514c9d799826ee5b2815d77d489 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-overview.md -->

# Experience Cloud Sites

Create custom Lightning web components for your Aura and Lightning Web Runtime (LWR) sites. Add custom property types and property editors to these components to give your Experience Builder users a smooth site-building experience.

<!-- document id=e4098b76045573e89c3c2977d9e4bbf7144f786b35467cb182c8070beabe5862 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-experience-block-builder-api.md -->

# `experience/blockBuilderApi` Module

Use this module only with [CMS Extensions for Marketing Cloud Next](https://developer.salesforce.com/docs/platform/cms/guide/cms-extensions-build-marketing.html). Get and replace a selected component in a Marketing Cloud Next content item.

- [`getCurrentSelectedBlock`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-current-selected-block.md)
- [`replaceBlock`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-replace-block.md)

<!-- document id=29c09e7e5aa9d9d060dbd50be8b55039e3ea6096ee0a34df91f72ff400f6586d url=/developer/current/en-us/lwc/lwc/guides/reference/reference-experience-cms-api.md -->

# `experience/cms*Api` Wire Adapters and Functions

Use these wire adapters and functions to work with Salesforce CMS content in Experience Cloud sites.

- [`experience/cmsDeliveryApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-experience-cms-delivery-api.md)
- [`experience/cmsEditorApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-experience-cms-editor-api.md)

<!-- document id=e2166bd2a11de638138c82e7b430fb87cce9d44780e913b619f9f9d2fbaff9c8 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-experience-cms-delivery-api.md -->

# `experience/cmsDeliveryApi`

Get published content or a list of published content from an enhanced CMS workspace.

- [`getContent`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-delivery-get-content.md)
- [`getContents`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-delivery-get-contents.md)

<!-- document id=5a0b482af07e79171e52a3f26c90ccc47d6d1c282534947be7c326dc2c68e630 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-experience-cms-editor-api.md -->

# `experience/cmsEditorApi`

Get and set content in the content editor of an enhanced CMS workspace.

- [`getContent`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-editor-get-content.md)
- [`getContext`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-editor-get-context.md)
- [`updateContent`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-editor-update-content.md)

<!-- document id=0902b1ae9befcbc60d6f41a461148f9dcf6408614dc3b8abb8fb6cbf03db6994 url=/developer/current/en-us/lwc/utam/references/explicit-waits.md -->

# Explicit Waits

Many page objects and UI tests rely on large implicit timeout values to find an element that appears as the result of a user action. This approach can be problematic and can often lead to flappy tests due to changes in the testing environment or network delays. Instead, write more durable tests by waiting for certain actions to complete and yield until the conditions are met. Instead of waiting for an implicit time, wait for a condition to be ready (explicit wait) for the test to proceed.

## Grammar

We define an explicit wait by setting the `apply` value to `waitFor`, which is a public method that exercises a fluent wait for an element.
The wait wraps one or more functions and repeatedly invokes them within a timeout until they return a truthy value (boolean `true` or any value that isn't `null` or `undefined`).

The function invoked inside `waitFor` is defined in the `args` array as a parameter for a method used in a compose statement:

- `type` is set to `function`.
- `predicate` is an array of compose statements that is invoked to test for the wait condition.

The `predicate` value is a list of compose statements that will be executed until a truthy value is returned (no error, not null, and not false).

```json
{
  "apply": "waitFor",
  "args": [
    {
      "type": "function",
      "predicate": [
        {
          "element": "foo",
          "apply": "click"
        }
      ]
    },
    {
      "value": "custom error message"
    }
  ]
}
```

The second parameter `"value" : "custom error message"` is optional and represents an error message that will be thrown if the action times out. By default, the error message is "Timeout after 20 seconds". A custom message makes the error more meaningful if a UI test fails.

## Wait for an element

To wait for a particular element to be present, set `wait` to true for the element. This shortcut generates a [waitFor method for the element](/grammar/element-types#wait-for-an-element).

## Load an element

For the `load` method of the page object to wait for a particular element to be present, set `load` to true for the element. This shortcut generates a [waitFor method for the element](/grammar/element-types#load-an-element) that is invoked in the [beforeLoad](/grammar/before-load) method. This is only applicable to elements without arguments or are not container elements.

## Return type inside predicate

If a compose statement is a `"waitFor"` action or an explicit wait, the return type is the return type of the last predicate statement. Similarly to a regular statement, the return type can be inferred, void, or set explicitly. Here are some examples.

- return type can be inferred because it's an element getter invocation, so this method returns the custom element type

```json
{
  "elements": [
    {
      "name": "custom",
      "selector": {
        "css": "my-custom-element"
      },
      "type": "my/custom/element"
    }
  ],
  "methods": [
    {
      "name": "returnCustomElement",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "custom"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

- return type is set explicitly, so this method returns a list or array of strings as specified in the last statement of the predicate

```json
{
  "elements": [
    {
      "name": "custom",
      "selector": {
        "css": "my-custom-element"
      },
      "type": "my/custom/element"
    }
  ],
  "methods": [
    {
      "name": "returnCustomElement",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "custom"
                },
                {
                  "chain": true,
                  "apply": "customElementPublicMethod",
                  "returnType": "string",
                  "returnAll": true
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**important:** Setting a `returnType` outside a predicate isn't allowed. This page object throws an error:

```json
{
  "methods": [
    {
      "name": "clickAndReturn",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "apply": "getString"
                }
              ]
            }
          ],
          "returnType": "string"
        }
      ]
    }
  ]
}
```

## Explicit wait timeout

You can set timeout values in UTAM for implicit and explicit waits for Java and JavaScript.

An implicit timeout is a time duration used to find an element inside its parent element or inside the driver for a root page object.

**important:** As of version 1.0.0, implicit timeouts in UTAM are set to 0. Do not override this value.

An explicit wait timeout is used for any `waitFor` method inside UTAM framework, for example `waitFor` is used inside `compose` and `beforeLoad` in JSON, or can be invoked on a page object in a test.
Explicit timeout duration depends on many factors such as application performance and network access to the environment where tests are being run. It should be set to the maximum reasonable duration for which a test should wait for the server to respond and for the browser to finish rendering the page. It can be as short as 5000 ms and as long as 90 seconds.

**note:** If a timeout isn’t set, the default for explicit timeouts is 20 seconds.

For more information on how implicit and explicit timeouts affect UI tests, see:

- [Selenium: Waits](https://www.selenium.dev/documentation/webdriver/waits/)
- [Webdriver.io: Auto-waiting](https://webdriver.io/docs/autowait/)

Here are some examples of using explicit waits.

## Use Explicit Wait instead of a Retry

Consider this Java unit test code snippet that retries an attempt to click a button:

```java
    try {
        button.click();
        Thread.sleep(1000);
    } catch (Exception e) {
        button.click();
    }
```

This code pattern usually means that the button isn't clickable initially and there’s a waiting period for an element to be in the state to accept such actions.

Here's a better pattern: wrap the click action into an explicit wait.

```json
{
  "elements": [
    {
      "name": "button",
      "type": "clickable",
      "selector": { "css": ".not-yet-clickable" }
    }
  ],
  "methods": [
    {
      "name": "waitAndClick",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "button",
                  "apply": "click"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Wait Before Assertion

Consider this Java unit test code snippet that repeatedly attempts to assert displayed text while the text is being loaded.

```java
    while(iterations < 10) {
        try {
            Thread.sleep(1000);
            if(fieldWithText.getText().equals("my expected text")) { return; }
        } catch (Exception e) {
            iterations ++;
        }
    }
```

Instead of hardcoding retry and sleep steps in a loop, add a `getLoadingText` method that accepts expected text as a parameter and uses an explicit wait to wait for the text to match.

```json
{
  "elements": [
    {
      "name": "fieldWithText",
      "selector": { "css": ".loading" }
    }
  ],
  "methods": [
    {
      "name": "getLoadingText",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "fieldWithText",
                  "apply": "getText",
                  "matcher": {
                    "type": "stringEquals",
                    "args": [
                      {
                        "name": "expectedText",
                        "type": "string"
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

Now the Java test code can look like this:

```java
assert pageObject.getLoadingText("my expected text");
```

## Wait for a Container Element

What if we need to wait for a container element? A container element is a placeholder for any internal component known only at runtime. Here's a container declaration:

```json
{
  "elements": [
    {
      "name": "panelContainer",
      "type": "container",
      "public": true
    }
  ]
}
```

To wait for a container element to be loaded, we can use one of the following approaches:

1. Add a `waitForAnyPanelContent` compose method that waits for any element inside a container using `containsElement`. This method is universal because it waits for any child element, so it's the preferred option. If waiting for the universal selector doesn't work for some reason, the page object needs to wait for a particular selector, as described in the example for the next approach.

```json
{
  "methods": [
    {
      "name": "waitForAnyPanelContent",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "root",
                  "apply": "containsElement",
                  "args": [
                    // this selector means any child
                    {
                      "type": "locator",
                      "value": { "css": ":scope > *:first-child" }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

2. Add a `waitForMyComponentPanelContent` compose method that waits for a particular selector using the same `containsElement` basic action.

```json
{
  "methods": [
    {
      "name": "waitForMyComponentPanelContent",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "root",
                  "apply": "containsElement",
                  "args": [
                    // this selector is specific for MyComponent
                    {
                      "type": "locator",
                      "value": { "css": "my-component" }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

3. If you need your method to return an instance of a particular page object inside a container, add a `waitForMyComponentPanelContent` compose method that invokes a container method wrapped in a wait with a hardcoded page object type. Then, the method will return an object of the given type:

```json
{
  "elements": [
    {
      "name": "panelContainer",
      "type": "container"
    }
  ],
  "methods": [
    {
      "name": "waitForMyComponentPanelContent",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "returnType": "utam/pageObjects/MyComponent",
                  "element": "panelContainer",
                  "args": [
                    {
                      "type": "pageObject",
                      "value": "utam/pageObjects/MyComponent"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

<!-- document id=e13862e3426ec9ba6d9e391ff5df8746ebd701be0b18b2f621bbe858b21fa03d url=/developer/current/en-us/lwc/lwc/guides/install/install-sample-code-repo.md -->

# Explore Trailhead and Sample Code

We’ve created Trailhead content and GitHub repositories to jump-start your Lightning Web Components development.

## Lightning Web Components Recipes

A collection of easy-to-digest code examples for Lightning Web Components. Each recipe demonstrates how to code a specific task in the fewest lines of code possible, while following best practices. A View Source link takes you right to the code in GitHub.

The recipes cover all the basics: composition, state management, events, data access, and navigation. The Lightning Web Components Developer Guide references many recipes from this repo.

To get started, [clone the repo](https://github.com/trailheadapps/lwc-recipes) and follow the steps in the README.

## Trailhead Projects and Modules

Get hands-on experience creating Lightning web components on the [Build Lightning Web Components](https://trailhead.salesforce.com/content/learn/trails/build-lightning-web-components) trail.

Troubleshoot Lightning Web Components and learn about best practices on the [Troubleshoot Lightning Web Components](https://trailhead.salesforce.com/content/learn/trails/troubleshoot-lightning-web-components) trail.

## E-Bikes Sample Application

The E-Bikes sample application demonstrates how to build applications with Lightning Web Components and integrate with Salesforce Experiences. E-Bikes is a fictitious electric bicycle manufacturer. The application helps E-Bikes manage their products and reseller orders using a rich user experience.

Install the [E-Bikes sample application](https://github.com/trailheadapps/ebikes-lwc).

<!-- document id=9cbc98aa88a8161a179f6823d385d7406f5bf1118ff0179bc864f102d60a5be9 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-expose-method.md -->

# Expose Apex Methods to Lightning Web Components

To expose an Apex method to a Lightning web component, the method must be `static` and either `global` or `public`. Annotate the method with `@AuraEnabled`.

## Syntax

```apex
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Picture__c != null
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

These types are supported for input and output.

- [Primitive](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_attr_types_basic.htm)—Boolean, Date, DateTime, Decimal, Double, Integer, Long, and String.
- [sObject](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_attr_types_object_salesforce.htm)—standard and custom sObjects are both supported.
- [Apex](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_attr_types_apex.htm#ref_attr_types_apex)—an instance of an Apex class. (Most often a custom class.)
- [Collection](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_attr_types_collection.htm)—a collection of any of the other types.

**note:** - An Apex inner class as a parameter or return value for an Apex method that's called by a Lightning web component isn’t supported.
- The `@NamespaceAccessible` Apex annotation for an `@AuraEnabled` Apex method referenced from a Lightning web component isn’t supported. A Lightning web component installed from a package can’t call an Apex method from an Apex class in another package, even if both packages are in the same namespace.

## Usage

The Lightning Component framework doesn’t enforce any rules about the location of Apex classes. If you’re using Salesforce DX, place Apex classes in the `<app dir>/main/default/classes` directory.

When you construct your Apex method, you must decide whether to pass in the parameters as primitives, or as complex data types—like an Apex class or an sObject.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an [`apexImperativeMethodWithParams`](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/apexImperativeMethodWithParams) and [`apexImperativeMethodWithComplexParams` component](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/apexImperativeMethodWithComplexParams) example that calls a method with primitives or complex parameters.

**See Also**

- [_Apex Developer Guide_: Static Methods](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_static.htm)
- [_Apex Developer Guide_: Access Modifiers](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_access_modifiers.htm)

<!-- document id=53b9e8826e735f226322066a0b495d31028c703ce1f1ca465468948db0f08ad6 url=/developer/current/en-us/lwc/slds_linter/guides/support/support-faq.md -->

# FAQ

For help with SLDS Linter, read our frequently asked questions.

## What are the Node.js Requirements for SLDS Linter?

SLDS Linter works best with Node.js version **v18.4.0 or later.**
You can check your Node.js version by using this command.

```bash
node --version
```

If you’re using an earlier version, upgrade to the latest [Active Long Term Support](https://nodejs.org/en/about/previous-releases) (LTS) version of Node.js.

## Does SLDS Linter Work on Windows Machines?

Yes, SLDS Linter works seamlessly on Windows systems.  
The tool is platform-independent and can be used on Windows, Mac, and Linux systems. All features, including auto-fixing, configuration, and VS Code integration work consistently across all platforms.

## How Do I automatically Fix Issues Identified by SLDS Linter?

See [Autofix Your Code](https://developer.salesforce.com/docs/platform/slds-linter/use/use-autofix-code.md).

## What Output Formats are Available to Display Identified Issues?

To display issues, SLDS Linter supports two formats.

- SARIF format:

  This is the default report format.

  For example, here's how to generate a SARIF report and place it in a specific directory.

  ```
  npx @salesforce-ux/slds-linter@latest report -o [output directory]
  ```

  The output file is named `slds-linter-report.sarif`.

- CSV format:

  You can generate a report in the CSV format using this command:

  ```
  npx @salesforce-ux/slds-linter@latest report  --format csv
  ```

## How Do I Enable Squiggly Lines for Errors?

To enable squiggly lines, follow these steps.

1. Install this recommended VS Code extension.

   [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint): Applicable for linting HTML, CMP, and CSS files.

2. Run the `emit` command to generate a custom configuration file. The VS Code extension uses this file to show squiggly lines in HTML, CMP, and CSS files.

   ```
   npx @salesforce-ux/slds-linter emit
   ```

   For more information, see the [Use SLDS Linter With Custom Configuration Files](https://developer.salesforce.com/docs/platform/slds-linter/use/use-custom-config-files.md) topic.

<!-- document id=c50e4bf2248c668c2194b0981ef7a667f9bea7a94d2c2abc6d86eb2ffe96029c url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-intro.md -->

# Fields, Properties, and Attributes

Declare fields in your component’s JavaScript class. Reference them in your component’s template to dynamically update content.

_Field_ and _property_ are almost interchangeable terms. A component author declares fields in a class. An instance of the class has properties. To component consumers, fields are properties. In a Lightning web component, only fields that a component author decorates with `@api` are publicly available to consumers as object properties. LWC observes changes to the values of fields and properties. See [Reactivity](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md).

[_Property_ and _attribute_](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-names.md) are almost interchangeable terms and can be confusing. Generally speaking, in HTML we talk about attributes, and in JavaScript we talk about properties.

Lightning web components reflect the properties of many [Web APIs](https://developer.salesforce.com/docs/platform/lwc/js/js-web-apis.md). For accessibility, you can also control whether public JavaScript properties appear as attributes in the rendered HTML of a Lightning web component. See [Reflect JavaScript Properties to HTML Attributes](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-html-attributes.md).

**tip:** If you’ve developed an Aura component, you’re familiar with the term attribute. In a Lightning web component, the closest thing to an Aura attribute is a JavaScript property.

Additionally, you can learn how to work with:

- [Getters and Setters](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getters-setters.md)
- [Boolean Properties](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-boolean.md)
- [Attribute Dependencies](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getters-dependencies.md)

<!-- document id=20232d4c1000e80538447aba3e7e588d129c5e6f6cbee7221edc5eedcb32ba83 url=/developer/current/en-us/lwc/utam/guide/find-sf-page-objects.md -->

# Find Salesforce Page Objects

The easiest way to find a UTAM page object that matches a particular UI element is to use UTAM's [browser extension](https://developer.salesforce.com/docs/platform/utam/guide/browser-extension.md). This article is an alternative more manual method to find Salesforce page objects by inspecting the DOM.

Lightning Experience uses Aura or Lightning web components for most of its UI elements. All UTAM page objects for Salesforce are written for one of those types of components.

Let's talk about how you can identify the type of component by inspecting the DOM in your browser.

- An Aura component always has a `data-aura-class` attribute.
- A Lightning web component always has a custom HTML tag, such as `lightning-input` or `records-record-layout-base-input`.

## Inspect an Element for an Aura Component

In your browser, inspect the UI element that you want to interact with in a test. In the browser console, find an element with a `data-aura-class` attribute:
![Aura UI component](https://developer.salesforce.com/docs/media/utam/auraComponent.jpg)

The `data-aura-class` attribute of an Aura component enables us to deduce the class name of the page object. The attribute value is in camel case. For example, the first part of `forceActionLink` (`force`) is the namespace and the remainder (`ActionLink`) is the class name.

The full Java class name is `utam.force.pageobjects.ActionLink`.

The full JavaScript class name is `utam-salesforce-pageobjects/force/pageObjects/actionLink` (assuming the package name that contains Salesforce Page Objects is `utam-salesforce-pageobject`).

## Inspect an Element for a Lightning Web Component

In your browser, inspect the UI element that you want to interact with in a test. In the browser console, find an element with a custom tag name:
![Lightning UI component](https://developer.salesforce.com/docs/media/utam/lightningComponent.jpg)

The custom HTML tag of a Lightning web component enables us to deduce the class name of the page object. For example, in the `lightning-input` tag, the first part before the dash (`lightning`) is the namespace and the remainder (`input`) is the class name.

The full Java class name is `utam.lightning.pageobjects.Input`.

Note that a Lightning web component isn't always in the `lightning` namespace. For example, the `records-record-layout-base-input` element is in the `records` namespace, and the class name is `utam.records.pageobjects.RecordLayoutBaseInput`.

The full JavaScript class name is `utam-salesforce-pageobjects/records/pageObjects/recordLayoutBaseInput` (assuming the package name that contains Salesforce Page Objects is `utam-salesforce-pageobject`).

## Find a Packaged Salesforce Page Object

First, download and unpack the Javadoc files, as explained [here](https://developer.salesforce.com/docs/platform/utam/guide/test-sf-applications.md#finventory-of-salesforce-pageobjects).

### Find by Selector

Use the browser Developer Tools to inspect the UI and find the CSS selector our page object should have; for example, `.forceActionLink` or `lightning-input`. Open the `index-all.html` file in the unpacked Javadoc jar and use the Javadoc search field in the browser:

![Search by selector](https://developer.salesforce.com/docs/media/utam/search-by-selector.png)

### Find by Class

You can also search by class name. For example, the `lightning-card` component would have the class name: `Card`.

![Search by class](https://developer.salesforce.com/docs/media/utam/search-by-type.png)

**important:** Unless you're using the Javadoc viewer, clicking on the class will not work. Once you've confirmed which class to use, go back to `index-all.html` to find all its methods.

## Get to a UI Element from the Root

Now, how do we get to an interactive UI element from the page root? Because of shadow boundaries, we mightn't be able to access the element directly.

![From root to element](https://developer.salesforce.com/docs/media/utam/hierarchy.jpg)

First, find the root page object, which is the outermost page object that the test will instantiate using `UtamLoader.load`. A root page object is marked with `"root": true` in its JSON file. In our example, the root page object is `ConsoleObjectHome`.

Follow the arrows and call getter methods for enclosing page objects to finally get to the actionLink:
`oneConsoleObjectHome -> forceListViewManager -> forceListViewManagerHeader -> forceActionsContainer -> forceActionLink`

Here's how we would navigate the page object hierarchy in a Java test:

```java
// first load root page object
ConsoleObjectHome objectHome = utam.load(ConsoleObjectHome.class);

// in a page object for ConsoleObjectHome find a getter method
// that returns an element with selector 'forceListViewManager'
ListViewManager listView = objectHome.getListView();

// in a page object for ListViewManager find a getter method
// that returns an element with selector 'forceListViewManagerHeader'
ListViewManagerHeader header = listView.getHeader();

// in a page object for ListViewManagerHeader find a getter method
// that returns an element with selector 'forceActionsContainer'
ActionsContainer actions = header.getActions();

// finally, find the method that returns a button by text
actions.getAction("New");
```

The name of the getter method isn't always intuitive, but you can always open either the JSON or generated page object and check which element or method returns an element selected by the locator that you need next. For example, `listViewHeader.utam.json` has an `actions` element like in the snippet below:

```json
{
  "name": "actions",
  "type": "utam-force/pageObjects/actionsContainer",
  "public": true,
  "selector": {
    "css": ".forceActionsContainer"
  }
}
```

<!-- document id=203dfa63859d12a2021647a396cb1eb199f3e8dda7f2bc0467b36cec513d24ab url=/developer/current/en-us/lwc/lwc/guides/use/use-flow.md -->

# Flows

Flow Builder lets admins automate business process with a flow. Learn to develop and configure Lightning web components to be used as flow screen components and custom UI for actions and screen components in Flow Builder.

<!-- document id=689625aecb89d3349f446fb5ad537b4029b89387f72494840c3284e115358b91 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-general-guidelines.md -->

# General Guidelines for Creating a Custom Property Editor

These recommendations can help you avoid common mistakes and deliver a consistent end-user experience when you create a custom property editor.

**Don't use the property editor to validate user input.** The property editor is intended to affect only the user interface in Experience Builder. Make sure that the property editor always sends the user-input value without changing or processing it. The property sheet validates the input value by ensuring that the property value is valid according to the property's type schema. If the property sheet finds any validation errors, it injects those errors into the property editor via the `errors` property.

This code sample shows what _not_ to do. In the sample, the code violates this guideline by performing a validation check on the value entered by the user and setting its own error message. The code also bypasses firing the `valuechange` event when this special validation condition is met.

```javascript
export default class CustomPropertyEditor extends LightningElement {
  @api value;
  @api label;
  @api schema;
  @api errors;
  handleOnBlur(event) {
    // Don't do this
    if (this.value.contains("myCustomValidation")) {
      this.errors = [{ message: "My Special validation is broken" }];
      return;
    }
    this.dispatchEvent(new CustomEvent("valuechange", { detail: { value: this.value } }));
  }
}
```

**Don't create flyouts, popouts, or window overlays (also known as modals)**. These user experience patterns can interrupt the Experience Builder user's editing experience.

**Don't use CSS to define the absolute position of an element.** This pattern doesn't always behave as expected and can cause elements to be misaligned. (See [MDN Web Docs: position](https://developer.mozilla.org/en-US/docs/Web/CSS/position) for more information.)

**Don't set CSS width properties to determine the width of your property editor.** Setting width properties affects the size of the property panel in Experience Builder and can cause problems with user experience.

**Don't fire the `valuechange` event too often.** A canvas refresh is triggered whenever the property sheet handles the `valuechange` event fired from a property editor. Too many refreshes of the canvas per second hinders Experience Builder performance. For example, when you bind `valuechange` to events such as `keydown` or `mousemove` for an input, the canvas refreshes multiple times per second. We recommend binding `valuechange` to a committal event, such as `blur`, instead.

This example shows what _not_ to do. Here, the `valuechange` event fires on every keypress of an input. An Experience Builder user who types rapidly can unknowingly trigger dozens of canvas refreshes and slow down the editing experience of this component.

```javascript
export default class AlignmentCPE extends LightningElement {
  @api value;
  @api label;
  @api errors;
  // Don't do this - Use "blur" instead
  handleOnKeyDown(event) {
    this.dispatchEvent(new CustomEvent("valuechange", { detail: { value: this.value } }));
  }
}
```

<!-- document id=d15aa44fefb467f1257f10b2b9bea644bd8ac73e0fb046118e07edfa3a72dbaf url=/developer/current/en-us/lwc/lwc/guides/reference/reference-generate-record-input-create.md -->

# `generateRecordInputForCreate(record, objectInfo)`

Generates a representation of a record (Record Input) that can be used to create a record using `createRecord(RecordInput)`. Passing in `ObjectInfo` filters the Record Input to only fields that are createable.

## Syntax

```javascript
import { generateRecordInputForCreate } from 'lightning/uiRecordApi';
generateRecordInputForCreate(record: Record, objectInfo?: ObjectInfo): RecordInput
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                  | Required?                               |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `record`       | Object | A [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm#ui_api_responses_record) object that contains source data. To get data to build the Record object, use the `getRecordCreateDefaults`.                                                              | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `objectInfo`   | Object | The [ObjectInfo](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm#ui_api_responses_object_info) corresponding to the `apiName` on the record. If provided, only fields with the property `createable=true` (excluding `Id`) are included in the response. |                                         |

## Returns

A [Record Input](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm) object with its data populated from the given record. Returns all fields whose values are not nested records.

## Usage

Return the Record Input object on a contact record.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecordCreateDefaults, generateRecordInputForCreate } from "lightning/uiRecordApi";
import CONTACT_OBJECT from "@salesforce/schema/Contact";

export default class WireGenerateRecordInput extends LightningElement {
  @wire(getRecordCreateDefaults, { objectApiName: CONTACT_OBJECT })
  contactCreateDefaults;

  get recordInputForCreate() {
    if (!this.contactCreateDefaults.data) {
      return undefined;
    }

    const contactObjectInfo = this.contactCreateDefaults.data.objectInfos[
      CONTACT_OBJECT.objectApiName
    ];
    const recordDefaults = this.contactCreateDefaults.data.record;
    const recordInput = generateRecordInputForCreate(recordDefaults, contactObjectInfo);
    return recordInput;
  }

  get errors() {
    return this.contactCreateDefaults.error;
  }
}
```

The object returned for a contact record by calling `generateRecordInputForCreate` with the value from `getRecordCreateDefaults` looks like this.

```javascript
{
  "apiName": "Contact",
  "fields": {
    "AccountId": null,
    "AssistantName": null,
    "AssistantPhone": null,
    "Birthdate": null,
    "Department": null,
    "Description": null,
    "Email": null,
    "Fax": null,
    "FirstName": null,
    "HomePhone": null,
    "LastName": null,
    // More fields here
  }
}
```

<!-- document id=e72846e75915bd35c6fdc839faf5d1ae6b57b4262e15e8a4f2b13f4922c3f12b url=/developer/current/en-us/lwc/lwc/guides/reference/reference-generate-record-input-update.md -->

# `generateRecordInputForUpdate(record, objectInfo)`

Generates a representation of a record (Record Input) that can be used to update a record using `updateRecord(recordInput)`. Passing in `ObjectInfo` filters the Record Input to only fields that are updateable.

## Syntax

```javascript
import { generateRecordInputForUpdate } from 'lightning/uiRecordApi';
generateRecordInputForUpdate(record: Record, objectInfo?: ObjectInfo): RecordInput
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                      | Required?                               |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `record`       | Object | A [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm#ui_api_responses_record) object that contains source data. To get data to build the Record object, use the [getRecord](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record.md) wire adapters.                                                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `objectInfo`   | Object | The [ObjectInfo](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm#ui_api_responses_object_info) corresponding to the `apiName` on the record. To get the object info, use the [getObjectInfo](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-object-info.md) wire adapter. If provided, only fields with the property `updateable=true` (excluding `Id`) are included in the response. |                                         |

## Returns

A [Record Input](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm) object with its data populated from the given record. Returns all fields whose values are not nested records.

## Usage

Return the Record Input object on a record.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord, generateRecordInputForUpdate } from "lightning/uiRecordApi";
import { getObjectInfo } from "lightning/uiObjectInfoApi";

export default class WireGenerateRecordInput extends LightningElement {
  @api recordId;
  @api objectApiName;

  @wire(getRecord, {
    recordId: "$recordId",
    layoutTypes: "Full",
    modes: "Edit",
  })
  wiredRecord;

  get recordInputForUpdate() {
    if (!this.wiredRecord.data || !this.objectInfo.data) {
      return undefined;
    }

    const recordInput = generateRecordInputForUpdate(this.wiredRecord.data, this.objectInfo.data);
    return recordInput;
  }

  get errors() {
    return this.wiredRecord.error;
  }
}
```

The object returned by `generateRecordInputForUpdate` for a contact record looks like this. The fields returned depend on what your admin has included in the object's layout.

```javascript
{
  "fields":{
    "AccountId":"0011a0000000000AAA",
    "AssistantName":null,
    "AssistantPhone":null,
    "Birthdate":"1941-09-26",
    "Department":"Finance",
    "Description":null,
    "Email":"ajames@example.com",
    "Fax":"+1 415 1234567",
    "FirstName":"Ashley",
    "HomePhone":null,
    "LastName":"James",
    "LeadSource":"Public Relations",
    "MailingCity":"San Francisco",
    "MailingCountry":"USA",
    // More fields here
    "Id":"0031a0000000000AAA"
  }
}
```

We recommend using `getRecord` with `layoutTypes` (instead of `fields`) only if the resulting data will be used with the actual layout.

If you need specific fields, use `fields` or `optionalFields` rather than assume that those fields are present in the layout.

## Example

See the [ldsGenerateRecordInputForCreate](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/ldsGenerateRecordInputForCreate) example in the lwc-recipes repository.

<!-- document id=3290d8cff51fc0c2d5acc4edae912a65f3fabf685d9dd4f95a1377e69c324cb7 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-generate-url.md -->

# `generateUrl`

Generates and returns a URL for downloading a file in an LWR site in Experience Cloud.

## Syntax

```javascript
import { generateUrl } from "lightning/fileDownload";
const url = generateUrl(recordId);
window.open(url);
```

## Parameters

`recordID`—(Required) The record ID of the file (ContentDocument, ContentVersion, Attachment, or Document) to be downloaded.

## Returns

A URL for downloading a file.

## Usage

Authenticated users can download files they have access to. Guest users can download only ContentDocument files that they have access to through Library membership.

This code sample generates a URL for downloading a file.

```javascript
import { LightningElement, api } from "lwc";
import { generateUrl } from "lightning/fileDownload";

export default class Download extends LightningElement {
  @api recordId;
  url;

  handleClick() {
    this.url = generateUrl(this.recordId);
  }
}
```

<!-- document id=233d4001157988e64840b840fcf40dc6c4147d10c7310adfa1362e7b3936faf2 url=/developer/current/en-us/lwc/utam/guide/generator-rules.md -->

# Generator Rules

All generator rules are optional and can be set at the project level, next to component HTML files, or in both places.
Generation parameters from the component-level rules override the rules defined at the project level.

Any runner or JSON generation parameter can be overridden at the source code level. See [Override generated content](https://developer.salesforce.com/docs/platform/utam/guide/generator-override-content.md).

Runner parameters are explained in [Generation runner parameters](https://developer.salesforce.com/docs/platform/utam/guide/generator-get-started.md#generation-runner-parameters).

The next sections explain the configuration parameters responsible for how the generator interprets HTML and affects the generated JSON.

**warning:** The supported parameters were updated in version 2.1.0. Do not use earlier versions.

Each string value set in the configuration for elements can be a regular string (for a full match) or a regular expression for a partial match.

## Public basic, container, and frame elements

A public [basic element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#basic-elements), [container](/docs/platform/utam/references/utam-grammar/page-object-elements.html#container-elements) or [frame](/docs/platform/utam/references/utam-grammar/page-object-elements.html#frame-elements) is generated from an HTML tag if it has a certain tag name, a `class` attribute with a given value, a `type` attribute with a given value, or if an element has one of the listed attributes.

To ignore something that is configured to be included, use the optional `excludeElements` parameter.

Configuration parameter: **`publicElements`**

- Type: `object`
- Default:

````js
publicElements: {
        withTags: {
            input: ['actionable', 'clickable', 'editable'],
            button: ['actionable', 'clickable'],
            a: ['actionable', 'clickable'],
            area: ['actionable', 'clickable'],
            li: ['actionable', 'clickable'],
            option: ['actionable', 'clickable'],
            menuItem: ['actionable', 'clickable'],
            textarea: ['actionable', 'clickable', 'editable'],
            select: ['actionable', 'clickable', 'editable'],
            iframe: 'frame',
            td: [],
            th: [],
            title: [],
            slot: 'container',
        },
        withType: {
            button: ['actionable', 'clickable'],
            checkbox: ['actionable', 'clickable'],
            radio: ['actionable', 'clickable'],
            reset: ['actionable', 'clickable'],
            submit: ['actionable', 'clickable'],
        },
        withAttributes: {
            onclick: ['actionable', 'clickable'],
            ondblclick: ['actionable', 'clickable', 'editable'],
            onkeydown: ['actionable', 'editable'],
            onkeypress: ['actionable', 'editable'],
            onchange: ['actionable'],
        },
    }
``

For example for the following HTML:

```html
<div>
    <button type="button">Click Me!</button>
    <div onchange={handle}>test events</div>
</div>
````

The generator produces the following public elements:

```json
"elements" : [
    {
        "public": true,
        "name": "button",
        "type": ["actionable", "clickable"],
        "selector": { "css": "button" }
    },
    {
        "public": true,
        "name": "div",
        "type": ["actionable"],
        "selector": { "css": "div" }
    },
]
```

## Container element

According to default rules for public elements, a public [container element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#container-elements) is generated from a `<slot>` HTML element.

```html
<template if:false="{computedShowOutputField}">
  <span class="test-id__field-value slds-size_1-of-1">
    <slot name="inputField"></slot>
    <slot></slot>
  </span>
</template>
```

The generator produces the following public container element:

```json
{
  "public": true,
  "name": "inputField",
  "type": "container",
  "selector": { "css": "[slot='inputField']" }
}
```

Configuration parameter: **`containerSelector`**

- Type: `string`
- Default: `:scope > *:first-child`

If the slot doesn't have a `name` attribute, it's the default slot, so the generated selector depends on the `containerSelector` parameter.
The content of the slot isn't processed further because a container can't have child elements.

```json
{
  "public": true,
  "name": "slot",
  "type": "container",
  "selector": { "css": ":scope > *:first-child" }
}
```

## Frame element

According to default rules for public elements, a [frame element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#frame-elements) is generated from an `<iframe>` HTML element.

```html
<div class="frame">
  <iframe src="https://www.w3schools.com" title="W3Schools Free Online Web Tutorials"></iframe>
</div>
```

The generator produces the following public frame element:

```json
{
  "public": true,
  "name": "iframe",
  "type": "frame",
  "selector": { "css": "iframe" }
}
```

## Custom elements

A [custom element](/docs/platform/utam/references/utam-grammar/page-object-elements.html#custom-elements) is generated from a custom HTML element. An HTML element is considered custom if its tag isn't part of the HTML5 standard and contains "-"; for example, `<custom-element>`.

```html
<template>
  <my-custom-element>Custom content</my-custom-element>
</template>
```

The generator produces the following public custom element:

```json
{
  "public": true,
  "name": "customElement",
  "type": "my-namespace/pageObjects/customElement",
  "selector": { "css": "my-custom-element" }
}
```

A generated element requires a `type`, so the generator splits a custom HTML tag by "-" and considers the first part a namespace (in our example, it's `my`). Then, the generator tries to find a proper type prefix for the given namespace looking at the following configuration parameters.

### `namespaces`

- Type: `map`
- Default: `empty or {}`

First, the generator tries to find a match in the namespaces map. Let's say our config looks like this:

```json
{
  "namespaces": {
    "my": "my-namespace/pageObjects",
    "lightning": "salesforce/lightning/pageObjects"
  }
}
```

Since the generator can find a map entry for our namespace prefix `my`, it picks the type and adds the name, so the type is `my-namespace/pageObjects/component2`.

### `defaultNamespace`

- Type: `string`
- Default: `"utam/pageObjects/"`

If the `namespaces` map is empty or doesn't have a proper entry, the generator uses the preconfigured default namespace.

If there isn't a matching namespace, a custom element's type is `utam/pageObjects/customElement`.

## Traverse content of a custom element

### `generateCustomContent`

- Type: `boolean`
- Default: `false`

When the generator processes a custom HTML tag such as `my-custom-tag`, it can be treated as a separate HTML source to generate another UTAM page object. If this parameter is set to `true` and `myComponent1.html` contains a custom HTML tag such as `<my-component2>some HTML here</my-component2>`, the generator treats the content of the custom tag as another HTML source for generation and creates a `component2.utam.json` file.

```
<inputRootDir>
├── utam-generator.config.json
├── src/
   └── modules/
      ├── component1/
         └── component1.html
         └── __utam__/
            └── component1.utam.json
            └── component2.utam.json
```

### `ignoreCustomTags`

- Type: `string array`
- Default: `[]`

For custom HTML elements with tags such as `my-custom-tag`, the default behavior is to generate a custom element and not traverse the body of the custom HTML element because it's considered a different component and a different page object.

Use `ignoreCustomTags` if you prefer to avoid a custom element and generate JSON for the body of a custom HTML element instead.

```html
<div>
  <my-generated-component>
    <button id="number"></button>
  </my-generated-component>
</div>
```

By default, the generated JSON would be:

```json
{
  "elements": [
    {
      "public": true,
      "name": "generatedComponent",
      "selector": {
        "css": "my-generated-component"
      },
      "type": "utam/pageObjects/generatedComponent"
    }
  ]
}
```

But if a configuration file includes `"ignoreCustomTags" : ["my-generated-component"]`, the HTML content in the body of `my-generated-component` is traversed and an element is generated for the button. Here's the output:

```json
{
  "elements": [
    {
      "public": true,
      "name": "generatedComponent",
      "selector": {
        "css": "my-generated-component"
      },
      "shadow": {
        "elements": [
          {
            "public": true,
            "name": "customTest",
            "type": "clickable",
            "selector": {
              "css": "button#number"
            }
          }
        ]
      }
    }
  ]
}
```

## Scope elements

Some HTML elements are used to scope other elements. When an element is configured to be a scope element, the generator creates a private element.

### `scopeElements`

- Type: `object`
- Default:

```js
scopeElements: {
        withTags: ['footer', 'form', 'header', 'label', 'section', 'table', 'tr', 'ul', 'ol', 'menu'],
        withClasses: [],
        withAttributes: ['id', 'name', 'slot'],
    },
```

Consider this HTML:

```html
<table>
  <tr>
    <td>table cell</td>
  </tr>
</table>
```

The generator produces the following JSON, creating private scope elements for `table` and `tr` as configured. `td` isn't defined as a scope element so the generator creates a public `tableCell` element.

```json
{
  "elements": [
    {
      "name": "table",
      "type": [],
      "selector": {
        "css": "table"
      },
      "elements": [
        {
          "name": "tableRow",
          "type": [],
          "selector": {
            "css": "tr"
          },
          "elements": [
            {
              "public": true,
              "name": "tableCell",
              "type": [],
              "selector": {
                "css": "td"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

## Exclude elements from generated JSON

The `excludeElements` parameter is responsible for ignoring HTML elements for any type, basic, custom, or scope. It overrides `publicElements` and `scopeElements`.

### `excludeElements`

- Type: `object`
- Default:

```js
excludeElements: {
        withTags: ['meta', 'script', 'head', 'tbody'],
        withClasses: [],
        withAttributes: []
    }
```

## List elements

### `loopElements`

- Type: `object`
- Default:

```js
loopElements: {
        withAttributes: ['for:each', 'for:item', 'for:iterator'],
        withTags: [],
        withClasses: []
    }
```

If an HTML element is located inside a loop element, it's marked as a list (the generated selector has `returnAll: true`).

```html
<template for:each="{filteredTodos}" for:item="todo">
  <todo-item onupdate="{handleTodoUpdate}"></todo-item>
</template>
```

The generator produces the following public list element with `"returnAll": true`:

```json
{
  "public": true,
  "name": "items",
  "type": "utam/pageObjects/item",
  "selector": { "css": "todo-item", "returnAll": true }
}
```

In addition, the generator adds a public element with an indexed selector:

```json
{
  "public": true,
  "name": "itemByIndex",
  "type": "utam/pageObjects/item",
  "selector": {
    "css": "todo-item:nth-of-type(%d)",
    "args": [{ "name": "index", "type": "number" }]
  }
}
```

Some HTML elements with siblings that have the same HTML tag are also considered a list.

For example, repeated options in a `select` tag.

```html
<select>
  <option>one</option>
  <option>two</option>
</select>
```

The generator produces the following output:

```json
{
  "public": true,
  "name": "select",
  "type": ["actionable", "clickable", "editable"],
  "selector": { "css": "select" },
  "elements": [
    {
      "public": true,
      "name": "options",
      "type": ["actionable", "clickable"],
      "selector": { "css": "option", "returnAll": true }
    }
  ]
}
```

The content of the list elements isn't processed further because a list can't have child elements.

## Marking page object as a root

### `rootSelectors`

- Type: `string array`
- Default: `['form', 'html', 'body']`

The generated JSON can be marked as a [root](/grammar/root) if the root HTML element is one of: `<html>, <form>, <body>`. The root selector is the same as the root HTML element:

```html
<html>
  <body>
    <!-- content -->
  </body>
</html>
```

Generated JSON:

```json
{
  "root": true,
  "selector": {
    "css": "html"
  },
  "elements": []
}
```

## Traverse frame content

### `traverseFrameContent`

- Type: `boolean`
- Default: `false`

If parameter is set to true, generator will traverse content of the frame and create a separate JSON file for the content. For example for the given HTML file 'my-html' with two nested frames:

```html
<div class="content iframe-parent">
    <iframe id="outer">
        <html>
            <body>
                <custom-tag>something</custom-tag>
                <form>
                    <input>Outer frame</input>
                </form>
                <iframe id="inner">
                    <html>
                        <body>
                            <input>Inner frame</input>
                        </body>
                    </html>
                </iframe>
            </body>
        </html>
    </iframe>
</div>
```

If configuration parameter is set to `true`, the generator produces three files:

```
├── __utam__/
   └── my-html.utam.json
   └── my-html_irame.utam.json // for iframe with id="outer"
   └── my-html_irame_iframe.utam.json // for iframe with id="inner"
```

<!-- document id=ada3267a5e1b540f643584818e6022263e77c16ae0fb53b8a4e4831e6160ecba url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice.md -->

# GeofencingService API

Create and monitor geofences in a Lightning web component. 

The **Syntax** sections in the next topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this one.


```js
startMonitoringGeofence(geofence: Geofence): Promise<String>
```


Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

For more information on how GeofencingService works, see [Monitor Geofence Regions on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_geofencingservice.htm).

<!-- document id=9365a75380ee250fe446a0e752ae705d7f2adfde906d46e38e8fec790a059f48 url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-data-types.md -->

# GeofencingService Data Types

GeofencingService defines and uses several data types.


## Geofence

An object representing the coordinates and radius of the geofence region.

| **Property Name** | **Type** | **Description**                                                   | **Example**               |
| ----------------- | -------- | ----------------------------------------------------------------- | ------------------------- |
| `latitude`        | Number   | The latitude, in degrees. Ranges from -90 to 90.                  | 37.785834                 |
| `longitude`       | Number   | The longitude, in degrees. Ranges from -180 to 180.               | -122.406417               |
| `radius`          | Number   | The radius of the geofence in meters.                             | 5                         |
| `notifyOnEntry`   | Boolean  | Monitors the entry into the geofence radius. Defaults to `true`.  | `false`                   |
| `notifyOnExit`    | Boolean  | Monitors the exit out of the geofence radius. Defaults to `true`. | `false`                   |
| `message`         | String   | Notification triggered by a geofence event.                       | “Geofence region entered” |
| `triggerOnce`     | Boolean  | Removes geofence after it’s triggered. Defaults to `true`.        | `false`                   |


## GeofencingServiceFailure

An object representing an error that occurred when accessing GeofencingService features.

| **Property Name** | **Type**                      | **Description**                                                                                                                                                                                                                                                                                                   |
| ----------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`            | GeofencingServiceFailureCode  | A value representing the reason for a location error. Possible failure codes include: <ul><li>`locationServiceDisabled`</li><li>`userDeniedPermission`</li><li>`userDisabledPermission`</li><li>`unavailableOnHardware`</li><li>`maxGeofenceMonitoredReached`</li><li>`invalidLatitude`</li><li>`invalidLongitude`</li><li>`serviceNotEnabled`</li><li>`nativeError`</li></ul>  |
| `message`         | String                        | A string value explaining the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.                                                                                                                                         |


**note:** `nativeError` is a special case because it represents an error that’s specific to the underlying platform (Android or iOS). If you receive this failure, check the `message` value for details.

<!-- document id=1a50a0a6da855d49b374bcc5648b38764ac451aeef6a269d5b0885db8df2d253 url=/developer/current/en-us/lwc/lwc/guides/create/create-community-info.md -->

# Get Information About the Current Experience Builder Site

Import information about the current Experience Builder site from the `@salesforce/community` and `@salesforce/site` scoped modules.

**important:** If a component imports `@salesforce/community` or `@salesforce/site`, it can target only an Experience Builder page. You can’t use the component in any other Salesforce container. See [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-community-builder.md).

An Experience Builder site is composed of a Network object that contains administration settings, such as email and membership configurations, and a Site object that contains domain and page setting information. Using the `@salesforce/community` module, you can retrieve the ID of the network part of the site, whereas the `@salesforce/site` module lets you retrieve the ID of the site part.

## `@salesforce/community`

Import the network ID and base path of the current Experience Builder site from `@salesforce/community`.

```javascript
import propertyName from "@salesforce/community/property";
```

- `property`—The supported properties are:

  - `Id`—The ID of the current site. For example, import the ID to pass as a parameter to an API.
  - `basePath`—The base path is the section of the site’s URL that comes after the domain. So if your site domain name is `UniversalTelco.force.com` and `myPartnerSite` was the URL value added when you created the site, the site's URL is `UniversalTelco.force.com/myPartnerSite/s`. In this case, `myPartnerSite/s` is the base path.

    For example, to build a link component that works across several sites, import the base path and use it to dynamically construct the full site URL.

- `propertyName`—A name that refers to the imported Experience Builder property.

This sample code calls an Apex controller that returns all the feed items for the current site.

```javascript
// miscGetCommunityId.js
import { LightningElement } from "lwc";
import Id from "@salesforce/community/Id";
import getFeedElementPageForCommunity from "@salesforce/apex/CommunityFeedController.getFeedElementPageForCommunity";

export default class CommunityFeedElementPage extends LightningElement {
  @wire(getFeedElementPageForCommunity, { networkId: "$Id" })
  feedElementPage;
}
```

The Apex controller takes a community ID to ensure that the feed result is scoped to that site.

```javascript
// CommunityFeedController.apex
public with sharing class CommunityFeedController {
    @AuraEnabled(cacheable=true)
    public static ConnectApi.FeedElementPage getFeedElementPageForCommunity(String networkId) {
    return ConnectApi.ChatterFeeds.getFeedElementsFromFeed(networkId, ConnectApi.FeedType.UserProfile,
        'me', 3, ConnectApi.FeedDensity.FewerUpdates, null, null,
        ConnectApi.FeedSortOrder.LastModifiedDateDesc, ConnectApi.FeedFilter.CommunityScoped);
    }
}
```

## `@salesforce/site`

Import the site ID and the list of active languages of the current Experience Builder site from `@salesforce/site`.

```javascript
import propertyName from "@salesforce/site/property";
```

- `property`—The supported properties are:

  - `Id`—The ID of the current site. For example, import the ID to pass as a parameter to an API.
  - `activeLanguages`—The list of active languages in your Experience Builder site includes metadata on the default site language and all other active languages. You can configure a site’s languages in Experience Builder in **Settings** | **Languages**. Inactive languages are excluded from the list. The return value is an array of language objects, where each object includes the language’s label and the code, such as en-US. The array is sorted alphabetically by the label.

- `propertyName`—A name that refers to the imported Experience Builder property.

This sample code uses `activeLanguages` in a language selector component.

```javascript
// languagePicker.js
// Sample data: [{ code: 'en-US', label: 'English (US)' },{ code: 'fr', label: 'Françias' }]
import activeLanguages from "@salesforce/site/activeLanguages";

import { LightningElement } from "lwc";
import currentLanguage from "@salesforce/i18n/lang";
import basePath from "@salesforce/community/basePath";

export default class LanguagePicker extends LightningElement {
  get options() {
    return activeLanguages.map((x) => ({ value: x.code, ...x }));
  }

  get currentValue() {
    return currentLanguage;
  }

  handleLanguageSelect(evt) {
    const selectedLanguageCode = evt.detail.value;
    // locale is in base path and needs to be replaced with new locale
    const newBasePath = this.updateLocaleInBasePath(
      basepath,
      currentLanguage,
      selectedLanguageCode,
    );

    const currentUrl = window.location.pathname;
    if (currentUrl) {
      const restOfUrl = currentUrl.substring(basepath.length);
      window.location.href = window.location.origin + newBasePath + restOfUrl;
    } else {
      // WARNING: this is a current limitation of Lightning Locker in LWR sites
      // Locker must be disabled to reference the global window object
      console.warn(
        "Lightning Locker must be disabled for this language picker component to redirect",
      );
    }
  }

  updateLocaleInBasePath(path, oldLocale, newLocale) {
    if (path.endsWith("/" + oldLocale)) {
      // replace with new locale
      return path.replace(new RegExp("/" + oldLocale + "$"), "/" + newLocale);
    } else {
      // since the default locale is not present in the base path,
      // append the new locale
      return path + "/" + newLocale;
    }
  }
}
```

The component displays a dropdown language picker using [`lightning-combobox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox).

<!--prettier-ignore-->
```html
<!-- languagePicker.html -->
<template>
    <lightning-combobox
        options={options}
        value={currentValue}
        onchange={handleLanguageSelect}
    ></lightning-combobox>
</template>
```

**See Also**

- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)
- [_Salesforce Help_: Experience Builder Overview](https://help.salesforce.com/articleView?id=community_designer_overview.htm&type=5)

<!-- document id=20b5fac6aefa56d0e218e7312910ae84fb30384f479999fd58497797b396715e url=/developer/current/en-us/lwc/lwc/guides/create/get-current-user.md -->

# Get Information About the Current User

To get information about the current user, use the `@salesforce/user` scoped module.

```javascript
import property from "@salesforce/user/property";
```

- `property`—The supported properties are `Id`, which is the user’s ID, and `isGuest`, which is a boolean value indicating whether the user is a guest user. Use the `isGuest` property to check whether or not the user is authenticated in the Experience Builder site.

This sample code imports the current user ID and assigns it to the `userId` property to provide access in the HTML template.

```
import { LightningElement } from 'lwc';
import Id from '@salesforce/user/Id';

export default class MiscGetUserId extends LightningElement {
    userId = Id;
}

```

To reference a user ID in a template, use `{property}` syntax, which is the same syntax you use to reference any JavaScript property.

```html
<!-- miscGetUserId -->
<template>
  <lightning-card title="MiscGetUserId" icon-name="custom:custom19">
    <div class="slds-m-around_medium">
      <p>User Id:</p>
      {userId}
    </div>
  </lightning-card>
</template>
```

**note:** You can use `@salesforce/user` in a [TypeScript file](https://developer.salesforce.com/docs/platform/lwc/guide/ts.md). This scoped module corresponds to the `user.d.ts` type definition in the [@salesforce/lightning-types](https://www.npmjs.com/package/@salesforce/lightning-types) npm package.

**See Also**

- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)
- [_Salesforce Help_: Configure the Guest User Profile](https://help.salesforce.com/articleView?id=rss_config_guest_user_profile.htm&type=5)

<!-- document id=59900757902ec90b72c9a10b0374306b6fd4c1c5d35a9fa8c36308993813c71a url=/developer/current/en-us/lwc/lwc/guides/data/data-wire-example.md -->

# Get Record Data

Let’s use the wire service to get record data and display some field names.

**tip:** This example uses the `wireGetRecordDynamicContact` component in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. This component uses a dynamic schema—it doesn’t import references to fields. For an example that uses a static schema, see `wireGetRecordStaticContact` in the lwc-recipes repo.

This component renders a custom UI for a contact. To get the data, the component uses the [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) wire adapter.

![Component UI showing record ID and record name.](https://developer.salesforce.com/media/get_record.png)

If the wire service provisions data, the template renders the name, title, phone, and email. If the wire service provisions an error, the template renders the `c-error-panel` component.

<!-- prettier-ignore -->
```html
<!-- wireGetRecordDynamicContact.html -->
<template>
  <lightning-card title="My Contact Record" icon-name="standard:contact">
    <template lwc:if={contact.data}>
      <div class="slds-m-around_medium">
        <p>{name}</p>
        <p>{title}</p>
        <p><lightning-formatted-phone value={phone}></lightning-formatted-phone></p>
        <p><lightning-formatted-email value={email}></lightning-formatted-email></p>
      </div>
    </template>
    <template lwc:if={contact.error}>
      <c-error-panel errors={contact.error}></c-error-panel>
    </template>
  </lightning-card>
</template>
```

Now let’s look at the component’s JavaScript.

First, the code imports the `getRecord` wire adapter from the `lightning/uiRecordApi` module, which is built on Lightning Data Service. Then it defines the fields to pass to the wire adapter.

The component uses `@api` to define a public `recordId` property. If the component is nested in a Lightning record page, which our component is, the Lightning page sets the value of `recordId`.

The `@wire` decorator tells [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) to get the values of the specified fields on the record with the specified `$recordId`. The `$` means that the value is passed dynamically. When the value changes, the wire service provisions data and the component rerenders.

The data is provisioned to the `data` and `error` objects of the property decorated with `@wire`. In this example, that’s the `contact` property.

**note:** Since the default value for `data` that's returned by the property is `undefined`, this example depends on the `lwc:if` directive to check if `contact.data` has been populated with the contact record. The getters in your JavaScript code are called when `contact.data` has been populated with the contact record. Alternatively, use [getFieldValue(record, field)](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-field-value.md).

```javascript
// wireGetRecordDynamicContact.js
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

const FIELDS = ["Contact.Name", "Contact.Title", "Contact.Phone", "Contact.Email"];

export default class WireGetRecordDynamicContact extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  contact;

  get name() {
    return this.contact.data.fields.Name.value;
  }

  get title() {
    return this.contact.data.fields.Title.value;
  }

  get phone() {
    return this.contact.data.fields.Phone.value;
  }

  get email() {
    return this.contact.data.fields.Email.value;
  }
}
```

Look back at the HTML template. The `name`, `title`, `phone`, and `email` fields are bound to the JavaScript class using the `{}` syntax. In JavaScript, each property has a getter function that uses the `contact.data` object to access the value of its namesake field.

The structure of the returned data is the same as the structure returned by the User Interface API that `getRecord` is built on. In this case, the response is [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm).

**note:** This example demonstrates data access via the returned JSON object. To simplify data access, use [`getFieldValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-field-value.md).

**See Also**

- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)

<!-- document id=3e24a0416accb42db582ac1cbabe4f15f55e29424481bd50aafe55203c1eec38 url=/developer/current/en-us/lwc/slds-validator/guides/get-started.md -->

# Get Started

To get started scanning your code with SLDS Validator, follow the developer workflow and choose resources that match your learning style.

## 1. Discover

SLDS Validator is a Visual Studio (VS) Code extension that scans your code, validates it against a database of Salesforce Lightning Design System (SLDS) guidelines, and offers recommendations on how to improve your code. SLDS Validator:

- Evaluates your HTML, Cascading Style Sheets (CSS), and component markup (CMP) code inline as you write it in VS Code.
- Simplifies working with SLDS in custom Aura components and Lightning web components.

With the SLDS Validator extension, you get:

- SLDS 1 and SLDS 2 support
- Validation with recommended tokens and utility classes
- Syntax highlighting
- Code completion
- Context awareness
- Bulk report generation


## 2. Set Up

Before you can scan your code, install SLDS Validator. If you’re working in SLDS 2, you must follow the customization steps to enable SLDS 2 scans. Whether you’re working in SLDS 1 or SLDS 2, learn about customization to improve how you work with SLDS Validator.

- [Set Up SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/guide/set-up.md)
- [Customize SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/guide/customize.md)

## 3. Scan Your Code

Now that you installed and customized SLDS Validator, the fun starts. Learn how to work with SLDS Validator. Then scan your code and interpret the results that you get.

- [Work with SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/guide/work-with.md)
- [Scan Your Code](https://developer.salesforce.com/docs/platform/slds-validator/guide/scan-your-code.md)
- [Interpret Your Results](https://developer.salesforce.com/docs/platform/slds-validator/guide/interpret-your-results.md)

## 4. Learn More

SLDS Validator is updated frequently. To learn the latest, read our release notes. Also, get support when you need it with our resources.

- [Release Notes](https://developer.salesforce.com/docs/platform/slds-validator/guide/release-notes.md)
- [Get Support](https://developer.salesforce.com/docs/platform/slds-validator/guide/get-support.md)

<!-- document id=b9f7f6687a416c498fda8e5476e1f675985a9cb37b5a9728494699717c98aed5 url=/developer/current/en-us/lwc/utam/guide/get-started-utam.md -->

# Get Started

UI Test Automation Model (UTAM) makes it easier to write end-to-end UI tests by abstracting page object code into JSON. Page objects encapsulate UI components into a scalable interface for your test code. The UTAM framework is a web standard, and can test non-Salesforce apps, too.

Other writing query selectors for end-to-end tests don't scale because when the DOM structure changes, query selectors break.
A large application can have a lot of query selectors, which means a lot of time fixing tests. But page objects encapsulate the capabilities of a UI component into an interface that test code can interact with.
Each application component has a corresponding JSON page object that declares its test interface.
UTAM provides a JSON grammar to write page objects and a compiler to generate runnable code in Java or JavaScript.
The runnable test code UTAM creates expects certain things in the UI (like clearing or setting text).
UTAM abstracts the DOM away from the test, insulating test expectations from implementation details like shadow DOM.

To get started with UTAM, choose the resources that match your learning style.

## Discover

- [UTAM Tutorials](https://utam.dev/tutorial/introduction) for a suite of interactive tutorials.
- [JSON page object grammar](/docs/platform/utam/references/utam-grammar/grammar.html)
- Salesforce Developers' Blog: [Run End-to-End Tests with UTAM](https://developer.salesforce.com/blogs/2022/05/run-end-to-end-tests-with-the-ui-test-automation-model-utam)

## Video Tutorial

::video{src="https://www.youtube.com/embed/rxZfsjIwWeU" title="Run End-to-End Tests With the UI Test Automation Model (UTAM)" type="youtube"}

## Hands-On Learning

The `utam-js-recipes` and `utam-java-recipes` repos contain examples of how to test the Salesforce UI.

### JavaScript

- [utam-js-recipes](https://github.com/salesforce/utam-js-recipes)
- [Guide for JavaScript Developers](https://developer.salesforce.com/docs/platform/utam/guide/js-guide.md)

### Java

- [utam-java-recipes](https://github.com/salesforce/utam-java-recipes)
- [Guide for Java Developers](https://developer.salesforce.com/docs/platform/utam/guide/java-guide.md)

## Develop

- [Browser extension](https://developer.salesforce.com/docs/platform/utam/guide/browser-extension.md) to help you find page objects provided by Salesforce
- [UTAM Generator](https://developer.salesforce.com/docs/platform/utam/guide/generator-get-started.md) to generate UTAM JSON page objects from HTML files
- [Design Page Objects](https://developer.salesforce.com/docs/platform/utam/guide/page-objects.md) if you prefer to manually build JSON page objects from scratch instead of using the UTAM generator
- Compile your JSON page objects to [JavaScript](https://developer.salesforce.com/docs/platform/utam/guide/js-guide.md#compiler-setup) or [Java](https://developer.salesforce.com/docs/platform/utam/guide/java-guide.md#compiler-setup) page objects
- Write tests for [JavaScript](https://developer.salesforce.com/docs/platform/utam/guide/js-guide.md#write-ui-tests) or [Java](https://developer.salesforce.com/docs/platform/utam/guide/java-guide.md#write-ui-tests)

<!-- document id=8cf816b5ec30c52442cc46216d3b797bb288c302620c68db065a1a83826e0ae2 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-lwc.md -->

# Get Started Coding

The fastest way to code your first Lightning web component is using a live code environment.

To get started with a simple component, we recommend the [StackBlitz](https://playground.lwc.dev/) online IDE. Alternatively, use [Salesforce DX tools](https://developer.salesforce.com/docs/platform/lwc/install/install-setup-develop.md) to push LWC code to your org. LWC.studio was discontinued on January 1, 2024.

**note:** StackBlitz is a third-party product and is subject to its own terms and conditions. Salesforce is not responsible for the content, services, or paid options offered on StackBlitz. Your use of those websites and platforms is at your own risk and is subject to any applicable additional terms, such as the terms of service or privacy policies of the third party.

## Create Your First Component

Use StackBlitz to kickstart your LWC development. StackBlitz doesn't have access to Salesforce data, but it's useful when you need to learn about LWC or reproduce a framework issue.

To create your first component on StackBlitz, go to https://playground.lwc.dev. You can use the online IDE without signing in. To save your changes, sign in using your GitHub account.

The default project includes a parent component `x-app` and a child component `x-counter`, where `x` is the namespace. To create a component:

1. Hover over the `x` directory and click the Add Folder icon. Enter a name for your component, for example, `myComponent`.
2. Hover over the `myComponent` directory and click the Add File icon. Enter the HTML file name, `myComponent.html`, which must match the directory name. Enter this sample code in the `myComponent.html` file.
   ```html
   <template>
     <p>Hello {name}!</p>
   </template>
   ```
3. Hover over the `myComponent` directory and click the Add File icon. Enter the JS file name, `myComponent.js`, which must match the directory name. Enter this sample code in the `myComponent.js` file.

   ```javascript
   import { LightningElement } from "lwc";

   export default class MyComponent extends LightningElement {
     name = "LWC";
   }
   ```

4. In `app.html`, add `<x-my-component></x-my-component>` right after the `<x-counter></x-counter>` component tag.
5. Save your changes and click the refresh icon [in the preview area](https://developer.stackblitz.com/guides/user-guide/ide-whats-on-your-screen). "Hello LWC!" is displayed in the preview area.

For more information, see the [StackBlitz documentation](https://developer.stackblitz.com/guides/user-guide/what-is-stackblitz).

## Third-Party IDE Guidelines

Using StackBlitz is a quick way to learn about LWC. Consider these guidelines when using the online IDE.

- StackBlitz automatically updates to the latest open source version of LWC when you use playground.lwc.dev. This version is usually ahead of the LWC version in your Salesforce org. To verify the LWC version on StackBlitz, go to the `package.json` file and check the `lwc` value on the `devDependencies` object. For example, an `lwc` value of 3.6.0 corresponds to the [v3.6.0 OSS release](https://github.com/salesforce/lwc/releases/tag/v3.6.0). See [LWC API Versioning](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-api-versioning.md).
- StackBlitz provides LWC features that are both available on the Salesforce platform and [LWC OSS](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-oss.md). However, It doesn't have access to your Salesforce data. For example, it doesn't support `@salesforce/*` imports and Lightning Data Service wire adapters.
- StackBlitz projects don't include SLDS and base components. Live examples specific to base components are available in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

## Next Steps

While the online IDEs are helpful to get started with LWC, we recommend that you [set up your development environment](https://developer.salesforce.com/docs/platform/lwc/install/install-setup-develop.md) on your local machine to start building Lightning web components in your Salesforce org.
To keep coding, jump to [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md). Have fun!

**See Also**

- [Hello World in a Scratch Org](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx-hello-world.md)

<!-- document id=679975efec2ad4bbb73478580f29abcddb634399c58558095de84d7b426af832 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-introduction.md -->

# Get Started with Lightning Web Components

Use the Lightning Web Components (LWC) framework to build custom user interfaces, web and mobile apps, and digital experiences on the Salesforce Platform. Lightning web components are custom HTML elements built using HTML and JavaScript.

| REQUIRED EDITIONS                                                                       |
| --------------------------------------------------------------------------------------- |
| Available in: Lightning Experience                                                      |
| Available in **Enterprise**, **Performance**, **Unlimited**, and **Developer** Editions |

Salesforce provides [Lightning base components](https://developer.salesforce.com/docs/platform/lightning-component-reference/) built on Lightning Design System to use as building blocks for your custom experiences. Use base components to give your users a consistent look and feel and to simplify your development experience. Salesforce Lightning Experience is built on Lightning Design System and base components.

**tip:** To get started, choose a path that's right for you.

- [Get Started Coding: Create Your First Component](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-lwc.md)
- [Set Up Your Development Environment](https://developer.salesforce.com/docs/platform/lwc/install/install-setup-develop.md)
- [Explore Trailhead and Sample Code](https://developer.salesforce.com/docs/platform/lwc/install/install-sample-code-repo.md)
- [Learn to Work with Salesforce Data](https://developer.salesforce.com/docs/platform/lwc/data/data-guidelines.md)
- [Learn to Customize Salesforce Features](https://developer.salesforce.com/docs/platform/lwc/use/use.md)

## Write Standard JavaScript and HTML

Lightning Web Components uses core [Web Components](https://github.com/w3c/webcomponents/) standards and provides only what’s necessary to perform well in browsers supported by Salesforce. Because it’s built on code that runs natively in browsers, Lightning Web Components is lightweight and delivers exceptional performance. Most of the code you write is standard JavaScript and HTML.

Salesforce is committed to developing open web standards and is a member of the [World Wide Web Consortium (W3C)](https://www.w3.org/Consortium/Member/List). Salesforce developers are contributing members of the Ecma International Technical Committee 39 ([TC39](https://tc39.github.io/ecma262/)), which is the committee that evolves JavaScript.

Lightning Web Components is also [open-source](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md).

## Backwards Compatibility

You can build Lightning components using two programming models: Lightning Web Components, and the original model, Aura Components. Lightning web components and Aura components can coexist and interoperate on a page. To admins and end users, they both appear as Lightning components.

Lightning base components are available as Lightning web components and as Aura components. The [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) includes documentation, specifications, and examples for both. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-map-aura-lwc-components.md) for differences between them.

When you have a choice between LWC and Aura, choose LWC. See [How to Choose Lightning Web Components or Aura](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-lwc-or-aura.md).

<!-- document id=838e884a09b658c285cf100dfd87c389d8a11df2e629a8980a7775813ad5c752 url=/developer/current/en-us/lwc/lightning-components-security/guides/get-started/get-started-intro.md -->

# Get Started with Security for Lightning Components

Lightning components, including both [Lightning web components (LWC)](/docs/platform/lwc/guide/get-started-introduction.html) and [Aura components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/intro_framework.htm), have a client-side security architectural layer that protects your custom components. This layer prevents components from accessing data that belongs to platform code or components from other namespaces without explicit permission. It automatically blocks or modifies any insecure behavior of APIs.

You can enable either Lightning Web Security (LWS) or Lightning Locker as the security architecture for your org.

- [Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md)

  - : Lightning Web Security (LWS) is a newer security architecture that Salesforce first introduced in Spring ’22. LWS is based on the latest [TC39](https://tc39.es/) web standards and prevents unsafe code behavior by running components in virtual JavaScript sandboxes. LWS has fewer restrictions and more functionality than Lightning Locker. New orgs have Lightning Web Security (LWS) enabled by default.

- [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md)
  - : Lightning Locker is the predecessor to LWS. Instead of using virtual JavaScript sandboxes, Lightning Locker wraps JavaScript objects in more secure versions to prevent behavior that isn't secure.

**tip:** To evaluate whether your org is ready to move from Lightning Locker to LWS, check out these resources:

- [Compare Lightning Web Security (LWS) and Lightning Locker Features](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/get-started-compare-lws-locker.md)
- [When to Enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-when.md)
- [Lightning Web Security FAQ](https://help.salesforce.com/s/articleView?id=000392327&type=1)

Regardless of the security architecture, Lightning components use [JavaScript strict mode](https://developer.salesforce.com/docs/platform/lightning-components-security/js/js-strict-mode-intro.md) to turn on native security features in the browser and [Content Security Policy (CSP)](https://developer.salesforce.com/docs/platform/lightning-components-security/content-security-policy/content-security-policy-intro.md) rules to control the source of content that can be loaded on a page.

<!-- document id=a3f8175cffac55c4f6a70fa65106f60049a1d8308b59257953168aba3a49e426 url=/developer/current/en-us/lwc/slds_linter/guides/get-started/get-started-intro.md -->

# Get Started with SLDS Linter

Linting involves analyzing your code ‌and highlighting issues in it. To get started linting your code with SLDS Linter, follow this developer workflow and choose resources that match your learning style.

## 1. Discover

SLDS Linter is an installable npm package that analyzes your code against Salesforce Lightning Design System 2 (SLDS 2) rules. SLDS Linter rules are also integrated into Salesforce Code Analyzer. SLDS Linter offers suggestions to better align your code with SLDS 2 guidelines and make it more future-proof. SLDS Linter can also apply the suggestions in bulk across your repository and automatically fix your code.

Use SLDS Linter to find UI violations if you're working on SLDS 1, SLDS 2, or transitioning from SLDS 1 to SLDS 2.

While both SLDS Validator and SLDS Linter scan your code and offer suggestions for improvement, SLDS Linter provides these advantages.

- Set up easily and get started faster.
- Bulk-fix your code by using a single command.
- Scan your code against SLDS Linter rules using Salesforce Code Analyzer via the CLI or the VS code extension.
  See [Use SLDS Linter Rules with Salesforce Code Analyzer](https://developer.salesforce.com/docs/platform/slds-linter/use/use-work-with-code-analyzer.md).
- Uplift your code to the latest Salesforce design system, SLDS 2.

See [SLDS Linter on Salesforce Lightning Design System 2 website](https://www.lightningdesignsystem.com/2e1ef8501/p/012d73-slds-linter).

## 2. Setup

Before you can scan your code, read [Set Up SLDS Linter](https://developer.salesforce.com/docs/platform/slds-linter/guide/get-started-setup-linter.md) and install the tool.

## 3. Lint & Autofix

Scan your code with the complete set of rules, or use custom configuration files to enable or disable specific rules. Automatically fix the identified issues in the code.

- [Work With SLDS Linter: Scan Your Code](https://developer.salesforce.com/docs/platform/slds-linter/use/use-scan-code.md)
- [Work With SLDS Linter: Use With Custom Configuration Files](https://developer.salesforce.com/docs/platform/slds-linter/use/use-custom-config-files.md)
- [Work With SLDS Linter: Interpret Your Results](https://developer.salesforce.com/docs/platform/slds-linter/use/use-interpret-results.md)
- [Work With SLDS Linter: Autofix Your Code](https://developer.salesforce.com/docs/platform/slds-linter/use/use-autofix-code.md)
- [Reference: Commands](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-commands.md)
- [Reference: Rules](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-rules.md)

## 4. Get Support

To get help with SLDS Linter, read the information in these topics.

- [Get Support: Frequently Asked Questions](https://developer.salesforce.com/docs/platform/slds-linter/support/support-faq.md)
- [Get Support: Troubleshoot](https://developer.salesforce.com/docs/platform/slds-linter/support/support-troubleshoot.md)
- [Get Support: Create Bugs, Feedback, and Feature Requests](https://developer.salesforce.com/docs/platform/slds-linter/support/support-create-requests.md)

## 5. Keep Up with the Latest News

SLDS Linter releases new versions frequently. Read the [Release Notes](https://developer.salesforce.com/docs/platform/slds-linter/get-started/get-started-release-notes.md) to learn about recent updates.

<!-- document id=e2be322b36bc8c304a61e3a875c4f115d237a2568f292759d4c0c7fa0fe298eb url=/developer/current/en-us/lwc/slds_linter/guides/support/support-intro.md -->

# Get Support

Before you file a [support request](https://developer.salesforce.com/docs/platform/slds-linter/guide/support-create-requests.md), check the [FAQ](https://developer.salesforce.com/docs/platform/slds-linter/guide/support-faq.md) and do some [troubleshooting](https://developer.salesforce.com/docs/platform/slds-linter/guide/support-troubleshoot.md).

<!-- document id=c4be0e9e6728d6518ff0b423663bb8f87f06fa6e211fa517cf38b54c67675abc url=/developer/current/en-us/lwc/slds-validator/guides/get-support.md -->

# Get Support

- To report an issue with SLDS Validator, create an [issue](https://github.com/forcedotcom/salesforcedx-vscode-slds/issues/new?assignees=&labels=&projects=&template=Bug_report.md).
- To suggest a feature enhancement, create a [feature request](https://github.com/forcedotcom/salesforcedx-vscode-slds/issues/new?assignees=&labels=&projects=&template=Feature_request.md).
- To report any security issues, follow [these instructions](https://github.com/forcedotcom/salesforcedx-vscode-slds/security/policy).

<!-- document id=5fc30101923e81a296fa3a30e6436006292e0fcbb54c34f391285006b510c57d url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-output-variables-example.md -->

# Get Values from Flow Output Variables

When you embed a flow in a `lightning-flow` component, you can show or reference the flow’s variable values.

To use this component, build a flow with the Salesforce Flow Builder first. The component includes the navigation buttons Back, Next, Pause, and Finish.

**note:** If your flow has custom Lightning web components or Aura components, then you can’t use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

## Use the `onstatuschange` Event Handler

To get values from the flow's output variables, use the `onstatuschange` event handler. Output variables are returned as an array. The variable must allow output access. If you reference a variable that doesn’t allow output access, attempts to get the variable are ignored.

## Example: Display Output Variables from Flow

This example takes the flow's output variables for `accountName` and `numberOfEmployees` and displays them in the template.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <p>{accountName}</p>
  <p>{numberOfEmployees}</p>
  <lightning-flow flow-api-name="myFlow" onstatuschange={handleStatusChange}> </lightning-flow>
</template>
```

```javascript
// myComponent.js
import { LightningElement, track, wire } from "lwc";

export default class MyComponent extends LightningElement {
  accountName;
  numberOfEmployees;

  handleStatusChange(event) {
    if (event.detail.status === "FINISHED") {
      const outputVariables = event.detail.outputVariables;
      for (let i = 0; i < outputVariables.length; i++) {
        const outputVar = outputVariables[i];
        if (outputVar.name == "accountName") {
          this.accountName = outputVar.value;
        } else {
          this.numberOfEmployees = outputVar.value;
        }
      }
    }
  }
}
```

<!-- document id=5a259bdaf69a23e511bfeea754a80340f6e4156daaf3dfbab23766e35e5bb136 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-actions.md -->

# `getActions`

Retrieves a collection of Salesforce actions available to a CRM Analytics user.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getActions } from "lightning/analyticsWaveApi";

export default class GetActions extends LightningElement {
  @api userId; // this is the CRM Analytics user ID
  @wire(getActions, {
    entityId: "$userId",
  })
  onGetActions({ data, error }) {
    if (error) {
      console.log("getActions ERROR:", error);
    } else if (data) {
      console.log("getActions RESPONSE:", data.actions);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/actions/${entityId}
```

`getActions` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_actions.htm).

## Parameters

| Parameter Name | Type   | Description                       | Required?                                  |
| -------------- | ------ | --------------------------------- | ------------------------------------------ |
| `entityId`     | String | The ID of the CRM Analytics user. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Action Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_action_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=1f385d2e03474e6620884327ab5ddcd2550b3b1f29abcb529330d51c9ae73dfb url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-analytics-limits.md -->

# `getAnalyticsLimits`

Retrieves the Analytics limits for CRM Analytics.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getAnalyticsLimits } from "lightning/analyticsWaveApi";

export default class GetAnalyticsLimits extends LightningElement {
  @wire(getAnalyticsLimits, {
    licenseType: "EinsteinAnalytics",
    types: ["Dataset​Queries"],
  })
  onGetAnalyticsLimits({ data, error }) {
    if (error) {
      console.log("getAnaltyicsLimits ERROR:", error);
    } else if (data) {
      console.log("getAnaltyicsLimits RESPONSE:", data.limits);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/limits
```

`getAnalyticsLimits` uses thisMeet [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_limits.htm).

## Parameters

These parameters are optional.

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `licenseType`  | String | The response includes CRM Analytics assets with this license type. The default is `EinsteinAnalytics.` <ul><li>`Cdp` (Data Cloud)</li><li>`DataPipelinesQuery` (Data Pipelines Query)</li><li>`EinsteinAnalytics` (CRM Analytics)</li><li>`IntelligentApps` (Intelligent Apps)</li><li>`MulesoftDataPath` (Mulesoft Data Path)</li><li>`Sonic` (Salesforce Data Pipelines)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `types`        | Array  | The types of limits used in CRM Analytics. Valid values are: <ul><li>`BatchTransformationHours`—Maximum dataflow runtime per month.</li><li>`DatasetQueries`—Maximum queries.</li><li>`DatasetRowCount`—Maximum rows of all datasets combined.</li><li>`MaxDailyRowsHighOutputCon`—Maximum rows for all high volume tier output connectors per rolling 24-hour period.</li><li>`MaxDailySizeHighOutputCon`—Maximum data size for all high volume tier output connectors per rolling 24-hour period.</li><li>`MaxDailyRowsMedOutputCon`—Maximum rows for all medium volume tier output connectors per rolling 24-hour period.</li><li>`MaxDailySizeMedOutputCon`—Maximum data size for all medium volume tier output connectors per rolling 24-hour period.</li><li>`MaxDailyRowsLowOutputCon`—Maximum rows for all low volume tier output connectors per rolling 24-hour period.</li><li>`MaxDailySizeLowOutputCon`—Maximum data size for all low volume tier output connectors per rolling 24-hour period.</li><li>`OutputLocalConnectorVolume`—Maximum cumulative bytes of data files written to Salesforce in a rolling 24-hour period.</li></ul> |

## Returns

- `data`—[Wave Analytics Limit Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_analytics_limit_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=1cdb5f0f06db6e2ecd8ce60a8421976163ffb96441200258c41c6f280db04049 url=/developer/current/en-us/lwc/lwc/guides/reference/appreviewservice/reference-lightning-appreviewservice-factory.md -->

# `getAppReviewService()`

Use this factory function to get an instance of `AppReviewService`.

## Syntax

```javascript
import { getAppReviewService } from 'lightning/mobileCapabilities';
getAppReviewService(): AppReviewService
```

## Parameters

None

## Returns

An instance of `AppReviewService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform app review-related operations.

**See Also**

- [AppReviewService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_appreviewservice_example.htm)

<!-- document id=cfbb6d3d1b3b34af5512962f0984d5a0b20d82dc54ca4cc7f86f1b004157bf18 url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-factory.md -->

# `getBarcodeScanner()`

Use this factory function to get an instance of `BarcodeScanner`.

## Syntax

```javascript
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
getBarcodeScanner(): BarcodeScanner
```

## Parameters

None.

## Returns

An instance of `BarcodeScanner`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform scanning operations.

**See Also**

- [BarcodeScanner Example—Modern Scanning API](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_example_modern.htm)

<!-- document id=d25dfe7ffbee490258079b3afccdbb494ff9f8e8b5d01b5106438881153ec791 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-factory.md -->

# `getBiometricsService`

Use this factory function to get an instance of `BiometricsService`.

## Syntax

```typescript
import { getBiometricsService } from "lightning/mobileCapabilities";
getBiometricsService: BiometricsService;
```

## Parameters

None.

## Returns

An instance of `BiometricsService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform biometrics service-related operations.

**See Also**

- [BiometricsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice_example.htm)

<!-- document id=62fd046329e34f22d2cd582f2d2e2f87a9ac98354032c4ec1b056c02f524c569 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-getcalendars.md -->

# `getCalendars(options)`

Returns all available calendars from the device’s native Calendar application. If needed, a permission pop-up for the user to grant calendar access is presented first.

## Syntax

```
import { getCalendarService } from 'lightning/mobileCapabilities';
getCalendars(options: CalendarServiceOptions): Promise<Object>
```

## Parameters

- `options`—(Required) A [`CalendarServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-data-types.md) object to configure the CalendarService request.

## Returns

A Promise object that resolves as an array of `Calendar` objects. If an error is encountered, the array is empty.

## Usage

Use this function to make device calendars available for use with CalendarService.

```javascript
myCalendarService
  .getCalendars(options)
  .then((results) => {
    this.calendars = results;
  })
  .catch((error) => {
    this.calendars = [];
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

- This function is a prerequisite for using any other CalendarService functionality; in other words, this function must be called before any other CalendarService function, except for `getCalendarService()`.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.

<!-- document id=3b93e08aa4d2e02c616ce08c9f925c9da98c9a8867719fcff63893c48291b2ce url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-factory.md -->

# `getCalendarService()`

Use this factory function to get an instance of CalendarService.

## Syntax

```javascript
import { getCalendarService } from 'lightning/mobileCapabilities';
getCalendarService(): CalendarService
```

## Parameters

None.

## Returns

An instance of `CalendarService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform calendar-related operations.

<!-- document id=3474bb9af5bec24a3216c4cfb5c53ee2e748c47babc7803c9df20e627b5e1b70 url=/developer/current/en-us/lwc/lwc/guides/reference/contactsservice/reference-lightning-contactsservice-getcontacts.md -->

# `getContacts(options)`

Allows the user to pick one or more contacts from the device’s Contacts app. If needed, presents a permissions pop-up to the user to request access to contacts first, and then presents the user with the contacts selector.

## Syntax

```javascript
import { getContactsService } from 'lightning/mobileCapabilities';
getContacts(OPTIONS: ContactsServiceOptions): Promise<Object>
```

## Parameters

- `options`—(Required) A [`ContactsServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice-data-types.md) object to configure the ContactsService request.

## Returns

- A Promise object that resolves as an array of [`Contact`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice-data-types.md) objects. If an error is encountered, the array is empty.

- A rejected promise returns a [`ContactsServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice-data-types.md) object containing details about the error.

## Usage

This function presents a contacts selection list, and then returns a list of the contacts that were selected.

```javascript
myContactsService
  .getContacts(options)
  .then((results) => {
    this.contacts = results;
  })
  .catch((error) => {
    this.contacts = [];
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

When this function is called, a list view displaying device contacts is displayed on the mobile device. The user can select any number of contacts, and then tap the check mark icon to continue.

- `getContacts()` is a synchronous function. That is, JavaScript execution pauses while the selection list is on screen. The user must finish selecting contacts and tap the continue button, or cancel the operation, for the promise to resolve. Your component’s execution resumes when the promise resolves.
- When contacts are selected, the result is returned via a fulfilled promise. Handle successful results in a `then` clause.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- If the user cancels contact selection, the promise is rejected with a `ContactsServiceFailure.code`value of `USER_DISMISSED`.
- The contacts selection list is a device-native window, and can’t be customized.
- While you can’t customize the contacts selection window itself, you can present a custom interface before contacts selection. After contacts selection, you can present another custom interface to offer additional options or features for processing the selected contacts.

**See Also**

- [ContactsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_contactsservice_example.htm)
- [ContactsService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice-data-types.md)

<!-- document id=a2854b881c4d7938251b0599e15d77f6a290bb7638986c1e2ba7ec5ffb1187d6 url=/developer/current/en-us/lwc/lwc/guides/reference/contactsservice/reference-lightning-contactsservice-factory.md -->

# `getContactsService()`

Use this factory function to get an instance of `ContactsService`.

## Syntax

```javascript
import { getContactsService } from 'lightning/mobileCapabilities';
getContactsService(): ContactsService
```

## Parameters

None

## Returns

An instance of `ContactsService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform contact-related operations.

**See Also**

- [ContactsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_contactsservice_example.htm)

<!-- document id=eceba1e0c777feb9e2120304c107af07ea39327f18fc019b4509fcd48c5dc4f4 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-delivery-get-content.md -->

# `getContent`

Retrieves published content from an enhanced CMS workspace or non-enhanced CMS workspace for an enhanced LWR site in Experience Cloud. This wire adapter can also retrieve published content from a non-enhanced CMS workspace for a non-enhanced LWR site.

**note:** To get Salesforce CMS content from an enhanced or non-enhanced CMS workspace for an Aura site, use the `lightning/cmsDeliveryApi` module’s [`listContent`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-list-content.md) wire adapter instead.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getContent } from "experience/cmsDeliveryApi";
import siteId from "@salesforce/site/Id";

export default class GetContentCmsDeliveryApiV2 extends LightningElement {
  @api contentKey;

  data;

  @wire(getContent, { channelOrSiteId: siteId, contentKeyOrId: "$contentKey" })
  onGetContent(result) {
    if (result.data) {
      this.data = result.data;
    }
  }
}
```

## User Interface API Resource

With `channelId` parameter:

```html
GET /connect/cms/delivery/channels/${channelId}/contents/${contentKeyOrId}
```

With `siteId` parameter:

```html
GET /connect/sites/${siteId}/cms/delivery/contents/${contentKeyOrId}
```

`getContent` uses this [CMS Delivery Content Resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_delivery_content.htm).

## Parameters

| Parameter Name    | Type   | Description                                                                                       | Required?                                  |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `channelOrSiteId` | String | The ID for the enhanced LWR site on which you want to use CMS content.                            | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `contentKeyOrId`  | String | The content key or content ID for the CMS content that you want to use on your enhanced LWR site. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Managed Content Delivery Document](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_managed_content_delivery_document.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=aeaccc1069da45e13109eae71fdb766928d350c900cdd6e70bbeb81e355da8f5 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-editor-get-content.md -->

# `getContent`

Retrieves the `title`, `urlName`, and `contentBody` of the content item in the content editor in an enhanced CMS workspace based on the content type—image, news, document, or custom content.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getContent }  from experience/cmsEditorApi;

export default class Example extends LightningElement {
  @wire(getContent, {})
  content;
}
```

## Returns

- `data`
  - `contentBody`—The JSON representation of the content body, which varies depending on the content type. See [JSON File Format for Content in Salesforce CMS](https://help.salesforce.com/s/articleView?id=xcloud.cms_import_content_json.htm) in Salesforce Help.
  - `title`—The title of the content item.
  - `urlName`—The content slug, which is the last part of the URL address.
- `error`—A validation error for invalid fields.

<!-- document id=acac96439b739aa094429e24de6d2e7248469ecfda7821499498ba2d06e088ee url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-delivery-get-contents.md -->

# `getContents`

Retrieves a list of published content from an enhanced CMS workspace or non-enhanced CMS workspace for an enhanced LWR site in Experience Cloud. This wire adapter can also retrieve published content from a non-enhanced CMS workspace for a non-enhanced LWR site.

**note:** To get Salesforce CMS content from an enhanced or non-enhanced CMS workspace for an Aura site, use the `lightning/cmsDeliveryApi` module’s [`listContent`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-list-content.md) wire adapter instead.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getContents } from "experience/cmsDeliveryApi";
import siteId from "@salesforce/site/Id";

export default class GetContentsCmsDeliveryApiV2 extends LightningElement {
  @api contentKeys;

  data;

  @wire(getContents, { channelOrSiteId: siteId, contentKeys: "$contentKeys" })
  onGetContents(result) {
    if (result.data) {
      this.data = result.data;
    }
  }
}
```

## User Interface API Resource

With `channelId` parameter:

```html
GET /connect/cms/delivery/channels/${channelId}/contents
```

With `siteId` parameter:

```html
GET /connect/sites/${siteId}/cms/delivery/contents
```

`getContent` uses this [CMS Delivery Contents Resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_delivery_contents.htm).

## Parameters

| Parameter Name       | Type     | Description                                                                                                                                                    | Required?                                  |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `channelOrSiteId`    | String   | The ID for the enhanced LWR site on which you want to use CMS content.                                                                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `contentKeys`        | String[] | The content keys for the CMS content that you want to use on your enhanced LWR site.                                                                           |                                            |
| `managedContentIds`  | String[] | The managed content IDs for the CMS content that you want to use on your enhanced LWR site.                                                                    |                                            |
| `contentTypeFQN`     | String   | Fully qualified name of the managed content type.                                                                                                              |                                            |
| `referenceDepth`     | Integer  | An integer 0–3 specifying the depth of references.                                                                                                             |                                            |
| `page`               | Integer  | Number of the page you want returned. Starts at 0. If you don’t specify a value or if you specify 0, the first page is returned.                               |                                            |
| `pageSize`           | Integer  | Specifies the number of items per page. Valid values are from 1 through 250. If unspecified, the default size is 25.                                           |                                            |
| `includeContentBody` | Boolean  | Specifies whether to return the content body (`true`) or summaries of references (`false`) in the response body. If unspecified, the default value is `false`. |                                            |

## Returns

- `data`—[Managed Content Delivery Document Collection](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_managed_content_delivery_document_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=a51dfdbca761ac79dd3801c98d54489a778147811670ae7d3af887b3df4b0399 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-editor-get-context.md -->

# `getContext`

Retrieves metadata about the content item in the content editor in an enhanced CMS workspace.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getContext }  from experience/cmsEditorApi;

export default class Example extends LightningElement {
  @wire(getContext, {})
  context;
}
```

## Returns

- `data`
  - `variantId`—ID of the content variant.
  - `contentSpaceId`—ID of the workspace that contains the content item.
  - `managedContentId`—ID of the CMS content item.
  - `contentKey`—Unique identifier that tracks a content item through version updates and across environments. Assigned automatically when content is added to a CMS workspace.
  - `schema`—Information layout based on the content type.
- `error`—A validation error for invalid fields.

<!-- document id=dd1235fa7a064ddb97622b8f073b701468ce9054eb80791edfea573e80b07f0c url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-getcurrentposition.md -->

# `getCurrentPosition(options)`

Gets the device’s current geolocation.

## Syntax

```javascript
import { getLocationService } from 'lightning/mobileCapabilities';
getCurrentPosition(options: LocationServiceOptions): Promise<Object>
```

## Parameters

- `options`—(Required) A [`LocationServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) object to configure the location request.

## Returns

A Promise object that resolves as a [`Location`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) object with the device location details.

A rejected promise returns a [`LocationServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) object containing details about the error.

## Usage

This function performs a one-time location request, and returns the device’s current location at that time.

```javascript
myLocationService
  .getCurrentPosition({ enableHighAccuracy: true })
  .then((result) => {
    this.myLocation = result.coords;
  })
  .catch((error) => {
    console.error(error);
  });
```

When this function is called, a request to get the current location is submitted to the device’s location capabilities. When the device’s current location is determined, the promise resolves with a `Location` object. Determining the current location can take varying lengths of time, from nearly instant to many seconds, depending on a number of external factors.

There’s no user interface associated with a location request. To provide feedback while waiting for a response, update your Lightning web component code. We suggest that you display a [lightning-spinner](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-spinner) just before calling `getCurrentPosition()`. Then remove the spinner in the `finally()` clause of the `getCurrentPosition()` promise handler.

**See Also**

- [LocationService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_locationservice_example.htm)
- [LocationService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md)

<!-- document id=b7ffc957dacc2d1b9ba684c311fe4b7d45aa55e3f2f68551d12cfb895a2857d1 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-current-selected-block.md -->

# `getCurrentSelectedBlock`

Retrieves the JSON structure of a selected component on the canvas of a marketing content item. Use this wire adapter when building a CMS extension for Marketing Cloud Next that interacts with components on the canvas.

## Syntax

```javascript
import { LightningElement, wire, api } from "lwc";
import { getCurrentSelectedBlock } from "experience/blockBuilderApi";

export default class Example extends LightningElement {
  @api paragraphText;

  @wire(getCurrentSelectedBlock, {})
  onCurrentSelectedBlock({ data }) {
    if (data) {
      const selectedBlockInUEMFormat = data;

      // check the type of the block
      const blockDefinition = selectedBlockInUEMFormat.definition;

      // handle a paragraph block
      if (blockDefinition === "lightning/paragraph") {
        const paragraphBlock = selectedBlockInUEMFormat;

        // extract the text attribute from the paragraph block
        this.paragraphText = paragraphBlock.attributes.text;
      }

      // do other things with the block...
    } else {
      // no block is currently selected
      this.paragraphText = "";
    }
  }
}
```

## Returns

- `data`—the JSON structure of the selected component. Undefined if the user hasn't selected a component.

<!-- document id=e109b7633f6bd73d71366d42393642912c707b0a799cb92475472e7a2e69a5c0 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector.md -->

# `getDataConnector`

Retrieves a specific CRM Analytics data connector by ID or developer name.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnector } from "lightning/analyticsWaveApi";

export default class GetDataConnector extends LightningElement {
  @api idOrApiName; // or fetch the ID or developer name
  @wire(getDataConnector, {
    connectorIdOrApiName: "$idOrApiName",
  })
  onGetDataConnector({ data, error }) {
    if (error) {
      console.log("getDataConnector(${connectorIdOrApiName}) ERROR:", error);
    } else if (data) {
      console.log("getDataConnector(${connectorIdOrApiName}) RESPONSE:", data.connectorType);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors/${connectorIdOrApiName}
```

`getDataConnector` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid.htm).

## Parameters

| Parameter Name         | Type   | Description                                     | Required?                                  |
| ---------------------- | ------ | ----------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Data Connector](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_data_connector.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=5758ecdd8ac971ccf8c68dc655b50a5020c2521de23b456d5b5463049be06b5c url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connectors.md -->

# `getDataConnectors`

Retrieves a collection of CRM Analytics data connectors.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getDataConnectors } from "lightning/analyticsWaveApi";

export default class GetDataConnectors extends LightningElement {
  @wire(getDataConnectors, {
    connectorType: ["SfdcLocal"],
  })
  onGetDataConnectors({ data, error }) {
    if (error) {
      console.log("getDataConnectors ERROR:", error);
    } else if (data) {
      console.log("getDataConnectors RESPONSE:", data.dataConnectors);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors
```

`getDataConnectors` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors.htm).

## Parameters

These parameters are optional.

| Parameter Name  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`      | String | Filters the collection to include only data connectors belonging to the specified category.<ul><li>`AdvancedPropertiesSupport` (Connector supports Advanced Properties)</li><li>`BatchRead` (Read/Input Connector that performs batch reads, instead of live queries)</li><li>`Direct` (Direct/Live Connector)</li><li>`FileBased` (File-based Connector)</li><li>`FilterSupport` (Connector supports pass-through filter)</li><li>`MuleSoft` (MuleSoft Connector)</li><li>`Output` (Write/Output/Target Connector)</li><li>`Private` (Private Connector that performs batch reads instead of live queries)</li></ul> |
| `connectorType` | String | Filters the collection to include only data connectors belonging to the specified connector type. The list of valid values can be found [here](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_dev_guide_rest_enums.htm#ConnectWaveDataConnectorTypeEnum_desc).                                                                                                                                                                                                                                                                                                         |
| `folderId`      | String | Filters the collection to only contain data connectors for the specified folder. The ID can be the requesting user's ID for data connectors in the user's private folder.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scope`         | String | Scope type to apply to the collection results. <ul><li>`CreatedByMe`</li><li>`Mru` (Most Recently Used)</li><li>`SharedWithMe`</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Returns

- `data`—[Data Connector Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_data_connector_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=59144e66a90b2cc7babf21031170e168d836bc96e3627a232861b25c356a764d url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector-source-fields.md -->

# `getDataConnectorSourceFields`

Retrieves a collection of source fields for a source object used by a CRM Analytics data connector.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnectorSourceFields } from "lightning/analyticsWaveApi";

export default class GetDataConnectorSourceFields extends LightningElement {
  @api idOrApiName; // or fetch the ID
  @api soName; // or set the source object name
  @wire(getDataConnectorSourceFields, {
    connectorIdOrApiName: "$idOrApiName",
    sourceObjectName: "$soName",
  })
  onGetDataConnectorSourceFields({ data, error }) {
    if (error) {
      console.log("getDataConnectorSourceFields ERROR:", error);
    } else if (data) {
      console.log("getDataConnectorSourceFields RESPONSE:", data.fields);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors/${connectorIdOrApiName}/sourceObjects/${sourceObjectName}/fields
```

`getDataConnectorSourceFields` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid_sourceobjects_sourceobjectname_fields.htm).

## Parameters

| Parameter Name         | Type   | Description                                       | Required?                                  |
| ---------------------- | ------ | ------------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector.   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `sourceObjectName`     | String | The source object name to request the fields for. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Source Field Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_source_field_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=81f3629af6c6b8359dd775c427878ca5e3b5a51412fa27b1fd938b927a6323b2 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector-source-object.md -->

# `getDataConnectorSourceObject`

Retrieves a source object used by a CRM Analytics data connector.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnectorSourceObject } from "lightning/analyticsWaveApi";

export default class GetDataConnectorSourceObject extends LightningElement {
  @api idOrApiName; // or fetch the ID
  @api soName; // or set the source object name
  @wire(getDataConnectorSourceObject, {
    connectorIdOrApiName: "$idOrApiName",
    sourceObjectName: "$soName",
  })
  onGetDataConnectorSourceObject({ data, error }) {
    if (error) {
      console.log("getDataConnectorSourceObject ERROR:", error);
    } else if (data) {
      console.log("getDataConnectorSourceObject RESPONSE:", data.name);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors/${connectorIdOrApiName}/sourceObjects/${sourceObjectName}
```

`getDataConnectorSourceObject` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid_sourceobjects_sourceobjectname.htm).

## Parameters

| Parameter Name         | Type   | Description                                        | Required?                                  |
| ---------------------- | ------ | -------------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector.    | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `sourceObjectName`     | String | The source object name to request information for. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Source Object](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_source_object.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=79e9d1e881ba6baa32347b5dad5629bde102e5f108f5d942a04abce006cc30f5 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector-source-object-data-previewwithfields.md -->

# `getDataConnectorSourceObjectDataPreviewWithFields`

Retrieves a preview collection of source fields for a source object used by a CRM Analytics data connector.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnectorSourceObjectDataPreviewWithFields } from "lightning/analyticsWaveApi";

export default class GetDataConnectorSourceObjectPreviewWithFields extends LightningElement {
  @api idOrApiName; // or fetch the ID
  @api soName; // or set the source object name
  @wire(getDataConnectorSourceObjectDataPreviewWithFields, {
    connectorIdOrApiName: "$idOrApiName",
    sourceObjectName: "$soName",
  })
  onGetDataConnectorSourceObjectDataPreviewWithFields({ data, error }) {
    if (error) {
      console.log("getDataConnectorSourceObjectDataPreviewWithFields ERROR:", error);
    } else if (data) {
      console.log("getDataConnectorSourceObjectDataPreviewWithFields RESPONSE:", data.dataListJson);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors/${connectorIdOrApiName}/sourceObjects/${sourceObjectName}/dataPreview
```

`getDataConnectorSourceObjectDataPreviewWithFields` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid_sourceobjects_sourceobjectname_datapreview.htm).

## Parameters

| Parameter Name         | Type   | Description                                               | Required?                                  |
| ---------------------- | ------ | --------------------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector.           | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `sourceObjectName`     | String | The source object name to request the preview fields for. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Source Object Data](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_source_object_data.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=2164cd80adc90139435b29bec67f0498a0a47523de157e5ddb6ec1920a69ca02 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector-status.md -->

# `getDataConnectorStatus`

Retrieves the status for a specific CRM Analytics data connector by ID or developer name.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnectorStatus } from "lightning/analyticsWaveApi";

export default class GetDataConnectorStatus extends LightningElement {
  @api idOrApiName; // or fetch the ID or developer name
  @wire(getDataConnectorStatus, {
    connectorIdOrApiName: "$idOrApiName",
  })
  onGetDataConnectorStatus({ data, error }) {
    if (error) {
      console.log("getDataConnectorStatus(${connectorIdOrApiName}) ERROR:", error);
    } else if (data) {
      console.log("getDataConnectorStatus(${connectorIdOrApiName}) RESPONSE:", data.status);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectors/${connectorIdOrApiName}/status
```

`getDataConnectorStatus` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid_status.htm).

## Parameters

| Parameter Name         | Type   | Description                                     | Required?                                  |
| ---------------------- | ------ | ----------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Data Connector Status](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_data_connector_status.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=0597e1dc7b9731a7e2af40f7043ca50f4090c5431b0f3daaa0db6530c00f708f url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-data-connector-types.md -->

# `getDataConnectorTypes`

Retrieves the collection of CRM Analytics data connector types.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataConnectorTypes } from "lightning/analyticsWaveApi";

export default class GetDataConnectorTypes extends LightningElement {
  @wire(getDataConnectorTypes, {})
  onGetDataConnectorTypes({ data, error }) {
    if (error) {
      console.log("getDataConnectorTypes() ERROR:", error);
    } else if (data) {
      console.log("getDataConnectorTypes() RESPONSE:", data.types);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataConnectorTypes
```

`getDataConnectorTypes` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectortypes.htm).

## Parameters

No parameters are needed.

## Returns

- `data`—[Data Connector Type Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_data_connector_type_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=4a5021de968c3d5ce6778509745070bf85b8c98bc2d71a775deb84c3d32ad720 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataflow-job.md -->

# `getDataflowJob`

Retrieves a specific CRM Analytics dataflow job.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataflowJob } from "lightning/analyticsWaveApi";

export default class GetDataflowJob extends LightningElement {
  @api jobId; // or fetch the ID
  @wire(getDataflowJob, {
    dataflowJobId: "$jobId",
  })
  onGetDataflowJob({ data, error }) {
    if (error) {
      console.log(`getDataflowJob(${jobId}) ERROR:`, error);
    } else if (data) {
      console.log(`getDataflowJob(${jobId}) RESPONSE:`, data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataflowjobs/${dataflowjobId}
```

`getDataflowJob` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs_id.htm).

## Parameters

| Parameter Name  | Type   | Description                 | Required?                                  |
| --------------- | ------ | --------------------------- | ------------------------------------------ |
| `dataflowjobid` | String | The ID of the dataflow job. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataflow Job](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=3af1b985437593767711415560c60000ab9f2c07c1e7ff17eebc9b47458b5651 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataflow-job-node.md -->

# `getDataflowJobNode`

Retrieves a specific CRM Analytics dataflow job node for a recipe or dataflow.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataflowJobNode } from "lightning/analyticsWaveApi";

export default class GetDataflowJobNode extends LightningElement {
  @api jobId; // or fetch the ID
  @api djNodeId; // or fetch the ID
  @wire(getDataflowJobNode, {
    dataflowJobId: "$jobId",
    nodeId: "$djNodeId",
  })
  onGetDataflowJobNode({ data, error }) {
    if (error) {
      console.log(`getDataflowJobNode(${jobId}, ${djNodeId}) ERROR:`, error);
    } else if (data) {
      console.log(`getDataflowJobNode(${jobId}, ${djNodeId}) RESPONSE:`, data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataflowjobs/${dataflowjobId}/nodes/${nodeId}
```

`getDataflowJobNode` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs_nodes_id.htm).

## Parameters

| Parameter Name  | Type   | Description                 | Required?                                  |
| --------------- | ------ | --------------------------- | ------------------------------------------ |
| `dataflowjobId` | String | The ID of the dataflow job. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `nodeId`        | String | The ID of the node.         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataflow Job Node](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job_node.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=4d930dd3fc3584f92cbe8fe58c9eab4ab9d43eba7476e853f6fc3e686da1d2fd url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataflow-job-nodes.md -->

# `getDataflowJobNodes`

Retrieves a collection of CRM Analytics dataflow job nodes.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataflowJobNodes } from "lightning/analyticsWaveApi";

export default class GetDataflowJobNodes extends LightningElement {
  @api jobId; // or fetch the ID
  @wire(getDataflowJobNodes, {
    dataflowJobId: "$jobId",
  })
  onGetDataflowJobNodes({ data, error }) {
    if (error) {
      console.log(`getDataflowJobNodes(${jobId}) ERROR:`, error);
    } else if (data) {
      console.log(`getDataflowJobNodes(${jobId}) RESPONSE:`, data.nodes);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataflowjobs/${dataflowjobId}/nodes
```

`getDataflowJobNodes` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs_nodes.htm).

## Parameters

| Parameter Name  | Type   | Description                 | Required?                                  |
| --------------- | ------ | --------------------------- | ------------------------------------------ |
| `dataflowjobId` | String | The ID of the dataflow job. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataflow Job Node Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job_node_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=ba3c146246265ae5b511375ed8e9b1a7bbdd0f282bd57a364cd0a2030e08f683 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataflow-jobs.md -->

# `getDataflowJobs`

Retrieves a collection of CRM Analytics dataflow jobs.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getDataflowJobs } from "lightning/analyticsWaveApi";

export default class GetDataflowJobs extends LightningElement {
  @wire(getDataflowJobs, {
    licenseType: "EinsteinAnalytics",
    status: "Success",
  })
  onGetDataflowJobs({ data, error }) {
    if (error) {
      console.log("getDataflowJobs ERROR:", error);
    } else if (data) {
      console.log("getDataflowJobs RESPONSE:", data.dataflowJobs);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataflowjobs
```

`getDataflowJobs` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs.htm).

## Parameters

These parameters are optional.

| Parameter Name  | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataflowId`    | String   | Filters the collection to only contain dataflow jobs tied to this specific dataflow. The ID must start with '02K'.                                                                                                                                                                                                                                                                                        |
| `jobTypes`      | String[] | Filters the collection to only contain dataflow jobs with a specific job type. Possible values include: <ul><li>`DataCloudRecipe`</li><li>`DataSync`</li><li>`FileUpload`</li><li>`Internal`</li><li>`Orchestrated`</li><li>`Recipe`</li><li>`Recipe_V3`</li><li>`Report`</li><li>`Restore`</li><li>`User`</li></ul>                                                                                      |
| `licenseType`   | String   | The response includes CRM Analytics assets with this license type. Possible values include: <ul><li>`Cdp (Data Cloud)`</li><li>`DataPipelinesQuery` (Data Pipelines Query)</li><li>`EinsteinAnalytics` (CRM Analytics)</li><li>`IntelligentApps` (Intelligent Apps)</li><li>`MulesoftDataPath` (Mulesoft Data Path)</li><li>`Sonic` (Salesforce Data Pipelines)</li></ul> Default is `EinsteinAnalytics`. |
| `page`          | String   | Generated token that indicates the view of dataflow jobs to be returned.                                                                                                                                                                                                                                                                                                                                  |
| `pageSize`      | Integer  | Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.                                                                                                                                                                                                                                                                                                     |
| `q`             | String   | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string. Special characters are automatically removed.                                                                                                                                                                                                                         |
| `startedAfter`  | String   | Filters the collection to only contain dataflow jobs started after the specified date and time (in Epoch seconds in UTC).                                                                                                                                                                                                                                                                                 |
| `startedBefore` | String   | Filters the collection to only contain dataflow jobs started before the specified date and time (in Epoch seconds in UTC).                                                                                                                                                                                                                                                                                |
| `status`        | String   | Filters the collection to only contain dataflow jobs with a specific runtime status. Possible values include: <ul><li>`Cancelled`</li><li>`Failure`</li><li>`Preprocessing`</li><li>`Queued`</li><li>`Running`</li><li>`Success`</li><li>`Warning`</li></ul>                                                                                                                                              |

**note:** If a `page` or `pageSize` parameter isn’t provided, the response includes only the dataflow jobs run in the last 7 days. To see jobs older than 7 days, provide a `page` or `pageSize` parameter.

## Returns

- `data`—[Dataflow Job Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=22c60e793e477e1d989be693e0f27d07a0b3e550cb202ed7f5cc2ad5abbd275b url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataflows.md -->

# `getDataflows`

Retrieves a collection of CRM Analytics dataflows.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getDataflows } from "lightning/analyticsWaveApi";

export default class GetDataflows extends LightningElement {
  @wire(getDataflows)
  onGetDataflows({ data, error }) {
    if (error) {
      console.log("getDataflows ERROR:", error);
    } else if (data) {
      console.log("getDataflows RESPONSE:", data.dataflows);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dataflows
```

`getDataflows` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflows.htm).

## Parameters

This parameter is optional.

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                             |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`            | String | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string. If the user's search query contains quotation marks or wildcards, those symbols are automatically removed from the query string in the URL along with any other special characters. |

## Returns

- `data`—[Dataflow Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=e1924033fa9f55404e78077b55f1bc0596f8091c427927381809e73e3b0d8831 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataset.md -->

# `getDataset`

Retrieves a specific CRM Analytics dataset by ID or developer name.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDataset } from "lightning/analyticsWaveApi";

export default class GetDataset extends LightningElement {
  @api idOrApiName; // or fetch the ID or developer name
  @wire(getDataset, {
    datasetIdOrApiName: "$idOrApiName",
  })
  onGetDataset({ data, error }) {
    if (error) {
      console.log("getDataset(${idOrApiName}) ERROR:", error);
    } else if (data) {
      console.log("getDataset(${idOrApiName}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/datasets/${datasetIdOrApiName}
```

`getDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataset_id.htm).

## Parameters

| Parameter Name       | Type     | Description                              | Required?                                  |
| -------------------- | -------- | ---------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | `String` | The ID or developer name of the dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=92254e3f9e370ed0e2fa06bfeb969e79ad9cafbe85eabc6452ca632f2686c38a url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-datasets.md -->

# `getDatasets`

Retrieves a collection of CRM Analytics datasets.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getDatasets } from "lightning/analyticsWaveApi";

export default class GetDatasets extends LightningElement {
  @wire(getDatasets, {
    datasetTypes: ["Default", "Live"],
    licenseType: "EinsteinAnalytics",
  })
  onGetDatasets({ data, error }) {
    if (error) {
      console.log("getDatasets ERROR:", error);
    } else if (data) {
      console.log("getDatasets RESPONSE:", data.datasets);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/datasets
```

`getDatasets` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets.htm).

## Parameters

These parameters are optional.

| Parameter Name          | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createdAfter`          | String   | Filter the collection to include only datasets created after a specific timestamp.                                                                                                                                                                                                                                                                                                                |
| `createdBefore`         | String   | Filter the collection to include only datasets created before a specific timestamp.                                                                                                                                                                                                                                                                                                               |
| `datasetTypes`          | String[] | Filters the collection to include only datasets of one or more of the specified types: <ul><li>`Default`</li><li>`Live`</li><li>`StagedData`</li><li>`Trended`</li></ul>                                                                                                                                                                                                                          |
| `folderId`              | String   | Filters the collection to only contain datasets for the specified folder. The ID can be the requesting user's ID for datasets in the user's private folder.                                                                                                                                                                                                                                       |
| `hasCurrentOnly`        | Boolean  | Filters the collection of datasets to include only those datasets that have a current version. The default is `false`.                                                                                                                                                                                                                                                                            |
| `ids`                   | String[] | Filter the collection to include only datasets with the specified IDs.                                                                                                                                                                                                                                                                                                                            |
| `includeCurrentVersion` | Boolean  | Includes the current dataset version metadata in the collection. The default is `false`.                                                                                                                                                                                                                                                                                                          |
| `lastQueriedAfter`      | String   | Filter the collection to include only datasets last queried after a specific timestamp.                                                                                                                                                                                                                                                                                                           |
| `lastQueriedBefore`     | String   | Filter the collection to include only datasets last queried before a specific timestamp.                                                                                                                                                                                                                                                                                                          |
| `licenseType`           | String   | The response includes datasets with this license type. Possible values include: <ul><li>`Cdp` (Data Cloud)</li><li>`DataPipelinesQuery` (Data Pipelines Query)</li><li>`EinsteinAnalytics` (CRM Analytics)</li><li>`IntelligentApps` (Intelligent Apps)</li><li>`MulesoftDataPath` (Mulesoft Data Path)</li><li>`Sonic` (Salesforce Data Pipelines)</li></ul> The default is `EinsteinAnalytics`. |
| `order`                 | String   | Ordering to apply to the collection results: <ul><li>`Ascending`</li><li>`Descending`</li></ul>                                                                                                                                                                                                                                                                                                   |
| `page`                  | String   | Generated token that indicates the view of datasets to be returned.                                                                                                                                                                                                                                                                                                                               |
| `pageSize`              | Integer  | Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.                                                                                                                                                                                                                                                                                             |
| `q`                     | String   | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string. Special characters are automatically removed.                                                                                                                                                                                                                 |
| `scope`                 | String   | Scope type to apply to the collection results: <ul><li>`CreatedByMe`</li><li>`Mru` (Most Recently Used)</li><li>`SharedWithMe`</li></ul>                                                                                                                                                                                                                                                          |
| `sort`                  | String   | Sort order to apply to the collection results: <ul><li>`ConnectionName`</li><li>`CreatedBy`</li><li>`CreatedDate`</li><li>`LastModified`</li><li>`LastQueried`</li><li>`LastRefreshed`</li><li>`Mru` (Most Recently Used, last viewed date)</li><li>`Name`</li><li>`TotalRows`</li></ul>                                                                                                          |
| `supportsNewDates`      | Boolean  | Indicates whether to include only datasets that support new dates in the collection (`true`) or not (`false`). The default is `false`.                                                                                                                                                                                                                                                            |
| `typeOfDataflow`        | String   | Filter the collection to include only datasets with the specified type of dataflow.                                                                                                                                                                                                                                                                                                               |

## Returns

- `data`—[Dataset Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=88505974faebcbf118ad3d255a1cb50efcf11efef1244cbdbf182ddfaa383d8e url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataset-version.md -->

# `getDatasetVersion`

Retrieves a specific CRM Analytics dataset version by dataset ID or developer name and version ID.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDatasetVersion } from "lightning/analyticsWaveApi";

export default class GetDatasetVersion extends LightningElement {
  @api idOrApiName; // or fetch the dataset ID or developer name
  @api vId; // or fetch the version id
  @wire(getDatasetVersion, {
    datasetIdOrApiName: "$idOrApiName",
    versionId: "$versionId",
  })
  onGetDatasetVersion({ data, error }) {
    if (error) {
      console.log("getDatasetVersion(${vId}) ERROR:", error);
    } else if (data) {
      console.log("getDatasetVersion(${vId}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/datasets/${datasetIdOrApiName}/versions/${versionId}
```

`getDatasetVersion` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets_id_versions_id.htm).

## Parameters

| Parameter Name       | Type   | Description                              | Required?                                  |
| -------------------- | ------ | ---------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The ID or developer name of the dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `versionId`          | String | The ID of the dataset version.           | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataset Version](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_version.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=f4a71efbbd63746f6a63bc91149dedbc91b8410dcb46902cdd676d1af099db16 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dataset-versions.md -->

# `getDatasetVersions`

Retrieves a list of CRM Analytics dataset versions for a specific dataset.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getDatasetVersions } from "lightning/analyticsWaveApi";

export default class GetDatasetVersions extends LightningElement {
  @api idOrApiName; // or fetch the dataset ID or developer name
  @wire(getDatasetVersions, {
    datasetIdOrApiName: "$idOrApiName",
  })
  onGetDatasetVersions({ data, error }) {
    if (error) {
      console.log("getDatasetVersions(${idOrApiName}) ERROR:", error);
    } else if (data) {
      console.log("getDatasetVersions(${idOrApiName}) RESPONSE:", data.versions);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/datasets/${datasetIdOrApiName}/versions
```

`getDatasetVersions` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets_id_versions.htm).

## Parameters

| Parameter Name       | Type    | Description                                                                                        | Required?                                  |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String  | The ID or developer name of the dataset.                                                           | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `createdAfter`       | String  | Filters the collection to include only dataset versions created after a specific timestamp.        |                                            |
| `createdBefore`      | String  | Filters the collection to include only dataset versions created before a specific timestamp.       |                                            |
| `includeArchived`    | Boolean | Filters the collection to include archived dataset versions in the collection. Default is `false`. |                                            |

## Returns

- `data`—[Dataset Version Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_version_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=b33c669709d04c2912af5e9fe8430da0de77293016f89b0ff52e8bdb28ee4651 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-dependencies.md -->

# `getDependencies`

Returns the dependencies for an asset. The dependencies resource returns only assets for which the user has view access.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getDependencies } from "lightning/analyticsWaveApi";

export default class GetDependencies extends LightningElement {
  @api aId; // this is the CRM Analytics asset ID
  @wire(getDependencies, {
    assetId: "$aId",
  })
  onGetDependencies({ data, error }) {
    if (error) {
      console.log("getDependencies ERROR:", error);
    } else if (data) {
      console.log("getDependencies RESPONSE:", data.dependencies);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/dependencies/${assetId}
```

`getDependencies` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dependencies.htm).

## Parameters

| Parameter Name | Type   | Description                        | Required?                                  |
| -------------- | ------ | ---------------------------------- | ------------------------------------------ |
| `assetId`      | String | The ID of the CRM Analytics asset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dependency Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dependency_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=9b812d2fef51bfb57c0c9dcc8867c922f34c94e7016a4e8ab02ebea4855f7c36 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-factory.md -->

# `getDocumentScanner()`

Use this factory function to get an instance of `DocumentScanner`.

## Syntax

```javascript
import { getDocumentScanner } from 'lightning/mobileCapabilities';
getDocumentScanner(): DocumentScanner
```

## Parameters

None.

## Returns

An instance of `DocumentScanner`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform scanning operations.

<!-- document id=623f80473af4cee75a6dc21635a12502cf87767a20414247dbee937d3c7825d0 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-getevents.md -->

# `getEvents(startDateSecondsUTC, endDateSecondsUTC, calendars?, options)`

Returns all events of all available calendar events in a specified date range from the specified calendars.

## Syntax

```javascript
import { getCalendarService } from 'lightning/mobileCapabilities';
getEvents(
  startDateSecondsUTC: number,
  endDateSecondsUTC: number,
  calendars?: string[],
  options: CalendarServiceOptions
  ): Promise<Object>
```

## Parameters

- `startDateSecondsUTC`—(Required) The start of the date range.
- `endDateSecondsUTC`—(Required) The end of the date range.
- `options`—(Required) A [`CalendarServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-data-types.md) object to configure the CalendarService request.
- `calendars`— The titles of calendars to get events from. If not provided, or null is passed in, events are fetched from all available calendars.

## Returns

A Promise object that resolves as an array of `Calendar` objects. If an error is encountered, the array is empty.

## Usage

Use this function to fetch all available events in a specified date range from specified calendars.

```javascript
myCalendarService
  .getEvents(options)
  .then((results) => {
    this.events = results;
  })
  .catch((error) => {
    this.events = [];
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

- If the `calendars` property is null, events are fetched from all available calendars.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.

<!-- document id=9ba36f3ef37dcaeca411b37879422736397bc9a9651c143df00b770ffb04e5a9 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-field-display-value.md -->

# `getFieldDisplayValue(record, field)`

Gets the display value of a field. Spanning fields are supported.

The display value provides formatted and localized values based on the org’s locale settings. In some cases, the display value differs from the value of a field in its raw data form returned by [getFieldValue(record, field)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-field-value.md). For information about these cases, see [Field Value](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_field_value.htm).

## Syntax

```javascript
import { getFieldDisplayValue } from "lightning/uiRecordApi";
getFieldDisplayValue(record, field);
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                           | Required?                               |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `record`       | Object | A [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm) object from which to retrieve the field value.                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `field`        | String | The API name of the field. The value can be either a string or reference to a field imported from `@salesforce/schema`. You can specify up to three **relationship fields** to reference parent objects and fields using this format: `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A string that displays the field value. If the field doesn’t exist, this function returns `undefined`.

## Usage

To get a field’s display value, you can use the [getRecord](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record.md) wire adapter which returns the property `record.data.fields.fieldName.displayValue`. However, to get the value of the property directly, call `getFieldDisplayValue(record, field)`.

The display value is returned in its localized and formatted form. For example, if your Salesforce locale is English (United States):

- Currency values are displayed in the format `$350,000,000`.
- Date values are displayed in the format `7/13/2019`.
- Date/time values are displayed in the format `6/17/2015 3:17 PM`.

`getFieldDisplayValue` returns undefined if a localized or formatted value is not available.

**See Also**

- [_Salesforce Help_: Salesforce Supported Locales and ICU Formats](https://help.salesforce.com/articleView?id=admin_locales_icu.htm)

<!-- document id=492ee76deb023f2f52f5e23f0a005171f2416c46782b3e830eeaa9f6dbe5f65a url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-field-value.md -->

# `getFieldValue(record, field)`

Gets a field’s value from a record. Spanning fields are supported.

The field’s value is returned in its raw data form. In some cases, the raw data form differs from the display value that’s returned by [`getFieldDisplayValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-field-display-value.md).

## Syntax

```javascript
import { getFieldValue } from "lightning/uiRecordApi";
getFieldValue((record: Record), (record: string));
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                           | Required?                               |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `record`       | Object | A [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm) object from which to retrieve the field value.                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `field`        | String | The API name of the field. The value can be either a string or reference to a field imported from `@salesforce/schema`. You can specify up to three **relationship fields** to reference parent objects and fields using this format: `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

The field’s value. A record may be returned if a relationship field is used. If the field you are requesting for doesn’t exist, this function returns `undefined`.

## Usage

To get the value of a record’s field, you can use the [getRecord](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record.md) wire adapter, which returns the property `record.data.fields.fieldName.value`. However, you can also call `getFieldValue(record, field)` to get the value directly.

The field value is returned in its raw data form, which is useful for calculations and comparisons. Here are a few examples of values in raw data form:

- Currency values are displayed like `350000000`.
- Date values are displayed like `2019-07-13`
- Date/time values are displayed like `2015-06-17T22:17:58.000Z`.

Import the field references that you pass to `getFieldValue(record, field)` from the `@salesforce/schema` scoped package using the `@salesforce/schema/ObjectName.FieldName` syntax. For a custom object, use the `@salesforce/schema/CustomObjectName__c.CustomFieldName__c` syntax. If you use a string to identify a field name like `fields: ["Account.Name"]`, you don't get the benefits that you get from importing a reference to the field. See [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md).

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";

import REVENUE_FIELD from "@salesforce/schema/Account.AnnualRevenue";
import CREATED_FIELD from "@salesforce/schema/Account.CreatedDate";
import EXP_FIELD from "@salesforce/schema/Account.SLAExpirationDate__c";

const FIELDS = [REVENUE_FIELD, CREATED_FIELD, EXP_FIELD];

export default class WireGetValue extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  account;

  get revenue() {
    return getFieldValue(this.account.data, REVENUE_FIELD);
  }

  get created() {
    return getFieldValue(this.account.data, CREATED_FIELD);
  }

  get expiration() {
    return getFieldValue(this.account.data, EXP_FIELD);
  }
}
```

To display formatted values, use base components such as [`lightning-formatted-number`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-number) or [`lightning-formatted-date-time`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time). The locale set in the Salesforce user preferences determines the formatting.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="WireGetFieldValue" icon-name="standard:account">
    <template lwc:if={account.data}>
      <div class="slds-m-around_medium">
        <p>
          <lightning-formatted-number format-style="currency" value={revenue} currency-code="USD">
          </lightning-formatted-number>
        </p>
        <p>
          <lightning-formatted-date-time
            weekday="long"
            month="short"
            year="numeric"
            day="2-digit"
            hour="2-digit"
            minute="2-digit"
            value={created}
          >
          </lightning-formatted-date-time>
        </p>
        <p>
          <lightning-formatted-date-time value={expiration}> </lightning-formatted-date-time>
        </p>
      </div>
    </template>
  </lightning-card>
</template>
```

The base components display the values:

- `$350,000,000.00`
- `Wednesday, Jun 17, 2015, 03:17 PM`
- `Jul 13, 2014`

Alternatively, use the [`getFieldDisplayValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-field-display-value.md) wire adapter to display the formatted and localized value for a field.

**See Also**

- [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md#import-references-to-salesforce-objects-and-fields)

<!-- document id=7704b9dab8b1f808ee6731f893e83e05e0f11699ef47f03add964efed5efc26f url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-get.md -->

# getGeofencingService()

Get an instance of `GeofencingService`.


## Syntax

```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
getGeofencingService(): GeofencingService
```




## Parameters

None.


## Returns

An instance of `GeofencingService`.


## Usage

There are no parameters or options when creating an instance. Use the instance to perform geofencing operations.

<!-- document id=53e32577f6ac56965bba5f6fdbfccf347a9b16b9af485f324cbfdb82351458ca url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice-factory.md -->

# `getHealthService()`

Use this factory function to get an instance of `HealthService`.

## Syntax

```javascript
import { getHealthService } from 'lightning/mobileCapabilities';
getHealthService(): HealthService
```

## Parameters

None

## Returns

An instance of `HealthService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform health data operations.

**See Also**

- [HealthService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice_example.htm)

<!-- document id=96ca495099ab94c423533d1904ddff3a501809a7a77e617c8838dcfa48bcfb0c url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-layout.md -->

# getLayout

This wire adapter gets layout information, metadata, and data to build UI for one or more records. Use it instead of the deprecated [`lightning/getRecordUi`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record-ui.md).

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getLayout } from "lightning/uiLayoutApi";

export default class Example extends LightningElement {
  @wire(getLayout, { objectApiName: string, layoutType: string, mode: string, recordTypeId?: string })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/layout/{objectApiName}
```

The `getLayout` wire adapter uses [this User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_layout.htm), but doesn’t support all its parameters.

## Parameters

| Parameter Name  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Required?                               |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName` | String | A [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm#ui_api_get_started_supported_objects).                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `layoutType`    | String | Layout type for the record. A string that contains one of these values: <ul><li>`Compact`—Use this value to get a layout that contains a record’s key fields.</li><li>`Full`—Use this value to get a full layout.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `mode`          | String | The access mode for the record. This value determines which fields to get from a layout. Layouts have different fields for create, edit, and view modes. For example, formula fields are rendered in view mode, but not in create mode because they’re calculated at run time, like formulas in a spreadsheet. Each string contains **one** of these values: <ul><li>`Create`—Use this mode if you intend to build UI that lets a user create a record.</li><li>`Edit`—Use this mode if you intend to build UI that lets a user edit a record.</li><li>`View`—Use this mode if you intend to build UI that displays a record.</li></ul> | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recordTypeId`  | String | The ID of the record type (`RecordType` object) for the new record. If not provided, the default record type is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                         |

## Returns

- `data`-[Record Layout](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_layout.htm#ui_api_responses_record_layout)

<!-- document id=b216c768d12cfd99d2e67599446c9d2cd36559517117c70e3510d2ca490696db url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-info-by-name.md -->

# `getListInfoByName`

Use this wire adapter to get the metadata for a list view.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListInfoByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListInfoByName, { objectApiName: ACCOUNT_OBJECT, listViewApiName: "AllAccounts" })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/list-info/${objectApiName}/${listViewApiName}
```

See [Get List View Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_md.htm?search_text=list-info)

## Parameters

| Parameter Name    | Type   | Description                                                                                                                      | Required?                               |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName` | String | The API name of a list view, such as `AllAccounts`.                                                                              | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[List Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_metadata.htm#topic-title)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches the List Info by API name, then iterates through the list of display columns in the List Info.

**note:** To retrieve metadata for a batch of list views, use [getListInfosByName](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-infos-by-name.md) instead.

<!-- prettier-ignore -->
```html
<!-- wireListInfoByName.html -->
<template>
  <lightning-card title="wireListInfoByName">
    <template lwc:if={displayColumns}>
      <div class="slds-m-around_medium">
        <template for:each={displayColumns} for:item="col">
          <p key={col.fieldApiName}>{col.fieldApiName} : {col.label}</p>
        </template>
      </div>
    </template>
  </lightning-card>
</template>
```

```javascript
// wireListInfoByName.js
import { LightningElement, wire } from "lwc";
import { getListInfoByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class WireListInfoByName extends LightningElement {
  error;
  displayColumns;
  @wire(getListInfoByName, {
    objectApiName: ACCOUNT_OBJECT.objectApiName,
    listViewApiName: "AllAccounts",
  })
  listInfo({ error, data }) {
    if (data) {
      this.displayColumns = data.displayColumns;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.displayColumns = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=c437ead33ec162ad1cc6d3fa3572227c9c861ffb61aa61f37e1564e8120250fa url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-infos-by-name.md -->

# `getListInfosByName`

Use this wire adapter to get the metadata for a batch of list views.

## Syntax

```javascript
import { getListInfosByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class KeywordResults extends LightningElement {
  @wire(getListInfosByName, {
    names: ["Account.AllAccounts"],
  })
  getListInfosByNameWire({ data }) {
    if (data && data.results) {
      this.listInfos = data.results.map(({ result }) => result);
    }
  }
}
```

## User Interface API Resource

```html
GET /ui-api/list-info/batch?names=Account.AllAccounts,Contact.AllContacts
```

See [Get a Batch of List View Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_md_batch.htm).

## Parameters

| Parameter Name | Type     | Description                                                                                                                                                                 | Required?                               |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `names`        | String[] | An array of comma-separated strings of list view names. A list view name starts with an entity name, a dot, and then the name of the list view, like `Account.AllAccounts`. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- A `results` object with [Simplified Batch Results](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_batch_results_simplified.htm) and [status codes](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_errors.htm).
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches the list information by API name, then iterates through the list of display columns in the list information.

**note:** To retrieve metadata for a single list view, use [getListInfoByName](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-info-by-name.md) instead.

<!-- prettier-ignore -->
```html
<!-- wireListInfosByName.html -->
<template>
    <lightning-card title="wireListInfosByName">
        <template for:each={listInfos} for:item="listInfo">           
            <div class="slds-m-around_medium" key={listInfo.id}>
                <header>{listInfo.listViewApiName}</header>
                <template for:each={listInfo.displayColumns} for:item="col">
                    <p key={col.fieldApiName}>
                      {col.fieldApiName} : {col.label}                     
                    </p>
                </template>     
            </div>
        </template>
    </lightning-card>
</template>
```

```javascript
// wireListInfosByName.js
import { LightningElement, wire } from "lwc";
import { getListInfosByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class WireListInfosByName extends LightningElement {
  listInfos;
  @wire(getListInfosByName, {
    names: ["${ACCOUNT_OBJECT.objectApiName}.AllAccounts"],
  })
  listInfo({ error, data }) {
    if (data) {
      this.listInfos = data.results.map(({ result }) => result);
    }
  }
}
```

<!-- document id=89d286272608ceef715492bf6d532191f3617dc2d5cadd7cea475e386ef329b5 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-infos-by-object-name.md -->

# `getListInfosByObjectName`

Use this wire to get the list views associated with a supported object.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListInfosByObjectName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListInfosByObjectName, {
    objectApiName: ACCOUNT_OBJECT,
    pageSize: 10,
    recentListsOnly: true,
  })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/list-info/${objectApiName}
```

See [Get List Views for an Object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_lists_object_get.htm).

## Parameters

| Parameter Name    | Type    | Description                                                                                                                                                                             | Required?                               |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String  | The API name of a [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm#ui_api_get_started_supported_objects). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `pageSize`        | Number  | The number of list records viewed at one time. The default value is 20. Valid values are 1–2000.                                                                                        |                                         |
| `pageToken`       | Number  | A token that represents the page offset. To indicate where the page starts, use this value with the `pageSize` parameter. The maximum offset is 2000, and the default is 0.             |                                         |
| `q`               | String  | A search term to filter the results. Wildcards are supported.                                                                                                                           |                                         |
| `recentListsOnly` | Boolean | Indicates whether to get recent lists only (`true`) or not (`false`). The default is `false`.                                                                                           |                                         |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`–[List Info Summary Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_info_summary_collection.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches the list of list views for an object and displays the list view labels.

<!-- prettier-ignore -->
```html
<!-- wireGetListInfosByObjectName.html -->
<template>
   <lightning-card title="wireGetListInfosByObjectName">
       <template lwc:if={lists}>
           <div class="slds-m-around_medium">
               <template for:each={lists} for:item="list">
                   <li key={list.label}>{list.label}</li>
               </template>
           </div>
       </template>
   </lightning-card>
</template>
```

```javascript
// wireGetListInfosByObjectName.js
import { LightningElement, wire } from "lwc";
import { getListInfosByObjectName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class GetListOfLists extends LightningElement {
  error;
  lists;
  @wire(getListInfosByObjectName, {
    objectApiName: ACCOUNT_OBJECT.objectApiName,
    pageSize: 10,
  })
  listOfLists({ error, data }) {
    if (data) {
      this.lists = data.lists;
      this.error = undefined;
      debugger;
    } else if (error) {
      this.error = error;
      this.lists = undefined;
      debugger;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=664c02a835d82a92a30290656aa754a331bc83b8869a713b265791b45578a235 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-object-info.md -->

# `getListObjectInfo`

This wire adapter gets the metadata for a list view object.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListObjectInfo } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class Example extends LightningElement {
  @wire(getListObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/list-object-info/${objectApiName}
```

See [Get Metadata for a List View Object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_lists_object_md_get.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                                                                                                                             | Required?                               |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName` | String | The API name of a [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm#ui_api_get_started_supported_objects). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`–[List Object Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_object_info.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches the list object info for an object and then displays the list of columns for the object.

<!-- prettier-ignore -->
```html
<!-- wireGetListObjectInfo.html -->
<template>
  <lightning-card title="wireGetListObjectInfo">
    <template lwc:if={columns}>
      <div class="slds-m-around_medium">
        <template for:each={columns} for:item="col">
          <li key={col.fieldApiName}>{col.fieldApiName} : {col.label}</li>
        </template>
      </div>
    </template>
  </lightning-card>
</template>
```

```javascript
// wireGetListObjectInfo.js
import { LightningElement, wire } from "lwc";
import { getListObjectInfo } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class WireListInfoByName extends LightningElement {
  error;
  columns;
  @wire(getListObjectInfo, {
    objectApiName: ACCOUNT_OBJECT.objectApiName,
  })
  listObjectInfo({ error, data }) {
    if (data) {
      this.columns = data.columns;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.columns = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=d55d2037b2fe37d45784da43991492f3216058f34ee7e5d26b4bbd3dc991edf2 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-preferences.md -->

# `getListPreferences`

Use this wire adapter to get the preferences for a list view.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListPreferences } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListPreferences, {
    objectApiName: ACCOUNT_OBJECT,
    listViewApiName: ‘AllAccounts’
  })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/list-preferences/${objectApiName}/${listViewApiName}
```

See [Get List View Preferences](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_preferences_get.htm).

## Parameters

| Parameter Name    | Type   | Description                                                                                                                                                                             | Required?                               |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String | The API name of a [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm#ui_api_get_started_supported_objects). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName` | String | The API name of a list view, such as `AllAccounts`.                                                                                                                                     | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`–[List Preferences](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_preferences.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches the preferences for a list view and displays the column widths for each displayed column.

<!-- prettier-ignore -->
```html
<!-- wireGetListPreferences.html -->
<template>
   <lightning-card title="wireGetListPreferences">
       <template lwc:if={columnWidths}>
           <div class="slds-m-around_medium">
               <template for:each={columnWidths} for:item="col">
                   <li key={col}>{col}</li>
               </template>
           </div>
       </template>
   </lightning-card>
</template>
```

```javascript
// wireGetListPreferences.js
import { LightningElement, wire } from "lwc";
import { getListPreferences } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class GetListPrefs extends LightningElement {
  error;
  columnWidths;
  @wire(getListPreferences, {
    objectApiName: ACCOUNT_OBJECT.objectApiName,
    listViewApiName: "AllAccounts",
  })
  listPrefs({ error, data }) {
    if (data) {
      this.columnWidths = Object.entries(data.columnWidths);
      this.error = undefined;
      debugger;
    } else if (error) {
      this.error = error;
      this.columnWidths = undefined;
      debugger;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=939b3cd0f96463057868c21075d41995e9cee7d2eb7c8a0c4fd11fb289a400a5 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-records-by-name.md -->

# `getListRecordsByName`

Use this wire adapter to get record data for a list view.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListRecordsByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListRecordsByName, {
    objectApiName: ACCOUNT_OBJECT,
    listViewApiName: "AllAccounts",
    fields: ["Account.Name", "Account.Id"],
    sortBy: ["Account.Name"],
  })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
POST /ui-api/list-records/${objectApiName}/${listViewApiName}
```

See [Get List View Records](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_view_records_post.htm).

## Parameters

| Parameter Name    | Type     | Description                                                                                                                                                                                                                                                                                                         | Required?                               |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String   | The API name of a [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm#ui_api_get_started_supported_objects).                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName` | String   | The API name of a list view, such as `AllAccounts`.                                                                                                                                                                                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`          | String[] | Additional fields queried for the records returned. These fields don’t create visible columns. If the field isn’t available to the user, an error occurs.                                                                                                                                                           |                                         |
| `optionalFields`  | String[] | Additional fields queried for the records returned. These fields don’t create visible columns. If the field isn’t available to the user, no error occurs and the field isn’t included in the records.                                                                                                               |                                         |
| `pageSize`        | Integer  | The number of list records viewed at one time. The default value is 50. Valid values are 1—2000.                                                                                                                                                                                                                    |                                         |
| `searchTerm`      | String   | A search term to filter the results. Wildcards are supported.                                                                                                                                                                                                                                                       |                                         |
| `sortBy`          | String   | The API name of the field the list view is sorted by. If the name is preceded with `-`, the sort order is descending. For example, `Name` sorts by name in ascending order, and `-CreatedDate` sorts by the created date in descending order. This parameter accepts only one value per request.                    |                                         |
| `where`           | String   | The filter applied to returned records, in GraphQL syntax. For example, `{ and: [ { StageName: { eq: "Prospecting" } }, { Account: { Name: { eq: "Dickenson plc" } } } ] }` filters an Opportunity related list to show only opportunities in the Prospecting stage that are linked to the "Dickenson plc" account. |                                         |
| `pageToken`       | Integer  | A token that represents the page offset. To indicate where the page starts, use this value with the `pageSize` parameter. The maximum offset is 2000 and the default is 0.                                                                                                                                          |                                         |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`–[List Record Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_record_collection.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example fetches list view records by API name then iterates through the list of records.
The `handleNextPage` click handler returns the next set of record names.

<!-- prettier-ignore -->
```html
<!-- wireGetListRecordsByName.html -->
<template>
   <lightning-card title="wireGetListRecordsByName">
       <template lwc:if={records}>
           <div class="slds-m-around_medium">
               <template for:each={records} for:item="rec">
                   <p key={rec.fields.Id.value}>{rec.fields.Name.value}</p>
               </template>
               <lightning-button-icon icon-name="utility:chevronright"
                  variant="border-filled"
                  alternative-text="Next"
                  title="Settings"
                  onclick={handleNextPage}></lightning-button-icon>
           </div>
       </template>
   </lightning-card>
</template>
```

The JavaScript code displays 10 records at one time. Initialize `pageToken` so the wire adapter has a defined value to start with. If any reactive config property is `undefined`, the wire service doesn't provision data, and both `data` and `error` stay undefined. To handle pagination, use `pageToken` with the `pageSize` parameter. Get the next set of record names by assigning `nextPageToken` to `pageToken`. This value is incremented in steps of 10, as determined by the `pageSize` value.

**tip:** If your component returns undefined `data` and undefined `error`, check that every reactive parameter (any value prefixed with `$`) has an initial value on the class. A `$pageToken` reactive parameter needs a `pageToken = null;` class property. Otherwise, the config is incomplete and the wire never fires.

```javascript
// wireGetListRecordsByName.js
import { LightningElement, wire } from "lwc";
import { getListRecordsByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class GetListRecords extends LightningElement {
  error;
  records;
  pageToken = null;
  nextPageToken = null;

  @wire(getListRecordsByName, {
    objectApiName: ACCOUNT_OBJECT.objectApiName,
    listViewApiName: "AllAccounts",
    fields: ["Account.Id", "Account.Name"],
    sortBy: ["Account.Name"],
    pageSize: 10,
    pageToken: "$pageToken",
  })
  listRecords({ error, data }) {
    if (data) {
      this.records = data.records;
      this.nextPageToken = data?.nextPageToken;
      this.error = undefined;
    } else if (error) {
      this.error = error;
    }
  }

  handleNextPage(event) {
    event.stopPropagation();
    if (this.nextPageToken) {
      this.pageToken = this.nextPageToken;
    }
  }
}
```

Similarly, you can also handle backward pagination by using the `previousPageToken` property that's returned by the `getListRecordsByName` wire adapter.
For more information, see [List Record Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_record_collection.htm).

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=078fb15a33b6dec5442257552e5c491dec6cc31e02fbb638acd1c6b17c7fb6bb url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-list-ui.md -->

# `getListUi` (Deprecated)

Use this wire adapter to get the records and metadata for a list view.

**note:** As a deprecated feature, `getListUi` no longer updates and isn’t part of the “Services” under your Main Services Agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. `getListUi` is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

## Get list view records and metadata for a list view by API name

**note:** Use the [`getListInfoByName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-info-by-name.md) wire adapter.

### Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListUi } from "lightning/uiListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListUi, { objectApiName: ACCOUNT_OBJECT, listViewApiName: "AllAccounts" })
  propertyOrFunction;
}
```

### User Interface API Resource

```html
GET /ui-api/list-ui/${objectApiName}/${listViewApiName}
```

See [Get List View Records and Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_records_md.htm).

### Parameters

- `objectApiName`—(Required) The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md).
- `listViewApiName`—(Required) The API name of a list view, such as `AllAccounts`.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


You can also pass the parameters listed in this [Request Parameters table](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_records_md.htm#request_parameters). See an example in the **Usage** section.

### Returns

- `data`—[List UI](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_ui.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

The records that are returned contain the fields specified by:

- The list view metadata, specified by `data.info.displayColumns`.
- The `fields` and `optionalFields` parameters.

  The underlying list view is controlled by the administrator so it may change. If a component requires fields, request them in the `fields` parameter. Don’t assume that specific fields will be returned unless you explicitly request them. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.

- The object’s system fields, if the object has them, such as `CreatedDate`, `Id`, `LastModifiedById`, `LastModifiedDate`, and `SystemModstamp`.

### Usage

When iterating through the previous or next set of data, consider these guidelines:

- Use the `nextPageToken` and `previousPageToken` values.
- You can’t use `pageToken` values across sessions or across page refreshes. Persisting and reusing page tokens across page refreshes isn’t guaranteed to work.

This example displays 10 contact names from a list view and lets users click through the previous and next set of data.

<!-- prettier-ignore -->
```html
<!-- wireListViewToken.html -->
<template>
  <lightning-card title="WireListViewToken">
    <template lwc:if={records}>
      <div class="slds-m-around_medium">
        <template for:each={records} for:item="record">
          <p key={record.fields.Id.value}>{record.fields.Name.value}</p>
        </template>
      </div>
    </template>
    <div class="slds-grid">
      <div class="slds-m-around_medium">
        <lightning-button label="Previous" onclick={handlePreviousPage}></lightning-button>
      </div>
      <div class="slds-m-around_medium slds-col_bump-left">
        <lightning-button label="Next" onclick={handleNextPage}></lightning-button>
      </div>
    </div>
  </lightning-card>
</template>
```

When a user clicks the **Previous** and **Next** buttons, the `pageToken` parameter is updated to the `previousPageToken` and `nextPageToken` values from the data the wire service provisioned. Because `pageToken` is prepended with `$`, when its value changes the wire service provisions new data.

```javascript
// wireListViewToken.js
import { LightningElement, wire } from "lwc";
import { getListUi } from "lightning/uiListApi";

import CONTACT_OBJECT from "@salesforce/schema/Contact";
import NAME_FIELD from "@salesforce/schema/Contact.Name";

export default class WireListViewToken extends LightningElement {
  pageToken = null;
  nextPageToken = null;
  previousPageToken = null;
  records;
  error;

  @wire(getListUi, {
    objectApiName: CONTACT_OBJECT,
    listViewApiName: "All_Recipes_Contacts",
    sortBy: NAME_FIELD,
    pageSize: 10,
    pageToken: "$pageToken",
  })
  listView({ error, data }) {
    if (data) {
      this.records = data.records.records;
      this.error = undefined;
      this.nextPageToken = data.records.nextPageToken;
      this.previousPageToken = data.records.previousPageToken;
    } else if (error) {
      this.error = error;
      this.records = undefined;
    }
  }

  handleNextPage(e) {
    this.pageToken = this.nextPageToken;
  }

  handlePreviousPage(e) {
    this.pageToken = this.previousPageToken;
  }
}
```

## Example

The `wireListViewToken` example is based on the `wireListView` component in the [`lwc-recipes`](https://github.com/trailheadapps/lwc-recipes) GitHub repo.

## Get list view records and metadata for a list view by ID

Return list view records and metadata using the list view ID.

### Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListUi } from "lightning/uiListApi";
export default class Example extends LightningElement {
  @wire(getListUi, { listViewId: "00BT0000001TONQMA4" })
  propertyOrFunction;
}
```

### User Interface API Resource

```html
GET /ui-api/list-ui/${listViewId}
```

See [Get List View Records and Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_records_md.htm).

### Parameters

- `listViewId`—(Required) The ID of a list view.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


You can also pass the parameters listed in this [Request Parameters table](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_records_md.htm#request_parameters).

### Returns

- `data`—[List UI](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_ui.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

The records that are returned contain the fields specified by:

- The list view metadata, specified by `data.info.displayColumns`.
- The `fields` and `optionalFields` parameters.

  The underlying list view is controlled by the administrator so it may change. If a component requires fields, request them in the `fields` parameter. Don’t assume that specific fields will be returned unless you explicitly request them. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.

- The object’s system fields, if the object has them, such as `CreatedDate`, `Id`, `LastModifiedById`, `LastModifiedDate`, and `SystemModstamp`.


## Get list view records and metadata for an MRU list view by object

Returns record data for an object’s most recently used (MRU) list view.

### Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListUi, MRU } from "lightning/uiListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListUi, { objectApiName: ACCOUNT_OBJECT, listViewApiName: MRU })
  propertyOrFunction;
}
```

### User Interface API Resource

```html
GET /ui-api/mru-list-records/${objectApiName}
```

See [Get Most Recently Used List View Records](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_mru_list_views_records.htm).

### Parameters

- `objectApiName`—(Required) The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md).
- `listViewApiName`—(Required) The API name of the MRU list view.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


You can also pass the parameters listed in this [Request Parameters table](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_mru_list_views_records_md.htm#request_parameters).

### Returns

- `data`—[MRU List UI Representation](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_mru_list_ui_representation.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

The records that are returned contain the fields specified by:

- The list view metadata, specified by `data.info.displayColumns`.
- The `fields` and `optionalFields` parameters.

  The underlying list view is controlled by the administrator so it may change. If a component requires fields, request them in the `fields` parameter. Don’t assume that specific fields will be returned unless you explicitly request them. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.

- The object’s system fields, if the object has them, such as `CreatedDate`, `Id`, `LastModifiedById`, `LastModifiedDate`, and `SystemModstamp`.


## Get list views for an object

Returns a collection of list views associated with an object.

### Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getListUi } from "lightning/uiListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getListUi, { objectApiName: ACCOUNT_OBJECT })
  propertyOrFunction;
}
```

### User Interface API Resource

```html
GET /ui-api/list-ui/${objectApiName}
```

See [Get List Views for an Object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_object.htm).

### Parameters

- `objectApiName`—(Required) The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md).

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


You can also pass the parameters listed in this [Request Parameters table](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_object.htm#request_parameters).

### Returns

- `data`—[List View Summary Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_view_summary_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

The records that are returned contain the fields specified by:

- The list view metadata, specified by `data.info.displayColumns`.
- The `fields` and `optionalFields` parameters.

  The underlying list view is controlled by the administrator so it may change. If a component requires fields, request them in the `fields` parameter. Don’t assume that specific fields will be returned unless you explicitly request them. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the optionalFields parameter.

- The object’s system fields, if the object has them, such as `CreatedDate`, `Id`, `LastModifiedById`, `LastModifiedDate`, and `SystemModstamp`.


**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)
- [getListInfoByName](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-info-by-name.md)

<!-- document id=33f839098f76c99c855d40f0da6c75683f0c344253cd800b6905db0ba090762f url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-factory.md -->

# `getLocationService()`

Use this factory function to get an instance of `LocationService`.

## Syntax

```javascript
import { getLocationService } from 'lightning/mobileCapabilities';
getLocationService(): LocationService
```

## Parameters

None

## Returns

An instance of `LocationService`.

## Usage

Use the instance to make location requests. There are no parameters or options when creating an instance.

**See Also**

- [LocationService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_locationservice_example.htm)

<!-- document id=f6d15c1e21e4564284dcf05c8206e02dccc3f061a56a641402ef63c6863a6a02 url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-get-monitored-ids.md -->

# getMonitoredGeofences

Get all IDs of monitored geofences.

## Syntax

```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
getMonitoredGeofences: Promise<[string]>;
```

## Parameters

None.

## Returns

A Promise object that resolves as an array of string values. The values are unique IDs assigned to monitored geofences. If there’s an error, a rejected promise returns the error type of `GeofenceServiceFailure`.

## Usage

This function calls all the IDs of monitored geofences.

```js
myGeofenceService
  .getMonitoredGeofences()
  .then((results) => {
    const activeGeofences = JSON.parse(JSON.stringify(results, undefined, 2));
    const msg = `Number of geofences: ${activeGeofences.length}`;
    console.log(msg);
  })
  .catch((error) => {
    const msg = `Failed to get current geofences:${JSON.stringify(error)}`;
    console.log(msg);
  });
```

<!-- document id=79cef166a8a72c946998afea2f62894fbeac9c46dfbf1af3ced9441bbfa6bd02 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-nav-items.md -->

# `getNavItems` (Beta)

Use this wire adapter to retrieve the items in the navigation menu.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getNavItems } from 'lightning/uiAppsApi';
import FORM_FACTOR from '@salesforce/client/formFactor';

export default class Example extends LightningElement {
  @api tabs = ['standard-Account', 'standard-CollaborationGroup'];
  @wire(getNavItems, {
    formFactor: FORM_FACTOR,
    navItemNames: '$tabs',
    pageSize: 30,
  })
  propertyOrFunction;
```

## User Interface API Resource

```html
GET /ui-api/nav-items/
```

`getNavItems` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_all_nav_items.htm).

## Parameters

| Parameter Name | Type     | Description                                                                                                                                                                                                                                                                                                                                        | Required? |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `formFactor`   | String   | The response includes navigation items that support this form factor. <ul><li>`Large`—(Default) Desktop display size.</li><li>`Medium`—Tablet display size.</li><li>`Small`—Phone display size.</li></ul> To get a value to pass as the `formFactor`, use the [`@salesforce/client/formFactor`](https://developer.salesforce.com/docs/platform/create/create-client-form-factor.md) module. |           |
| `navItemNames` | String[] | A comma-delimited list of [TabDefinition](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_tabdefinition.htm) `name` values to include in the response. If `navItemNames` isn’t specified, the response includes all the navigation items for the specified `formFactor`.               |           |
| `page`         | Integer  | The page offset from which to begin returning nav items. The default value is 0, which returns nav items from the first page. For example, for `page=2` and `pageSize=10`, the first item returned is the 21st item in the list.                                                                                                                   |           |
| `pageSize`     | Integer  | The maximum number of nav items to return on a page. The default value is 25.                                                                                                                                                                                                                                                                      |           |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Nav Items](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_nav_items.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=05530ce91e432914ed9fb5380a98b311f4de67a72d249d91bc883a33f9127c3c url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-factory.md -->

# `getNFCService()`

Use this factory function to get an instance of `NFCService`.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
getNFCService(): NFCService
```

## Parameters

None.

## Returns

An instance of `NFCService`.

## Usage

There are no parameters or options when creating an instance. Use the instance to perform NFC operations.

<!-- document id=e59b879f9f0a43f874ec5094ea296c336e93c8d6a5721e21c0d945eabbbb8944 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-object-info.md -->

# `getObjectInfo`

Use this wire adapter to get metadata about a specific object. The response includes metadata describing the object’s fields, child relationships, record type, and theme.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getObjectInfo } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/object-info/{objectApiName}
```

`getObjectInfo` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_object_info.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                                                                      | Required?                                  |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `objectApiName` | String | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Object Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

To get metadata for a single object, use `getObjectInfo`. To work with multiple objects, use [`getObjectInfos`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-infos.md).

This example returns the record type Ids and the Id that matches the record type name “Special Account”.

```javascript
import { LightningElement, api, wire, track } from "lwc";
import { getObjectInfo } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class RecordFormWithRecordType extends LightningElement {
  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;

  @track objectInfo;

  @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  objectInfo;

  get recordTypeId() {
    // Returns a map of record type Ids
    const rtis = this.objectInfo.data.recordTypeInfos;
    return Object.keys(rtis).find((rti) => rtis[rti].name === "Special Account");
  }
}
```

See [Compare Base Components](https://developer.salesforce.com/docs/platform/data/data-get-user-input.md) for a full example.

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)
- [Compare Base Components](https://developer.salesforce.com/docs/platform/data/data-get-user-input.md)

<!-- document id=5d6ae5d3e08d0e41cd3e15edc08db25c0ac132e9f861db89b7cadea338e9b08b url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-object-infos.md -->

# `getObjectInfos`

Use this wire adapter to get metadata for multiple objects. The response includes metadata describing the fields, child relationships, record type, and theme for each object.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getObjectInfos } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import OPPORTUNITY_OBJECT from "@salesforce/schema/Opportunity";

export default class GetObjectInfosExample extends LightningElement {
  @wire(getObjectInfos, { objectApiNames: [ACCOUNT_OBJECT, OPPORTUNITY_OBJECT] })
  propertyOrFunction;
}
```

## Parameters

| Parameter Name  | Type     | Description                                                                           | Required?                                  |
| --------------- | -------- | ------------------------------------------------------------------------------------- | ------------------------------------------ |
| `objectApiName` | String[] | The API name of a [supported object](https://developer.salesforce.com/docs/platform/reference/reference-supported-objects.md). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—Contains a `results` object with [Object Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm) metadata and [status codes](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_errors.htm).
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

Get the object metadata using `data.results`. The object metadata is returned in the same order they are requested. If a requested object contains an error, the error code and message are returned in `data.results[].result`. The `error` object is returned only if the server call fails.

```javascript
{
  "results": [
    {
      "result": ObjectInfo1,
      "statusCode": 200
    },
    {
      "result": ObjectInfo2,
      "statusCode": 200
    },
    {
      "result": [
                {
                    "errorCode": "FORBIDDEN",
                    "message": "You don't have access to this record. Ask your administrator for help or to request access."
                }
        ],
        "statusCode": 403
    }
  ]
}
```

## Usage

To get metadata for multiple objects, use `getObjectInfos`. To work with a single object, use [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info.md).

This example returns object info for Account and Opportunity.

```javascript
import { LightningElement, wire } from "lwc";
import { getObjectInfos } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import OPPORTUNITY_OBJECT from "@salesforce/schema/Opportunity";

export default class WireGetObjectInfo extends LightningElement {
  objectApiNames = [ACCOUNT_OBJECT, OPPORTUNITY_OBJECT];

  @wire(getObjectInfos, { objectApiNames: "$objectApiNames" })
  objectInfos;

  get objectInfosStr() {
    return this.objectInfos ? JSON.stringify(this.objectInfos.data, null, 2) : "";
  }
}
```

<!-- document id=94408beddef14f24e31bce59cb32a5fdf6137e83e861f16eec15384119c2e82e url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-picklist-values.md -->

# `getPicklistValues`

Use this wire adapter to get the picklist values for a specified field.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getPicklistValues } from "lightning/uiObjectInfoApi";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class Example extends LightningElement {
  @wire(getPicklistValues, { recordTypeId: "012000000000000AAA", fieldApiName: INDUSTRY_FIELD })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/object-info/{objectApiName}/picklist-values/{recordTypeId}/{fieldApiName}
```

`getPicklistValues` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_picklist_values.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                 | Required?                                  |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `recordTypeId` | String | The ID of the record type. Use the Object Info `defaultRecordTypeId` property, which is returned from [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info.md). If there isn’t a default record type, this value is the master record type, which is `012000000000000AAA`. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fieldApiName` | String | The API name of the picklist field on a [supported object](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).                                                                                                                                                                              | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


**note:** Using `objectApiName` with this wire adapter isn't supported since this information is also already included with `fieldApiName`.

## Returns

- `data`—[Picklist Values](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_values.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

Picklist values are scoped to a record type. For dependent picklists, `getPicklistValues` returns data for controlling fields and how they map to the picklist. For more information, see [Build UI for Picklists](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_dependent_picklist.htm).

**note:** To retrieve all picklists of a record type, use [`getPicklistValuesByRecordType`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values-record.md) instead.

Both the `recordTypeId` and `fieldApiName` parameters are required. To provide the `recordTypeId` value, use the [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info.md) wire adapter and set the `defaultRecordTypeId` property on a reactive variable. Then, pass the reactive variable to the `getPicklistValues` wire adapter.

This example returns the picklist values-Hot, Warm, and Cold-from the Rating field on Account.

```javascript
// wireGetRatingPicklist.js
import { LightningElement, wire } from "lwc";
import { getObjectInfo, getPicklistValues } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import RATING_FIELD from "@salesforce/schema/Account.Rating";

export default class WireGetRatingPicklist extends LightningElement {
  accountRecordTypeId;
  ratings;

  @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  results({ error, data }) {
    if (data) {
      this.accountRecordTypeId = data.defaultRecordTypeId;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.accountRecordTypeId = undefined;
    }
  }

  @wire(getPicklistValues, { recordTypeId: "$accountRecordTypeId", fieldApiName: RATING_FIELD })
  picklistResults({ error, data }) {
    if (data) {
      this.ratings = data.values;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.ratings = undefined;
    }
  }
}
```

`data.values` returns a list of picklist labels and values. See [Picklist Value](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_value.htm).

```json
[
  { "attributes": null, "label": "Hot", "validFor": [], "value": "Hot" },
  { "attributes": null, "label": "Warm", "validFor": [], "value": "Warm" },
  { "attributes": null, "label": "Cold", "validFor": [], "value": "Cold" }
]
```

## Translate Picklist Labels

The `label` property returns the picklist label translated into the running user's language. Salesforce looks up the translation in [Translation Workbench](https://help.salesforce.com/s/articleView?id=sf.customize_wbench.htm&type=5). Admins must enable Translation Workbench and provide a translation for each picklist label. Otherwise, `label` falls back to the org's default language.

The `value` property always returns the untranslated API name. Use `value` to save the user's selection back to Salesforce, and use `label` only for display.

To detect the running user's language in your component, import it from the [`@salesforce/i18n/lang`](https://developer.salesforce.com/docs/platform/create/create-i18n.md) scoped module.

## Display Picklist Values

To display the picklist values on your component, iterate over the list using the `for:each` directive.

<!-- prettier-ignore -->
```html
<!-- wireGetRatingPicklist.html -->
<template>
    <lightning-card title="WireGetRatingPicklist" icon-name="custom:custom67">
        <ul class="slds-var-m-around_medium">
            <template for:each={ratings} for:item="rating" for:index="index">
                <li key={rating.index}>
                    {rating.label}
                </li>
            </template>
        </ul>
    </lightning-card>
</template>

```

**tip:** The `wireGetPicklistValues` component in the [`lwc-recipes`](https://github.com/trailheadapps/lwc-recipes) GitHub repo gets the picklist values for an Account field.

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)
- [Access Internationalization Properties](https://developer.salesforce.com/docs/platform/create/create-i18n.md)

<!-- document id=8ae692bb90826b4aa4f8aaa0a5b6bf72fe5312261090e3ae7e89c714b1bc1e4c url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-picklist-values-record.md -->

# `getPicklistValuesByRecordType`

Use this wire adapter to get the values for every picklist of a specified record type.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getPicklistValuesByRecordType } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class Example extends LightningElement {
  @wire(getPicklistValuesByRecordType, {
    objectApiName: ACCOUNT_OBJECT,
    recordTypeId: "012000000000000AAA",
  })
  propertyOrFunction;
}
```

## User Interface API Resource

```html
GET /ui-api/object-info/{objectApiName}/picklist-values/{recordTypeId}
```

`getPicklistValuesByRecordType` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_picklist_values_collection.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                                                                                                      | Required?                                  |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `objectApiName` | String | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).                                                                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recordTypeId`  | String | The ID of the record type. Use the Object Info `defaultRecordTypeId` property, which is returned from [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info.md). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Picklist Values Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_values_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

Picklist values are scoped to a record type. `getPicklistValuesByRecordType` returns a collection of picklist values for all of the picklists of a specified record type. For more information, see [Build UI for Picklists](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_features_records_dependent_picklist.htm).

To retrieve picklist values for a specific field, use [`getPicklistValues`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values.md) instead.

**note:** The `label` property in each returned picklist value is translated into the running user's language. For details, see [Translate Picklist Labels](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values.md#translate-picklist-labels).

## Example

See the `wireGetPicklistValuesByRecordType` component in the [`lwc-recipes`](https://github.com/trailheadapps/lwc-recipes) GitHub repo.

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=900e136632f43541ef3293754777727f7f3fedebeba94450f383e1e54f5c0eb0 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-recipe.md -->

# `getRecipe`

Retrieves a specific data prep recipe by ID.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecipe } from "lightning/analyticsWaveApi";

export default class GetRecipe extends LightningElement {
  @api recipeId; // or fetch the ID
  @wire(getRecipe, {
    id: "$recipeId",
    format: "R3",
  })
  onGetRecipe({ data, error }) {
    if (error) {
      console.log(`getRecipe(${recipeId}) ERROR:`, error);
    } else if (data) {
      console.log(`getRecipe(${recipeId}) RESPONSE:`, data);
    }
  }
}
```

## Data Prep Recipe API Resource

```html
GET /wave/recipes/${id}
```

`getRecipe` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes_id.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                          | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `id`           | String | The ID of the recipe.                                                                                                                | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `format`       | String | Specifies the format of the returned recipe: <ul><li>`R2` (Data Prep Classic)</li><li>`R3` (Data Prep)</li></ul>The default is `R3`. |                                            |

## Returns

- `data`—[Recipe](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_responses_recipe.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=afa169727bbb103f84e6c54123db1af758695af395cef1eff3c12f13651e31de url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-recipe-notification.md -->

# `getRecipeNotification`

Retrieves the notification settings for a specific data prep recipe by ID.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecipeNotification } from "lightning/analyticsWaveApi";

export default class GetRecipeNotification extends LightningElement {
  @api recipeId; // or fetch the ID
  @wire(getRecipeNotification, {
    id: "$recipeId",
  })
  onGetRecipeNotification({ data, error }) {
    if (error) {
      console.log(`getRecipeNotification(${recipeId}) ERROR:`, error);
    } else if (data) {
      console.log(`getRecipeNotfication(${recipeId}) RESPONSE:`, data);
    }
  }
}
```

## Data Prep Recipe API Resource

```html
GET /wave/recipes/${id}/notification
```

`getRecipeNotification` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes_id_notification.htm).

## Parameters

| Parameter Name | Type   | Description           | Required?                                  |
| -------------- | ------ | --------------------- | ------------------------------------------ |
| `id`           | String | The ID of the recipe. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Recipe Nofication](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_responses_recipe_notification.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=0d24008cedbe2482e6bfb51dfcdc4446558ddcb2a00933b92b374fa76f9f86b3 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-recipes.md -->

# `getRecipes`

Retrieves a collection of data prep recipes.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getRecipes } from "lightning/analyticsWaveApi";

export default class GetRecipes extends LightningElement {
  @wire(getRecipes, {
    format: "R3",
    licenseType: "Sonic",
  })
  onGetRecipes({ data, error }) {
    if (error) {
      console.log("getRecipes ERROR:", error);
    } else if (data) {
      console.log("getRecipes RESPONSE:", data.recipes);
    }
  }
}
```

## Data Prep Recipe API Resource

```html
GET /wave/recipes
```

`getRecipes` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes.htm).

## Parameters

These parameters are optional.

| Parameter Name        | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folderId`            | String   | Filters the collection to include only recipes associated with the specified folder ID.                                                                                                                                                                                                                                                                                                                                                                 |
| `format`              | String   | Filters the collection to include only recipes of the specified format. <ul><li>`R2` (Data Prep Classic)</li><li>`R3` (Data Prep)</li></ul>                                                                                                                                                                                                                                                                                                             |
| `lastModifiedAfter`   | Date     | Filters the collection to include only recipes with a last modified date after the given value.                                                                                                                                                                                                                                                                                                                                                         |
| `lastModifiedBefore`  | Date     | Filters the collection to include only recipes with a last modified date before the given value.                                                                                                                                                                                                                                                                                                                                                        |
| `licenseType`         | String   | The response includes assets with this license type. The default is `EinsteinAnalytics`. <ul><li>`Cdp` (Data Cloud)</li><li>`DataPipelinesQuery` (Data Pipelines Query)</li><li>`EinsteinAnalytics` (CRM Analytics)</li><li>`IntelligentApps` (Intelligent Apps)</li><li>`MulesoftDataPath` (Mulesoft Data Path)</li><li>`Sonic` (Salesforce Data Pipelines)</li></ul>                                                                                  |
| `nextScheduledAfter`  | Date     | Filters the collection to include only recipes with a scheduled run after the given value.                                                                                                                                                                                                                                                                                                                                                              |
| `nextScheduledBefore` | Date     | Filters the collection to include only recipes with a scheduled run before the given value.                                                                                                                                                                                                                                                                                                                                                             |
| `page`                | String   | Generated token that indicates the view of recipes to be returned.                                                                                                                                                                                                                                                                                                                                                                                      |
| `pageSize`            | Int      | Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.                                                                                                                                                                                                                                                                                                                                                   |
| `q`                   | String   | Search terms. Individual terms are separated by spaces.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sort`                | String   | Sort order to apply to the collection results. <ul><li>`App`</li><li>`CreatedBy`</li><li>`CreatedById`</li><li>`CreatedDate`</li><li>`FolderName`</li><li>`LastModified`</li><li>`LastModifiedBy`</li><li>`LastModifiedById`</li><li>`Location`</li><li>`Mru` (Most Recently Used, last viewed date)</li><li>`Name`</li><li>`Outcome`</li><li>`Owner`</li><li>`RefreshDate`</li><li>`RunDate`</li><li>`Status`</li><li>`Title`</li><li>`Type`</li></ul> |
| `status`              | String[] | Filters the collection to include only recipes with the specified statuses. <ul><li>`Cancelled`</li><li>`Failure`</li><li>`New` (Never run or has no recent run)</li><li>`Queued`</li><li>`Running`</li><li>`Success`</li><li>`Warning`</li></ul>                                                                                                                                                                                                       |

## Returns

- `data`—[Recipe Collection](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_responses_recipe_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=8b72697e96887d83566134576966e1e24b0abd8637afec85efddccd7c4aac1ee url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-record.md -->

# `getRecord`

Use this wire adapter to get a record’s data.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRecord } from 'lightning/uiRecordApi';

@wire(getRecord, { recordId: string, fields: string|string[], optionalFields?: string|string[] })
propertyOrFunction

@wire(getRecord, { recordId: string, layoutTypes: string|string[],
                    modes?: string|string[], optionalFields?: string|string[] })
propertyOrFunction
```

## User Interface API Resource

```html
GET /ui-api/records/{recordId}
```

The `getRecord` wire adapter uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_get.htm), but doesn’t support all its parameters.

## Parameters

| Parameter Name   | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Required?                                  |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `recordId`       | String   | The ID of a record from a [supported object](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`         | String[] | Either `fields` or `layoutTypes` is required. A field or an array of fields to return. If the context user doesn’t have access to a field, an error is returned. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the `optionalFields` parameter. Specify field names in the format `ObjectApiName.FieldName` or `ObjectApiName.JunctionIdListName`. **[Polymorphic fields](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_relationships_and_polymorph_keys.htm) aren't supported. Including a polymorphic field in `fields` can result in an invalid field error.**                                                                                                                                                                                                                                                                                 | See description                            |
| `layoutTypes`    | String[] | Either `fields` or `layoutTypes` is required. Specifies the fields to return. If this property is specified, the response is a union of `layoutTypes`, `modes`, and `optionalFields`. <ul><li>`Compact`—Use this value to get a layout that contains a record’s key fields.</li><li>`Full`—Use this value to get a full layout.</li></ul> Not all objects support layouts, for example, [the Report object](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_report.htm) doesn’t include a `describeLayout()` call. In this case, we recommend using `optionalFields` to specify a default set of fields. **To improve performance, specify fields instead of a layout whenever possible. Specify a layout only when you want the administrator, not the component, to control the fields that are provisioned. The component must handle receiving every field that is assigned to the layout for the context user.** | See description                            |
| `modes`          | String[] | Optional if `layoutTypes` is specified. If `layoutTypes` is not specified, this parameter is ignored. The access modes for the record. This value determines which fields to get from a layout. Layouts have different fields for create, edit, and view modes. <ul><li>`Create`—Use this mode if you intend to build UI that lets a user create a record.</li><li>`Edit`—Use this mode if you intend to build UI that lets a user edit a record.</li><li>`View`—(Default) Use this mode if you intend to build UI that displays a record.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                              |                                            |
| `optionalFields` | String[] | An optional field name or an array of optional field names. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error. Specify field names in the format `ObjectApiName.FieldName` or `ObjectApiName.JunctionIdListName`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                            |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm)

  In the Record response, don’t use the `recordTypeInfo` property. Instead, use the `recordTypeId` property, which is returned for every record.

- `error`—[`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

**tip:** To filter by criteria and work with dynamic record IDs easily, consider using the [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/graphql/reference-graphql.md) instead.

This example loads the record with required and optional fields. Use `getRecord` and `getFieldValue` to get a record and display its fields values. Replace the `recordId` value with your own.

```javascript
import { LightningElement, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import OWNER_NAME_FIELD from "@salesforce/schema/Account.Owner.Name";
import PHONE_FIELD from "@salesforce/schema/Account.Phone";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class Example extends LightningElement {
  @wire(getRecord, {
    recordId: "001456789012345678",
    fields: [NAME_FIELD, INDUSTRY_FIELD],
    optionalFields: [PHONE_FIELD, OWNER_NAME_FIELD],
  })
  account;

  get name() {
    return getFieldValue(this.account.data, NAME_FIELD);
  }

  get phone() {
    return getFieldValue(this.account.data, PHONE_FIELD);
  }

  get industry() {
    return getFieldValue(this.account.data, INDUSTRY_FIELD);
  }

  get owner() {
    return getFieldValue(this.account.data, OWNER_NAME_FIELD);
  }
}
```

Load the field values in a custom user interface.

<!-- prettier-ignore -->
```html
<template lwc:if={account.data}>
  <div class="slds-m-around_medium">
    <p>Account Name: {name}</p>
    <p>Industry: {industry}</p>
    <p>Phone: {phone}</p>
    <p>Owner: {owner}</p>
  </div>
</template>
```

This example loads the record by layout. Replace the `recordId` value with your own. Similar to the previous example, you can render field values using the `getFieldValue` wire adapter.

```javascript
import { LightningElement, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

export default class Example extends LightningElement {
  @wire(getRecord, { recordId: "001456789012345678", layoutTypes: ["Full"], modes: ["View"] })
  accountRecord;
}
```

See [Get Record Data](https://developer.salesforce.com/docs/platform/data/data-wire-example.md) for an example of using `getRecord` with a custom UI.

## Error Handling

Use a Promise with `then()` and `catch()` blocks. To display errors, use toasts provided by the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api, wire } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { getRecord } from "lightning/uiRecordApi";

const FIELDS = ["Contact.Name", "Contact.Phone"];

export default class LoadContact extends LightningElement {
  @api recordId;
  contact;
  name;
  phone;
  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  wiredRecord({ error, data }) {
    if (error) {
      let message = "Unknown error";
      if (Array.isArray(error.body)) {
        message = error.body.map((e) => e.message).join(", ");
      } else if (typeof error.body.message === "string") {
        message = error.body.message;
      }
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Error loading contact",
          message,
          variant: "error",
        }),
      );
    } else if (data) {
      this.contact = data;
      this.name = this.contact.fields.Name.value;
      this.phone = this.contact.fields.Phone.value;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)
- [Get Record Data](https://developer.salesforce.com/docs/platform/data/data-wire-example.md)
- [createRecord(recordInput)](https://developer.salesforce.com/docs/platform/lwc/reference-create-record.md)
- [updateRecord(recordInput, clientOptions)](https://developer.salesforce.com/docs/platform/lwc/reference-update-record.md)
- [deleteRecord(recordId)](https://developer.salesforce.com/docs/platform/lwc/reference-delete-record.md)

<!-- document id=31cfe156f0e09de6c917f69a5ebc28f3fc9376331a7c6050b5c66a4acb68bea7 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-create-record-values.md -->

# `getRecordCreateDefaults`

Use this wire adapter to get default information and data needed to create a record.

## Syntax

```javascript
import { getRecordCreateDefaults } from 'lightning/uiRecordApi';
@wire(getRecordCreateDefaults, { objectApiName: string })
propertyOrFunction;
```

## User Interface API Resource

```html
GET /ui-api/record-defaults/create/{objectApiName}
```

`getRecordCreateDefaults` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_defaults_create.htm).

## Parameters

| Parameter Name   | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                   | Required?                                  |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `objectApiName`  | String   | A [supported object](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).                                                                                                                                                                                                                                                                                                                                      | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `formFactor`     | String[] | The layout display size for the record. An array containing any of these values: <ul><li>`Large`—(Default) Layout for desktop display size.</li><li>`Medium`—Layout for tablet display size.</li><li>`Small`—Layout for phone display size.</li>To get a value to pass as the `formFactor`, use the [`@salesforce/client/formFactor`](https://developer.salesforce.com/docs/platform/create/create-client-form-factor.md) module.</ul> |                                            |
| `recordTypeId`   | String   | The ID of the record type (RecordType object) for the new record. If not provided, the default record type is used.                                                                                                                                                                                                                                                                           |                                            |
| `optionalFields` | String[] | An optional array of field names. If an optional field is accessible to the context user, it’s included in the response. Specify names in the format `['ObjectApiName.FieldName']`.                                                                                                                                                                                                           |                                            |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Record Defaults](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_defaults.htm)

  In the response, don’t use the `recordTypeInfo` property. Instead, use the `recordTypeId` property, which is returned for every record.

- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

To create UI that lets a user create a record, first get information about which fields are required. This adapter’s response contains the default field values for a new record of the object type specified in `{apiName}`. It also contains object metadata and the corresponding layout for Create mode. In the Salesforce user interface, an admin with “Customize Application” permission can mark a field as required in a layout. When you’re building UI, to determine which fields to mark as required in a layout for create and update, use the `ObjectInfo.fields[fieldName].required` property.

**tip:** The `ldsGenerateRecordInputForCreate` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo shows an example on how to use `getRecordCreateDefaults`.

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=bb974c1d32a650ba3b52f6e90ccfb1d592cd16bb1431146fce86bc891f1c0771 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-get-record-notify.md -->

# `getRecordNotifyChange(recordIds)` (Deprecated)

Deprecated. Use `notifyRecordUpdateAvailable(recordIds)` instead. `getRecordNotifyChange(recordIds)` fetches record updates for the specified record IDs and refreshes the Lightning Data Service cache, providing your wire adapters with the latest record data. `getRecordNotifyChange(recordIds)` isn’t suitable for use with multiple adapters that return data of the same type.

**note:** `getRecordNotifyChange(recordIds)` is deprecated. We recommend that you use [notifyRecordUpdateAvailable(recordIds)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-notify-record-update.md) instead.

## Syntax

```javascript
import { getRecordNotifyChange } from 'lightning/uiRecordApi';

getRecordNotifyChange(items: Array<{recordId: string}>)
```

## Parameters

- `items`—(Required) An array of objects with an object shape of `{ recordId: string }`. The record ID can be either 15 or 18 characters long, and it must be from a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md).

## Returns

The return type is `void`.

## Usage

**note:** To notify Lightning Data Service that a record has changed outside its mechanisms, such as via imperative Apex or by calling User Interface API via a third-party framework, use [notifyRecordUpdateAvailable(recordIds)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-notify-record-update.md) instead.

Calling `getRecordNotifyChange(recordIds)` signals that the data for the provided _recordIds_ has changed, so that the Lightning Data Service cache and wires can be updated as needed.

**note:** If you’re using an `@wire` to get record data via an Apex method, simply call [`refreshApex()`](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md), which uses the configuration bound to the `@wire` to get the data and update the cache.

**See Also**

- [MDN web docs: `async` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
- [Supported JavaScript](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-javascript.md)

<!-- document id=4e38b36befff97523dc2b9c85ba7d483596adb27c48b12d09b7d743a9c98074a url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-records.md -->

# `getRecords`

Use this wire adapter to get data for a batch of records at once. You can request multiple objects or different record types.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRecords } from 'lightning/uiRecordApi';

@wire(getRecords, { records: [ { recordIds: string[], fields: string[] } ] })
propertyOrFunction

@wire(getRecords, { records: [ { recordIds: string[], fields: string[], optionalFields?: string[] } ] })
propertyOrFunction


```

## User Interface API Resource

```html
GET /ui-api/records/batch/{recordIds}
```

The `getRecords` wire adapter uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_records_batch.htm), but doesn’t support all its parameters.

## Parameters

| Parameter Name | Type   | Description                                                                    | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------ | ------------------------------------------ |
| `records`      | Object | An array of record data, which can be across multiple objects or record types. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

`records` has several properties.

| `records` Property | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required?                                  |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `recordIds`        | String[] | (At least one required) The ID of records to fetch from [supported objects](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`           | String[] | An array of fields to return. If the context user doesn’t have access to a field, an error is returned. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the `optionalFields` parameter. <br>Specify field names in the format `ObjectApiName.FieldName` or `ObjectApiName.JunctionIdListName`. **[Polymorphic fields](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_relationships_and_polymorph_keys.htm) aren't supported. Including a polymorphic field in `fields` can result in an invalid field error.** |                                            |
| `optionalFields`   | String[] | An array of optional field names. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error. Specify field names in the format `ObjectApiName.FieldName` or `ObjectApiName.JunctionIdListName`.                                                                                                                                                                                                                                                                                                         |                                            |

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `results`—[Batch Results](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_batch_results.htm#ui_api_responses_batch_results)
- `error`-[`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

To get data for a single record, use [getRecord](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-record.md) instead.

**tip:** To filter by criteria and work with dynamic record IDs easily, consider using the [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/graphql/reference-graphql.md) instead.

This example loads several records using the record IDs. Replace the `recordIds` values with your own.

```javascript
import { LightningElement, wire } from "lwc";
import { getRecords } from "lightning/uiRecordApi";
import NAME_FIELD from "@salesforce/schema/User.Name";
import EMAIL_FIELD from "@salesforce/schema/User.Email";

export default class GetRecordsExample extends LightningElement {
  @wire(getRecords, {
    records: [
      {
        recordIds: ["005XXXXXXXXXXXXXXX", "005XXXXXXXXXXXXXXX"],
        fields: [NAME_FIELD],
        optionalFields: [EMAIL_FIELD],
      },
    ],
  })
  wiredRecords;
}
```

Alternatively, you can request for records across multiple objects.

```javascript
import { LightningElement, wire } from "lwc";
import { getRecords } from "lightning/uiRecordApi";
import USER_NAME_FIELD from "@salesforce/schema/User.Name";
import USER_EMAIL_FIELD from "@salesforce/schema/User.Email";
import ACCOUNT_NAME_FIELD from "@salesforce/schema/Account.Name";

export default class GetRecordsExample extends LightningElement {
  @wire(getRecords, {
    records: [
      {
        recordIds: ["005XXXXXXXXXXXXXXX"],
        fields: [USER_NAME_FIELD],
        optionalFields: [USER_EMAIL_FIELD],
      },
      {
        recordIds: ["001XXXXXXXXXXXXXXX"],
        fields: [ACCOUNT_NAME_FIELD],
      },
    ],
  })
  wiredRecords;
}
```

To work with dynamic record IDs, consider using the [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-multiple-objects.md) instead.

If you use the `getRecords` wire adapter with dynamic record IDs, we recommend that you create a `parameterObject` array that you can push your record parameters to as a single property. Using an array enables you to define record IDs and fields for multiple objects.

For example, you can retrieve contact IDs by account via an Apex controller and then pass them to the `parameterObject` array. You can also pass in your record parameters from a parent component to a child component that initializes the array.

**note:** When you call the wire adapter, the User Interface API composes a SOQL query for the request. This SOQL query has [a limit of 100k characters](https://help.salesforce.com/s/articleView?id=000333028&type=1). If you expect to exceed this limit, we recommend splitting the query into multiple queries and running them in batches.

This example shows how you can retrieve contact and user records on an account. It assumes that you retrieve the contacts on an account using an Apex controller.

```java
public with sharing class ContactsController {
  @AuraEnabled(cacheable=true)
  public static List<Contact> getContactsByAccount(Id accountId) {
    return [
            SELECT Id
            FROM Contact
            WHERE AccountId = :accountId
    ];
  }
}
```

In your JavaScript, set up the `parameterObject` array to define record IDs and fields for the contact and user records. Then, pass in the `$parameterObject` dynamic variable to the `getRecords` wire adapter.

```javascript
import { LightningElement, api, wire, track } from "lwc";
import getContacts from "@salesforce/apex/ContactsController.getContactsByAccount";
import CONTACT_NAME_FIELD from "@salesforce/schema/Contact.Name";
import USER_NAME_FIELD from "@salesforce/schema/User.Name";
import userId from "@salesforce/user/Id";

export default class DynamicIDExample extends LightningElement {
  @api recordId; //current Account's Id
  contacts = [];
  @track filteredData = [];
  parameterObject;

  @wire(getContacts, { accountId: "$recordId" })
  retrievedContacts({ error, data }) {
    if (data) {
      this.contacts = data;
      if (this.contacts.length > 0) {
        this.parameterObject = [];
        this.contacts.forEach((contact) => {
          this.parameterObject.push({
            recordIds: [contact.Id],
            fields: [CONTACT_NAME_FIELD],
          });
        });
        this.parameterObject.push({
          recordIds: [userId],
          optionalFields: [USER_NAME_FIELD],
        });
      } else if (error) {
        this.contacts = undefined;
      }
    }
  }

  @wire(getRecords, { records: "$parameterObject" })
  wiredRecords({ error, data }) {
    if (data) {
      data.results.forEach((record) => {
        this.filteredData.push({
          Name: record.result.fields.Name.value,
          Id: record.result.id,
        });
      });
    } else if (error) {
      console.log("error: ", error);
    }
  }
}
```

When you use this component on an account record page, it renders a list of contact names that are associated on the account and the username of the account owner.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="DynamicIDExample" icon-name="standard:contact">
    <div class="slds-var-m-around_medium">
      <template lwc:if={filteredData}>
        <template for:each={filteredData} for:item="record">
          <p key={record.Id}>{record.Name}</p>
        </template>
      </template>
      <template lwc:elseif={errors}>
        <c-error-panel errors={errors}></c-error-panel>
      </template>
    </div>
  </lightning-card>
</template>
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has several examples that demonstrate `getRecords` usage. Look for components that start with `wireGetRecords`, such as [`wireGetRecordsDifferentTypes` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/wireGetRecordsDifferentTypes).

## Error Handling

`getRecords` returns errors in the `error` property. For example, you get a 400 Bad Request error if you pass in an invalid field name to the `fields` or `optionalFields` array.

```json
{
  "status": 400,
  "body": {
    "message": "Expected '.' in all qualified names: badFieldName is invalid",
    "statusCode": 400,
    "errorCode": "ILLEGAL_QUERY_PARAMETER_VALUE",
    "id": "1369078084"
  },
  "headers": {},
  "ok": false,
  "statusText": "Bad Request",
  "errorType": "fetchResponse"
}
```

If the response status returns a 200 success code but a subrequest returns a `statusCode` of 400 or another non-200 error code, the network response returns `hasErrors:true`, but this property isn't returned as part of `data`.

To identify errors in a subrequest, check the `data.results` object.

- If the subrequest returns a 200 success code, the `results.result` object contains record data with the requested fields.
- If the subrequest returns a non-200 error code or 400 error code, the `results.result` object contains the `errorCode` and `message` properties.

For example, you get an overall 200 success code if you request two records - a record with valid fields and a record with an invalid ID. Although the subrequest for the first record is returned with a 200 success code, the subrequest for the second record is returned with a 400 error code.

```json
{
  "results": [
    {
      "statusCode": 200,
      "result": {
        "apiName": "Contact",
        "childRelationships": {},
        "fields": {
          "Name": {
            "displayValue": null,
            "value": "Sean Forbes"
          },
          "Email": {
            "displayValue": null,
            "value": "sean@edge.com"
          }
        },
        "id": "0031a00000527vwAAA",
        "lastModifiedById": "0051a000000GqXfAAK",
        "lastModifiedDate": "2015-06-17T22:17:58.000Z",
        "recordTypeId": "012000000000000AAA",
        "recordTypeInfo": null,
        "systemModstamp": "2015-06-17T22:17:58.000Z"
      }
    },
    {
      "statusCode": 400,
      "result": [
        {
          "errorCode": "UNKNOWN_EXCEPTION",
          "message": "Record ID is malformed: 0031a00000527vxAAb"
        }
      ]
    }
  ]
}
```

To display errors, you can use toasts provided by the `lightning/platformShowToastEvent` module with a Promise that includes `then()` and `catch()` blocks.

```javascript
import { LightningElement, api, wire } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { getRecords } from "lightning/uiRecordApi";

const FIELDS = ["Contact.Name", "Contact.Phone"];

export default class LoadContact extends LightningElement {
  @api recordId;
  contacts;
  name;
  phone;
  @wire(getRecords, {
    records: [
      {
        recordIds: ["005XXXXXXXXXXXXXXX", "005XXXXXXXXXXXXXXX"],
        fields: FIELDS,
      },
    ],
  })
  wiredRecord({ error, data }) {
    if (error) {
      let message = "Unknown error";
      if (Array.isArray(error.body)) {
        message = error.body.map((e) => e.message).join(", ");
      } else if (typeof error.body.message === "string") {
        message = error.body.message;
      }
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Error loading contacts",
          message,
          variant: "error",
        }),
      );
    } else if (data) {
      this.contacts = data;
      this.name = this.contacts.results[1].result.fields.Name.value;
      this.phone = this.contacts.results[1].result.fields.Phone.value;
    }
  }
}
```

<!-- document id=4284add02ebef085bd73f2bb9f2cb96381f0ab0b67d09c2d2fad6c5772d6600d url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-record-ui.md -->

# `getRecordUi` (Deprecated)

Deprecated. This wire adapter gets layout information, metadata, and data to build UI for one or more records.

To create a UI for working with records, use the [`getLayout`](https://developer.salesforce.com/docs/platform/lwc/reference-get-layout.md) wire adapter instead.

**note:** As a deprecated feature, `getRecordUi` no longer updates and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. `getRecordUi` is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRecordUi } from 'lightning/uiRecordApi';

export default class Example extends LightningElement {
  @wire(getRecordUi, { recordIds: string|string[], layoutTypes: string|string[],
                        modes: string|string[], optionalFields?: string|string[] })
  propertyOrFunction;
}
```

## User Interface API Resource

```nolang
GET /ui-api/record-ui/{recordsIds}
```

The `getRecordUi` wire adapter uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_ui.htm), but doesn’t support all its parameters.

## Parameters

- `recordIds`—(Required) IDs of records to load. A string or an array of strings. All record IDs must be from a [supported object](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md).
- `layoutTypes`—(Required) Layout types for the record. A string or an array of strings. Each string is one of these values:
  - `Compact`—Use this value to get a layout that contains a record’s key fields.
  - `Full`—Use this value to get a full layout.
- `modes`—(Required) The access mode for the record. This value determines which fields to get from a layout. Layouts have different fields for create, edit, and view modes. For example, formula fields are rendered in view mode, but not in create mode because they’re calculated at run time, like formulas in a spreadsheet.

  A string or an array of strings. Each string contains one of these values:

  - `Create`—Use this mode if you intend to build UI that lets a user create a record.
  - `Edit`—Use this mode if you intend to build UI that lets a user edit a record.
  - `View`—Use this mode if you intend to build UI that displays a record.

- `optionalFields`—An optional field name or an array of optional field names. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


## Returns

- `data`—[Record UI](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_ui.htm)

  In the response, don’t use the `recordTypeInfo` property. Instead, use the `recordTypeId` property, which is returned for every record.

- `error`—[`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md)

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=336cc57550424f2f8d378106d8965a04b6d951628b867055ae8d38d847b1a966 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-list-count.md -->

# `getRelatedListCount`

Use this wire adapter to get the `RelatedList` record count.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRelatedListCount } from 'lightning/uiRelatedListApi';

export default class LdsGetRelatedListCount extends LightningElement {
  @wire(getRelatedListCount, {
      parentRecordId: '001RM000003UNu6YAG',
      relatedListId: 'Contacts',
  })
}
```

## User Interface API Resource

```html
GET /ui-api/related-list-count/${parentRecordId}/${relatedListId}
```

See [Get Related List Record Count](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_count.htm).

## Parameters

| Parameter Name   | Type   | Description                                                                             | Required?                                  |
| ---------------- | ------ | --------------------------------------------------------------------------------------- | ------------------------------------------ |
| `parentRecordId` | String | The ID of the parent record that you want to get related lists for, like an Account ID. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `relatedListId`  | String | The API name of a related list object such as Contacts, Opportunities, or Cases.        | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `maxCount`       | Number | The maximum number of records to return. The default value is 20.                       |                                            |

## Returns

- `data`—[Related List Record Count](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_record_count.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches the record count for a related list.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListCount.html -->
<template>
  <lightning-card title="wireGetRelatedListCount">
    <template lwc:if={responseData}>
      <div class="slds-m-around_medium">
        <p key={responseData.count}>{responseData.count} : {responseData.hasMore}</p>
      </div>
    </template>
  </lightning-card>
</template>
```

```javascript
// wireGetRelatedListCount.js
import { LightningElement, wire } from "lwc";
import { getRelatedListCount } from "lightning/uiRelatedListApi";
export default class WireGetRelatedListCount extends LightningElement {
  error;
  responseData;
  @wire(getRelatedListCount, {
    parentRecordId: "001RM000003UNu6YAG",
    relatedListId: "Contacts",
  })
  listInfo({ error, data }) {
    if (data) {
      this.responseData = data;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.responseData = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=630fafc682b9ab2049f1405e0af8e3621234a745282332332c1f7fa96c90a0b6 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-list-info.md -->

# `getRelatedListInfo`

Use this wire adapter to get the metadata for `RelatedList`.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRelatedListInfo } from 'lightning/uiRelatedListApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';

export default class LdsGetRelatedListInfo extends LightningElement {
  @wire(getRelatedListInfo, {
      parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
      relatedListId: 'Contacts',
      recordTypeId: '012000000000000AAA', //optional
      fields: ['Contact.Name', 'Contact.Id'], //optional
      optionalFields: ['Contact.OptionalField'], //optional
      restrictColumnsToLayout: false //optional
  })
}
```

## User Interface API Resource

```html
GET /ui-api/related-list-info/${parentObjectApiName}/${relatedListId}
```

See [Get Related List Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_info_md.htm).

## Parameters

| Parameter Name            | Type             | Description                                                                                                                                                                                                                                                                                                               | Required?                                  |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `parentObjectApiName`     | String           | The API name of a parent object that you want to get related lists for, like an Account.                                                                                                                                                                                                                                  | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `relatedListId`           | String           | The API name of a related list object such as Contacts, Opportunities, or Cases.                                                                                                                                                                                                                                          | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recordTypeId`            | String           | The ID of the parent record type. If not provided, the default record type is used.                                                                                                                                                                                                                                       |                                            |
| `fields`                  | Array of Strings | The API names of the related list’s fields to query. If the context user doesn’t have access to a field, or if the field doesn’t exist, an error is returned. If you’re not sure whether the context user has access to a field and you don’t want the request to fail if they don’t, use the `optionalFields` parameter. |                                            |
| `optionalFields`          | Array of Strings | The API names of additional fields in the related list to query. If a field is accessible to the context user, it’s included in the response. If a field isn’t accessible to the context user, it isn’t included in the response, but it doesn’t cause an error.                                                          |                                            |
| `restrictColumnsToLayout` | Boolean          | Indicates whether to retrieve metadata for only the list columns in the page layout (true) or all columns (false). The default value is true. To further filter columns, use `restrictColumnsToLayout` with `fields` and `optionalFields`.                                                                                |                                            |

## Returns

- `data`—[Related List Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_metadata.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches the metadata for the Contacts related list in the Account object, then iterates through the list of display columns.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListInfo.html -->
<template>
  <lightning-card title="wireGetRelatedListInfo">
    <template lwc:if={displayColumns}>
      <div class="slds-m-around_medium">
        <template for:each={displayColumns} for:item="col">
          <p key={col.fieldApiName}>{col.label}</p>
        </template>
      </div>
    </template>
  </lightning-card>
</template>
```

```javascript
// wireGetRelatedListInfo.js
import { LightningElement, wire } from "lwc";
import { getRelatedListInfo } from "lightning/uiRelatedListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class WireGetRelatedListInfo extends LightningElement {
  error;
  displayColumns;
  @wire(getRelatedListInfo, {
    parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
    relatedListId: "Contacts",
    recordTypeId: "012000000000000AAA", // optional
  })
  listInfo({ error, data }) {
    if (data) {
      this.displayColumns = data.displayColumns;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.displayColumns = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=aa2483917d76132e2c721848e7b2c5f45ee43de031ded2f81d19f3f4f15ffac6 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-list-info-batch.md -->

# `getRelatedListInfoBatch`

Use this wire adapter to get the metadata for a batch of `RelatedLists`.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRelatedListInfoBatch } from 'lightning/uiRelatedListApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';

export default class LdsGetRelatedListInfoBatch extends LightningElement {
  @wire(getRelatedListInfoBatch, {
    parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
    relatedListNames: ['Contacts', 'Opportunities'],
  })
}
```

## User Interface API Resource

```html
GET /ui-api/related-list-info/batch/${parentObjectApiName}/${relatedListIds}
```

See [Get a Batch of Related List Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_info_batch.htm).

## Parameters

| Parameter Name        | Type     | Description                                                                                                                                                                                                                                                              | Required?                                  |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `parentObjectApiName` | String   | The API name of a parent object that you want to get related lists for, like an Account.                                                                                                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `relatedListNames`    | String[] | An array of comma-separated strings that contain the API names of supported related lists for the parent object such as Contacts, Opportunities, or Cases. **In the wire adapter code, `relatedListNames` maps to `relatedListIds` in the User Interface API resource.** | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recordTypeId`        | String   | The ID of the parent record type. If not provided, the default record type is used.                                                                                                                                                                                      |                                            |

## Returns

- `data`—[Simplified Batch Results](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_batch_results_simplified.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches the metadata for the Contacts and Opportunities related lists in the Account object, then iterates through the list of display columns.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListInfoBatch.html -->
<template>
  <template lwc:if={results}>
    <div class="slds-m-around_medium">
      <template for:each={results} for:item="result">
        <lightning-card key={result.result.fieldApiName} title={result.result.label}>
          <template for:each={result.result.displayColumns} for:item="col">
            <p key={col.fieldApiName}>{col.label}</p>
          </template>
        </lightning-card>
      </template>
    </div>
  </template>
</template>
```

```javascript
// wireGetRelatedListInfoBatch.js
import { LightningElement, wire } from "lwc";
import { getRelatedListInfoBatch } from "lightning/uiRelatedListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class WireGetRelatedListInfoBatch extends LightningElement {
  error;
  results;
  @wire(getRelatedListInfoBatch, {
    parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
    relatedListNames: ["Contacts", "Opportunities"],
  })
  listInfo({ error, data }) {
    if (data) {
      this.results = data.results;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.results = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=330e74d175799d503d0bba1e669815441641e2a268b3831af4244bf0e0e72d79 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-list-records.md -->

# `getRelatedListRecords`

Use this wire adapter to get `RelatedList` records. [Related lists](https://help.salesforce.com/s/articleView?id=xcloud.basics_understanding_related_lists_parent.htm) display details and links to records that are associated with a specific record. For example, an account can have related lists for contacts, cases, notes, or even files.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRelatedListRecords } from 'lightning/uiRelatedListApi';

export default class LdsGetRelatedListRecords extends LightningElement {
  @wire(getRelatedListRecords, {
    parentRecordId: '001RM000003UNu6YAG',
    relatedListId: 'Contacts',
    fields: ['Contact.Name','Contact.Id'],
    sortBy: ['Contact.Name']
  })
}
```

## User Interface API Resource

```html
POST /ui-api/related-list-records/${parentRecordId}/${relatedListId}
```

See [Get Related List Records with a Request Body](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_records_get.htm).

**tip:** The [/ui-api/related-list-info/\${parentObjectApiName}](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_object.htm) resource returns related lists for an object, including the `relatedListId` values.

## Parameters

| Parameter Name   | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Required?                                  |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `parentRecordId` | String   | The ID of the parent record that you want to get related lists for, like an Account ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `relatedListId`  | String   | The API name of a related list or child relationship, like `Contacts`, `Opportunities`, or `Cases`. To provide an API name of a related list custom object, use the `Custom_Objects__r` format, where `Custom_Objects` is the plural form of your custom object name, and `__r` is the related list suffix. For more information on retrieving all related lists for an object or custom object, see [`RelatedListDefinition`](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_relatedlistdefinition.htm). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`         | String[] | The API names of the related list’s column fields. To use a standard field on a custom object, use the `Custom_Object__c.FieldName` format. To use a custom field on a custom object, use the `Custom_Object__c.FieldName__c` format.                                                                                                                                                                                                                                                                                                                                  |                                            |
| `optionalFields` | String[] | The API names of additional fields in the related list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                            |
| `pageSize`       | Number   | The number of list records to return per page. The default value is 50. Enter a value between 1 and 1999.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                            |
| `sortBy`         | String[] | An array of field API names to sort the related list by. Accepts only one value per request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                            |
| `where`          | String   | The filter to apply to related list records. [Semi-joins and anti-joins filters](https://developer.salesforce.com/docs/platform/graphql/guide/filter-joins.html) are currently not supported. For example, passing in a query using `inq` results in a Malformed Join Input Object error.                                                                                                                                                                                                                                                                              |                                            |

## Returns

- `data`—[Related List Record Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_record_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches the related list records by parent ID and related list object, then iterates through the list of records.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListRecords.html -->
<template>
  <lightning-card title="wireGetRelatedListRecords">
    <template lwc:if={records}>
      <div class="slds-m-around_medium">
        <template for:each={records} for:item="rec">
          <p key={rec.fields.Id.value}>{rec.fields.Name.value}</p>
        </template>
      </div>
    </template>
  </lightning-card>
</template>
```

<!-- prettier-ignore -->
```javascript
// wireGetRelatedListRecords.js
import { LightningElement, wire } from 'lwc';
import { getRelatedListRecords } from 'lightning/uiRelatedListApi';
export default class WireGetRelatedListRecords extends LightningElement {
  error;
  records;
  @wire(getRelatedListRecords, {
    parentRecordId: '001RM000003UNu6YAG',
    relatedListId: 'Contacts',
    fields: ['Contact.Id', 'Contact.Name'],
    where: '{ Name: { like: "Bob%" }}',
  })
  listInfo({ error, data }) {
    if (data) {
      this.records = data.records;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.records = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=32de0a454f76b178e91511b5e1f6c902142aa462dc4cadad0ea817669ab4ac25 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-list-records-batch.md -->

# `getRelatedListRecordsBatch`

Use this wire adapter to get records for a batch of `RelatedLists`.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { getRelatedListRecordsBatch } from 'lightning/uiRelatedListApi';

export default class LdsGetRelatedListRecordsBatch extends LightningElement {
  @wire(getRelatedListRecordsBatch, {
    parentRecordId: '001RM000003UNu6YAG',
    relatedListParameters: [
      {
        relatedListId: 'Contacts',
        fields: ['Contact.Name','Contact.Id'],
        sortBy: ['Contact.Name']
      },
      {
        relatedListId: 'Opportunities',
        fields: ['Opportunity.Name', 'Opportunity.Amount'],
        sortBy: ['Opportunity.Amount'],
        where: "{ and: [{ Name: { like: \"ACME%\" }}] }"
      }
    ]
  })
}
```

## User Interface API Resource

```html
POST /ui-api/related-list-records/batch/${parentRecordId}
```

See [Get a Batch of Related List Records with a Request Body](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_records_batch_get.htm).

## Parameters

| Parameter Name          | Type   | Description                                                                             | Required?                                  |
| ----------------------- | ------ | --------------------------------------------------------------------------------------- | ------------------------------------------ |
| `parentRecordId`        | String | The ID of the parent record that you want to get related lists for, like an Account ID. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `relatedListParameters` | Object | An array of related list parameter collections.                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

`relatedListParameters` has several properties.

| `relatedListParameters` Property | Type     | Description                                                                                  | Required?                                  |
| -------------------------------- | -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `relatedListId`                  | String   | The API name of a related list object, like Contacts, Opportunities, or Cases.               | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `fields`                         | String[] | The API names of the related list’s column fields.                                           |                                            |
| `optionalFields`                 | String[] | The API names of additional fields in the related list.                                      |                                            |
| `pageSize`                       | Number   | The number of list records to return per page.                                               |                                            |
| `sortBy`                         | String[] | An array of field API names to sort the related list by. Accepts only one value per request. |                                            |
| `where`                          | String   | The filter to apply to related list records, in GraphQL syntax.                              |                                            |

## Returns

- `data`—[Simplified Batch Results](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_batch_results_simplified.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches a batch of related list records by parent ID and multiple related list objects, then iterates through the list of records.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListRecordsBatch.html -->
<template>
  <template for:each={results} for:item="result">
    <lightning-card
      key={result.result.listReference.relatedListId}
      title={result.result.listReference.relatedListId}>
      <template lwc:if={result.result.count}>
        <div class="slds-m-around_medium">
          <template for:each={result.result.records} for:item="rec">
            <p key={rec.fields.Name.value}>{rec.fields.Name.value}</p>
          </template>
        </div>
      </template>
    </lightning-card>
  </template>
</template>
```

```javascript
// wireGetRelatedListRecordsBatch.js
import { LightningElement, wire } from "lwc";
import { getRelatedListRecordsBatch } from "lightning/uiRelatedListApi";
export default class WireGetRelatedListRecordsBatch extends LightningElement {
  error;
  results;
  @wire(getRelatedListRecordsBatch, {
    parentRecordId: "001RM000003UNu6YAG",
    relatedListParameters: [
      {
        relatedListId: "Contacts",
        fields: ["Contact.Name", "Contact.Id"],
        sortBy: ["Contact.Name"],
      },
      {
        relatedListId: "Opportunities",
        fields: ["Opportunity.Name", "Opportunity.Amount"],
        sortBy: ["Opportunity.Amount"],
      },
    ],
  })
  listInfo({ error, data }) {
    if (data) {
      this.results = data.results;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.results = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=69834d399a0836c5857f5dbc2e80b9b39512be015f2c3e9994d5658eb5297e11 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-related-lists-info.md -->

# `getRelatedListsInfo`

Use this wire adapter to get the metadata for `RelatedLists` in an object’s default layout.

## Syntax

```javascript
import { LightningElement, api, wire, track } from 'lwc';
import { getRelatedListsInfo } from 'lightning/uiRelatedListApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';

export default class LdsGetRelatedListsInfo extends LightningElement {
  @wire(getRelatedListsInfo, {
    parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
    recordTypeId: '012000000000000AAA'// optional
  })
}
```

## User Interface API Resource

```html
GET /ui-api/related-list-info/${parentObjectApiName}
```

See [Get Related Lists Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_object.htm).

## Parameters

| Parameter Name        | Type   | Description                                                                              | Required?                                  |
| --------------------- | ------ | ---------------------------------------------------------------------------------------- | ------------------------------------------ |
| `parentObjectApiName` | String | The API name of a parent object that you want to get related lists for, like an Account. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recordTypeId`        | String | The ID of the parent record type.                                                        |                                            |

## Returns

- `data`—[Related List Summary Collection](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_summary_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This code example fetches the related lists info by API name of the parent object, then iterates through the related lists.

<!-- prettier-ignore -->
```html
<!-- wireGetRelatedListsInfo.html -->
<template>
  <lightning-card title="wireGetRelatedListsInfo">
    <template lwc:if={relatedLists}>
      <div class="slds-m-around_medium">
        <template for:each={relatedLists} for:item="relatedList">
          <p key={relatedList.label}>{relatedList.label}</p>
        </template>
      </div>
    </template>
  </lightning-card>
</template>
```

```javascript
// wireGetRelatedListsInfo.js
import { LightningElement, wire } from "lwc";
import { getRelatedListsInfo } from "lightning/uiRelatedListApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class WireGetRelatedListsInfo extends LightningElement {
  error;
  relatedLists;
  @wire(getRelatedListsInfo, {
    parentObjectApiName: ACCOUNT_OBJECT.objectApiName,
    recordTypeId: "012000000000000AAA", //optional
  })
  listInfo({ error, data }) {
    if (data) {
      this.relatedLists = data.relatedLists;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.relatedLists = undefined;
    }
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/reference-supported-objects.md)

<!-- document id=c141a14a2a4d331106acf3d78dcde086b473b45f46f7ebaf0352d60ca75d566e url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-replicated-dataset.md -->

# `getReplicatedDataset`

Retrieves a specific CRM Analytics replicated dataset by ID, also known as a connected object.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getReplicatedDataset } from "lightning/analyticsWaveApi";

export default class GetReplicatedDataset extends LightningElement {
  @api rdId; // or fetch the ID
  @wire(getReplicatedDataset, {
    id: "$rdId",
  })
  onGetReplicatedDataset({ data, error }) {
    if (error) {
      console.log("getReplicatedDataset($id) ERROR:", error);
    } else if (data) {
      console.log("getReplicatedDataset($id) RESPONSE:", data.replicatedDatasets);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/replicateddatasets/{id}
```

`getReplicatedDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id.htm).

## Parameters

| Parameter Name | Type   | Description                 | Required?                                  |
| -------------- | ------ | --------------------------- | ------------------------------------------ |
| `id`           | String | The ID of connected object. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Replicated Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_dataset.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=13557a04f099ce3837f3c5d2e05c9a747e74652da3e6b038795fd36df9ab0c70 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-replicated-datasets.md -->

# `getReplicatedDatasets`

Retrieves a collection of CRM Analytics replicated datasets, also known as connected objects.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getReplicatedDatasets } from "lightning/analyticsWaveApi";

export default class GetReplicatedDatasets extends LightningElement {
  @wire(getReplicatedDatasets, {
    category: "Output",
  })
  onGetReplicatedDatasets({ data, error }) {
    if (error) {
      console.log("getReplicatedDatasets ERROR:", error);
    } else if (data) {
      console.log("getReplicatedDatasets RESPONSE:", data.replicatedDatasets);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/replicateddatasets
```

`getReplicatedDatasets` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets.htm).

## Parameters

These parameters are optional.

| Parameter Name | Type    | Description                                                                                                                    |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `category`     | String  | Filters the collection to include only connected objects of the specified category. <ul><li>`Input`</li><li>`Output`</li></ul> |
| `connector`    | String  | Filters the collection to include only connected objects belonging to the specified CRM Analytics connector.                   |
| `includeLive`  | Boolean | Filters the collection to include live datasets. The default is `false`.                                                       |
| `q`            | String  | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token.                |
| `sourceObject` | String  | Filters the collection to include only connected objects belonging to the specified source object.                             |

## Returns

- `data`—[Replicated Dataset Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_dataset_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=a89de54e7a6878faedf6dae628fb27794f3623b385070d4c177516f3409703f5 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-replicated-fields.md -->

# `getReplicatedFields`

Retrieves a collection of fields belonging to a CRM Analytics replicated dataset, also known as a connected object.

## Syntax

```javascript
import { LightningElement, api wire } from 'lwc';
import { getReplicatedFields } from 'lightning/analyticsWaveApi';

export default class GetReplicatedFields extends LightningElement {
  @api rdId; // or fetch the ID of the replicated dataset
  @wire(getReplicatedFields, {
    id: '$rdId'
  })
  onGetReplicatedFields({data, error}) {
    if (error) {
      console.log('getReplicatedFields ERROR:', error);
    } else if (data) {
      console.log('getReplicatedFields RESPONSE:', data.fields);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/replicateddatasets/${id}/fields
```

`getReplicatedFields` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id_fields.htm).

## Parameters

| Parameter Name | Type   | Description                       | Required?                                  |
| -------------- | ------ | --------------------------------- | ------------------------------------------ |
| `id`           | String | The ID of the replicated dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Replicated Field Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_field_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=a562d70c38461f85aabe821c3c212a076650b71176d6fa230fdff2663083d08c url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-replicated-fields-adv-props.md -->

# `getReplicatedFieldsWithAdvancedProps`

Retrieves a collection of fields, using advanced filtering options, belonging to a CRM Analytics replicated dataset, also known as a connected object.

## Syntax

```javascript
import { getReplicatedFieldsWithAdvancedProps } from 'lightning/analyticsWaveApi';
getReplicatedFieldsWithAdvancedProps( {id: string, advancedProps: SourceObjectDataInput} ): Promise<ReplicatedFieldCollection>
```

## CRM Analytics API Resource

```html
POST /wave/replicateddatasets/${id}/fields
```

`getReplicatedFieldsWithAdvancedProps` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id_fields.htm).

## Parameters

| Parameter Name | Type   | Description                       | Required?                                  |
| -------------- | ------ | --------------------------------- | ------------------------------------------ |
| `id`           | String | The ID of the replicated dataset. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `sourceObjectParam` | Object | The SourceObjectDataInput providing the advanced properties for filtering | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Replicated Field Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_field_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

There are several ways to use `getReplicatedFieldsWithAdvancedProps`. For example, you can display a list of replicated datasets and the filtered fields for each replicated dataset.

This example adds a Get button to a page with replicated datasets. The page must contain form elements for the information required to filter the fields for the replicated dataset, like 
the advanced properties names and values, and a list of fields to filter. Filtering the fields for a replicated dataset displays a toast message using the 
`lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { getReplicatedFieldsWithAdvancedProps } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class GetReplicatedFieldsWithAdvancedProps extends LightningElement {
  @api rdId; // or fetch the ID of the replicated dataset
  sourceObjectData = {
    "advancedProperties" : [
      {"name": "filterProp1", value: "filterValue1"},
      {"name": "filterProp2", value: "filterValue2"}
    ]
    "sourceObjectFields" : [ "Field1", "Field2", "Field3" ]
  };

  get(event) {
    getReplicatedFieldsWithAdvancedProps({ id: this.rdId, sourceObjectData : this.sourceObjectData })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Success',
            message: 'Replicated dataset fields filtered',
            variant: 'success'
          })
        );
      })
      .catch(error => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Error filtering replicated dataset fields',
            message: error.body.message,
            variant: 'error'
          })
        );
      });
  }
}
```

This button calls the `getReplicatedFieldsWithAdvancedProps()` method.

```html
<template>
  <lightning-button
    label="Get Fields"
    icon-name="utility:play"
    icon-position="right"
    onclick={Get}
  ></lightning-button>
</template>
```

<!-- document id=bcb19ee0bad09432ccccff53e25a18a6ab1e925cf4f814bf19270646dba68475 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-schedule.md -->

# `getSchedule`

Retrieves a schedule for a CRM Analytics recipe, dataflow, or data sync.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getSchedule } from "lightning/analyticsWaveApi";

export default class GetSchedule extends LightningElement {
  @api id; // or fetch the ID
  @wire(getSchedule, {
    assetId: "$id",
  })
  onGetSchedule({ data, error }) {
    if (error) {
      console.log(`getSchedule(${id}) ERROR:`, error);
    } else if (data) {
      console.log(`getSchedule(${id}) RESPONSE:`, data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/asset/${assetId}/schedule
```

`getSchedule` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_schedule.htm).

## Parameters

| Parameter Name | Type   | Description                                   | Required?                                  |
| -------------- | ------ | --------------------------------------------- | ------------------------------------------ |
| `assetId`      | String | The ID of the dataflow, recipe, or data sync. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Schedule](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_schedule.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=3d106f13ace2c1b4b7e00bf2d445c81ac3741bd7033c5d4f5a705f2a2654d28c url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-security-coverage-dataset-version.md -->

# `getSecurityCoverageDatasetVersion`

Returns the security coverage, also known as sharing inheritance, for a particular dataset version. The source objects listed are local to the org. Objects from other orgs or other external sources aren’t returned.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getSecurityCoverageDatasetVersion } from "lightning/analyticsWaveApi";

export default class GetSecurityCoverageDatasetVersion extends LightningElement {
  @api dIDorAPI; // or fetch the id or developer name for the dataset object
  @api vId; // or fetch the version id
  @wire(getSecurityCoverageDatasetVersion, {
    datasetIdOrApiName: "$dIDorAPI",
    versionId: "$vId",
  })
  onGetSecurityCoverageDatasetVersion({ data, error }) {
    if (error) {
      console.log("getSecurityCoverageDatasetVersion(${dIDorAPI}) ERROR:", error);
    } else if (data) {
      console.log("getSecurityCoverageDatasetVersion(${dIDorAPI}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/security/coverage/objects/${objectApiName}/users/${userId}
```

`getSecurityCoverageDatasetVersion` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_security_coverage_dataset_version.htm).

## Parameters

| Parameter Name       | Type   | Description                         | Required?                                  |
| -------------------- | ------ | ----------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The API name of the dataset object. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `versionId`          | String | The ID of the dataset version.      | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Dataset Coverage](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_coverage.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=1b13f6e1068a01e4f72cc61162f5f550f6b752fe38141e5e4b9adc1127e21928 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-stories.md -->

# `getStories`

Retrieves a collection of Einstein Discovery stories.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getStories } from "lightning/analyticsSmartDataDiscoveryApi";

export default class GetStories extends LightningElement {
  @wire(getStories, {
    sourceType: ["AnalyticsDataset"],
  })
  onGetStories({ data, error }) {
    if (error) {
      console.log("getStories ERROR:", error);
    } else if (data) {
      console.log("getStories RESPONSE:", data.stories);
    }
  }
}
```

## Einstein Discovery API Resource

```html
GET /smartdatadiscovery/stories
```

`getStories` uses this [Einstein Discovery API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest_sdd.meta/bi_dev_guide_rest_sdd/bi_sdd_resources_stories.htm).

## Parameters

These parameters are optional.

| Parameter Name | Type     | Description                                                                                                                                                                                                                                                                                                             |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folderId`     | String   | Filters the collection to only contain stories for the specified CRM Analytics folder. The ID can be the requesting user's ID for stories in the user's private folder.                                                                                                                                                 |
| `inputId`      | String   | Filters the collection to only contain stories for the specified story input ID.                                                                                                                                                                                                                                        |
| `page`         | String   | Generated token that indicates the view of stories to be returned.                                                                                                                                                                                                                                                      |
| `pageSize`     | Number   | Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.                                                                                                                                                                                                                   |
| `q`            | String   | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string. If the user’s search query contains quotation marks or wildcards, those symbols are automatically removed from the query string in the URL along with any other special characters. |
| `scope`        | String   | Scope type to apply to the collection results.<ul><li>`CreatedByMe`</li><li>`SharedWithMe`</li></ul>                                                                                                                                                                                                                    |
| `sourceType`   | String   | Single source type to apply to the collection results. <ul><li>`AnalyticsDataset`</li><li>`LiveDataset`</li><li>`Report`</li></ul>                                                                                                                                                                                      |
| `sourceTypes`  | String[] | List of source type to apply to the collection results. <ul><li>`AnalyticsDataset`</li><li>`LiveDataset`</li><li>`Report`</li></ul>                                                                                                                                                                                     |

## Returns

- `data`—[Story Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest_sdd.meta/bi_dev_guide_rest_sdd/bi_sdd_responses_story_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)

<!-- document id=771ea9c5406f1366ccb2f226676c42d868bb39c8de7fa1d903e989a7471917cd url=/developer/current/en-us/lwc/lwc/guides/reference/paymentsservice/reference-lightning-paymentsservice-get.md -->

# getSupportedPaymentMethods()

Get a list of supported payment methods for the specified device and verify whether the device supports Tap-To-Pay.

## Syntax

```js
import { getPaymentsService } from 'lightning/mobileCapabilities';
getSupportedPaymentMethods(options:
GetSupportedPaymentsMethodsOptions): Promise<[String]>
```

## Parameters

- `countryIsoCode`–(Required) A text field that represents the currency ISO code.
- `merchantAccountId`—(Required) A text field that represents the ID of the Merchant Account object.
- `permissionRationaleText`–(Optional) A text field that’s presented to the user in case permission is missing (for example, location permission) and must be requested from the user. Defaults to a predefined text if it’s empty.

## Returns

A Promise object that resolves to an array of string values. The values are available payment methods supported for the specific running device (for example, `["TAP_TO_PAY"]`). If there’s an error, a rejected promise returns the error type of `PaymentsServiceFailure`.

## Usage

```js
myPaymentsService
  .getSupprtedPaymentMethods(options)
  .then((results) => {
    const supportedPayments = JSON.parse(JSON.stringify(results, undefined, 2));
    const msg = `Available Payment Methods: ${supportedPayments}`;
    console.log(msg);
  })
  .catch((error) => {
    const msg = `Failed to get supprted payment methods: ${JSON.stringify(
      error
    )}`;
    console.log(msg);
  });
```

<!-- document id=b48d0c62ea254db9a0681033b3f1e9e9f71e42047bd306fe62de15ac310f26e6 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-folder.md -->

# `getWaveFolder`

Retrieves a specific CRM Analytics app or folder.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveFolder } from "lightning/analyticsWaveApi";

export default class GetWaveFolder extends LightningElement {
  @api folderID; // or fetch the ID
  @wire(getWaveFolder, {
    folderId: "$folderID",
  })
  onGetWaveFolder({ data, error }) {
    if (error) {
      console.log("getWaveFolder(${folderId}) ERROR:", error);
    } else if (data) {
      console.log("getWaveFolder(${folderId}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/folders/${folderId}
```

`getWaveFolder` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders_id.htm).

## Parameters

These parameters are optional.

| Parameter Name             | Type   | Description                                                                                                                                                                |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disableMru`               | String | Indicates whether to update the MRU (`true`) or not (`false`). The default is `false`.                                                                                     |
| `mobileOnlyFeaturedAssets` | String | Filters the response to only return a folder which contain dashboards that are enabled for the CRM Analytics mobile app (`true`) or not (`false`). The default is `false`. |

## Returns

- `data`—[Wave Folder](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_folder.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=aa3266ca917103c0f449b2a691126ca5616a7e3bb6d593cee3e23824394b0c5c url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-folders.md -->

# `getWaveFolders`

Retrieves a collection of CRM Analytics apps or folders.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveFolders } from "lightning/analyticsWaveApi";

export default class GetWaveFolders extends LightningElement {
  @wire(getWaveFolders, {
    sort: "Name",
  })
  onGetWaveFolders({ data, error }) {
    if (error) {
      console.log("getWaveFolders ERROR:", error);
    } else if (data) {
      console.log("getWaveFolders RESPONSE:", data.folders);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/folders
```

`getWaveFolders` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders.htm).

## Parameters

These parameters are optional.

| Parameter Name             | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isPinned`                 | Boolean  | Filters the collection to include only folders that are pinned (`true`) or not (`false`). The default is `false`.                                                                                                                                                                                                                                                                                                                                       |
| `mobileOnlyFeaturedAssets` | Boolean  | Filters the collection to only contain folders that contain dashboards that are enabled for the CRM Analytics mobile app. The default is `false`.                                                                                                                                                                                                                                                                                                       |
| `page`                     | String   | Generated token that indicates the view of folders to be returned.                                                                                                                                                                                                                                                                                                                                                                                      |
| `pageSize`                 | Integer  | Number of items to be returned in a single page. Minimum is 1, maximum is 200, and the default is 25.                                                                                                                                                                                                                                                                                                                                                   |
| `q`                        | String   | Search terms. Individual terms are separated by spaces. A wildcard is automatically appended to the last token.                                                                                                                                                                                                                                                                                                                                         |
| `scope`                    | String   | Scope type to apply to the collection results. <ul><li>`CreatedByMe`</li><li>`Mru` (Most Recently Used)</li><li>`SharedWithMe`</li></ul>                                                                                                                                                                                                                                                                                                                |
| `sort`                     | String   | Sort order to apply to the collection results. <ul><li>`App`</li><li>`CreatedBy`</li><li>`CreatedById`</li><li>`CreatedDate`</li><li>`FolderName`</li><li>`LastModified`</li><li>`LastModifiedBy`</li><li>`LastModifiedById`</li><li>`Location`</li><li>`Mru` (Most Recently Used, last viewed date)</li><li>`Name`</li><li>`Outcome`</li><li>`Owner`</li><li>`RefreshDate`</li><li>`RunDate`</li><li>`Status`</li><li>`Title`</li><li>`Type`</li></ul> |
| `templateFilters`          | String[] | Filters the collection to include only folders that match the filter value. <ul><li>`AppsConstructedByTemplate`</li><li>`AppsWithInstallHistory`</li></ul>                                                                                                                                                                                                                                                                                              |
| `templateSourceId`         | String   | Filters the collection to include only folders that are created from a specific template source.                                                                                                                                                                                                                                                                                                                                                        |

## Returns

- `data`—[Wave Folder Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_folder_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=4f25936db6408ed840bf62a24a5ddd602946750187cf1f03cbe7ebb30b8faed4 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-template.md -->

# `getWaveTemplate`

Retrieves a CRM Analytics template.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveTemplate } from "lightning/analyticsWaveApi";

export default class GetWaveTemplate extends LightningElement {
  @api templateID; // or fetch the ID
  @wire(getWaveTemplate, {
    templateIdOrApiName: "$templateId",
  })
  onGetWaveTemplate({ data, error }) {
    if (error) {
      console.log("getWaveTemplate(${templateId}) ERROR:", error);
    } else if (data) {
      console.log("getWaveTemplate(${templateId}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/templates/${templateIdOrApiName}
```

`getWaveTemplate` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_templates_id.htm).

## Parameters

| Parameter Name        | Type   | Description                                                                                                                               | Required?                                  |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `templateIdOrApiName` | String | The ID or developer name of the template.                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `options`             | String | Template visibility options to apply to the collection results. <ul><li>`CreateApp`</li><li>`ManageableOnly`</li><li>`ViewOnly`</li></ul> |                                            |

## Returns

- `data`—[Template](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_template.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=6491298a1ca1dccb7b59b5574dab9479798bde719edaff98c373b262964bc041 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-template-config.md -->

# `getWaveTemplateConfig`

Retrieves the configuration for a CRM Analytics template.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveTemplateConfig } from "lightning/analyticsWaveApi";

export default class GetWaveTemplateConfig extends LightningElement {
  @api templateID; // or fetch the ID
  @wire(getWaveTemplateConfig, {
    templateIdOrApiName: "$templateId",
  })
  onGetWaveTemplateConfig({ data, error }) {
    if (error) {
      console.log("getWaveTemplateConfig(${templateId}) ERROR:", error);
    } else if (data) {
      console.log("getWaveTemplateConfig(${templateId}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/templates/${templateIdOrApiName}/configuration
```

`getWaveTemplateConfig` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_templates_configuration.htm).

## Parameters

| Parameter Name        | Type    | Description                                                                                                                                                  | Required?                                  |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `templateIdOrApiName` | String  | The ID or developer name of the template.                                                                                                                    | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `disableApex`         | Boolean | Indicates whether Apex integration hooks are disabled (`true`) or not (`false`).                                                                             |                                            |
| `options`             | String  | Filters the configuration by template visibility options. <ul><li>`CreateApp`</li><li>`ManageableOnly`</li><li>`OrgCanViewOnly`</li><li>`ViewOnly`</li></ul> |                                            |

## Returns

- `data`—[Template Configuration](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_template_configuration.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=79f1ae7c490adf1cdf69982ea3b22e4e991feeda6241cd9308ea3e70f7427883 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-template-release-notes.md -->

# `getWaveTemplateReleaseNotes`

Retrieves the release notes for a CRM Analytics template.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveTemplateReleaseNotes } from "lightning/analyticsWaveApi";

export default class GetWaveTemplateReleaseNotes extends LightningElement {
  @api templateID; // or fetch the ID
  @wire(getWaveTemplateReleaseNotes, {
    templateIdOrApiName: "$templateId",
  })
  onGetWaveTemplateReleaseNotes({ data, error }) {
    if (error) {
      console.log("getWaveTemplateReleaseNotes(${templateId}) ERROR:", error);
    } else if (data) {
      console.log("getWaveTemplateReleaseNotes(${templateId}) RESPONSE:", data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/templates/${templateIdOrApiName}/releasenotes
```

`getWaveTemplateReleaseNotes` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_templates_id_releasenotes.htm).

## Parameters

| Parameter Name        | Type   | Description                               | Required?                                  |
| --------------------- | ------ | ----------------------------------------- | ------------------------------------------ |
| `templateIdOrApiName` | String | The ID or developer name of the template. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Template Release Notes](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_template_release_notes.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=acc90275ae0c2788726b9727053143fc095092b1a651401e5986253d749438e8 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-wave-templates.md -->

# `getWaveTemplates`

Retrieves a collection of CRM Analytics templates.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { getWaveTemplates } from "lightning/analyticsWaveApi";

export default class GetWaveTemplates extends LightningElement {
  @wire(getWaveTemplates, {
    type: "App",
  })
  onGetWaveTemplates({ data, error }) {
    if (error) {
      console.log("getWaveTemplates ERROR:", error);
    } else if (data) {
      console.log("getWaveTemplates RESPONSE:", data.templates);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/templates
```

`getWaveTemplates` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_templates.htm).

## Parameters

These parameters are optional.

| Parameter Name | Type   | Description                                                                                                                                    |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `options`      | String | Template visibility options to apply to the collection results. <ul><li>`CreateApp`</li><li>`ManageableOnly`</li><li>`ViewOnly`</li></ul>      |
| `type`         | String | Template type to apply to the collection results. <ul><li>`App`</li><li>`Dashboard`</li><li>`Data`</li><li>`Embedded`</li><li>`Lens`</li></ul> |

## Returns

- `data`—[Template Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_template_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=2290666937aa0a00ca419eded63074d926bc91cafcbe2e13b5eff000900fec49 url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice-getweight.md -->

# `getWeight(options)`

Reads body-weight records from the device’s health store. If needed, presents a permissions prompt to the user to request access to health data first, and then returns the records that match the options you provide.

## Syntax

```javascript
import { getHealthService } from 'lightning/mobileCapabilities';
getWeight(options: GetWeightOptions|null): Promise<Array>
```

## Parameters

- `options`—A [`GetWeightOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md) object to filter the records by time range, limit the number of records, and set the unit for the returned values. Pass `null` to use the defaults.

## Returns

- A Promise object that resolves as an array of [`WeightRecord`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md) objects. If no records match, the array is empty.

- A rejected promise returns a [`HealthServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md) object containing details about the error.

## Usage

This function reads weight records from the device’s health store and returns them as an array.

```javascript
const options = {
  startTime: null,
  endTime: null,
  limit: 10,
  preferredUnit: 'kg'
};
myHealthService
  .getWeight(options)
  .then((results) => {
    this.weightRecords = results;
  })
  .catch((error) => {
    this.weightRecords = [];
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- When records are read, the result is returned via a fulfilled promise. Handle successful results in a `then` clause.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- If the user denies permission to read health data, the promise is rejected with a `HealthServiceFailure.code` value of `USER_DENIED_PERMISSION`.
- The device’s health store records weight without a unit. HealthService converts the returned values to the unit that you set in `preferredUnit`. If you don’t set a unit, HealthService returns values in kilograms.

**See Also**

- [HealthService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice_example.htm)
- [HealthService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md)
- [`writeWeight(record)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-writeweight.md)

<!-- document id=9101a78d42884de5365b11930f140928753d9d1bca30a9578861ada42e5f2ece url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-get-xmd.md -->

# `getXmd`

Retrieves a specific CRM Analytics extended metadata type (Xmd) for a version of a dataset.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { getXmd } from "lightning/analyticsWaveApi";

export default class GetXmd extends LightningElement {
  @api idOrApiName; // or fetch the ID or dev name
  @api vId; // or fetch the version ID
  type = "Main";
  @wire(getXmd, {
    datasetIdOrApiName: "$idOrApiName",
    versionId: "${vId}",
    xmdType: "${type}",
  })
  onGetXmd({ data, error }) {
    if (error) {
      console.log(`getXmd(${idOrApiName}, ${versionId}, ${xmdType}) ERROR:`, error);
    } else if (data) {
      console.log(`getXmd(${idOrApiName}, ${versionId}, ${xmdType}) RESPONSE:`, data);
    }
  }
}
```

## CRM Analytics API Resource

```html
GET /wave/datasets/${datasetIdOrApiName}/versions/${versionId}/xmds/${xmdType}
```

`getXmd` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_xmd_main.htm).

## Parameters

| Parameter Name       | Type   | Description                                                                            | Required?                                  |
| -------------------- | ------ | -------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The ID or developer name of the dataset.                                               | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `versionId`          | String | The ID of the dataset version.                                                         | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `xmdType`            | String | The xmd type. <ul><li>`Asset`</li><li>`Main`</li><li>`System`</li><li>`User`</li></ul> | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`—[Xmd](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_xmd.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

<!-- document id=56958673f5b3a98ad4a86de8243fc2c75f1057b34187a45b17895a82125ce5b7 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-wire.md -->

# `graphql`

Import `graphql` from `lightning/graphql`. This module supports newer GraphQL API features, such as optional fields, dynamic query construction, and mutations.

**note:** `lightning/graphql` doesn’t currently support Mobile Offline use cases. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md).

The GraphQL wire adapter manages your data using Lightning Data Service (LDS). You don’t need different wire adapters for each query defined in the GraphQL schema, unlike the other wire adapters. Instead, LDS provides a single wire adapter that accepts a GraphQL query document and a variables map.

The GraphQL wire adapter uses the [Salesforce GraphQL API schema](https://developer.salesforce.com/docs/platform/graphql/guide/), which enables you to use UI API enabled objects with the object-level security and field-level security of the current user. UI API supports the [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm) for pagination.

To explore the GraphQL API schema, we recommend reviewing the schema documentation via introspection using the [Altair GraphQL client](https://developer.salesforce.com/docs/platform/graphql/guide/get-started-graphql.html). The client provides a query editor that includes field auto-completion, enabling you to add fields easily for a given type on any Salesforce object. We recommend that you use this client to help you build your queries quickly and accurately.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/graphql";

export default class MyGQLQuery extends LightningElement {
  @wire(graphql, {
    query: gql`
      query AccountInfo {
        uiapi {
          query {
            Account(where: { Name: { like: "Account1" } }) {
              edges {
                node {
                  Name {
                    value
                    displayValue
                  }
                }
              }
            }
          }
        }
      }
    }`,
  })
  graphqlQueryResults(result) {
    const { data, errors, refresh } = result;
  }
}
```

## GraphQL API Resource

```html
POST /graphql
```

The GraphQL wire adapter uses this [GraphQL API resource](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=Graphql).

## Parameters

- `query`—(Required) Parsed GraphQL query. Parse the query using the `gql` JavaScript template literal function. `gql` parses the GraphQL query into a format that the wire adapter can use. `gql` isn’t reactive.
- `variables`—A key-value pair of dynamic values for the `gql` query. Use `variables` with a getter function so the wire adapter can react to changes.

  **note:** The value passed to variables must be a map that includes a value for every variable on the query that does not specify a default value.

- `operationName`—The name of the operation you want to perform in the query. Use `operationName` to select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with `query operationName` instead of using the shorthand syntax `query` for improved server-side debugging to identify different GraphQL requests. For example, `query bigAccounts` or `query serviceReports`.

## Returns

- `data`—[GraphQL API response](https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html)
- `errors`—[GraphQL API errors](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=type%3AGraphQLErrorRepresentation)
- `refresh`—Returns a promise. When the promise is resolved, the data in the wire is fresh. Store the `refresh` method and call it in an `async` function. For more information, see [Update Cached Query Results](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-refresh.html) in the _GraphQL API Developer Guide_.

**note:** To maintain compatibility with the [GraphQL response specification](https://graphql.org/learn/serving-over-http/#response), the GraphQL wire adapter uses `errors` instead of `error`, unlike other LWC wire adapters.

## Usage

To start using the wire adapter, import an identifier and provide a configuration for the properties on your component. Pass in your query using the `gql` function.

```javascript
// simpleAccounts.js
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/graphql";

export default class SimpleGQL extends LightningElement {
  results;
  errors;

  @wire(graphql, {
    query: gql`
      query AccountWithName {
        uiapi {
          query {
            Account(first: 10) {
              edges {
                node {
                  Id
                  Name {
                    value
                  }
                }
              }
            }
          }
        }
      }
    `,
  })
  graphqlQueryResult({ data, errors }) {
    if (data) {
      this.results = data.uiapi.query.Account.edges.map((edge) => edge.node);
    }
    this.errors = errors;
  }
}
```

This HTML template displays the first 10 account names returned by the query.

<!-- prettier-ignore -->
```html
<!-- simpleAccounts.html -->
<template>
  <div class="slds-var-m-horizontal_medium">
    <template lwc:if={results}>
      <template for:each={results} for:item="account">
        <div key={account.Id}>
          <lightning-card icon-name="standard:account">
            <h1 slot="title">{account.Name.value}</h1>
          </lightning-card>
        </div>
      </template>
    </template>
  </div>
</template>
```

To add reactivity, pass in your values to the `variables` parameter and create a getter for the return value.

The getter function enables the GraphQL wire adapter to be reactive to changes in `minAmount`.

The example declares the `Currency` type for the `$minAmount` variable. `Currency` refers to types in the [Salesforce GraphQL API schema](https://developer.salesforce.com/docs/platform/graphql/guide/). A `Currency` type is a raw value, for example, `1000`. In this case, you can’t pass in a value with formatting, like `1,000`. When a user selects a different amount, the `handleMinAmountChange` event handler updates the query.

```javascript
// accountsMinAmount.js
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/graphQLApi";

export default class AccountsGQL extends LightningElement {
  records;
  errors;

  minAmount = "50000000";

  minAmounts = [
    { label: "All", value: "0" },
    { label: "$5,000,000", value: "5000000" },
    { label: "$50,000,000", value: "50000000" },
    { label: "$500,000,000", value: "500000000" },
  ];

  @wire(graphql, {
    query: gql`
      query bigAccounts($minAmount: Currency) {
        uiapi {
          query {
            Account(where: { AnnualRevenue: { gte: $minAmount } }) {
              edges {
                node {
                  Id
                  Name {
                    value
                  }
                  AnnualRevenue {
                    displayValue
                  }
                }
              }
            }
          }
        }
      }
    }`,
    // Use a getter function (see get variables() below)
    // to make the variables reactive.
    variables: "$variables",

    // The operation name is optional
    // since the GraphQL query defines a single operation only.
    operationName: "bigAccounts",
  })
  graphqlQueryResult({ data, errors }) {
    if (data) {
      this.records = data.uiapi.query.Account.edges.map((edge) => edge.node);
    }
    this.errors = errors;
  }

  get variables() {
    return {
      minAmount: this.minAmount,
    };
  }

  handleMinAmountChange(event) {
    this.minAmount = event.detail.value;
  }
}
```

This HTML template enables you to select a minimum amount and displays the queried accounts.

<!-- prettier-ignore -->
```html
<!-- accountsMinAmount.html -->
<template>
  <div class="slds-var-m-horizontal_medium">
    <lightning-combobox
      name="minAmount"
      label="Amount"
      value={minAmount}
      placeholder="Select a minimum amount"
      options={minAmounts}
      onchange={handleMinAmountChange}
    >
    </lightning-combobox>

    <template lwc:if={records}>
      <template for:each={records} for:item="account">
        <div class="card-spacer" key={account.Id}>
          <lightning-card icon-name="standard:account">
            <h1 slot="title">{account.Name.value}</h1>
            {account.AnnualRevenue.displayValue}
          </lightning-card>
        </div>
      </template>
    </template>
  </div>
</template>
```

Many Salesforce fields map to a raw value and an object with `value`, `displayValue`, and `format` fields. We recommend that you review the schema documentation using the [Altair GraphQL client](https://developer.salesforce.com/docs/platform/graphql/guide/get-started-graphql.html).

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many GraphQL API examples. Look for components that start with `graphql`, such as [graphqlContacts](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/graphqlContacts).

## Known Limitations

If your GraphQL query fails prefetch in the Salesforce mobile app, Salesforce Field Service, or Mobile Offline, you must continue to use metaschema directives in your GraphQL query for referential integrity and priming functionality. See _Known Issue_: [GraphQL query fails prefetch with an "Unknown Field" warning](https://issues.salesforce.com/issue/a028c00000xGGwE/graphql-query-fails-prefetch-with-an-unknown-field-warning).

Additionally, the usage of fragments on custom objects and custom fields has known limitations. Currently, referential integrity breaks if the custom object or field gets renamed. Since a GraphQL query that uses fragments can be composed without the fragments, you can query the same data by replacing the fragments.

Let’s look at a query that contains a fragment. To maintain referential integrity, remove the fragment from the query.

```
query fragment {
  uiapi {
    query {
      warehouse__c {
        edges {
          node {
            ...CustomFragment
          }
        }
      }
    }
  }
}

fragment CustomFragment on warehouse__c {
  Id
  Name {
    value
  }
}
```

To use the query without a fragment, remove and replace the fragment like this.

```
query fragment {
  uiapi {
    query {
      warehouse__c {
        edges {
          node {
            Id
            Name {
              value
            }
          }
        }
      }
    }
  }
}
```

**note:** Some fields are not filterable using the `where` filter. To find out if a field is supported for filtering, see the [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm). For example, the [NewValue and OldValue fields](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_casehistory.htm) on the CaseHistory object don’t include "Filter" in the **Properties** section and aren’t supported for filtering. If you attempt to pass in an unsupported field to the `where` filter, you get a "Field 'FieldName' in type 'ObjectName' is undefined" error.

**See Also**

- [_GraphQL API Developer Guide_: Use GraphQL API with Lightning Web Components](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html)
- [_GraphQL API Developer Guide_: GraphQL Wire Adapter Limitations](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-limitations.html)
- [_Mobile and Offline Developer Guide_: Use Salesforce Features While Offline](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use.htm)

<!-- document id=8eca3c0466c80b52cbd0f33ccedb6c1acb5ad9954bcfe96bb79c1380c082ea0e url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql.md -->

# `graphql`

Import `graphql` from `lightning/uiGraphQLApi`. This module supports Mobile Offline use cases, but it doesn’t support newer features, such as optional fields and dynamic query construction.

**note:** `lightning/graphql` supersedes the `lightning/uiGraphQLApi` module. We recommend that you use `lightning/graphql` where possible. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md).

The GraphQL wire adapter manages your data using Lightning Data Service (LDS). You don’t need different wire adapters for each query defined in the GraphQL schema, unlike the other wire adapters. Instead, LDS provides a single wire adapter that accepts a GraphQL query document and a variables map.

The GraphQL wire adapter uses the [Salesforce GraphQL API schema](https://developer.salesforce.com/docs/platform/graphql/guide/), which enables you to use UI API enabled objects with the object-level security and field-level security of the current user. UI API supports the [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm) for pagination.

To explore the GraphQL API schema, we recommend reviewing the schema documentation via introspection using the [Altair GraphQL client](https://developer.salesforce.com/docs/platform/graphql/guide/get-started-graphql.html). The client provides a query editor that includes field auto-completion, enabling you to add fields easily for a given type on any Salesforce object. We recommend that you use this client to help you build your queries quickly and accurately.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/uiGraphQLApi";

export default class MyGQLQuery extends LightningElement {
  @wire(graphql, {
    query: gql`
      query AccountInfo {
        uiapi {
          query {
            Account(where: { Name: { like: "Account1" } }) {
              edges {
                node {
                  Name {
                    value
                    displayValue
                  }
                }
              }
            }
          }
        }
      }
    }`,
  })
  propertyOrFunction;
}
```

## GraphQL API Resource

```html
POST /graphql
```

The GraphQL wire adapter uses this [GraphQL API resource](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=Graphql).

## Parameters

- `query`—(Required) Parsed GraphQL query. Parse the query using the `gql` JavaScript template literal function. `gql` parses the GraphQL query into a format that the wire adapter can use. `gql` isn’t reactive.
- `variables`—A key-value pair of dynamic values for the `gql` query. Use `variables` with a getter function so the wire adapter can react to changes.

  **note:** The value passed to variables must be a map that includes a value for every variable on the query that does not specify a default value.

- `operationName`—The name of the operation you want to perform in the query. Use `operationName` to select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with `query operationName` instead of using the shorthand syntax `query` for improved server-side debugging to identify different GraphQL requests. For example, `query bigAccounts` or `query serviceReports`.

## Returns

- `data`—[GraphQL API response](https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html)
- `errors`—[GraphQL API errors](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=type%3AGraphQLErrorRepresentation)

**note:** To maintain compatibility with the [GraphQL response specification](https://graphql.org/learn/serving-over-http/#response), the GraphQL wire adapter uses `errors` instead of `error`, unlike other LWC wire adapters.

## Usage

To start using the wire adapter, import an identifier and provide a configuration for the properties on your component. Pass in your query using the `gql` function.

```javascript
// simpleAccounts.js
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/uiGraphQLApi";

export default class SimpleGQL extends LightningElement {
  results;
  errors;

  @wire(graphql, {
    query: gql`
      query AccountWithName {
        uiapi {
          query {
            Account(first: 10) {
              edges {
                node {
                  Id
                  Name {
                    value
                  }
                }
              }
            }
          }
        }
      }
    `,
  })
  graphqlQueryResult({ data, errors }) {
    if (data) {
      this.results = data.uiapi.query.Account.edges.map((edge) => edge.node);
    }
    this.errors = errors;
  }
}
```

This HTML template displays the first 10 account names returned by the query.

<!-- prettier-ignore -->
```html
<!-- simpleAccounts.html -->
<template>
  <div class="slds-var-m-horizontal_medium">
    <template lwc:if={results}>
      <template for:each={results} for:item="account">
        <div key={account.Id}>
          <lightning-card icon-name="standard:account">
            <h1 slot="title">{account.Name.value}</h1>
          </lightning-card>
        </div>
      </template>
    </template>
  </div>
</template>
```

To add reactivity, pass in your values to the `variables` parameter and create a getter for the return value.

The getter function enables the GraphQL wire adapter to be reactive to changes in `minAmount`.

The example declares the `Currency` type for the `$minAmount` variable. `Currency` refers to types in the [Salesforce GraphQL API schema](https://developer.salesforce.com/docs/platform/graphql/guide/). A `Currency` type is a raw value, for example, `1000`. In this case, you can’t pass in a value with formatting, like `1,000`. When a user selects a different amount, the `handleMinAmountChange` event handler updates the query.

```javascript
// accountsMinAmount.js
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/uiGraphQLApi";

export default class AccountsGQL extends LightningElement {
  records;
  errors;

  minAmount = "50000000";

  minAmounts = [
    { label: "All", value: "0" },
    { label: "$5,000,000", value: "5000000" },
    { label: "$50,000,000", value: "50000000" },
    { label: "$500,000,000", value: "500000000" },
  ];

  @wire(graphql, {
    query: gql`
      query bigAccounts($minAmount: Currency) {
        uiapi {
          query {
            Account(where: { AnnualRevenue: { gte: $minAmount } }) {
              edges {
                node {
                  Id
                  Name {
                    value
                  }
                  AnnualRevenue {
                    displayValue
                  }
                }
              }
            }
          }
        }
      }
    }`,
    // Use a getter function (see get variables() below)
    // to make the variables reactive.
    variables: "$variables",

    // The operation name is optional
    // since the GraphQL query defines a single operation only.
    operationName: "bigAccounts",
  })
  graphqlQueryResult({ data, errors }) {
    if (data) {
      this.records = data.uiapi.query.Account.edges.map((edge) => edge.node);
    }
    this.errors = errors;
  }

  get variables() {
    return {
      minAmount: this.minAmount,
    };
  }

  handleMinAmountChange(event) {
    this.minAmount = event.detail.value;
  }
}
```

This HTML template enables you to select a minimum amount and displays the queried accounts.

<!-- prettier-ignore -->
```html
<!-- accountsMinAmount.html -->
<template>
  <div class="slds-var-m-horizontal_medium">
    <lightning-combobox
      name="minAmount"
      label="Amount"
      value={minAmount}
      placeholder="Select a minimum amount"
      options={minAmounts}
      onchange={handleMinAmountChange}
    >
    </lightning-combobox>

    <template lwc:if={records}>
      <template for:each={records} for:item="account">
        <div class="card-spacer" key={account.Id}>
          <lightning-card icon-name="standard:account">
            <h1 slot="title">{account.Name.value}</h1>
            {account.AnnualRevenue.displayValue}
          </lightning-card>
        </div>
      </template>
    </template>
  </div>
</template>
```

Many Salesforce fields map to a raw value and an object with `value`, `displayValue`, and `format` fields. We recommend that you review the schema documentation using the [Altair GraphQL client](https://developer.salesforce.com/docs/platform/graphql/guide/get-started-graphql.html).

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many GraphQL API examples. Look for components that start with `graphql`, such as [graphqlContacts](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/graphqlContacts).

## Known Limitations

The `lightning/uiGraphQLApi` module doesn’t currently support these use cases. We recommend that you use the [`lightning/graphql` module](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.md) instead.

- Dynamic construction of GraphQL queries at runtime, such as referencing a fragment from another component
- String interpolation constructs using `${}`
- Using variables in [directives](https://graphql.org/learn/queries/#directives) such as `@skip` and `@include`

**note:** GraphQL API features can take several releases to be available in the wire adapter. See [GraphQL Wire Adapter Limitations](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-limitations.html).

If your GraphQL query fails prefetch in the Salesforce mobile app, Salesforce Field Service, or Mobile Offline, you must continue to use metaschema directives in your GraphQL query for referential integrity and priming functionality. See _Known Issue_: [GraphQL query fails prefetch with an "Unknown Field" warning](https://issues.salesforce.com/issue/a028c00000xGGwE/graphql-query-fails-prefetch-with-an-unknown-field-warning).

Additionally, the usage of fragments on custom objects and custom fields has known limitations. Currently, referential integrity breaks if the custom object or field gets renamed. Since a GraphQL query that uses fragments can be composed without the fragments, you can query the same data by replacing the fragments.

Let’s look at a query that contains a fragment. To maintain referential integrity, remove the fragment from the query.

```
query fragment {
  uiapi {
    query {
      warehouse__c {
        edges {
          node {
            ...CustomFragment
          }
        }
      }
    }
  }
}

fragment CustomFragment on warehouse__c {
  Id
  Name {
    value
  }
}
```

To use the query without a fragment, remove and replace the fragment like this.

```
query fragment {
  uiapi {
    query {
      warehouse__c {
        edges {
          node {
            Id
            Name {
              value
            }
          }
        }
      }
    }
  }
}
```

**note:** Some fields are not filterable using the `where` filter. To find out if a field is supported for filtering, see the [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm). For example, the [NewValue and OldValue fields](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_casehistory.htm) on the CaseHistory object don’t include "Filter" in the **Properties** section and aren’t supported for filtering. If you attempt to pass in an unsupported field to the `where` filter, you get a "Field 'FieldName' in type 'ObjectName' is undefined" error.

**See Also**

- [_GraphQL API Developer Guide_: Use GraphQL API with Lightning Web Components](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html)
- [_Mobile and Offline Developer Guide_: Use Salesforce Features While Offline](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use.htm)

<!-- document id=00d22c30c0232c6a56eb3f2b4d52ec81a411ac68c2ec2006d0f2b5cebdbf19d5 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-intro.md -->

# GraphQL API Wire Adapter

Fetch data using the GraphQL API wire adapter for LWC, which comes with client-side caching and data management capabilities.

`lightning/graphql` (v2) supersedes the `lightning/uiGraphQLApi` (v1) module. Here are several differences between the modules:

- `lightning/graphql` provides newer features, such as optional fields, dynamic query construction, and mutations.
- `lightning/graphql` enables you to trigger a refresh of the query results by calling the `refresh` method on the emitted data.
- `lightning/uiGraphQLApi` supports Mobile Offline use cases, but `lightning/graphql` doesn’t.
- `lightning/uiGraphQLApi` enables you to trigger a refresh of the query results by calling the `refreshGraphQL(result)` function.

**note:** The terms v2 and v1 are annotations that are used only in documentation to highlight the difference and recency of the modules.

## GraphQL API Wire Adapter Comparison

This table compares the GraphQL API wire adapters and the features they support.

| GraphQL API Wire Adapter Feature | `lightning/uiGraphQLApi` (v1)              | `lightning/graphql` (v2)                   |
| -------------------------------- | ------------------------------------------ | ------------------------------------------ |
| Mobile Offline                   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |                                            |
| Standard GraphQL API features    | ![Yes](https://developer.salesforce.com/media/checkmark.png) | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Optional fields                  |                                            | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Dynamic query construction       |                                            | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| Mutation operations              |                                            | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

For usage details, see these references.

- [`lightning/graphql`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-module.md)
- [`lightning/uiGraphQLApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-api.md)

**See Also**

- [_GraphQL API Developer Guide_: GraphQL Wire Adapter Best Practices](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-best.html)
- [_GraphQL API Developer Guide_: When to Use GraphQL Wire Adapter](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-when.html)
- [_GraphQL API Developer Guide_: GraphQL Wire Adapter Limitations](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-limitations.html)

<!-- document id=c7664192e97bb0912d3019f2b9046389966929503ccc91f40838ca2e5f49b141 url=/developer/current/en-us/lwc/utam/guide/java-guide.md -->

# Guide for Java Developers

This document explains how to configure the UTAM compiler, generate UTAM Java page objects, and use them in a UI test. Examples of tests and setup are available in the [Java recipes repo](https://github.com/salesforce/utam-java-recipes).

If you write mobile UI tests using Appium, see these [additional steps](#mobile-setup) to set up your environment.

## Compiler setup

**note:** We use Maven for page object generation as part of the build process. You can use an alternative tool rather than Maven if you prefer. We don't mandate a particular version of the Maven plugins. Use the plugin versions that work best for your setup.

There are two main phases in the generation of UTAM page objects:

1. Delete the previously generated page objects if they exist (cleanup phase)
2. Create new files with generated page objects (generation phase)

An example of a `pom.xml` file that's configured to first delete previously generated page objects and then generate new page objects can be found in the [Java recipes repo](https://github.com/salesforce/utam-java-recipes/blob/main/utam-preview/pom.xml).

### Prerequisites

We require Java version 11 or higher.

If you're using a Java version higher than version 11, follow these steps as a prerequisite for generating UTAM page objects:

1. In the directory containing your Maven `pom.xml` file, create a directory called `.mvn`.
2. In that directory, create a file called `jvm.config` with the following contents:

```
--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
```

This file is required for Java versions greater than 11 to generate UTAM page objects, but optional for version 11. Note carefully that to use previously
compiled UTAM page objects, this step is not required. An example of this directory and file can be
found in the [Java recipes repo](https://github.com/salesforce/utam-java-recipes/blob/main/utam-preview/pom.xml).

#### Cleanup phase

To remove the previously generated page objects, the example uses `maven-clean-plugin`. The plugin configuration defines which files need to be deleted relative to the project root.

```xml
          <filesets>
            <fileset>
              <directory>src/main/java/utam</directory>
              <includes>
                <include>**</include>
              </includes>
              <excludes>
                <exclude>**/utils/**/*.java</exclude>
              </excludes>
              <followSymlinks>false</followSymlinks>
            </fileset>
          </filesets>
```

**note:** Remember to remove both generated page objects and imperative utilities if you use them.

#### Generation phase

To run the compiler and generate new page objects, the example uses `exec-maven-plugin` with two mandatory arguments:

- `--config` points to the JSON file with the compiler configuration. The format of the configuration file is described in the next section.
- `--compilerRoot` points to the root folder for all paths in the configuration file.

The page object generation runner is implemented in the `utam.compiler.EntryPoint` class that's part of the `utam-compiler` package.

To configure the Java compiler, create a JSON configuration file and fill the **required** properties with appropriate settings for your project. Those properties don't have a default fallback value in Java. Enter values for those properties in the configuration file before running the compiler.

**tip:** We recommend `utam.config.json` as the name of the compiler configuration file.

#### Format of the compiler configuration JSON file

Here's an example of a valid configuration for the Java compiler.

```json
{
  "pageObjectsRootDir": "/src/main/resources/spec",
  "pageObjectsFileMask": "(.*)\\.utam\\.json$",
  "pageObjectsOutputDir": "/src/main/java",
  "resourcesOutputDir": "/src/main/resources",
  "unitTestsOutputDir": "/src/test/java",
  "unitTestsRunner": "junit",
  "namespaces": [],
  "version": null,
  "copyright": null,
  "module": null,
  "profiles": null,
  "lintingOutputFile": "utam-lint.sarif",
  "lint": null
}
```

This section lists all the options supported by the Java compiler. For each option, we describe its JSON type, its default value, if it's required or not, and what it does.

By default, generated Java page objects are in the `utam.pageobjects` Java package. You can override the default package name by setting the `namespaces` option.

In Java, you must pass a `--compilerRoot` runtime argument to the compiler to set the root directory for the compiler, against which all paths are resolved.

**`pageObjectsRootDir`**

- Type: `String`
- Default: none
- **Required**

The path to the root directory containing JSON page objects. The compiler looks recursively in the root directory for declarative JSON page objects and [extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md).

**`pageObjectsFilesMask`**

- Type: `String`
- Default: `"(.*)\\.utam\\.json$"`

The file mask pattern used by the compiler to find input JSON page objects. It tells the compiler where to find the source JSON page objects relative to the root directory. Declare the file mask as a regular expression.

**`pageObjectsOutputDir`**

- Type: `String`
- Default: none
- **Required**

The relative path from the root directory to the target directory for generated page objects. The
compiler generates compiled Java classes from the JSON page objects and puts them in the output directory.

**`resourcesOutputDir`**

- Type: `String`
- Default: none
- **Required**

The target folder for generated resources, such as profile configurations.

**`unitTestsOutputDir`**

- Type: `String`
- Default: none

The root folder where unit tests are generated.

**`unitTestsRunner`**

- Type: `"none" | "junit" | "testng"`
- Default: `"none"`

The type of unit test runner. Used to generate unit tests that target that specific runner.

**`namespaces`**

- Type: `List<Namespace>`
- Default: none

`namespaces` is a list of mappings between a folder in `pageObjectsRootDir` and the package name prefix for generated page objects. This option allows you to generate different Java packages for JSON page objects in different folders. By default, generated Java page objects are in the `utam.pageobjects` Java package.

A mapping consists of a `pathMatch` and a `typeMatch`.

- `pathMatch` is a matching pattern for a folder in `pageObjectsDirectory` to search for JSON page objects.

- `typeMatch` is a descriptor for the generated page object Java classes from the JSON page objects in `pathMatch`

Let's look at an example configuration file.

```json
{
  "pageObjectsRootDir": "/src/main/resources/spec",
  "pageObjectsFileMask": "(.*)\\.utam\\.json$",
  "pageObjectsOutputDir": "/src/main/java",
  "namespaces": [
    {
      "typeMatch": "utam-lightning",
      "pathMatch": ".*/lightning"
    },
    {
      "typeMatch": "utam-custom",
      "pathMatch": ".*/custom"
    }
  ]
}
```

A JSON page object in `/src/main/resources/spec/lightning/input.utam.json` generates a `utam.lightning.pageobjects.Input` Java page object.

A JSON page object in `/src/main/resources/spec/custom/input.utam.json` generates a `utam.custom.pageobjects.Input` Java page object.

**`version`**

- Type: `String`
- Default: the current date and time

Version is an optional string that is propagated as `@version` in the generated page object Javadoc.
For example, if the version is set:

```json
{
  "version": "Spring '22"
}
```

The generated Javadoc in the code is:

```java
/**
 * ...
 * @version Spring '22
 */
```

If the version isn't set, the current date and time is used:

```java
/**
 * ...
 * @version 2022-12-01 09:12:01
 */
```

**`copyright`**

- Type: `String[]`
- Default: none

An optional array of strings that is added at the top of the generated page object.
If the copyright is set:

```json
{
  "copyright": ["Copyright (c) 2022, salesforce.com, inc.", "All rights reserved."]
}
```

The generated Javadoc in the code is:

```java
/**
 * Copyright (c) 2022, salesforce.com, inc. All rights reserved.
 */
package pageobjects;

public interface MyPageObject extends PageObject {
  //....
}
```

**`module`**

- Type: `String`
- Default: none

The name of the module used to generate [injections config](#set-up-injection-config-for-interfaces). It's a mandatory configuration parameter if the UTAM compiler generates page objects for [interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**`profiles`**

- Type: array of objects
- Default: none

Used in injections config. See [interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**`lintingOutputFile`**

- Type: `String`
- Default: `utam-lint.sarif`

If [linting](https://developer.salesforce.com/docs/platform/utam/guide/linting.md) is enabled, the SARIF report is generated after compilation and written to this file.

**`lint`**

The object for the linting configuration. See [linting](https://developer.salesforce.com/docs/platform/utam/guide/linting.md).

**`interruptCompilerOnError`**

- Type: `boolean`
- Default: true

By default, the compiler interrupts execution if a compilation error occurs. If this parameter is set to `false`, the compiler continues to generate other page objects, combines all compilation errors into one report, and throws an error at the end. All the errors are added to the `utam.errors.txt` file and printed to the console.

## Test setup

After you generate UTAM page objects, you can create a UI test that uses the page objects. Before your test can interact with the UI, UTAM needs to have access to a driver and to certain configuration parameters.

For Java, configure WebDriver in code by first creating an instance of `UtamLoaderConfig`. Set all configuration parameters, such as [implicit and explicit timeouts](/docs/platform/utam/references/utam-grammar/explicit-waits.html#explicit-wait-timeout) on `UtamLoaderConfig`. Then, create an instance of `UtamLoader`, which is the object that can create UTAM page objects.

Add this code in a test class or in a super class or utility class that you can call from a test.

```java
import java.time.Duration;
import utam.core.framework.consumer.UtamLoader;
import utam.core.framework.consumer.UtamLoaderConfig;
import utam.core.framework.consumer.UtamLoaderConfigImpl;
import utam.core.framework.consumer.UtamLoaderImpl;
import utam.core.selenium.factory.WebDriverFactory;

// ...

  UtamLoaderConfig config = new UtamLoaderConfigImpl();
  // configure timeouts
  config.setImplicitTimeout(Duration.ofSeconds(0));
  config.setExplicitTimeout(Duration.ofSeconds(60));

  // webDriver is an instance of org.openqa.selenium.WebDriver
  UtamLoader loader = new UtamLoaderImpl(config, webDriver);
```

For an example using this configuration code, see the [utam-java-recipes](https://github.com/salesforce/utam-java-recipes/blob/main/utam-tests/src/test/java/utam/base/UtamWebTestBase.java) repo.

Now, a test can create UTAM page objects by calling the `UtamLoader.load()` method.

An instance of the WebDriver can be created in the same class as the configuration code or elsewhere. UTAM provides a utility that can create an instance of the driver. Here's an example for Chrome:

```java
import org.openqa.selenium.WebDriver;
import utam.core.driver.DriverType;
import utam.core.selenium.factory.WebDriverFactory;

// ...

  System.setProperty("webdriver.chrome.driver",  "my path to chromedriver here");
  WebDriver driver = WebDriverFactory.getWebDriver(DriverType.chrome);
```

## Set up injection config for interfaces

If your UI tests use [UTAM interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html), you need to set up [injection configs](/docs/platform/utam/references/utam-grammar/interfaces.html#interface-implementation-resolution-at-run-time).

### Find injection configs in consumed modules

Injection config is generated with page objects. It can be located:

- in the resources folder of your local generated page objects
  ![injection-java](https://developer.salesforce.com/docs/media/utam/injection-java.png)
- at the root of the artifact that you consume. Example for [Salesforce Page Objects](https://developer.salesforce.com/docs/platform/utam/guide/test-sf-applications.md):
  ![dependencies](https://developer.salesforce.com/docs/media/utam/dependencies.png)

### Add injection configs to UtamLoader

- Create a `utam.loader.json` JSON loader config file at the root of your test resources (usually `src/test/resources`).

- Add an `injectionConfigs` property with a list of all injection configuration files from the modules that your tests consume.

  To cover all consumed modules, our config should be:

  ```json
  {
    "injectionConfigs": [
      "vanilla-js-components/profile.config.json",
      "utam-salesforceapp-pageobjects.config.json",
      "ui-utam-pageobjects.config.json",
      "ui-spec.config.json",
      "base-components.config.json"
    ]
  }
  ```

- Pass the name of the file to the constructor of UtamLoaderConfig

  ```java
  config = new UtamLoaderConfigImpl("utam.loader.json");
  ```

### Set active profile

Setting the active profile affects which implementing class is picked. A common example is mobile tests, which need to set the current platform.

```java
config.setProfile(MobilePlatformType.fromDriver(driver));
```

After the profile is set, UtamLoader knows how to pick up the right implementation based on the dependency injections config `utam-salesforceapp-pageobjects.config.json`, which looks like this:

```json
{
  "platform": {
    "ios_tablet": [
      {
        "interface": "utam.pageObjects.auth.AddConn",
        "implementation": "utam.pageObjects.auth.AddConnIOSTabletImpl"
      }
    ]
  }
}
```

This particular config means that if the active profile is "ios_tablet", and `UtamLoader.load(AddConn.class)` is invoked, the loader should instantiate the `AddConnIOSTabletImpl` class.

## Mobile setup

To execute a test using a UTAM page object against a local simulator or emulator, the UTAM framework needs to know your local environment through system properties for Java or a wdio configuration file for JavaScript.

These properties are common for both iOS and Android platforms:

- the installation location for Appium package (appium)
- the installation location for NodeJS (nodejs)
- bundleID (app.bundleid)
- test device name (ios.device/android.device)
- test application package location (ios.app/android.app)

  ```java
  System.setProperty("nodejs", "/usr/local/bin/node");
  System.setProperty("appium", "/usr/local/lib/node_modules/appium/");
  System.setProperty("app.bundleid", "com.salesforce.chatter");
  ```

  - For iOS:

    ```java
    System.setProperty("ios.device", "iPhone 8 Plus");
    System.setProperty("ios.app", "<path to iOS test app>");
    ```

  - For Android:

    ```java
    System.setProperty("android.app", "<path to Android test app>");
    // initial activity (app.activity), Android only
    System.setProperty("app.activity", "com.salesforce.chatter.Chatter");
    ```

### Appium setup

For Java, a test must use `AppiumServerFactory` to start an Appium server and `WebDriverFactory` to start an Appium session using the Appium server.

```java
appiumService = AppiumServerFactory.getAppiumServer()

// For iOS:
driver = WebDriverFactory.getWebDriver(DriverType.ios, appiumService, desiredCapabilities);

// For Android:
driver = WebDriverFactory.getWebDriver(DriverType.android, appiumService, desiredCapabilities);
```

## Write UI tests

See examples in the [Java recipes repo](https://github.com/salesforce/utam-java-recipes).

## Code completion (IntelliSense) for UTAM JSON files

The JSON schema for UTAM page objects is available at [Schema Store](https://json.schemastore.org/utam-page-object.json).

Most source code editors or IDEs support code completion (IntelliSense) for `.utam.json` file extensions either automatically or through configuration.

### Example automatic schema mapping by IntelliJ IDEA

In IntelliJ IDEA, no configuration is needed and the IDE automatically identifies schema from [Schema Store](https://www.schemastore.org/json/) for `.utam.json` files as shown below.

![IntelliJ IDEA screenshot](https://developer.salesforce.com/docs/media/utam/intellij-automatic-schema.png)

### Example configuration for Eclipse

In Eclipse, add a catalog entry for the JSON schema.

![Eclipse JSON Schema configuration](https://developer.salesforce.com/docs/media/utam/eclipse-json-configuration.png)

<!-- document id=186145f1f1aaf0c6cebdcd509f43af21bf24a530f5f1af8f3433455934e6dbc1 url=/developer/current/en-us/lwc/utam/guide/js-guide.md -->

# Guide for JavaScript Developers

This document explains how to configure the UTAM compiler, generate UTAM JavaScript page objects and use them in a JavaScript or TypeScript UI test. Examples of tests and setup are available in the [JavaScript recipes repo](https://github.com/salesforce/utam-js-recipes).

## Compiler Setup

To configure the UTAM compiler, add a dependency for UTAM in your project. Optionally, create a JSON configuration file and declare the required options and the optional values for which the default values don't match your project structure.

### Project Dependencies for JavaScript

The `package.json` file configures the dependencies for a JavaScript project.

Add a development dependency for the UTAM compiler by running one of these commands:

- `yarn add utam --dev`
- `npm install utam --save-dev`

These commands are equivalent and add `utam` to the `devDependencies` property in `package.json`, where `x.y.z` represents the installed version and is the latest version by default.

```json
{
  "devDependencies": {
    "utam": "x.y.z"
  }
}
```

For a working example, see the [utam-js-recipes](https://github.com/salesforce/utam-js-recipes/blob/main/utam-preview/package.json) repo.

The `wdio-utam-service` dependency includes an adapter between UTAM page objects and the browser API that WebdriverIO provides. The dependency includes a transitive dependency on the UTAM compiler. If the project needs the UTAM compiler only, use the `"utam"` dependency instead.

Add a development dependency for `wdio-utam-service` by running one of these commands:

- `yarn add wdio-utam-service --dev`
- `npm install wdio-utam-service --save-dev`

Running one of these commands updates `devDependencies` to look like this:

```json
{
  "devDependencies": {
    "wdio-utam-service": "x.y.z"
  }
}
```

### Set Up Compile Step in package.json

This `package.json` file has a script that runs the `utam` compile CLI command. The `utam` CLI is installed locally in your project because you added it to the `devDependencies` in `package.json`. In this example, the compiler configuration file is `utam.config.json`.

```json
{
  "scripts": {
    "build": "yarn build:utam && yarn build:ts",
    "build:ts": "tsc -b tsconfig.json",
    "build:utam": "utam -c utam.config.json"
  }
}
```

The `build` script name is arbitrary. You could use another name, such as `compile`. Use the script name with `yarn` or `npm` to run the script. For example:

```bash
yarn build
or
npm run build
```

The `"build:ts"` option is needed only if you're using TypeScript.

### Compiler Configuration File

The compiler configuration file enables you to customize the [options](#configure-the-javascript-compiler) supported by the JavaScript compiler. We recommend `utam.config.json` as the name of the compiler configuration file. The file can have any name, as long as the name matches the value of the `-c` flag used with the `utam` CLI.

After you've added `utam` as a dependency, run the compiler using one of these approaches:

- Set up a script in `package.json`. If the script is called `build`, run `yarn build` or `npm run build`.
- Invoke the `utam` CLI. Use yarn: `yarn utam -c utam.config.json` or npx: `npx utam -c utam.config.json`. The `-c` flag points the compiler at the `utam.config.json` configuration file.

Some developers prefer to use a `utam.config.js` configuration file because it's easier to add comments to a JavaScript file compared to a JSON file. The compiler automatically looks for a `utam.config.js` configuration file at the project root. If you use `utam.config.js`, you don't need to use the `-c` flag.

### Configure the JavaScript Compiler

To configure the JavaScript compiler, you have two options:

1. Use the default convention, which is the easiest way to configure the compiler. It implies that your project structure adheres with some built-in assumptions; for example, where to find declarative page objects, and where to output compiled page objects. That's the recommended approach when starting a new project because you don't have to tweak the compiler configuration.
2. Explicitly declare compiler options to fit your project structure. Consider this option when you integrate UTAM with an existing project or when the default convention doesn't align with your project structure. It gives you more control at the expense of additional configuration time.

#### Option 1: JavaScript Compiler Default Convention

You don't have to explicitly declare any options for the JavaScript compiler because all options have default values. If your project
structure follows the default convention, the compiler works out of the box. In that case, set the `utam.config.json` compiler
configuration file to be an empty object, `{}`.

Here's an overview of all configuration options supported by the JavaScript compiler with their associated default values:

```json
{
  "pageObjectsRootDir": "./", // config file directory name
  "pageObjectsFileMask": ["**/__utam__/**/*.utam.json"],
  "extensionsFileMask": ["**/__utam__/**/*.utam.js"],
  "pageObjectsOutputDir": "pageObjects",
  "extensionsOutputDir": "utils",
  "moduleTarget": "commonjs",
  "skipCommonJs": false,
  "alias": {},
  "version": undefined,
  "copyright": undefined,
  "module": undefined,
  "profiles": undefined
}
```

Let's look at an example project that follows the default convention.

```
<packageRoot>
├── package.json
├── utam.config.json
└── src/
   └── modules/
      └── component1/
         └── __utam__/
            └── component1.utam.json
      ├── component2/
         └── __utam__/
            ├── component2.utam.json
            └── extension.utam.js
      ..
      └── componentN/
         └── __utam__/
            └── componentN.utam.json
```

This sample project structure follows the default convention. The `utam.config.json` compiler configuration file is
at the package root level and is a sibling to `package.json`. The declarative page objects are next to their associated components in `__utam__` subfolders.

The resulting project structure after compiling is:

```
<packageRoot>
├── package.json
├── utam.config.json
├── pageObjects/
   ├── component1.d.ts
   ├── component1.js
   ├── component1.mjs
   ..
   ├── componentN.d.ts
   ├── componentN.js
   └── componentN.mjs
├── src/
   └── modules/
      ├── component1/
         └── __utam__/
            └── component1.utam.json
      ├── component2/
         └── __utam__/
            ├── component2.utam.json
            └── extension.utam.js
      ..
      └── componentN/
         └── __utam__/
            └── componentN.utam.json
└── utils/
   ├── extension.js
   └── extension.mjs
```

By following the default convention, the compiler finds the declarative page objects and [extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md) and
generates their respective implementations in `pageObjects` and `utils` folders at the package root level.

#### Option 2: Explicitly Declare Compiler Options

Explicitly declare [compiler options](#configure-the-javascript-compiler) when the default convention doesn't align with your project structure.

There are multiple approaches to configure compiler options. We offer these different approaches to allow for different project structures and different developer preferences.

### Use a compiler configuration file

You can specify options in the compiler configuration file.

Use the `-c` flag of the `utam` CLI to point at the configuration file. In this example, we use `utam.config.json`.

```bash
utam -c utam.config.json
```

Use the `-p` flag of the `utam` CLI to point the compiler at multiple configuration files. Pass in a list of space-separated UTAM compiler configuration file paths. This approach is useful if you have a repo where you need different compiler configuration options in different subprojects. In most scenarios, the `-c` flag suffices and you don't need to use the `-p` flag.

```bash
utam -p 'path/to/project1/utam.config.json' 'path/to/project2/utam.config.json'
```

### Use a configuration object in package.json

Alternatively, you can specify options in a configuration object for the `utam` key in `package.json`. For example:

```json
{
  "devDependencies": {
    "utam": "x.y.z"
  },
  "utam": {
    "pageObjectsOutputDir": "pageObjectsJS",
    "extensionsOutputDir": "pageObjects/utils"
  }
}
```

As you can see, we offer multiple approaches to configure compiler options. With great flexibility comes the risk of over complicating your configuration. We recommend that you stick to one approach for each project for the sake of simplicity.

The compiler looks for configuration options in this order:

1. `utam` CLI with the `-c` or `-p` flags
2. Default `utam.config.js` configuration file
3. Configuration object in `package.json`

### JavaScript Compiler Options Reference

This section lists all the options supported by the JavaScript compiler. For each option, we describe its JSON type, its
default value, and what it does.

**`pageObjectsRootDir`**

- Type: `string`
- Default: `path.dirname(configFilePath)`

The relative path from the configuration file's directory that represents the root directory path. The compiler looks recursively in the root directory for declarative JSON page objects and [extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md). It's also the
directory in which the compiler generates compiled page objects and extensions.

Defaults to the configuration file's directory if not specified. For instance, if your `utam.config.json` configuration file is
at the package root (the same level as the `package.json` file), the page object root directory defaults to the package root directory.

**`pageObjectsFileMask`**

- Type: `string[]`
- Default: `["**/__utam__/**/*.utam.json"]`

The file mask pattern used by the compiler to find input JSON page objects. It tells the compiler
where to find the source JSON page objects relative to `pageObjectsRootDir`. Declare the file mask as a list of glob
patterns.

For example, if we want to search for input files inside the `src` directory only, set the `pageObjectsFileMask` as follows:

```json
{
  "pageObjectsFileMask": ["src/**/__utam__/**/*.utam.json"]
}
```

**`extensionsFileMask`**

- Type: `string[]`
- Default: `["**/__utam__/**/*.utam.js"]`

The file mask pattern used by the compiler to find input [extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md) (JavaScript ESM extensions). It works exactly as the `pageObjectsFileMask` option but for extensions rather than declarative page objects.

**`pageObjectsOutputDir`**

- Type: `string`
- Default: `"pageObjects"`

The relative path from the root directory to the target directory for generated page objects. That's where the
compiler generates compiled JavaScript modules from the JSON page objects.

**`extensionsOutputDir`**

- Type: `string`
- Default: `"utils"`

The relative path from the root directory to the target directory for generated [extensions](https://developer.salesforce.com/docs/platform/utam/guide/imperatives.md). That's where the
compiler copies and transpiles JavaScript extensions.

**`moduleTarget`**

- Type: `"module" | "commonjs"`
- Default: `"commonjs"`

The module system used for compiled page objects and extensions whose file extension is `.js`. Configure this option to match
your package's module system. If your package uses ES Modules, set this option to `"module"`. If your package uses CommonJS,
set this option to `"commonjs"` or use the default value.

This table illustrates the module format used for a generated file extension depending on the `moduleTarget`
value. CJS stands for "CommonJS" and ESM stands for "ES Modules."

| Page Objects file ext | commonjs | module |
| --------------------- | -------- | ------ |
| `*.js`                | CJS      | ESM    |
| `*.cjs`               |          | CJS ¹  |
| `*.mjs`               | ESM      |        |

**note:** ¹ The CJS file is only generated if `skipCommonJs` is set to `false`.

**`skipCommonJs`**

- Type: `boolean`
- Default: `false`

Toggle page objects and extensions transpilation from ES Modules to CommonJS. If set to `false` or missing,
the compiler transpiles ESM Page Objects and extensions to CJS. If set to `true`, the compiler doesn't
transpile ESM page objects and extensions and only generates ES Modules.

**note:** This option is only useful when `moduleTarget` is set to `module`

**`alias`**

- Type: `string | Record<string, string>`
- Default: `{}`

A collection of matching patterns and replacement values used to map `type` values to import paths for custom elements and extensions. An alias provides flexibility by enabling you to match a `type` value and replace it in the generated import path.

When you declare a custom element or extension in a declarative page object, the `type` property represents the path
used by the platform module resolver. By default, the `type` property value translates to the custom
element or extension module specifier.

Let's look at an example that illustrates how the compiler translates the `type` property value into an `import` path:

Let's declare a custom element in a JSON page object:

```json
// filename: myPageObject.utam.json
{
  "elements": [
    {
      "name": "myCustomElement",
      "selector": {
        "css": ".my-custom-element"
      },
      "type": "packageName/pageObjects/path/to/myCustomElement"
    }
  ]
}
```

The import statement for that element in the generated page object is:

```js
// filename: myPageObject.mjs
import _myCustomElement from "packageName/pageObjects/path/to/myCustomElement";
```

That built-in behavior ensures that the `type` property value has a specific semantic structure with three parts:

1. the first part represents the package name (required)
2. the path to the page object (optional)
3. the page object name (required)

Sometimes, that coupling between the `type` property value and the import path lacks flexibility.
For instance, you might want to use an internal import reference that's different from the package name published
on the public registry.

An alias decouples the 1-to-1 relationship between `type` and `import` paths. Let's look at how we can use aliases to
add a package scope in front of your custom element.

Define an alias in the compiler configuration file:

```json
// filename: utam.config.json
{
  "alias": {
    "packageName/*": "@scope/packageName/*"
  }
}
```

With this mapping, the compiler replaces all `type` values that contain `packageName` by `@scope/packageName`.
The generated import statement is:

```js
// filename: myPageObject.mjs
import _myCustomElement from "@scope/packageName/pageObjects/path/to/myCustomElement";
```

The `*` character is replaced by everything it matches in the `type` property value. Here, `*` matches `path/to/myCustomElement`
so `@scope/packageName/*` translates to `@scope/packageName/path/to/myCustomElement` in the import path.

**note:** The matching pattern is a simple string matching pattern that supports the `*` wildcard.

There are two ways to declare type aliases:

1. Inline in the compiler configuration file
2. Externally in another JSON file that is referenced in the compiler config file

To declare type aliases inline, set the `alias` property value to be an object:

```json
// filename: utam.config.json
{
  "alias": {}
}
```

Declare all aliases as key-value pairs where the keys represent matching patterns and the values represent replacement values.

```json
// filename: utam.config.json
{
  "alias": {
    // aliases are key-values of
    // type Matching Pattern: import Replacement Value
    "packageName/pageObjects/*": "@scope/packageName/pageObjects/*"
  }
}
```

To declare type aliases externally, create a JSON file that defines the aliases:

```json
// filename: utam-alias.config.json
{
  "packageName/pageObjects/*": "@scope/packageName/pageObjects/*"
}
```

Then set the `alias` property in the compiler configuration file to reference the aliases JSON config file:

```json
// filename: utam.config.json
{
  // assuming both config files are siblings
  "alias": "./utam-alias.config.json"
}
```

The JavaScript compiler automatically resolves the alias configuration path and loads the aliases.

**`version`**

- Type: `string`
- Default: the current date and time

Version is an optional string that is propagated as `@version` in the generated page object JSDoc.
For example, if version is set:

```json
{
  "version": "Spring '22"
}
```

The generated JSDoc in the code is:

```js
/**
 * ...
 * @version Spring '22
 */
export default class DescriptionClass extends _UtamBasePageObject {
```

If the version isn't set, the current date and time is used:

```js
/**
 * ...
 * @version 2022-12-01 09:12:01
 */
export default class DescriptionClass extends _UtamBasePageObject {
```

**`copyright`**

- Type: `string[]`
- Default: none

An optional array of strings that is added at the top of the generated page object.
If the copyright is set:

```json
{
  "copyright": ["Copyright (c) 2022, salesforce.com, inc.", "All rights reserved."]
}
```

The generated JSDoc in the code is:

```js
/**
 * Copyright (c) 2022, salesforce.com, inc.
 * All rights reserved.
 */
import { By as _By } from "@utam/core";

// ... class code
```

**`module`**

- Type: `String`
- Default: none

The name of the module used to generate [injections config](#set-up-injection-config-for-interfaces). It's a mandatory configuration parameter if the UTAM compiler generates page objects for [interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**`profiles`**

- Type: array of objects
- Default: none

Used in injections config. See [interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html).

**`interruptCompilerOnError`**

- Type: `boolean`
- Default: true

By default, the compiler interrupts execution if a compilation error occurs. If this parameter is set to `false`, the compiler continues to generate other page objects, combines all compilation errors into one report, and throws an error at the end. All the errors are added to the `utam.errors.txt` file and printed to the console.

## Test Setup

After you generate UTAM page objects, you can create a UI test that uses the page objects. Before your test can interact with the UI, UTAM needs to have access to a driver and to certain configuration parameters.

### UTAM and WebdriverIO Integration

This `package.json` file includes a dependency for [WebdriverIO](https://webdriver.io/docs/what-is-webdriverio), which is an automation framework for JavaScript apps.

```json
{
  "devDependencies": {
    "wdio-utam-service": "0.0.7"
  }
}
```

`wdio-utam-service` is an adapter between UTAM page objects and the browser API that WebdriverIO provides. The dependency includes a transitive dependency on the UTAM compiler.

### WDIO config and utam service

The `wdio.config.js` file configures WebdriverIO and requires `wdio-utam-service`. It's set in the root folder of the project.

We describe only the relevant parts of the wdio configuration. For the full configuration, see the [JavaScript recipes](https://github.com/salesforce/utam-js-recipes) repository.

For the complete list of WebdriverIO configuration properties, see [WebdriverIO's configuration page](https://webdriver.io/docs/configurationfile.html).

```js
const { UtamWdioService } = require('wdio-utam-service');
...
exports.config = {
    ...
    services: ['chromedriver', [UtamWdioService, {}]]
    ...
}
```

A driver instance is created by WebDriverIO. `UtamWdioService` wraps the driver instance and uses the configured timeouts. Now, you can create an instance of a UTAM page object in a test.

### Set Timeouts for JavaScript in WebDriverIO

The `wdio.config.js` file also configures the [timeouts](/docs/platform/utam/references/utam-grammar/explicit-waits.html#explicit-wait-timeout) and should be set depending on the speed of your testing environment.

```js
// This service creates an instance of UtamLoader from a WebDriverIO driver
const { UtamWdioService } = require("wdio-utam-service");
// ...

exports.config = {
  // ...
  // sets explicit timeout to 5 seconds
  waitforTimeout: 1000 * 5,
  // optional parameter that sets the polling interval for explicit waits
  waitforInterval: 200,
  // ....
  services: [
    // WebDriverIO doesn't allow setting an implicit timeout through config
    // so we set it via UtamWdioService parameters
    [UtamWdioService, { implicitTimeoutMsec: 0 }],
  ],
  // ...
};
```

`waitforTimeout` property sets the default timeout for all `waitFor*` basic actions and for explicit waits. This example sets the explicit wait timeout to 5 seconds.

The implicit wait timeout is set via `implicitTimeout` argument of the UTAM WDIO service and we recommend using 0 (which is also the default).

## Set up injection config for interfaces

If your UI tests use [UTAM interfaces](/docs/platform/utam/references/utam-grammar/interfaces.html), you must set up [injection configs](/docs/platform/utam/references/utam-grammar/interfaces.html#interface-implementation-resolution-at-run-time).

### Find injection configs in consumed modules

The injection config is generated with page objects. It can be:

- in the root folder of your local generated page objects
  ![injection-js](https://developer.salesforce.com/docs/media/utam/injection-js.png)
- or a file from a dependency package

### Add injection configs to UtamLoader

Add `injectionConfigs` to WebDriverIO config as a UtamWdioService parameter:

```js
{
    // ...
    services: [
        'chromedriver',
        [
            UtamWdioService,
            {
                implicitTimeout: 0,
                injectionConfigs: [
                       // load a dependency config from a dependency
                       'vanilla-js-components/profile.config.json',
                       // load a dependency config local to the project
                       path.join(__dirname, '../path/to/anotherProfile.config.json')
                ]
            }
        ]
    ],
    // ...
}
```

Each string in the `injectionConfigs` array should point to the actual JSON injection configuration file generated with page objects.

### Set active profile

Setting the active profile affects which implementing class is picked. A common example is mobile tests, which must set the current platform in UtamWdioService:

```js
// utam variable is instance of UtamLoader
utam.setProfile("platform", getMobilePlatformType(browser));
```

## Mobile setup

To execute a test using a UTAM page object against a local simulator or emulator, the UTAM framework needs to know your local environment through the wdio configuration file.

For iOS:

```js
exports.config = {
    ...baseMobileConfig,
    capabilities: [
        {
            ...
            'appium:deviceName': 'iPhone 12',
            'appium:app': '<path to iOS test app>',
            'appium:platformVersion': '15.2',
        },
    ]
};
```

For Android:

```js
exports.config = {
    ...baseMobileConfig,
    capabilities: [
        {
            ...
            'appium:deviceName': 'emulator-5554',
            'appium:app': '<path to Android test app>',
            'appium:appActivity': 'com.salesforce.chatter.Chatter',
            'appium:appPackage': 'com.salesforce.chatter',
        },
    ]
};
```

### Start Appium server

Start an Appium server locally before executing any test by running `appium --port 4444`.

## Write UI Tests

Before you start to write test code, clarify the use case for your test. Identify the DOM elements that your test needs to exercise and ensure that those elements are accessible in your page objects. Start small and iterate when you're creating your first test and page objects.

The [Write a Test tutorial](https://utam.dev/tutorial/write-tests) gives you a good introduction to test code for a Hello World example. The UI enables you to see the DOM, JSON page object, generated JavaScript code, test code, and a DOM tree viewer. The sidebar walks you through the moving parts.

Let's look at the test code in the [compose method tutorial](https://utam.dev/tutorial/compose-method).

```js
// Import a root page object
import LoginFormRoot from "tutorial/loginForm";

runPlaygroundTest(async () => {
  // Load the page object
  const loginFormRoot = await utam.load(LoginFormRoot);
  const usernameElement = await loginFormRoot.getUsername();
  const passwordElement = await loginFormRoot.getPassword();

  await loginFormRoot.login("utam@salesforce.com", "azerty123");

  assert.strictEqual(await usernameElement.getValue(), "utam@salesforce.com");
  assert.strictEqual(await passwordElement.getValue(), "azerty123");
});
```

**note:** The `runPlaygroundTest()` method is specific to the tutorial environment. For a more generic test, see [Sample Repo Using WebDriverIO](https://github.com/salesforce/utam-js-recipes/blob/main/wdio.conf.js).

Here are the basic steps you perform in test code.

### Import the root page object

Import a root page object using JavaScript module syntax. You can use any name to refer to the default export from the module. The tutorial code uses `LoginFormRoot`.

```js
import LoginFormRoot from "tutorial/loginForm";
```

**tip:** To load a page object directly from a UI test, the page object must declare `"root" : true` in its JSON page object file.

### Load a page object

This line loads the root page object.

```js
const loginFormRoot = await utam.load(LoginFormRoot);
```

The `utam.load()` method guarantees that by the time you load, the root element is available and present. If the page object can't be loaded, you get an error. UTAM always tries to fail as fast as possible if there's an error. The fast failure makes it easier to locate the line of code that's failing when you debug a test.

### Call page object methods

The page object exposes the `getUsername()`, `getPassword()`, and `login()` methods so you can call them in your test.

**tip:** Use a compose method instead of a public element in a page object where possible. A compose method provides better encapsulation of element structure and gives you better flexibility for page-object maintenance.

```js
const usernameElement = await loginFormRoot.getUsername();
const passwordElement = await loginFormRoot.getPassword();

await loginFormRoot.login("utam@salesforce.com", "azerty123");
```

The `getPassword()` method returns an element on the page. You can then call a [basic action](/docs/platform/utam/references/utam-grammar/basic-actions.html) on the element. The `getValue()` basic action returns the value of an `input` element's `value` property. For example:

```js
await passwordElement.getValue();
```

### Use assertions

Use assertions to ensure that your test returns expected results. Use any assertion library of choice, such as [Node.js assertions](https://nodejs.org/dist/latest-v14.x/docs/api/assert.html). For example:

```js
assert.strictEqual(await passwordElement.getValue(), "azerty123");
```

### Run tests

The process to run tests depends on your test automation framework and the programming language that you use. For an example, see [Sample Repo Using WebDriverIO](https://github.com/salesforce/utam-js-recipes/blob/main/wdio.conf.js).

We looked at the basic steps in a test. Now, let's see some other common actions in a test.

### Use Developer Tools and console.log()

If you're playing around with tutorial code, you can add a `debugger;` statement to invoke the Developer Tools debugger and step through your code. Call `console.log()` to output a message to the browser console and to the tutorial console.

### Wait until a condition is met

Write more durable tests by waiting for certain actions to complete and yield until the conditions are met. Use an [explicit wait](/docs/platform/utam/references/utam-grammar/explicit-waits.html) to wait for a condition to be ready for the test to proceed.

### Use Jasmine to structure tests

[Jasmine](https://jasmine.github.io/) is a behavior-driven development framework for testing JavaScript code. This repo uses a [WebdriverIO Jasmine plugin](https://www.npmjs.com/package/@wdio/jasmine-framework) that's an adapter for the Jasmine testing framework.

When you look at the test code in [utam-js-recipes repo](https://github.com/salesforce/utam-js-recipes), you see some standard Jasmine methods.

- [`describe()`](https://jasmine.github.io/api/edge/global.html#describe) creates a group of specs, also known as a suite.

- [`it()`](https://jasmine.github.io/api/edge/global.html#it) defines a single spec. A spec should contain one or more expectations that test the state of the code.

We don't have documentation yet for integrating with other test frameworks.

## Code completion (IntelliSense) for UTAM JSON files

The JSON schema for UTAM page objects is available at [Schema Store](https://json.schemastore.org/utam-page-object.json).

Most source code editors or IDEs support code completion (IntelliSense) for `.utam.json` file extensions either automatically or through configuration.

### Example configuration for Visual Studio Code

To configure IntelliSense for UTAM JSON files, add the following snippet to `.vscode/settings.json`.

```json
{
  "json.schemas": [
    {
      "fileMatch": ["*.utam.json"],
      "url": "https://json.schemastore.org/utam-page-object.json"
    }
  ]
}
```

<!-- document id=314ebf601a866b06e15799f97f1991579f94457b3734be7346e795cf123706f3 url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks-error.md -->

# Handle Component Errors

The `errorCallback()` hook is unique to Lightning Web Components. Implement it to create an error boundary component that captures errors in all the **descendent** components in its tree. Like a JavaScript `catch{}` block, `errorCallback()` captures errors that occur in lifecycle hooks or during an event handler declared in an HTML template. You can code the error boundary component to log stack information and render an alternative view to tell users what happened and what to do next.

::video{src="https://youtube.com/embed/_sdRQJuAeys" title="LWC Error Handling Best Practices" type="youtube" }

After you create an error boundary component, you can reuse it throughout an app. It’s up to you where to define those error boundaries. You can wrap the entire app, or every individual component. Most likely, your architecture falls somewhere in between. Think about where you’d like to tell users that something went wrong.

<!-- prettier-ignore -->
```html
<!-- boundary.html -->
<template>
  <template lwc:if={error}>
    <error-view error={error} info={stack}></error-view>
  </template>
  <template lwc:else>
    <healthy-view></healthy-view>
  </template>
</template>
```

The `error-view` component displays the error returned by `errorCallback()`. Otherwise, it displays the `healthy-view` component. By wrapping your component inside the boundary component, any unhandled errors are still caught by the boundary component and displayed by `error-view`. When an error is thrown, `healthy-view` is unmounted and removed from the DOM.

```javascript
// boundary.js
import { LightningElement } from "lwc";
export default class Boundary extends LightningElement {
  error;
  stack;
  errorCallback(error, stack) {
    this.error = error;
  }
}
```

**tip:** To access the host element, use `this`. To access elements in the component’s template, use `this.template`.

The `error` argument is a JavaScript native error object, and the `stack` argument is a string.

You don’t have to use `lwc:[if|elseif|else]` in a template. For example, let’s say you define a single component template. If this component throws an error, the framework calls `errorCallback` and unmounts the component during rerender, which removes the component from the DOM.

```html
<!-- boundary.html -->
<template>
  <my-one-and-only-view></my-one-and-only-view>
</template>
```

Errors from programmatically assigned event handlers are not caught by `errorCallback()`. If you provide an event handler on an element such as for a button's `onclick` event, `errorCallback()` is called when the component encounters an error. However, if you assign the handler to your element via JavaScript such as by using `addEventHandler`, `errorCallback()` isn't called when the component encounters an error.

**See Also**

- [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)

<!-- document id=a34eb9f1cef8416f5ae55cfde5df5d10854496212393a1147276e67c819baaf8 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-error-handling.md -->

# Handle Errors from Apex

Apex throws different exceptions like `DmlException` or `QueryException`. You can use these [Apex built-in exceptions](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_exception_methods.htm) or create a custom exception. You can also create and throw an `AuraHandledException` to handle the exception more gracefully in your JavaScript code. `AuraHandledException` is supported in LWC and Aura components.

When your Apex controller code encounters an error, you can use a try-catch block and handle the error in Apex. Otherwise, the error becomes unhandled and gets thrown directly to the client.

::video{src="https://youtube.com/embed/_sdRQJuAeys" title="LWC Error Handling Best Practices" type="youtube" }

## Return the Default Unhandled Exception

Handling Apex errors allow you to control the error details that are returned to the client. Consider this Apex method that uses a variable that returns null and throws an unhandled exception. Since we're not passing in the `str` parameter, `str` is null and `str.toUpperCase()` throws an exception.

```apex
//ErrorExamples.cls
public with sharing class ErrorExamples {

  @AuraEnabled(cacheable=true)
  public static String unhandled(String str) {
    return str.toUpperCase();
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many examples that demonstrate error handling when retrieving data from Apex. Look for components that start with `apex*`, such as [`apexImperativeMethod`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/apexImperativeMethod).

The error is returned directly from Apex and surfaces the `ErrorExamples` class name in the `body.stackTrace` property.

```json
{
  "status": 500,
  "body": {
    "exceptionType": "System.NullPointerException",
    "isUserDefinedException": false,
    "message": "Attempt to de-reference a null object",
    "stackTrace": "Class.ErrorExamples.unhandled: line 9, column 1"
  },
  "headers": {},
  "ok": false,
  "statusText": "Server Error",
  "errorType": "fetchResponse"
}
```

## Create a Custom Exception

You can throw and catch a custom exception using `AuraHandledException` or by defining a custom exception class that extends `Exception`.

### Throw a Custom `AuraHandledException` Error

The `AuraHandledException` returns a custom error message to a JavaScript controller on an Aura component. However, it's also supported on Lightning web components.

```apex
//ErrorExamples.cls
public with sharing class ErrorExamples {

  @AuraEnabled(cacheable=true)
  public static String auraException(String str) {
    try {
      return str.toUpperCase();
    } catch(Exception e) {
      throw new AuraHandledException('Something went wrong: ' + e.getMessage());
    }
  }
}
```

The error message includes your custom message and the one returned from Apex, which is available via `e.getMessage()`. But the error doesn't include the `body.stackTrace` property.

```json
{
  "status": 500,
  "body": { "message": "Something went wrong: Attempt to de-reference a null object" },
  "headers": {},
  "ok": false,
  "statusText": "Server Error",
  "errorType": "fetchResponse"
}
```

### Throw a Custom `MyException` Error

You can throw your own exception and pass in your own message, for example, using `MyException`. See [Create Custom Exceptions](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_exception_custom.htm).

```apex
//ErrorExamples.cls
public with sharing class ErrorExamples {

  @AuraEnabled(cacheable=true)
  public static String custom(String str) {
    try {
      return str.toUpperCase();
    } catch(Exception e) {
      throw new MyException('Something went wrong: ' + e);
    }
  }

  public class MyException extends Exception {}
}
```

The error message includes the line number and Apex class name that triggered the exception.

```json
{
  "status": 500,
  "body": {
    "exceptionType": "ErrorExamples.MyException",
    "isUserDefinedException": true,
    "message": "Something went wrong: ",
    "stackTrace": "Class.ErrorExamples.custom: line 26, column 1\nCaused by\nClass.ErrorExamples.custom: line 24, column 1"
  },
  "headers": {},
  "ok": false,
  "statusText": "Server Error",
  "errorType": "fetchResponse"
}
```

## Suppress Exceptions for Null Values

In some cases, you can choose to handle errors on the server and not return an exception to the client at all. For example, if you encounter an exception from a third-party call, you can handle the exception in Apex and not forward the error to the client.

This example uses the [safe navigation operator](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/langCon_apex_SafeNavigationOperator.htm) to return the upper case of a given string only when the `str` variable is not null, or return null otherwise.

```apex
@AuraEnabled(cacheable=true)
public static String noException(String str) {
  return str?.toUpperCase();
}
```

## Return a Custom Error Object

All the previous examples return an error using a string. To return a custom error object instead, create a wrapper class that defines the variables you want to include.

The error includes the variables you defined in the wrapper class.

```json
{
  "status": 500,
  "body": {
    "exceptionType": "AccountController.MyException",
    "isUserDefinedException": true,
    "message": "{\"severity\":\"LOW\",\"errorMessage\":\"Attempt to de-reference a null object\"}",
    "stackTrace": "Class.AccountController.customErrorWrapper: line 38, column 1"
  },
  "headers": {},
  "ok": false,
  "statusText": "Server Error",
  "errorType": "fetchResponse"
}
```

Using a wrapper class to define your error structure can be helpful when you work with a team that needs to standardize their Apex errors.

## Apex Error Handling Considerations

When handling Apex errors, make sure the `catch` block considers different Apex exceptions. For example, handle `DmlException` and `QueryException` errors if you're working with DML and SOQL statements.

```apex
try {
   ...
} catch(QueryException e){
   ...
} catch(DMLException e){
   ...
} catch(Exception e){
   ...
}
```

Consider these additional guidelines.

- Split your code into different modules if you expect to handle multiple use cases. Don't place all code inside the `try` block.
- If errors from different blocks must be handled in different ways, use multiple try-catch blocks.
- Handle only the errors you expect to see in the `catch` block. The rest should be propagated further.

**See Also**

- [_Apex Developer Guide_: Exception Statements](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_exception_statements.htm)
- [_Apex Reference Guide_: Exception Class and Built-In Exceptions](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_exception_methods.htm)
- [_Lightning Aura Components Developer Guide_: Returning Errors from an Apex Server-Side Controller](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/controllers_server_apex_custom_errors.htm)

<!-- document id=1ece63eb81523d617b7fbf2405dd30e54ae9cddd33aef56af6244ff4804da1b9 url=/developer/current/en-us/lwc/lwc/guides/data/data-error.md -->

# Handle Errors in Lightning Data Service

Lightning Data Service (LDS) wire adapters return an error when a resource, such as a record or an object, is inaccessible on the server.

For example, an error occurs if you pass in an invalid input to the wire adapter, such as an invalid record Id or missing required fields. An error is also returned if the record isn’t in the cache and the server is offline. Also, a resource can become inaccessible on the server when it’s deleted or has its sharing or visibility settings updated.

::video{src="https://youtube.com/embed/_sdRQJuAeys" title="LWC Error Handling Best Practices" type="youtube" }

## Errors in Asynchronous JavaScript

Using the LDS wire adapters means you are working with [asynchronous JavaScript](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous), which is similar to promises. To handle errors, you typically use a [try-catch block](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch). However, the try-catch block can handle exceptions in synchronous code only. So only errors within a single transaction are caught by a try-catch block.

Consider this asynchronous code.

```javascript
connectedCallback() {
  try {
    console.log("first");
    setTimeout(() => {
      throw new Error("some error");
      console.log("second");
    }, 1000);
  } catch (e) {
    console.log(e);
  }
  console.log("third");
}
```

The code prints `first`, then runs `setTimeOut()`, and prints `third` in a single transaction. The callback function is called 1 second later, as specified by the timeout delay. However, `second` isn't printed since it's not part of the first transaction.

To ensure that your error in asynchronous code is handled correctly in a try-catch block, use the try-catch block inside the callback function.

```javascript
connectedCallback() {
  console.log("first");
  setTimeout(() => {
    try {
      throw new Error("some error");
      console.log("second");
    } catch(e) {
      console.log("error");
    }
  }, 1000);
  console.log("third");
}
```

The code prints `first`, then runs `setTimeOut()`, and prints `third` in a single transaction. When the callback is called 1 second later, the try-catch block handles the error and prints `error` correctly.

## Errors in LDS Wire Adapters

When you specify the `@wire` decorator and make a call out to a wire service, the wire service calls the wire adapter to fetch the data. The wire adapter fetches the data either from Salesforce servers or the LDS cache, if it's available. The wire adapter then returns the data back to the service, which provisions the data back to your component.

**note:** We say "provisions" instead of "requests" or "fetches" because a network request isn't involved if the data exists in the client cache.

The response may throw an error during or after value provisioning. For example, the wire adapter tries to fetch the data from your Apex method and the Apex method throws an exception. This exception can occur because of a number of reasons, such as if you don't parse a required parameter or if there's an issue fetching from the cache.

If the value provisioning is successful, you can also encounter an error while handling the response on your component.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many wire service examples. Look for components that start with `lds*`, such as [ldsCreateRecord](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/ldsCreateRecord), or components that start with `apex*`, such as [apexImperativeMethod](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/apexImperativeMethod).

When you wire a method to a function or a property, the `error` property stores the error during value provisioning. We recommend that you include the `else if` block to handle errors on your wire functions. Wire a method to a function with error handling like this.

```javascript

@wire(getApexMethod)
wiredContacts({ error, data }) {
  if (data) {
    try {
      // handle result
    } catch(e) {
      // error when handling result
    }
  } else if (error) {
    // error with value provisioning
  }
}
```

If you wire a method to a property instead, you can handle the error by checking the `yourPropertyName.error` value.

**note:** You must use the `data` and `error` properties as they are hardcoded values in the API. See [Wire Service Syntax](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about.md#wire-service-syntax).

## Error Response

The `FetchResponse` error object is modeled after the Fetch API’s Response object. It contains the body of the response and a status code and message.

Here's an example error response when you provide an incorrect recordId for an object.

```json
{
  "status": 400,
  "body": {
    "message": "The \"fields\" query string parameter contained object api names that do not correspond to the api names of any of the requested record ids. The requested object api names were: [Account], while the requested records had object types: [Contact]",
    "statusCode": 400,
    "errorCode": "INVALID_INPUT"
  },
  "headers": {},
  "ok": false,
  "statusText": "Bad Request",
  "errorType": "fetchResponse"
}
```

## Error Properties

The error response includes these properties.

- `body` (Object or Array)—The body of the response, which is defined by the underlying API.
- `ok` (Boolean)—Specifies whether the response was successful or not. For an error, `ok` is always `false` and contains a status in the range 400–599.
- `status` (Number)—Contains the status code of the response, for example, 404 if a resource is not found or 500 for an internal server error.
- `statusText` (String)—Contains the status message corresponding to the status code, for example, `NOT_FOUND` for a status code of 404.

## Example: Handle Errors from the `getRecord` Wire Adapter

To handle errors returned by the `getRecord` wire adapter, you can display the error in your HTML template or handle them in JavaScript only. This example displays the error to users.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="Handle Error" icon-name="standard:contact">
    <template lwc:if={error}>
      <p>{error}</p>
    </template>
  </lightning-card>
</template>
```

The JavaScript code checks if the error body is an array or object and returns the error message.

```javascript
import { LightningElement, api, wire, track } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

const fields = [
  // This invalid field causes @wire(getRecord) to return an error
  "Contact.invalidField",
];

export default class WireGetRecordDynamicContact extends LightningElement {
  @api recordId;

  @track error;

  @wire(getRecord, { recordId: "$recordId", fields })
  wiredRecord({ error, data }) {
    if (error) {
      this.error = "Unknown error";
      if (Array.isArray(error.body)) {
        this.error = error.body.map((e) => e.message).join(", ");
      } else if (typeof error.body.message === "string") {
        this.error = error.body.message;
      }
      this.record = undefined;
    } else if (data) {
      // Process record data
    }
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an [`ldsUtils`](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/ldsUtils/ldsUtils.js) example that reduces one or more LDS errors into a string array of error messages.

## Body Payload

The body of the error response depends on the API that returns it.

- UI API read operations, such as the `getRecord` wire adapter, return `error.body` as an array of objects.
- UI API write operations, such as the `createRecord` wire adapter, return `error.body` as an object, often with object-level and field-level errors.
- Apex read and write operations return `error.body` as an object.
- Network errors, such as an offline error, return `error.body` as an object.

**note:** Before the wire fires for the first time, both data and error are undefined. The wire isn't in an error state, it just hasn't fired yet. See [Wire Service Syntax](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about.md#wire-service-syntax).

**See Also**

- [_User Interface API Developer Guide_: Error Message](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_error_message.htm)
- [_User Interface API Developer Guide_: Status Codes and Error Responses](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_errors.htm)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about.md)
- [Debug Wire Adapters](https://developer.salesforce.com/docs/platform/lwc/debug/debug-wire.md)

<!-- document id=f36de0da059abebaea9fe9890a1ce43ee98497c2c3aef33018944f5d00158ad2 url=/developer/current/en-us/lwc/lwc/guides/events/events-handling.md -->

# Handle Events

After you [create and dispatch a custom event](https://developer.salesforce.com/docs/platform/lwc/guide/events-create-dispatch.md), you can listen to the event in two ways:

- Attach the event listener declaratively from the component’s HTML template
- Attach the event listener declaratively and dynamically
- Attach the event listener imperatively using JavaScript

It’s better to listen from the HTML template since it reduces the amount of code you have to write. To handle events, define methods in the component’s JavaScript class.

## Attach an Event Listener Declaratively

Declare the listener in markup in the template of the owner component, in this example, `c-parent`.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <c-child onnotification={handleNotification}></c-child>
</template>
```

Define the handler function, in this example `handleNotification`, in the `c-parent` JavaScript file.

```javascript
// parent.js
import { LightningElement } from "lwc";
export default class Parent extends LightningElement {
  handleNotification() {
    // Code runs when event is received
  }
}
```

## Attach Multiple Event Listeners Declaratively

To declaratively attach multiple event listeners, use the `lwc:on` directive. Also, use this directive if you want to add event listeners whose event types are computed dynamically, for example, when passed from the owner component via `@api`.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button lwc:on={eventHandlers} label="Click me"></lightning-button>
</template>
```

Pass an object to `lwc:on` where each property key in the object specifies an event type, and the corresponding property's value is the event handler function. Property keys must be a string, such as `click`, `customEvent`, or `'custom-event'`.

```javascript
import { LightningElement } from "lwc";

export default class EventHandlerExample extends LightningElement {
  eventHandlers = {
    click: this.handleClick,
    mouseover: this.handleMouseOver,
  };

  handleClick(event) {
    console.log("Button clicked");
  }

  handleMouseOver(event) {
    console.log("Mouse over button");
  }
}
```

An event handler that's added using `lwc:on` is bound to the component instance; `this` inside the handler refers to the component, allowing access to its properties and methods.

## Attach Event Listeners Declaratively and Dynamically

To dynamically add event listeners on a child component, define an object with event types and handlers in the owner component's JavaScript file. Then, use the `lwc:on` directive in the owner component's template to bind these handlers to the child component.

<!-- prettier-ignore -->
```html
<!-- eventDynamic -->
<template>
  <c-event-dynamic-child lwc:on={eventHandlers}></c-event-dynamic-child>
  <p>Custom event received: {customEventDetail}</p>
  <lightning-button onclick={switchEventListener} label="Switch Event Listener">
  </lightning-button>
</template>
```

The `eventDynamic` component dynamically switches between two event listeners for `customEvent` and `anotherCustomEvent`. To toggle the message between the event listeners, click the **Switch Event Listener** button and then click the **Update Message** button.

```javascript
// eventDynamic.js
import { LightningElement } from "lwc";

export default class EventDynamic extends LightningElement {
  customEventDetail = "";
  eventHandlers = {
    customEvent: this.handleCustomEvent,
  };

  handleCustomEvent(event) {
    this.customEventDetail = `${event.detail}`;
  }

  switchEventListener() {
    this.eventHandlers = this.eventHandlers.customEvent
      ? { anotherCustomEvent: this.handleCustomEvent }
      : { customEvent: this.handleCustomEvent };
  }
}
```

The `eventDynamicChild` component contains a button that dispatches the custom events.

<!-- prettier-ignore -->
```html
<!-- eventDynamicChild -->
<template>
  <div>Child Component</div>
  <lightning-button onclick={handleButtonClick} label="Update Message"> </lightning-button>
</template>
```

The `eventDynamicChild` component dispatches two custom events, `customEvent` and `anotherCustomEvent`, when it's connected to the DOM and when the button is clicked. The `eventDynamic` component attaches the event listeners using `lwc:on`.

```javascript
// eventDynamicChild.js
import { LightningElement } from "lwc";

export default class EventDynamicChild extends LightningElement {
  connectedCallback() {
    // Dispatch a custom event when this component is connected
    this.dispatchEvent(
      new CustomEvent("customEvent", {
        detail: "customEvent from child component connectedCallback",
      }),
    );
    this.dispatchEvent(
      new CustomEvent("anotherCustomEvent", {
        detail: "anotherCustomEvent from child component connectedCallback",
      }),
    );
  }

  handleButtonClick() {
    this.dispatchEvent(
      new CustomEvent("customEvent", {
        detail: "Button clicked in child component for customEvent",
      }),
    );
    this.dispatchEvent(
      new CustomEvent("anotherCustomEvent", {
        detail: "Button clicked in child component for anotherCustomEvent",
      }),
    );
  }
}
```

For more information, see [Dynamic Event Listeners Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/events-dynamic-considerations.md).

## Attach an Event Listener Imperatively

Define both the listener and the handler function in the `c-parent` JavaScript.

```javascript
// parent.js
import { LightningElement } from "lwc";
export default class Parent extends LightningElement {
  constructor() {
    super();
    this.template.addEventListener("notification", this.handleNotification);
  }
  handleNotification = () => {};
}
```

If the same listener is added to the same element repeatedly, the browser ignores the duplicates.

If the event listener isn’t removed, you can choose to inline the `handleNotification` code in the `addEventListener()` call.

```javascript
this.template.addEventListener("notification", (evt) => {
  console.log("Notification event", evt);
});
```

**important:** Don’t use `addEventListener({eventName}, this.handleNotification.bind(this))`. It’s an anti-pattern because `bind()` returns a new function and thus the component can’t call `removeEventListener()` with the same function instance. Because the component can’t use the same function instance, the listener creates a memory leak.

## Add an Event Listener

There are two syntaxes for adding an event listener. One to add an event listener to an element within a component’s shadow boundary, and one to add an event listener to an element that the template doesn’t own, for example, an element passed into a slot.

To add an event listener to an element within the shadow boundary, use `template`.

```javascript
this.template.addEventListener();
```

To add an event listener to an element that a template doesn’t own, call `addEventListener` directly.

```javascript
this.addEventListener();
```

## Get a Reference to the Component That Dispatched the Event

To get a reference to the object that dispatched the event, use the [`Event.target`](https://developer.mozilla.org/en-US/docs/Web/API/Event/target) property, which is part of the DOM API for events.

**tip:** Several recipes in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo use `Event.target`. To find examples, search the repo for `Event.target`.

## Event Retargeting

When an event bubbles up the DOM, if it crosses the shadow boundary, the value of `Event.target` changes to match the scope of the listener. This change is called “event retargeting.” The event is retargeted so the listener can’t see into the shadow DOM of the component that dispatched the event. Event retargeting preserves shadow DOM encapsulation.

Let’s look at a simple example.

<!-- prettier-ignore -->
```html
<!-- myButton.html -->
<template>
  <button>{label}</button>
</template>
```

A click listener on `<my-button>` always receives `my-button` as the target, even if the click happened on the `button` element.

Imagine an event is dispatched from a `div` element in the `c-todo-item` component. Within the component’s shadow DOM, `Event.target` is `div`. But to a listener on the `p` element in the containing `c-todo-app` component, the `Event.target` is `c-todo-item`, because the `p` element can’t see into the `c-todo-item` shadow DOM.

<!-- prettier-ignore -->
```html
<c-todo-app>
  #shadow-root
  <div>
    <p>Your To Do List</p>
  </div>
  <c-todo-item>
    #shadow-root
    <div>
      <p>Go to the store</p>
    </div>
  </c-todo-item>
</c-todo-app>
```

It’s interesting to note that to a listener on `c-todo-item`, the `Event.target` is `c-todo-item`, not `div`, because `c-todo-item` is outside the shadow boundary.

## Listen for Changes to Input Fields

To listen for changes from an element in your template that accepts input, such as a text field (`<input>` or `<lightning-input>`), use the `onchange` event.

<!-- prettier-ignore -->
```html
<!-- form.html -->
<template>
  <input type="text" value={myValue} onchange={handleChange} />
</template>
```

```javascript
// form.js
import { LightningElement } from "lwc";
export default class Form extends LightningElement {
  myValue = "initial value";

  handleChange(evt) {
    console.log("Current value of the input: " + evt.target.value);
  }
}
```

In this example, the `handleChange()` method in the JavaScript file is invoked every time the value of the input changes.

The `myValue` property represents the value for the input element. This _property_ value is not updated automatically on every change.

You might want extra validation of the value the user enters for auto-correction or restriction of some values as they type. To keep `myValue` synchronized with the current value of the input, update `myValue` in the `handleChange()` method. The following auto-corrects the typed value by removing white spaces at the beginning and end of the string. Use `evt.target.value` to get the current value of the input field.

```javascript
// form.js
import { LightningElement } from "lwc";
export default class Form extends LightningElement {
  myValue = "initial value";

  handleChange(evt) {
    const typedValue = evt.target.value;
    const trimmedValue = typedValue.trim(); // trims the value entered by the user
    if (typedValue !== trimmedValue) {
      evt.target.value = trimmedValue;
    }
    this.myValue = trimmedValue; // updates the internal state
  }
}
```

This example shows how to reset the input value property to the trimmed value in line `evt.target.value = trimmedValue`. It also shows how to keep `myValue` property in sync with the normalized value in case the component gets rehydrated (loaded with new values) in the future.

**note:** Mutating properties from elements defined through a template could have undesired side effects elsewhere in the component. In our example, the input value property of the element changes from the value defined in the template represented by `evt.target`. The example changes the value used in the template (`myValue`) to keep the state of the component elements in sync. Otherwise, template rehydration detects a mismatch of the property value while attempting to reconcile the state of the input element with the state of your component. This mismatch generates a runtime warning, and you need to adapt your component or JavaScript to keep the integrity of the data throughout your template.

## Remove Event Listeners

The framework takes care of managing and cleaning up listeners for you as part of the component lifecycle. However, if you add a listener to anything else (like the `window` object, the `document` object, and so on), you’re responsible for removing the listener yourself.

To remove the event listeners, use the [`disconnectedCallback`](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-dom.md) lifecycle hook.

If you add an event listener using `lwc:on`, you could also remove the event listener by omitting that property in the object that's passed to `lwc:on`.

**See Also**

- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md)
- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md)

<!-- document id=9b0f285d006297c4b224d700819f2f940fc4db46ee964b156adc819d6723eafa url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-events.md -->

# Handle Events on Base Components

Base components come with a rich user interface, where user interactions like a mouse click or a field value change can trigger an event. Handle an event, like [`click`](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) or [`change`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event), by appending an event handler on a base component. The event handler uses the format `oneventname`, such as `onclick` or `onchange`.

**note:** Global events that are not explicitly documented may have no effect on the base
component, result in regressions, or result in events not firing if the components' internals change in a future release.

A base component can also dispatch a custom event that you can handle, such as the `resize` and `rowselection` custom events on `lightning-datatable`. Review the Documentation tab for a base component in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

Handling an event on a base component is similar to handling an event on an HTML element.

<!-- prettier-ignore -->
```html
<lightning-input 
    type="text"
    label="Enter some text"
    onchange={handleChange}></lightning-input> 
<p>{val}</p>
```

In this example, the `val` property renders the text that's entered in the input field by binding its value to `event.target.value`.

```javascript
import { LightningElement } from "lwc";
export default class ChangeEventExample extends LightningElement {
  val = "Your input here";
  handleChange(event) {
    this.val = event.target.value;
  }
}
```

To dispatch an event from a base component and handle it from a parent component, use the `EventTarget.dispatchEvent()` method. For example, say your child component contains a button that handles the `click` event. It also dispatches a custom event `childbuttonclick` that the parent component can handle.

<!-- prettier-ignore -->
```html
<!-- child.html -->
<lightning-button label="Click me" onclick={handleClick}></lightning-button>
```

When you click the button, the `handleClick` function dispatches the `childbuttonclick` custom event, which you create using `new CustomEvent()`.

```javascript
// child.js
export default class Child extends LightningElement {
  handleClick() {
    this.dispatchEvent(new CustomEvent("childbuttonclick"));
  }
}
```

The parent component listens for the event using the `onchildbuttonclick` event handler, since the event is called `childbuttonclick`.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<c-child onchildbuttonclick={handleButtonClick}></c-child>
```

To dispatch an event from a base component with data, pass the `label: this.buttonLabel` data into the `detail` property.

```javascript
// child.js
export default class Child extends LightningElement {
  buttonLabel = "Click me";
  handleClick() {
    const childEvent = new CustomEvent("childbuttonclick", {
      detail: { label: this.buttonLabel },
    });
    this.dispatchEvent(new CustomEvent("childEvent"));
  }
}
```

In the parent component, you can get the data using the `event.detail.label` syntax.

```javascript
// parent.js
export default class Parent extends LightningElement {
  handleButtonClick(event) {
    const childLabel = event.detail.label;
  }
}
```

When you dispatch an event, it can propagate up through the DOM. By default, the event doesn't bubble up nor pass through the shadow boundary. Consider these guidelines when working with events.

- Avoid composed events when you don’t need them.
- If you do need composed events, consider stopping propagation at the intended component.
- Reduce unnecessary event propagation and unintended behaviors.

**See Also**

- [Handle Events](https://developer.salesforce.com/docs/platform/lwc/events/events-handling.md)
- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/events/events-create-dispatch.md)
- [Configure Event Propagation](https://developer.salesforce.com/docs/platform/lwc/events/events-propagation.md)

<!-- document id=6e06ad715e0e68250eaeeca893922f89611a0096af4b15ba740a62ec3b22de44 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-focus.md -->

# Handle Focus

To make your components accessible to people with disabilities, program them to handle which element has focus and can receive input.

Web browsers are fully navigable with the keyboard using the tab key. For accessibility purposes, users who rely on keyboard navigation need a visual cue to see which element has focus. People with low vision also use screen readers to navigate web pages. Screen readers read aloud the elements on the page, including the element that has focus. As a developer, you need to ensure that when a user tabs through a page, the browser moves focus to the next logical element.

When a user tabs through a page, interactive elements like `<a>`, `<button>`, `<input>`, and `<textarea>` receive focus automatically. Elements that are not natively focusable, such as `<div>` or `<span>`, can use `tabindex="0"` to receive keyboard focus.

**note:** Only `0` and `-1` tabindex values are supported. Assigning `tabindex="0"` means that the element focuses in standard sequential keyboard navigation. Assigning it `tabindex="-1"` removes the element from sequential keyboard navigation. For more information, see [Keyboard Accessibility](https://webaim.org/techniques/keyboard/tabindex).

## Focus Behavior During Tab Navigation

For custom components, focus skips the component container and moves to the elements inside the component.

Let’s look at some code.

In this example, when a user tabs, focus moves from a button element in `parent` to an input element in `child`, skipping `child` itself.

```html
<!-- parent.html -->
<template>
  <button>Button</button>
  <c-child></c-child>
</template>
```

```html
<!-- child.html -->
<template>
  <span
    >Tabbing to the custom element moves focus to the input, skipping the component itself.</span
  >
  <br /><input type="text" />
</template>
```

![Code output with custom component selected.](https://developer.salesforce.com/media/handle_focus_input.png)

## Apply Focus on Child Component

To add focus to a custom component, use the `tabindex` attribute. In the parent template, we set the child component's `tabindex` to `0` to add the child component itself to the navigation sequence.

```html
<!-- parent.html -->
<template>
  <button>Button</button>
  <c-child tabindex="0"></c-child>
</template>
```

```html
<!-- child.html -->
<template>
  <span>Tabbing to the custom element moves focus to the whole component.</span>
  <br /><input type="text" />
</template>
```

```javascript
// child.js
import { LightningElement } from "lwc";

export default class Child extends LightningElement {}
```

![Code output with whole custom component selected.](https://developer.salesforce.com/media/handle_focus_component.png)

## Delegate Focus in Custom Components

When creating custom components that contain focusable elements, you might find yourself managing tab indexes or setting focus manually on these elements. To manage focus automatically, set `delegatesFocus` to `true`.

Let’s say we have a custom component with a button, which behaves like a native HTML button.

```html
<!-- coolButton.html -->
<template>
  <button>Focus!</button>
</template>
```

```javascript
// coolButton.js
import { LightningElement } from "lwc";

export default class CoolButton extends LightningElement {
  static delegatesFocus = true;
}
```

Using `delegatesFocus` enables the following cases.

- Adds focus to the native button HTML element using `coolButton.focus()`.
- If you click a node inside shadow DOM and the node is not a focusable area, the first focusable area becomes focused. This is similar to when you click on a label and focus jumps into an input.
- When a node inside shadow DOM gains focus, the `:focus` CSS selector applies to the host in addition to the focused element.

**note:** Don’t use `tabindex` with `delegatesFocus` because it throws off the focus order.

<!-- document id=fd2dcf07d0b4428d0dc4eb94bb911de8ba387a593e941bf1f237f9928303a6c0 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-events.md -->

# Handle Lightning Out 2.0 App Events

Configure custom events so that embedded components and the host page can communicate with each other.

## Overview

Lightning Out 2.0 app components load in iframes instead of directly on the host page. To overcome communication restrictions across iframe boundaries, Lightning Out 2.0 wraps custom events in messages using [`window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This internal implementation allows event listeners on one side of the iframe boundary to detect events dispatched from the other side. From your perspective, events are still created and handled with the standard [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) and [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) interfaces.

Recall that a Lightning Out 2.0 app includes Lightning Out 2.0 web components that mirror your embedded LWC components but run in the context of the host page. If you need a refresher, review [Understand Lightning Out 2.0 Architecture](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-architecture.md). This mirroring extends to events.

If you add an event listener to a Lightning Out 2.0 web component, Lightning Out 2.0 also adds the event listener to the corresponding LWC component running in the Salesforce context.

```js
const loComponent = document.querySelector("c-lwc-component");
loComponent.addEventListener("my-custom-event", (event) => {
  console.log("Received event.detail: ${event.detail}");
});
```

If you dispatch an event from a Lightning Out 2.0 web component, Lightning Out 2.0 also dispatches the event from the corresponding LWC component. When you create a custom event, set the `bubbles` and `composed` properties to `true` so that events can pass through the shadow DOM boundary.

```js
const loComponent = document.querySelector('c-lwc-component');
loComponent.dispatchEvent(
    New CustomEvent("my-custom-event", {
        detail: "Hello!",
        bubbles: true,
        composed: true,
    })
);
```

Therefore, if an event is fired inside the Salesforce context, the event can bubble up from the LWC component event listener to the Lightning Out 2.0 web component event listener. Then, the event is handled in the host page context. And similarly, if an event is fired in the host page context, the event can propagate down from the Lightning Out 2.0 web component event listener to the LWC component event listener. Then, the event is handled in the Salesforce context.

## Eventing Example

Let’s demonstrate Lightning Out 2.0 event handling with some example code.

### cardComponent.html

Here’s a custom Lightning web component called `c-card-component`, which is a wrapper for the `lightning-card` component. The card has a `lightning-button` component that sends a message to the host page when clicked. The card also has a conditional directive that renders a new message card when a user clicks a button on the host page.

```html
<!--cardComponent.html-->
<template>
  <lightning-card title="Custom Card Component" icon-name="standard:lightning_component">
    <div class="slds-p-around_medium">
      <div class="slds-text-heading_small slds-m-bottom_medium">
        Lightning Web Component
      </div>

      <p class="slds-text-body_regular slds-m-bottom_medium">
        This component can receive messages from the host page and send responses back.
      </p>

      <div class="slds-m-bottom_medium">
        <lightning-button
          label="Send Message to Host Page"
          variant="brand"
          onclick="{handleSendMessage}"
          class="slds-m-bottom_small"
        >
        </lightning-button>

        <div class="slds-text-body_small slds-text-color_weak">
          Click this button to test communication from LWC to the host page.
        </div>
      </div>

      <div class="slds-text-heading_small slds-m-bottom_small">
        Received Messages ({messages.length})
      </div>

      <template if:true="{messages.length}">
        <div class="message-list">
          <template for:each="{messages}" for:item="message">
            <div key="{message.id}" class="message-item slds-box slds-m-bottom_small">
              <div class="slds-text-body_regular"><strong>Message:</strong> {message.text}</div>
              <div class="slds-text-body_small slds-text-color_weak">
                <strong>Time:</strong> {message.timestamp}
              </div>
              <div class="slds-text-body_small slds-text-color_weak">
                <strong>Source:</strong> {message.source}
              </div>
            </div>
          </template>
        </div>
      </template>

      <template if:false="{messages.length}">
        <div class="slds-text-body_regular slds-text-color_weak">
          No messages received yet. Click "Send Message to LWC" on the host page to start
          communication.
        </div>
      </template>
    </div>
  </lightning-card>
</template>
```

### cardComponent.js

Here’s the JavaScript for `c-card-component`.
The `connectedCallback()` function runs when the component first loads. It initializes an event listener that responds to the `sendMessageToLWC` custom event defined on the host page. When the host page dispatches this event, the event listener calls the `handleMessageFromHost()` event handler. The event handler adds the received message to a list for the `c-card-component` to display.

`c-card-component` also has the `handleSendMessage` event handler, which responds to users clicking the component’s nested `lightning-button`. The event handler defines and dispatches the `lwcMessagetoHost` event to the host page.

```js
//cardComponent.js
import { LightningElement, track } from "lwc";

export default class CardComponent extends LightningElement {
  @track messages = [];
  @track messageCounter = 0;

  connectedCallback() {
    // Listen for messages from the host page
    this.addEventListener("sendMessageToLWC", this.handleMessageFromHost);
  }

  disconnectedCallback() {
    // Clean up event listeners
    this.removeEventListener("sendMessageToLWC", this.handleMessageFromHost);
  }

  handleMessageFromHost = (event) => {
    console.log("Message received from host page:", event.detail);

    // Add message to our list
    this.messageCounter++;
    const newMessage = {
      id: this.messageCounter,
      text: event.detail.message,
      timestamp: event.detail.timestamp,
      source: event.detail.source,
    };

    this.messages = [...this.messages, newMessage];
  };

  handleSendMessage() {
    console.log("Sending message to host page...");

    const newMessage = `Message from LWC at ${new Date().toLocaleTimeString()}`;

    const hostEvent = new CustomEvent("lwcMessageToHost", {
      detail: {
        message: newMessage,
        timestamp: new Date().toISOString(),
        component: "c-card-component",
      },
      bubbles: true,
      composed: true,
    });

    this.dispatchEvent(hostEvent);
    console.log("Message sent to host page");
  }
}
```

### Host Page HTML

Now let’s examine the host page. It has three main UI areas relevant to this example: the embedded `c-card-component` (1), a button that users click to send messages to `c-card-component` (2), and an area where messages from `c-card-component` will appear (3).

![The host page after the Lightning Out 2.0 app is initialized, but before any custom events are dispatched](https://developer.salesforce.com/media/lightning_out_event_start.png '{"class": "image-full"}')

Here’s an HTML snippet of the host page. It includes:

- The Lightning Out 2.0 JavaScript library.
- A Lightning Out 2.0 app with a `c-card-component` web component.
- A `sendMessageButton` button that dispatches a custom event to `c-card-component` when clicked. When the message is dispatched, the host page also shows a confirmation message.
- An `lwcMessageResponse` element that shows the latest message that the host page receives from the embedded `c-card-component`.

```html
<!-- body of index.html-->
<body>
  <script
    type="text/javascript"
    async=""
    src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
  ></script>
  <div class="main-wrapper">
    <div class="responsive-container">
      <lightning-out-application
        app-id="18_DIGIT_SALESFORCE_ID"
        components="c-card-component"
        frontdoor-url=""
      ></lightning-out-application>
      <c-card-component></c-card-component>
    </div>
    <div class="container">
      <h1>Lightning Out Example</h1>
      <div class="communication-section">
        <p>Send a message to the LWC component and see the response</p>
        <button id="sendMessageButton" class="btn control-btn">
          Send Message to LWC
        </button>
        <div id="messageResponse" class="response" style="display: none;">
          <h4>Communication Response:</h4>
          <div id="messageContent"></div>
        </div>
      </div>

      <div class="lwc-message-section">
        <p>Messages sent from the LWC component appear here</p>
        <div id="lwcMessageResponse" class="response" style="display: none;">
          <h4>Latest Message:</h4>
          <div id="lwcMessageContent"></div>
        </div>
      </div>
    </div>
  </div>
  <script src="script.js"></script>
</body>
```

### Host Page JavaScript

Here’s a snippet of the host page’s `script.js` file.

To dispatch an event to the embedded `c-card-component`, an event listener is set on the `sendMessageButton` button. When a user clicks the button, the event listener calls an anonymous event handler. This event handler defines and dispatches the `sendMessageToLWC` event directly on the Lightning Out 2.0 web component `c-card-component`. The event is mirrored to the embedded LWC component `c-card-component`.

To receive the `lwcMessageToHost` event from the embedded `c-card-component`, set an event listener on the Lightning Out 2.0 web component `c-card-component`. Ensure that the Lightning Out 2.0 app and the `c-card-component` have loaded before setting this event listener. For example, set the event listener conditionally based on whether the `frontdoor-url` attribute has been set on the `lightning-out-application`. When the embedded `c-card-component` dispatches the `lwcMessageToHost` event, the event listener calls the `handleLwcMessage` function. This function displays the latest message from the embedded component on the host page.

**tip:** To learn how to set the frontdoor URL at run time, see [Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_auth.htm&type=5) in _Salesforce Help_.

```js
// script.js

// DOM elements
const sendMessageButton = document.getElementById("sendMessageButton");
const messageResponse = document.getElementById("messageResponse");
const messageContent = document.getElementById("messageContent");
const lwcMessageResponse = document.getElementById("lwcMessageResponse");
const lwcMessageContent = document.getElementById("lwcMessageContent");
const lightningOutApp = document.querySelector("lightning-out-application");

// Obtain frontdoor URL and set its frontdoor-url attribute on the lightning-out-application to this value (OAuth flow and UI Bridge implementation not shown)
// ... existing code ...
if (result.success) {
  // Set the frontdoor URL on the lightning-out-application component
  if (lightningOutApp && result.frontdoorUrl) {
    lightningOutApp.setAttribute("frontdoor-url", result.frontdoorUrl);

    // Set up event listener for lwcMessageToHost event
    const cardComponent = document.querySelector("c-card-component");
    if (cardComponent) {
      cardComponent.addEventListener("lwcMessageToHost", handleLwcMessage);
    }
  }
}

// Send message to LWC component
sendMessageButton.addEventListener("click", function () {
  console.log("Sending message to LWC component...");

  // Wait for Lightning Out 2.0 to initialize, and then dispatch the event
  setTimeout(() => {
    const cardComponent = document.querySelector("c-card-component");

    if (cardComponent) {
      console.log("Found card component, sending message...");

      // Create a custom event to communicate with the LWC component
      const messageEvent = new CustomEvent("sendMessageToLWC", {
        detail: {
          message: `Hello from host page at ${new Date().toLocaleTimeString()}`,
          timestamp: new Date().toISOString(),
          source: "host-page",
        },
        bubbles: true,
        composed: true,
      });

      // Dispatch the event to the card component
      cardComponent.dispatchEvent(messageEvent);

      messageContent.innerHTML = `
                <strong>Status:</strong> Message sent<br>
                <strong>Target:</strong> c-card-component<br>
                <strong>Timestamp:</strong> ${new Date().toISOString()}
            `;

      messageResponse.style.display = "block";

      console.log("Message sent to LWC component");
    } else {
      messageContent.innerHTML = `
                <strong style="color: red;">Error:</strong> LWC component not found<br>
                <strong>Message:</strong> Ensure Lightning Out is properly loaded
            `;
      messageResponse.style.display = "block";
      console.error("LWC component not found");
    }
  }, 500);
});

// Handle lwcMessageToHost event
function handleLwcMessage(event) {
  console.log("Message received from LWC:", event.detail);

  lwcMessageContent.innerHTML = `
        <strong>Message:</strong> ${event.detail.message}<br>
        <strong>Component:</strong> ${event.detail.component}<br>
        <strong>Timestamp:</strong> ${event.detail.timestamp}
    `;

  lwcMessageResponse.style.display = "block";

  // Add a visual indicator that a message was received
  lwcMessageResponse.style.borderLeftColor = "#28a745";
  lwcMessageResponse.style.background = "#d4edda";

  // Reset the styling after 3 seconds
  setTimeout(() => {
    lwcMessageResponse.style.borderLeftColor = "#667eea";
    lwcMessageResponse.style.background = "#f8f9fa";
  }, 3000);

  console.log("Message displayed in the host page.");
}
```

Here’s the host page after a user dispatched three messages from the host page to `c-card-component` (1). Whenever the user dispatches a message to `c-card-component`, a confirmation message appears in the Messages to the LWC Component section (2). The user also dispatched messages from `c-card-component` to the host page. The most recent message appears in the Messages from the LWC Component section (3).

![The host page after custom events are dispatched to and from the embedded LWC component](https://developer.salesforce.com/media/lightning_out_event_after.png '{"class": "image-full"}')

**See Also**

- [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md)
- _Salesforce Help_: [Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_auth.htm&type=5)

<!-- document id=e304194267d5da5e1373d13fddc53ad717b9d1a3dbfc2728fdb1e1da2c02de3c url=/developer/current/en-us/lwc/utam/guide/stale-elements.md -->

# Handle Stale Elements

A stale element reference error occurs when a referenced web element is no longer attached to the DOM. For a WebDriver-based UI test, an error message can look like: `The element reference is stale; either the element is no longer attached to the DOM, it is not in the current frame context, or the document has been refreshed`.

This error message points to the reason why an error occurred. In a test, we found and saved an instance of an element, but then the content was refreshed (partially or completely) and the element became "stale". Basically, the element is now an orphan because it's no longer part of the DOM tree.

To avoid this type of test, a test should create a new element reference by finding the element again after it's attached to the DOM.

Let's look at a few use cases.

## Page is refreshed completely

If a page is completely refreshed, we must:

- Wait for the old content to become stale (this step is important!)
- Find all elements starting from the root (inside the Driver). In UTAM, you can use `UtamLoader.load`, which creates a new instance of the root page object.

Example of a Java test:

```java
HomePage homePage = utam.load(HomePage.class);
assert homePage.isPresent();
// now something happened to refresh the page, for example you hit Save

// wait for refresh before you proceed!
homePage.waitForAbsence();

// create new instance of the root page object
homePage = utam.load(HomePage.class);
assert homePage.isPresent();
```

Example of a JavaScript test:

```js
let homePage = await utam.load(HomePage);
expect(await homePage.isPresent()).toBeTrue();
// now something happened to refresh the page, for example you hit Save

// wait for refresh before you proceed!
await homePage.waitForAbsence();
expect(await pageContent.isPresent()).toBeFalse();

// create new instance of the root page object
homePage = await utam.load(HomePage);
expect(await homePage.isPresent()).toBeTrue();
```

## Part of the page is refreshed

With AJAX-based applications, often only part of the content is refreshed. In this scenario, we don't need to recreate an instance of the root page object, but we need to call an element method for the element that's refreshed.

Example of a Java test:

```java
HomePage homePage = utam.load(HomePage.class);
Content content = homePage.getDynamicContent();
// now something happened to refresh part of the content

// wait for refresh before you proceed!
content.waitForAbsence();

// call getter to invoke Element.findElement and assign a new variable
content = homePage.getDynamicContent();
assert content.isPresent();
```

Example of a JavaScript test:

```js
let homePage = await utam.load(HomePage);
let content = await homePage.getDynamicContent();
// now something happened to refresh part of the content

// wait for refresh before you proceed!
await content.waitForAbsence();

// call getter to invoke Element.findElement and assign new variable
content = await homePage.getDynamicContent();
expect(await content.isPresent()).toBeTrue();
```

<!-- document id=10a3f826a9e2681df04620352338e600c4ad0301b3ad3a3b32b1c3d88c55605e url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice.md -->

# HealthService API

Read and write body-weight records from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how HealthService works, see [Access Health Data on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice.htm).

<!-- document id=d123ea3433fe94fdcb242f5b667bdf18edbec410135060d92b6ae3abf0edd373 url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice-data-types.md -->

# HealthService Data Types

HealthService defines and uses several data types.

## `WeightRecord`

An object representing a single body-weight measurement.

| Property Name | Type         | Description                                                                                                                                                | Example         |
| ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `value`       | Number       | The weight measurement, expressed in `unit`. On a write, the value must be greater than 0.                                                                 | `80.5`          |
| `unit`        | `WeightUnit` | The unit that `value` is expressed in.                                                                                                                     | `"kg"`          |
| `startTime`   | Number       | The time that the measurement was taken, in epoch milliseconds (UTC). On a write, defaults to the current time when omitted.                               | `1721990400000` |
| `endTime`     | Number       | The end time for the measurement, in epoch milliseconds (UTC). `null` for an instantaneous measurement.                                                    | `null`          |

## `GetWeightOptions`

An object representing the options for a `getWeight()` request. All properties are optional. Pass `null` for the entire object to use the defaults.

| Property Name   | Type         | Description                                                                                                                                                                                                        | Example |
| --------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `startTime`     | Number       | The earliest time to read records from, in epoch milliseconds (UTC). `null` means no lower bound.                                                                                                                | `null`  |
| `endTime`       | Number       | The latest time to read records to, in epoch milliseconds (UTC). `null` means the current time.                                                                                                                 | `null`  |
| `limit`         | Number       | The maximum number of records to return. `null` means no limit, subject to a soft cap.                                                                                                                           | `10`    |
| `preferredUnit` | `WeightUnit` | The unit that the returned `value` of each record is expressed in. The device’s health store records weight without a unit, so HealthService converts to this unit. `null` defaults to `"kg"`.                    | `"kg"`  |

## `WeightUnit`

A string value that represents the unit for a weight measurement.

| Value   | Description |
| ------- | ----------- |
| `"kg"`  | Kilograms.  |
| `"lbs"` | Pounds.     |

## `HealthServiceFailure`

An object representing an error that occurred when accessing HealthService features.

| Property Name | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `HealthServiceFailureCode` | A value representing the reason for a health data error. Possible failure codes include the following:<ul><li>`SERVICE_NOT_ENABLED`</li><li>`USER_DENIED_PERMISSION`</li><li>`PROVIDER_NOT_INSTALLED` (Android only)</li><li>`PROVIDER_UPDATE_REQUIRED` (Android only)</li><li>`UNKNOWN_REASON`</li></ul> |
| `message`     | String                     | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.                                                                                                                                                                                                       |

<!-- document id=dc8a0582f1de46530ae53fcd3fc5683c08125f611ff3e5d3371401f84c51b554 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-sfdx-hello-world.md -->

# Hello World in a Scratch Org

Let’s create a Hello World component and use Lightning App Builder to add it to a Lightning page. Then, we’ll view it in a scratch org.

**note:** Before you create a component, see [Set Up an Editor, Linter, and Org](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md) and [Install the Salesforce CLI](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-cli.md).

## Create a Salesforce DX Project

A Salesforce DX project has a specific structure and a configuration file that identifies the directory as a Salesforce DX project.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Project**. For project name, enter `lwc-hello-world`.

You can also run this command from the command line.

```bash
cd PATH/TO/YOUR/SFDX/PROJECTS
sf project generate --name lwc-hello-world
cd lwc-hello-world
```

## Authorize Your Dev Hub Org

Before you can create a scratch org, authorize your Dev Hub org. Running this command opens a browser to the Salesforce login page. Enter your Dev Hub username and password. Authorize your Dev Hub only the first time you work on a project.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Authorize a Dev Hub**.

You can also run this command from the command line.

```bash
sf org login web
```

## Create a Default Scratch Org

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create a Default Scratch Org**. Accept the default values.

You can also run this command from the command line.

```bash
sf org create scratch -s -f config/project-scratch-def.json -a "lwchelloworld"
```

## Create a Lightning Web Component

Create Lightning web components in the `force-app/main/default/lwc` folder.

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Create Lightning Web Component**. For desired directory, accept the default. For filename, enter `helloWorld`.

You can also run this command from the command line.

```bash
cd force-app/main/default/lwc
sf lightning generate component --type lwc -n helloWorld -d force-app/main/default/lwc
```

Use camel case to name your Lightning web components (`helloWorld`) because it maps to kebab-case in HTML (`<c-hello-world>`). See [Component Folder](https://developer.salesforce.com/docs/platform/lwc/create/create-components-folder.md).

## Create the Hello World Component

Add this code to the `helloWorld.js` file.

```javascript
import { LightningElement, api } from "lwc";

export default class HelloWorld extends LightningElement {
  @api name;
}
```

The [`@api` decorator](https://developer.salesforce.com/docs/platform/lwc/reference/reference-decorators.md) makes the `name` property public.

Add this code to the `helloWorld.html` file.

```html
<template>
  <lightning-card title="HelloWorld" icon-name="custom:custom14">
    <div class="slds-card__body slds-card__body_inner">Hello, {name}!</div>
  </lightning-card>
</template>
```

The [`{}` syntax](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md) binds the `name` property in the HTML template to the `name` property in the JavaScript class. The other markup gives the text some padding and wraps it in the `lightning-card` base component to make it look better.

## Configure the Component for Lightning App Builder

Configure the `helloWorld` component for Lightning App Builder so that we can add it to a Lightning page in our scratch org.

Open `helloWorld.js-meta.xml` and add the code in bold. To use the component in Lightning App Builder, set `<isExposed>` to `true`. The `<target>` lets us add the component to an app page. The `<targetConfigs>` section lets us set the component’s `name` property in Lightning App Builder.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="anotherComponent">
    <apiVersion>45.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Hello World</masterLabel>
    <description>Add a classic greeting to any page.</description>
    <targets>
      <target>lightning__AppPage</target>
    </targets>
    <targetConfigs>
      <targetConfig targets="lightning__AppPage">
          <property name="name" type="String" label="Name" placeholder="World" description="Enter the name of the person to greet."/>
      </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

You can also add [targets](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) for the Lightning Experience home page, record pages, and Experience Builder.

## Push Source to the Scratch Org

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Push Source to Default Scratch Org**.

You can also run this command from the command line.

```bash
sf project deploy start
```

## Open the Scratch Org

In VS Code, press Command + Shift P, enter `sfdx`, and select **SFDX: Open Default Scratch Org**.

You can also run this command from the command line.

```bash
sf org open
```

## Add the Component to a Lightning Page

1.  In the scratch org, in Setup, enter `bui` and click Lightning App Builder.
2.  To create a Lightning page, click New.
3.  Select App Page and click Next.
4.  Enter the label `Hello World`.
5.  Select Three Regions and click Finish.
6.  Drag the Hello World component from the Custom list of components to a region on the page.

    ![Screenshot of Lightning App Builder.](https://developer.salesforce.com/media/sfdx_lab.png)

7.  Select the component and enter a Name.
8.  Drag more Hello World components to the page, and set a different name for each component.
9.  When your page is complete, click Save and Activate.
10. On the Activation page, select an icon, then click Lightning Experience, and add the page to the Lightning Bolt app. Click Save.
11. To exit Lightning App Builder, click Back.
12. From the App Picker, click Bolt Solutions.
13. Click the Hello World tab to see your page and all its greetings.

![A Lightning page in Salesforce with 6 Hello World components, each with a different greeting.](https://developer.salesforce.com/media/sfdx_hello_world.png)

To return to Lightning App Builder to edit the page, click the gear and select Edit Page.

When you edit code, push it to the scratch org and hard refresh the browser.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Get Started Coding](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-lwc.md)

<!-- document id=39d748882b05922c6ebca5542808bbf528db34e7f1d80d22c6267f7a194ae98f url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-high-level-guide.md -->

# High-Level Guide to Creating Custom Property Types and Editors

After you decide which data validations and property editors you want for the properties in your custom component, it's time to start building. This step-by-step summary outlines the process.

Creating a custom property type requires you to create a new metadata type, `LightningTypeBundle`, and a new Lightning web component for each custom property editor. These are the custom elements required for the Custom Article component example.

- **`articleDate`** requires a standard Lightning type
- **`textAlignment`** requires a custom property editor
- **`layoutProperties`** requires a custom property type and a custom property editor

These steps summarize how to build the custom component. To follow along, download the [sample components](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples).

## Reference a Lightning Type

1. Refer to the list of Lightning property types. (See [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html) in the Lightning Types Developer Guide)
2. To use a Lightning type in the Custom Article component, reference it by type attribute in the component's `js-meta.xml` file. (See [Reference a Custom Property Type by Type Attribute](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-reference-by-type-attribute.md).)

## Reference a Custom Property Editor

1. Create a Lightning web component called `alignmentCPE` to act as the property editor for Text Alignment. (See [Create a Custom Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-create-custom-editor.md).)
2. To show the custom property editor in the Custom Article component, reference it by editor attribute in the component's `js-meta.xml` file. (See [Reference a Custom Property Editor by Editor Attribute](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-reference-by-editor-attribute.md).)

## Reference a Custom Property Type That Includes a Custom Property Editor

1. Create a custom property editor for Border Style called `borderStyleDropdownCPE`. (See [Create a Custom Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-create-custom-editor.md).)
2. Create a custom property type called `layoutProperty` and define its `schema.json` file. (See [Create a LightningTypeBundle](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-create-lightningtypebundle.md).)
3. Specify the custom property editor and define the layout for the properties for the custom property type.
   1. Create an `editor.json` file in the `experienceBuilder` folder. (See [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.html))
   2. In the `editor.json` file, reference the custom property editor in the `componentOverrides` object and specify the layout of the properties in the `layout` object.
4. To show the custom property type in the Custom Article component, reference it by type attribute in the component's `js-meta.xml` file.

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)
- [Decide on the Validation for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-validation.md)
- [Decide on the Editor for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-editor.md)
- _Lightning Types Developer Guide_: [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html)

<!-- document id=588a2cc50f171ebef5bc85fc9cfc178f2c098ec27e9f8d0776d0d7b0e28e8905 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-proxy.md -->

# How Lightning Locker Uses the Proxy Object

Lightning Locker uses the standard JavaScript [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object to filter a component’s access to underlying JavaScript objects. The `Proxy` object ensures that a component only sees DOM elements created by a component in the same namespace.

You can interact with a `Proxy` object in the same way as you interact with the raw JavaScript object, but the object shows up in the browser’s console as a `Proxy`. It’s useful to understand Lightning Locker’s usage of `Proxy` if you drop into your browser’s debugger and start poking around.

When a component creates a JavaScript object, Lightning Locker returns the raw JavaScript object. When Lightning Locker filters the object, it returns a `Proxy` object. Some scenarios where Lightning Locker filters an object and returns a `Proxy` object are:

- Passing an object to a Lightning web component (LWC) or an Aura component in a different namespace.
- Passing an object from an Aura component on API version less than 40.0 to the method of a component on API version greater than or equal to 40.0.
- Calling `cmp.get()` to retrieve an Aura component attribute value that you set with the value of a native JavaScript object or array. The object or array isn’t filtered when it’s originally created.

When you access these objects, Lightning Locker returns a `Proxy` object.

- Any object that implements the [HTMLCollection](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection) interface
- A `SecureElement` object, which represents an HTML element.

**See Also**

- [DOM Access Containment](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-dom.md)
- [Secure Wrappers](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-global-access.md)
- [Arrays Proxied When Passed to Child Components](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-array-proxy.md)

<!-- document id=daca4297b823027a22e94b7c9a0848917127bb313ba913695e2afea2ae792045 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-compare.md -->

# How Lightning Out 2.0 Compares to Lightning Out (Beta)

Lightning Out 2.0 is generally available. It’s a new feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. Learn how the architecture and features currently available in Lightning Out 2.0 compare to those in Lightning Out (beta). The feature comparison list is updated as more Lightning Out 2.0 features are added.

## Architecture Comparison

- Lightning Out 2.0

  - : Lightning Out 2.0 uses core [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) standards and is built on Lightning Web Runtime (LWR). Each embedded Lightning web component (LWC) loads in an iframe and is encapsulated in a closed shadow Document Object Model (DOM). This approach provides stronger security through a Content Security Policy (CSP) directive that allows only your external apps to load the Lightning Out 2.0 app. For more information, see [Understand Lightning Out 2.0 Architecture](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-architecture.md).

- Lightning Out (Beta)
  - : Lightning Out (beta) is a standalone Aura application that dynamically creates Lightning components directly on the external host page.

**important:** Lightning Out (beta) is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## Feature Comparison

| Feature                         | Lightning Out 2.0                                                                                                                                                                                                                                                      | Lightning Out (Beta)                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| App configuration               | Supports both declarative and programmatic configuration.                                                                                                                                                                                                              | Supports only programmatic configuration.                                                                                               |
| Embedded component types        | Currently supports only custom Lightning web components.                                                                                                                                                                                                               | Supports custom Lightning web components and custom Aura components, as well as certain Lightning base components.                      |
| Lightning security architecture | Lightning Web Security (LWS) is automatically applied to the embedded LWC components. Lightning Locker isn't supported.                                                                                                                                                | Requires Lightning Locker. LWS isn't supported.                                                                                         |
| User access                     | Currently supports only authenticated users. Unauthenticated user access is on the roadmap.                                                                                                                                                                            | Supports authenticated users and unauthenticated users. For unauthenticated access, the Salesforce org must enable Digital Experiences. |
| Component styling               | Declare LWC styles using a CSS stylesheet in the component folder or in a CSS module. Set SLDS styling hooks and other CSS custom properties values in the Lightning Out 2.0 app. Otherwise, components inherit styles from Salesforce Lightning Design System (SLDS). | Components either inherit styles from Salesforce Lightning Design System (SLDS) or are unstyled.                                        |
| Events                          | Supported.                                                                                                                                                                                                                                                             | Not supported.                                                                                                                          |

**See Also**

- [Understand Lightning Out 2.0 Architecture](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-architecture.md)
- [Lightning Out 2.0 Limitations](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-limitations.md)

<!-- document id=5a5636f958d515c1ea0cf180ee90410773896c244685471698acb084f84ff873 url=/developer/current/en-us/lwc/lightning-components-security/guides/get-started/get-started-compare-lws-locker.md -->

# How Lightning Web Security Compares to Lightning Locker

[Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md) and [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md) both block or modify behavior of APIs that aren’t secure. In addition, as the newer architecture, LWS supports features that Lightning Locker doesn’t.

## Summary of LWS-Only Features

Here’s a summary of additional features that Lightning Web Security supports.

### Cross-Namespace Component Use

Your Lightning components can import components or modules from other namespaces and use them via composition or extension. Components are isolated in their own namespace JavaScript sandbox, but it’s transparent to you because the security architecture performs virtual communication behind the scenes. See [Components from Different Namespaces](/docs/platform/lwc/guide/create-components-namespace.html#components-from-different-namespaces) in the _Lightning Web Components Developer Guide_.

### Interactions with Global Objects

Because each namespace is given its own detached JavaScript sandbox, we can expose `window`, `document`, and `element` global objects directly without needing to use wrappers to secure your components. Lightning Web Security modifies behaviors of those objects to prevent a component from accessing global objects used by components from another namespace.

### Access to iframe Content and Identity

Your Lightning components can access content in `iframe` elements, although web browsers prevent access to content from a different origin. The iframe identity is also maintained across the sandbox boundary, so that checking the identity of `postMessage` event origin works normally. Lightning Locker blocks access to content in iframes. See [Access to iframe Content in Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-iframes.md).

### Use of Custom Elements and Third-Party Non-Lightning Web Components

Your Lightning web components (LWC) can create custom elements and use third-party web components. Lightning Locker blocks the use of custom elements and third-party web components.

### Improved Performance

Execution of your code in the JavaScript sandbox is faster than in Lightning Locker because Lightning Web Security doesn’t use secure wrappers, which can reduce performance. See [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-performance.md).

### Better Support of Third-Party JavaScript

Libraries can use techniques such as manipulating global objects because they’re running in a JavaScript sandbox and their changes to globals don’t affect components in other namespaces. Lightning Locker provides secure wrapper versions of the `window`,`document`, and `element` objects to prevent access to some APIs of those global objects. The wrappers prevent use of some third-party libraries that access those protected APIs.

### Compatibility with Standard JavaScript as It Evolves

Lightning Web Security is modeled after the latest TC39 standards that evolve with the browser platforms.

## Lightning Locker and LWS Comparison Table

This table compares the features of Lightning Locker and Lightning Web Security.

| Feature                                                                                                                                                                                                                      | Lightning Locker                                                                                                                                                                                                                                                                                    | Lightning Web Security                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [JavaScript strict mode](https://developer.salesforce.com/docs/platform/lightning-components-security/js/js-strict-mode-intro.md)                                                                                                                                                                      | Enforced                                                                                                                                                                                                                                                                                            | Enforced                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| DOM access containment                                                                                                                                                                                                       | Components can only access elements they create. See [DOM Access Containment](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-dom.md). For LWC, Lightning Locker prevents you from breaking [Shadow DOM](/docs/platform/lwc/guide/create-dom.html) encapsulation between components, and you can't modify `shadowRoot` properties. | LWC access to the DOM is controlled by the browser through [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), which is a web standard implemented in web browsers. Lightning Web Security makes the `shadowRoot` mode appear to be closed to code running outside a component's sandbox. Inside a component's sandbox, code access works as intended, whether mode is set to open or closed. See [MDN Web Docs: ShadowRoot.mode](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode). |
| Secure wrappers                                                                                                                                                                                                              | Lightning Locker wraps JavaScript objects in more secure versions to prevent behavior that isn't secure. All interaction with the object is through the secure version of the object. See [Secure Wrappers](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-global-access.md).                                                     | Lightning Web Security doesn't use wrappers. It uses [distortions](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-architecture.md#distortions) to selectively modify APIs that enable non-secure behaviors.                                                                                                                                                                                                                                                                                            |
| Custom elements allowed?                                                                                                                                                                                                     | Lightning Locker blocks `customElements`. See [Third-Party Web Components With Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-custom-elements.md).                                                                                                                                                              | Lightning Web Security virtualizes `customElementRegistry` APIs to enable use of custom elements within your component namespace.                                                                                                                                                                                                                                                                                                                                  |
| `eval()` function limitations                                                                                                                                                                                                | `eval()` is limited to the global scope by Lightning Locker. See [eval() Function Is Limited by Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-js-eval.md)                                                                                                                                                      | `eval()` isn’t blocked but is prevented from doing unsafe activities by distortions in the sandbox.                                                                                                                                                                                                                                                                                                                                                                |
| MIME types allowed in Blob objects                                                                                                                                                                                           | Lightning Locker allows a list of [MIME Types Permitted](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-js-mime.md).                                                                                                                                                                                                              | The same MIME types are permitted. However, you must [specify the MIME type when creating a Blob object](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-mime.md).                                                                                                                                                                                                                                                                                                                                      |
| Arrays passed to child components                                                                                                                                                                                            | Filtering arrays passed between components can cause a performance problem in Lightning Locker. See [Arrays Proxied When Passed to Child Components](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-array-proxy.md).                                                                                                              | This issue is solved with Lightning Web Security because it doesn't filter DOM requests and relies on shadow DOM.                                                                                                                                                                                                                                                                                                                                                  |
| Going back to previous version of Locker                                                                                                                                                                                     | Lightning Locker supports setting the org to use a previous version of Locker rules. See [Select the Locker API Version for an Org](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-api-setting.md).                                                                                                                               | The Locker API Version setting has no effect on Lightning Web Security. The setting to use Lightning Web Security isn't associated with any API version. When you enable Lightning Web Security, all Lightning components in the org are affected until you disable it.                                                                                                                                                                                            |
| [Lightning Out (Beta)](/docs/platform/lwc/guide/lightning-out.html) and [Lightning Components for Visualforce (Beta)](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_visualforce.htm) | To use Lightning Out, you must use Lightning Locker. See [Lightning Out Requirements](/docs/platform/lwc/guide/lightning-out-requirements.html).                                                                                                                                                    | Lightning Out isn't supported when LWS is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                 |

**See Also**

- [Experience Builder Sites and Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-lms-ec.md)

<!-- document id=9ff49d1e257e5d4e13daf7febcc6f720d5a04455c72e7834204c756820e51afd url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-sanitize-svg-static-resource.md -->

# How Lightning Web Security Sanitizes Static Resources in SVG Elements

**important:** LWS doesn’t [sanitize](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize.md) input text. Your code must validate or sanitize any user input.

Lightning Web Security (LWS) sanitizes resources loaded using the `<use>` tag and other SVG elements that support an `href` attribute.

For example, the URL in this `<use>` tag is sanitized.

```html
<use href="foo.svg#circle"></use>
```

LWS replaces the `href` value with a sanitized value. The sanitized URL is similar to:

```html
<use href="httplocalhostfoo_svg#circle"></use>
```

The sanitized URL is unknown outside the sandbox.

Despite the changes to the DOM, the content continues to function as expected.

**See Also**

- [SVG Allowlist for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg.md)

<!-- document id=89ebdbff5dfc26caf92c99402ff6af48c369d25a50cc16f136de897dc3e9c291 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-architecture.md -->

# How Lightning Web Security Works

As with Lightning Locker, the goal of Lightning Web Security (LWS) is to prevent Lightning components from interfering with or accessing data that belongs to platform code or components from other namespaces. The architecture of Lightning Web Security protects Lightning components using a different approach.

A Salesforce page can include components created by multiple companies. Components created by an organization’s developer team coexist with components created by Salesforce. If you create apps and deploy them on AppExchange, your components coexist with components that Salesforce created and with the components of the customer who installs your app.

Without preventative measures in place, a component can access the `window` global objects and obtain private resources or data from other components on the page. One preventative measure is to isolate components by namespace so that a malicious component is unable to access the resources of components outside its namespace.

## Isolation Through Virtualization

The industry standard for achieving isolation is virtualization. Code runs inside a virtual environment, which is a replica of the environment of the host. The virtual environment exposes a fraction of the host’s resources to the code running in the virtual environment. Multiple virtual environments run simultaneously in the host environment, but code running in one virtual environment can’t access any of the resources of another virtual environment. Malicious code can only impact the virtual environment where it’s running.

Virtual environments are created and managed by a virtualization engine running in a host environment. The virtualization engine has full access to the resources of the host environment, and it strictly controls what resources are made available to individual virtual environments. Examples of virtualization engines at the hardware platform and operating system level are VMWare and Docker.

## Virtualization of the Browser

Carrying the virtualization concept down to the web app level, the host environment is the browser. Lightning Web Security is the virtualization engine running in the host environment, creating and controlling the virtual environments. The namespace JavaScript sandboxes are the virtual environments. Lightning Web Security grants each virtual environment limited access to specific resources from the host environment. These resources include global objects, network access, cookie access, local storage, and so on.

![Corresponding diagram of browser virtualization](https://developer.salesforce.com/media/lws-architecture.png)

With components running in their namespace’s own virtual environments, Lightning Web Security can prevent behavior that is not secure by modifying code at the JavaScript API level. The modifications, or distortions, are applied in the sandboxes.

**tip:** To learn more about how LWS uses virtualization and how to optimize performance with LWS enabled, see [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.md).

## Virtualization Effects

To illustrate the effects of virtualization through sandboxes, let’s look at some cookies. Components can store cookies. Platform code, including LWS, can store cookies too. In the browser host environment, code runs unrestricted. Without LWS enabled, component code executes in that realm and can access all the cookies, and can see everything in them and do anything to them without restrictions. You don’t want your components to store cookies where other code can access them. With LWS enabled, the component code is protected by running in namespace sandboxes. When the components try to access cookies, they can only see cookies they have set and that they have access to, because LWS controls what they can access by containing them in a sandbox.

For example, in the sandbox for the `c` namespace, the component can only access the `foo=1` cookie that it set. LWS presents that cookie differently in the browser host environment by adding a prefix to the key to associate it with the component’s sandbox. The code that wants to read this cookie is running in the sandbox environment and it can read the cookie in the way it expects, where `foo=1`. The component doesn’t need to know that the cookie key is changed in the browser host environment because the component has no access to the cookie there. If the value of the cookie is changed in the sandbox, LWS takes care of updating the value of the cookie in the host environment. LWS manages cookie key prefixes to associate them to the namespace sandboxes and prevents access to cookies in the host environment by components from a different namespace.

**note:** The cookie prefix is `LSKey-{namespace}$`, so in this example the cookie key is changed to `LSKey-c$foo`. The prefix is considered an internal implementation detail that can change without notice. Your code can’t depend on the prefix remaining constant. The cookies received from the server have the prefix, which you can see in your browser’s developer tools. For example, the Application tab in Chrome DevTools shows cookie details.

## Distortions

Instead of the secure wrappers used in Lightning Locker, Lightning Web Security uses a technique called distortion. This technique refers to the alteration of code running in the JavaScript sandbox to prevent unsafe behavior.

A distortion dynamically modifies a native JavaScript API to:

- Prevent attempts of the API to alter content and data outside the JavaScript sandbox
- Confine running code to the boundaries of the sandbox
- Restrict or reduce access inside the JavaScript sandbox to DOM and shared global objects such as `window.location`, and data such as cookies

Most API distortions in Lightning Web Security fall into these categories.

- Content filtering—to filter out attempts to access properties in other sandboxes, for example in `document.cookie`, `localStorage`, `sessionStorage`, but allow them in the current sandbox
- Sanitization—to strip out malicious code, for example from `innerHTML` and `outerHTML` elements
- Property accessor modification—to prevent reading or writing values of certain properties, for example `shadowRoot.mode`

The distortions are documented in [LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer), a tool designed to make it easier to understand the effect of individual distortions.

**See Also**

- [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.md)
- [Look Up Distortion Details in Lightning Web Security Distortion Viewer](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-distortion-viewer.md)

<!-- document id=2941232c1ba5f5501069d05c36fdf192f401dc3e00bc5518490f1aa879a596cb url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-lwc-or-aura.md -->

# How to Choose Lightning Web Components or Aura

Lightning web components perform better and are easier to develop than Aura components. However, when you develop Lightning web components, you also may need to use Aura, because LWC doesn’t yet support everything that Aura does.

How do you decide which components to develop as Lightning web components and which to develop as Aura components?

**Always choose Lightning Web Components unless you need a feature that isn’t supported.**

To use an [unsupported experience or feature](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-experiences.md) or to use an [unsupported interface](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-interfaces.md), develop a Lightning web component and wrap it in an Aura component that simply accesses the experience, feature, or interface.

**note:** A Lightning web component can’t contain an Aura component. When you develop a Lightning web component, its DOM subtree must be composed entirely of Lightning web components.

To use a [base component](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-base-components.md) that isn’t available as a Lightning web component, you may need to develop everything (or nearly everything) in Aura.

**See Also**

- [Case Study: DreamHouse Gains Speed by Switching to LWC](https://developer.salesforce.com/blogs/2019/06/case-study-dreamhouse-gains-speed-by-switching-to-lwc.html)

<!-- document id=a846b834a422368d0930befa83c5217cde00b12e34bab8de63eb2bb0eeb18eec url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-sanitize-html.md -->

# HTML Allowlist for Lightning Web Security

**important:** LWS doesn’t [sanitize](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize.md) input text. It only filters HTML strings that components inserted into the DOM. Your code must validate or sanitize any user input.

Here’s a list of allowed HTML elements that are retained in the DOM after sanitization. Lightning Web Security (LWS) removes HTML elements that aren’t in this list.

- `a, abbr, acronym, address, area, article, aside, audio`
- `b, bdi, bdo, big, blockquote, body, br, button`
- `caption, canvas, center, cite, code, col, colgroup, command`
- `datalist, dd, del, details, dfn, dir, div, dl, dt`
- `em`
- `fieldset, figure, figcaption, footer, form`
- `h1, h2, h3, h4, h5, h6, head, header, hgroup, hr`
- `i, iframe, img, input, ins`
- `keygen, kbd`
- `label, legend, li`
- `map, mark, menu, meter`
- `nav`
- `ol, optgroup, option, output`
- `p, pre, progress`
- `q`
- `rp, rt, ruby`
- `s, samp, section, select, small, source, span, strike, strong, style, sub, summary, sup`
- `table, tbody, td, textarea, tfoot, th, thead, time, tr, track, tt`
- `u, ul`
- `var, video`
- `wbr`

For example, this code contains a `<script>` tag, which isn’t allowed.

```html
<div>
  <script>
    alert(1);
  </script>
</div>
```

After sanitization, it becomes:

```html
<div></div>
```

<!-- document id=9943e0e382abb38d63176c9958be2e46baf9d1a49fdc21397dc0a2d99316c517 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-compatibility.md -->

# HTML Syntax Compatibility

**important:** Expressions must be compatible with HTML syntax because they are parsed as HTML. Certain characters have special meaning in HTML and can’t be used directly in expressions.

## HTML Compliance Requirements

Expressions must be HTML compliant because they are parsed as HTML. The `<` character in a text node expression would be interpreted as the opening of an HTML tag, causing a parsing error. However, `<` is allowed in attribute expressions when properly quoted. This applies to all characters that carry a special meaning in HTML. Caution against being too clever, and thorough testing, is recommended.

```html
<!-- ❌ Invalid - < character causes HTML parsing issues in text nodes -->
<div>{foo < bar}</div>
<div>{age < 18 ? 'Minor' : 'Adult'}</div>

<!-- ✅ Valid - use HTML-compliant equivalents in text nodes -->
<div>{bar > foo}</div>
<div>{age >= 18 ? 'Adult' : 'Minor'}</div>

<!-- ✅ Valid - < character works in quoted attributes -->
<div class="{bar > foo ? 'high' : 'low'}"></div>
<input min="{minValue}" max="{maxValue}" />
```

```javascript
import { LightningElement } from "lwc";

export default class HtmlComplianceComponent extends LightningElement {
  foo = 5;
  bar = 10;
  age = 20;
  minValue = 0;
  maxValue = 100;
}
```

### Guidelines

- **Text nodes**: Use `{bar > foo}` instead of `{foo < bar}`
- **Text nodes**: Use `{bar >= foo}` instead of `{foo <= bar}`
- **Attributes**: `<` character works when expressions are quoted in attributes, but doesn’t work in text nodes
- **Both**: Avoid expressions that contain `<` followed by text that could be interpreted as HTML tags

## Attribute Quoting Requirements

Complex template expressions in attributes must be quoted. This requirement is backward compatible with existing LWC templates — simple property bindings don’t require quotes.

```html
<!-- ✅ Valid - complex expressions must be quoted -->
<div class="{isActive ? 'active' : 'inactive'}"></div>
<input value="{user?.name ?? 'Enter name'}">
<button onclick="{() => handleClick()}">Click me</button>
<div data-value="{bar > foo ? 'high' : 'low'}"></div>

<!-- ✅ Valid - simple property bindings don't need quotes -->
<div class={simpleClass}></div>
<input value={simpleValue}>
<button onclick={simpleHandler}>Click me</button>

<!-- ❌ Invalid - complex expressions without quotes -->
<div class={isActive ? 'active' : 'inactive'}></div>
<button onclick={() => handleClick()}>Click me</button>
<div data-value={bar > foo ? 'high' : 'low'}></div>
```

### Guidelines

- **Complex expressions**: Must be quoted (any expression with operators, function calls, etc.)
- **Simple property bindings**: Don't need quotes (just property names like `{value}`)
- **Backward compatibility**: Existing simple bindings continue to work without quotes

## HTML Entities

HTML entities are **not** decoded in expressions:

```html
<!-- ❌ HTML entities not decoded -->
<div>{'Price &lt; $100'}</div>

<!-- ❌ Use proper characters (but be mindful of HTML compliance as the below example would not work) -->
<div>{'Price < $100'}</div>

<!-- ✅ Better - use HTML-compliant expressions -->
<div>{'Price under $100'}</div>
<div>{price >= 100 ? 'Over $100' : 'Under $100'}</div>
```

```javascript
import { LightningElement } from "lwc";

export default class HtmlEntitiesComponent extends LightningElement {
  price = 99;
}
```

## HTML Parsing Edge Cases

Certain expressions can cause HTML parsing issues when they contain characters that have special meaning in HTML:

```html
<!-- ❌ Invalid - A double quoted string that contains HTML-like content would produce invalid results -->
<div>{() => foo("}<c-status></c-status>")}</div>
<div attr="{() => call("><c-status></c-status>")}"></div>

<!-- ✅ Valid - avoid expressions that could be interpreted as HTML, for example by using single quotes in attribute expressions -->
<div>{() => foo('status')}</div>
<div attr="{() => call('status')}"></div>
```

```javascript
import { LightningElement } from "lwc";

export default class HtmlParsingComponent extends LightningElement {
  foo(value) {
    return `Processed: ${value}`;
  }

  call(value) {
    return `Called with: ${value}`;
  }
}
```

### Guidelines

Avoid expressions that:

- Contain `<` followed by text that could be interpreted as an HTML tag
- Contain `</` followed by text that could be interpreted as a closing HTML tag
- Mix HTML-like syntax within string literals

<!-- document id=57b1c369a9c7af8a5cc10cf2f4cafbb9c76767d0a582b7afd93e54121ef0a6b3 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-directives.md -->

# HTML Template Directives

A directive is a special attribute that adds dynamic behavior to an HTML template. You can use certain directives on a root `<template>` tag, a nested `<template>` tag, or an HTML element such as a `<p>` tag. Some directives are supported for use with different tags.

This page lists guidelines for using HTML template directives.

## Directives for Root Templates

A root `<template>` tag is the first element in a component's HTML template. It supports the following directives.

### `lwc&colon;preserve-comments`

Preserves HTML comments so that they are rendered in the DOM. For example, you can use [conditional comments](https://developer.salesforce.com/docs/platform/lwc/guide/%3Chttps://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/compatibility/ms537512(v=vs.85)>) to improve design and styling in specific browsers.

<!-- prettier-ignore -->
```html
<template lwc:preserve-comments>
  <!-- This comment is preserved in the DOM -->
  <h2>Hello HTML comments!</h2>
  <template lwc:if={display}>
    <!-- More comments in a nested template -->
    Hello again!
  </template>
</template>
```

When `lwc:preserve-comments` is enabled, you can’t place comments between sibling conditional directives.

<!-- prettier-ignore -->
```html
<!-- Invalid -->
<template lwc:preserve-comments>
  <template lwc:if={property}></template>
  <!-- Remove this comment -->
  <template lwc:else></template>
</template>
```

### `lwc&colon;render-mode='light'`

Renders a component using [light DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-light-dom.md), which enables third-party tools to traverse the DOM using standard browser query APIs such as `querySelector`.

## Directives for Nested Templates

A component's template can include nested `<template>` tags with certain directives. These nested `<template>` tags support only the following directives.

### `for&colon;each={array}`

Iterates over an array and renders a list. `for:each={array}` can be used with nested templates and HTML elements. See [Render Lists](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md).

### `for&colon;item=''currentItem''`

Accesses the current item.

The `currentItem` placeholder is an identifier that the model injects into the current scope.

### `for&colon;index=''index''`

Accesses the current item's zero-based index.

The `index` placeholder is a new identifier that the model injects into the current scope.

### `if&colon;true|false={expression}`

**important:** The `if:true` and `if:false` directives are no longer recommended. They may be deprecated and removed in the future. Use `lwc:if`, `lwc:elseif`, and `lwc:else` instead.

`if:true|false={expression}` conditionally renders DOM elements in a template, calling the expression for each of `if:true` and `if:false`. In cases where you chain `if:true` and `if:false` directives, they are not as performant nor as lightweight as the `lwc:if`, `lwc:elseif`, and `lwc:else` directives. See [Render DOM Elements Conditionally](https://developer.salesforce.com/docs/platform/lwc/create/create-conditional.md).

The `expression` can be a JavaScript identifier (for example, `person`) or dot notation that accesses a property from an object (`person.firstName`).

The engine doesn’t allow computed expressions (`person[2].name['John']`). To compute the value of `expression`, use a [getter](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md) in the JavaScript class.

### `lwc&colon;if|elseif={expression}` and `lwc&colon;else`

Conditionally render DOM elements in a template. `lwc:if`, `lwc:elseif`, and `lwc:else` supersede the `if:true` and `if:false` directives.

Use the conditional directives on nested `<template>` tags, `<div>` tags or other HTML elements, and on your custom components tags like `<c-custom-cmp>`.

Both `lwc:elseif` and `lwc:else` must be immediately preceded by a sibling `lwc:if` or `lwc:elseif`.

<!-- prettier-ignore -->
```html
<template lwc:if={expression}></template>
<template lwc:else></template>
```

Both `lwc:if` and `lwc:elseif` must evaluate an expression. However, `lwc:else` must not have an attribute value.

<!-- prettier-ignore -->
```html
<template lwc:if={expression}></template>
<template lwc:elseif={expression_elseif1}></template>
<template lwc:elseif={expression_elseif2}></template>
<template lwc:else></template>
```

The expression passed in to `lwc:if` and `lwc:elseif` supports simple dot notation. Complex expressions like `!condition`, `object?.property?.condition` or `sum % 2 === 1` aren't supported. To compute such expressions, use a [getter](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getters-setters.md) in the JavaScript class.

**note:** The expressions and property getters are only accessed once per instance of an `lwc:if` or `lwc:elseif`. In the above case, if `expression` is truthy, then none of the other property getters are accessed.

You can't precede `lwc:elseif` or `lwc:else` with text or another element. Whitespace is ignored between the tags when the whitespace is a sibling of the conditional directive. For example you can't have a `<div>` tag that comes after `lwc:if` and before `lwc:else`.

<!-- prettier-ignore -->
```html
<!-- Invalid -->
<template lwc:if={expression}></template>
This text node makes the pattern invalid
<div>This div tag makes the pattern invalid</div>
<template lwc:else></template>
```

Code comments can be included as a sibling of the conditional directive only if `lwc:preserve-comments` isn't enabled.

To check for a [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy), pass in the negation operator in your getter's return value so the `expression` is `true`.

<!-- prettier-ignore -->
```html
<template lwc:if={notCondition}></template>
```

```javascript
get notCondition() {
    return !this.condition;
}
```

**note:** `lwc:if`, `lwc:elseif`, and `lwc:else` can't be applied to the same element and they cannot be combined with the `if:true` and `if:false` directives.

### `iterator&colon;iteratorname={array}`

Applies special behavior to the first or last item in an array and renders a list. `iterator:iteratorname={array}` can be used with nested templates and HTML elements. `iteratorname` must be lowercase. See [Render Lists](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md).

Accesses these properties on the `iteratorname`:

- `value`—The value of the item in the list. Use this property to access the properties of the array. For example, `iteratorname.value.propertyName`.
- `index`—The index of the item in the list.
- `first`—A boolean value indicating whether this item is the first item in the list.
- `last`—A boolean value indicating whether this item is the last item in the list.

### `lwc&colon;slot-data`

Links the scoped slot fragment in a parent component to the `lwc:slot-bind` directive in a child component. The child component must use [light DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-light-dom.md).

Add `lwc:slot-data` to the `<template>` element in the parent component and set the value of `lwc:slot-data` to a string literal.

The `<template lwc:slot-data>` element must be a direct child of a custom element. For example, the `<template lwc:slot-data>` element is nested in the custom element `<c-child>`.

The string literal for `lwc:slot-data` and the variable used by the corresponding `lwc:slot-bind` don’t have to share the same name.

A `<template>` element can have only one instance of `lwc:slot-data`. A scoped slot fragment binds to only one child component.

## Directives for Slots

A `<slot>` tag supports the following directives.

### `lwc&colon;slot-bind`

This directive binds data to the scoped slot in a child component. The child component must use [light DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-light-dom.md).

Add `lwc:slot-bind` to the `<slot>` element of the child component and set the value of `lwc:slot-bind` to a variable name.

The `<slot lwc:slot-bind>` element can only be used in a light DOM element’s HTML `<template>`.

You can add only one instance of `lwc:slot-bind` to a `<slot>` element. A scoped slot can bind to only one source of data.

## Directives for HTML Elements

You can use certain directives on an HTML element, such as on a `<p>` tag, a base component, or your own custom component.

The `lwc:if`, `lwc:elseif`, and `lwc:else` directives in the previous section are also supported for use with HTML tags, a base component, or your own custom component.

### `for&colon;each={array}`

Iterates over an array and renders a list, using `for:item={currentItem}` and `for:index={index}`. Also supported for use with nested templates, as described in the previous section.

### `iterator&colon;iteratorname={array}`

Applies special behavior to the first or last item in an array and renders a list. Also supported for use with nested templates, as described in the previous section.

### `key={uniqueId}`

Improves rendering performance by assigning a unique identifier to each item in a list. Use this directive with `iterator:iteratorname={array}` or `for:each={array}`.

The `key` must be a string or a number, it can’t be an object. The engine uses the keys to determine which items have changed. See [Render Lists](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md).

### `lwc&colon;dom=''manual''`

Add this directive to a native HTML element to call `appendChild()` on the element from the owner’s JavaScript class and preserve styling.

If a call to `appendChild()` manipulates the DOM, styling isn’t applied to the appended element. Using JavaScript to manipulate the DOM isn’t recommended when programming Lightning web components, but some third-party JavaScript libraries require it.

### `lwc&colon;external`

Enables a third-party web component or custom element to be rendered as a native web component in an LWC template. See [Third-Party Web Components](https://developer.salesforce.com/docs/platform/lwc/create/create-use-third-party-intro.md).

### `lwc&colon;on={eventHandlers}`

Adds event listeners to an element dynamically.

```html
<template>
  <lightning-button lwc:on="{eventHandlers}" label="Click Me"></lightning-button>
</template>
```

The `lwc:on` directive uses the properties of the `eventHandlers` object to set up event listeners on the element. Each property key in the object specifies an event type to listen for.

```javascript
import { LightningElement } from "lwc";

export default class EventHandlersExample extends LightningElement {
  eventHandlers = {
    focus: function (event) {
      console.log("Button focused");
    },
    click: function (event) {
      console.log("Button clicked");
    },
  };
}
```

See [Add Event Listener Dynamically on Children](https://developer.salesforce.com/docs/platform/lwc/create/create-components-spread-dynamic.md).
### `lwc&colon;ref=''uniqueId''`

Refs locate DOM elements without a selector and query elements in a specified template only.

To use refs, add the `lwc:ref` directive to your element and assign it a value. To call that reference, use `this.refs`. In this example, `this.refs` references the directive `lwc:ref="myDiv"` to access the `<div>` at runtime.

```html
<template>
  <div lwc:ref="myDiv"></div>
</template>
```

```javascript
export default class extends LightningElement {
  renderedCallback() {
    console.log(this.refs.myDiv);
  }
}
```

We recommend that you use `this.refs` instead of `this.template.querySelector()` in shadow DOM or `this.querySelector()` in light DOM. For shadow DOM components, `this.refs` refers to elements inside of the shadow DOM. For light DOM components, `this.refs` refers to elements inside of the light DOM. If `lwc:ref` is not defined in the template, then `this.refs` returns undefined.

See [Access Elements the Component Owns](https://developer.salesforce.com/docs/platform/lwc/create/create-components-dom-work.md).

### `lwc&colon;spread={childProps}`

Spreads properties to a child component, enabling elements to accept an object that’s bound as properties at runtime. Define your properties in your component's JavaScript. To dynamically add an event handler, use [`lwc:on`](#lwccolononeventhandlers)instead.

```javascript
// c/myComponent.js
import { LightningElement } from "lwc";

export default class MyComponent extends LightningElement {
  childProps = {
    name: "My child property",
  };
}
```

Apply *childProps* as a property to the child component. Only one instance of `lwc:spread` on an element is allowed.

<!-- prettier-ignore -->
```html
<template>
  <a lwc:spread={childProps}></a>
</template>
```

See [Spread Properties on Child Components](https://developer.salesforce.com/docs/platform/lwc/create/create-components-spread-properties.md).

## Directives for Dynamic Components

To instantiate a component dynamically, use the `<lwc:component>` managed element with the `lwc:is` directive in a component's HTML file.

Here's an HTML template that uses `<lwc:component>`.

<!-- prettier-ignore -->
```html
<template>
    <div class="container">
        <lwc:component lwc:is={componentConstructor}></lwc:component>
    </div>
</template>
```

For more information, see [Dynamically Instantiate Components](https://developer.salesforce.com/docs/platform/lwc/js/js-dynamic-components.md).

**See Also**

- [Use HTML Templates](https://developer.salesforce.com/docs/platform/lwc/create/create-components-html-use.md)
- [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md)

<!-- document id=7cb5cc7c9a96331895d59fa4f020aeff26cc3d6bc2bf4546b37f99fedb9034d3 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-template-errors.md -->

# HTML Template Errors

LWC enforces valid syntax in your custom components and throws an error for [a number of invalid syntaxes](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors). The framework implements the syntax restrictions from [parse5](https://github.com/inikulin/parse5).

In LWC API version 58.0 and earlier, the following invalid syntax are returned as warnings. In VS Code, warnings appear as a popover in the editor. The offending tags are underlined with a squiggly line. When you push or deploy your code to your org, the web console displays the invalid HTML syntax warnings.

HTML validation is stricter in LWC API version 59.0 and later, returning an error where a warning was previously returned. For errors, the component code displays with red squiggly lines with a popover that explains the problem. The component can be saved locally but it can't be pushed or deployed to your org.

Starting in LWC API version 59.0 and later, the following invalid syntaxes throw an error.

## Errors for HTML Elements

You can encounter these errors when working with HTML elements.

### `closing-of-element-with-open-child-elements`

The closing tag for a child element is missing.

<!-- prettier-ignore -->
```html
<template>
  <child>
  <!-- Close this child tag first -->
</template>
```

### `end-tag-without-matching-open-element`

The open tag for an element's close tag is missing.

```html
<template>
    <h1>hello</h1>
</template>
</template> <!-- Remove this end tag -->
```

### `eof-in-element-that-can-contain-only-text`

Unexpected end of file in an element that can contain only text.

<!-- prettier-ignore -->
```html
<template>
  <p>Hello
  <!-- Close the tags accordingly -->
```

## Errors for the `<!DOCTYPE>` Element

These errors are associated with the [`<!DOCTYPE>` element](https://developer.mozilla.org/en-US/docs/Glossary/Doctype). LWC ignores the `<!DOCTYPE>` element in custom components, but you might encounter this tag when working with third-party web components or libraries.

**note:** Although LWC ignores the `<!DOCTYPE>` tag in your template, the framework includes these syntax restrictions from its [parse5](https://github.com/inikulin/parse5) implementation.

### `misplaced-doctype`

Unexpected `<!DOCTYPE>` element after the `<head>` element or another invalid location.

```html
<!DOCTYPE html>
<title>misplaced-doctype</title>
<!DOCTYPE html>
<!-- Remove the unexpected tag -->
```

### `missing-doctype`

Missing a `<!DOCTYPE>` element before other content in an HTML document.

```html
<!-- Add the DOCTYPE element before other content -->
<html>
  <body>
    ...
  </body>
</html>
```

### `non-conforming-doctype`

Only `<!doctype html>`, `<!DOCTYPE html>`, or another valid `<!DOCTYPE>` element is supported.

<!-- prettier-ignore -->
```html
<!DOCTYPE>
<title>Fix the doctype tag</title>
```

## Errors for the `<head>` Element

These errors are associated with the [`<head>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head). LWC ignores the `<head>` element in custom components, but you can encounter this tag when working with [Experience Builder sites](https://help.salesforce.com/s/articleView?id=experience.community_builder_page_head.htm&type=5), and third-party web components or libraries.

**note:** Although LWC ignores tags like `<html>`, `<head>`, and `<body>`, the framework includes these syntax restrictions from its [parse5](https://github.com/inikulin/parse5) implementation.

### `abandoned-head-element-child`

Unexpected element after the `<head>` element. Place the `<head>` element between the `<html>` element and the `<body>` element and make sure they have matching closing tags.

### `disallowed-content-in-noscript-in-head`

Unexpected content in a `<noscript>` element in `<head>`. When used within the `<head>` element, the `<noscript>` element can only contain zero or more `<link>`, `<style>`, or `<meta>` elements.

### `misplaced-start-tag-for-head-element`

Unexpected location of the open tag for the `<head>` element instead of directly after the `<!DOCTYPE>` element.

### `nested-noscript-in-head`

Unexpected `<noscript>` element within another `<noscript>` element.

```html
<noscript>
  <!-- link, style, and meta elements optional -->
  <noscript><!-- Remove this nested tag --></noscript>
</noscript>
```

### `open-elements-left-after-eof`

Unexpected end of file where a closing tag is expected.

<!-- prettier-ignore -->
```html
<!DOCTYPE html>
<title>Add the missing closing tag</title>
<noscript>
```

## Fix HTML Syntax Errors With lwc-codemod

To clean up common HTML syntax errors in your code, use the [lwc-codemod tool](https://github.com/salesforce/lwc-codemod).

The tool removes:

- Excessive `if:true` and `if:false` attributes on the same element
- Invalid attributes from both `<template>` tags

The tool also fixes errors generated during LWC HTML parsing. For example:

- An unexpected end of file
- Mismatched tags

For more information, see the [lwc-codemod documentation](https://github.com/salesforce/lwc-codemod).

**See Also**

- [Set Up an Editor, Linter, and Org](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md)
- [parse5 Error Codes](https://parse5.js.org/enums/parse5.ErrorCodes.html)

<!-- document id=7bad84503bf761928264a3eba97a862a8c8a028210881b80ae9c55dd56cef623 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html.md -->

# HTML Templates

The power of Lightning Web Components is the templating system, which uses the virtual DOM to render components smartly and efficiently. It’s a best practice to let LWC manipulate the DOM instead of writing JavaScript to do it.

Use a `<template>` root tag in your [HTML template](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-use.md). You can also use nested `<template>` tags to work with directives.

When working with an HTML template, you can:

- [Bind data in a template](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md)
- [Render HTML conditionally](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.md)
- [Render lists](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.md)
- [Render multiple templates](https://developer.salesforce.com/docs/platform/lwc/guide/create-render.md)

**See Also**

- [Lifecycle Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)

<!-- document id=5eca9d2664c20db945f0ec8b23b5d2edbff1c67b9f50a91592eb2417df116ae3 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-http-caching.md -->

# HTTP Caching for Custom Components

Salesforce caches the latest version of a component with an HTTP cache using a time to live (TTL) of 5 minutes, or up to 10 minutes with the [stale-while-revalidate](https://web.dev/articles/stale-while-revalidate) directive. HTTP caching of your components means that your code changes can take up to 10 minutes to display in the UI. This directive applies to all supported browsers except Safari. The browser continues to serve the file from the cache after it has expired, while simultaneously requesting a new copy.

To see component updates without a delay during debugging or testing, [enable debug mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md).

**note:** The **Enable secure and persistent browser caching to improve performance** option in the Session Settings setup page has no impact on HTTP caching for custom components.

## Requests for the Latest Component Version

After Lightning Experience has been bootstrapped, the component definition is served from the cache if it's preloaded during bootstrapping. Otherwise, the browser requests the latest version of a component definition. The server responds with a [302 redirect](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) to the specific version of the component.

To view the redirect in Chrome DevTools, go to the [Headers tab](https://developer.chrome.com/docs/devtools/network/#details) on the Network panel. A request URL with a redirect contains the `uid=LATEST` parameter and has a status code of 302. For example:

```javascript
https://lng-dev-ed.lightning.force.com/auraCmpDef?_au=zrAD0qv6qvYSMksnSeQhvg&_c=false
&_density=VIEW_ONE&_ff=DESKTOP&_l=true&_l10n=en_US&_lrmc=-386269907&_style=1474136371
&aura.app=markup://one:one&aura.mode=PROD&adminsuccess=init
&one=lexOnboardingManagerService,maskContainer,onePreloads,sidebarWrapper
&runtime_iag_core=onboardingManager&_uid=LATEST
```

The redirect points to the following URL that contains a `uid=117337808` parameter and has a status code of 200. For example:

```javascript
https://lng-dev-ed.lightning.force.com/auraCmpDef?_au=zrAD0qv6qvYSMksnSeQhvg&_c=false
&_density=VIEW_ONE&_ff=DESKTOP&_l=true&_l10n=en_US&_lrmc=-386269907&_style=1474136371
&_uid=117337808&adminsuccess=init
&aura.app=markup://one:one&aura.mode=PROD&one=sidebarWrapper,lexOnboardingManagerService,onePreloads,maskContainer
&runtime_iag_core=onboardingManager
```

Since the component version can change at any time, the redirect ensures that the your browser receives the latest version of the component.

## Caching Directives for Custom Components

Custom components return the [`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) with the following response directives.

```
private,max-age=300,stale-while-revalidate=300
```

- `private`- Indicates that the response can be stored only in a private cache, such as a local cache in a browser.
- `max-age=300` - Indicates that the response remains fresh until 300 seconds after the response is generated. Indicates that caches can store this response and reuse it for subsequent requests while it's fresh.
- `stale-while-revalidate=300` - Indicates that the cache can reuse a stale response while it revalidates it to a cache.

`stale-while-revalidate` allows the browser or the CDN to continue to serve the file from cache after it has expired (for the next 5 minutes) while it requests a new copy of the component. Therefore, the browser can be up to 10 minutes out of sync with the server for the given component. This directive applies to [all supported Lightning Experience browsers](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-supported-browsers.html) except Safari.

The caching header doesn't apply to components in [debug mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md).

**See Also**

- [Salesforce Developers' Blog: Our Detailed Plan to Improve Lightning Experience Performance](https://developer.salesforce.com/blogs/2023/09/our-detailed-plan-to-improve-lightning-experience-performance)

- [MDN Web Docs: HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)

<!-- document id=a47b52494819afc529e86ea98a8e9fd617426c02c6f8b3cfbd4f63cfa4f12326 url=/developer/current/en-us/lwc/utam/guide/imperatives.md -->

# Imperative Extensions

Imperative extensions enable you to create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar. For example, you can't use the JSON grammar to navigate a data table where each column shows data from a different type of component with different markup.

**important:** While imperative extensions are powerful, only use them as a last resort. They violate the declarative nature of UTAM and require you to individually implement and maintain them in each programming language that you use with UTAM.

To author an imperative extension:

- In JavaScript, use an **ES module** that exports a set of **named functions**.
- In Java, use a class with a set of **static public methods**.

The utility code is referenced from a page object's JSON file so that a test writer can call the code.

## Reference Imperative Code from a Page Object

Declare an imperative utility method in a `compose` statement in a page object. A page object can reference any number of utility classes.

This page object declares a compose method, `myMethod`, that calls two utility methods, `utilityA` and `utilityB`. There's a separate `applyExternal` statement for each utility method.

```json
{
  "methods": [
    {
      "name": "myMethod",
      "return": "actionable",
      "returnList": true,
      "compose": [
        {
          "applyExternal": {
            "type": "utam-impext/utils/impext/exampleUtils",
            "invoke": "utilityA"
          }
        },
        {
          "applyExternal": {
            "type": "utam-impext/utils/impext/exampleUtils",
            "invoke": "utilityB",
            "args": [
              {
                "name": "stringArg",
                "type": "string"
              }
            ]
          }
        }
      ]
    }
  ]
}
```

The `applyExternal` property declares an imperative extension. For a full explanation of the syntax, see [Grammar: imperative extensions](/grammar/imperative-extensions).

## JavaScript Example

A JavaScript imperative extension must:

- Be an ES module (ESM) that exports a set of named functions.
- Have `.utam.js` as its file extension.

Additionally, the first parameter of each exported function must be a `context` object that represents the context that an imperative extension requires to interact with the page object. The `context` object holds a single `pageObject` property, which is a reference to the page object.

This example implements the `utilityA` and `utilityB` functions declared in the page object.

```javascript
// An imperative extension is authored as a JavaScript ES module.
// It exports a set of named functions.

// The first parameter of every function is a context object.
// It has a single pageObject property that holds a reference
// to the current page object in which the function has been referenced.
export async function utilityA(context) {
  const { pageObject } = context;
  // add logic for utility method here
}

// Destructure the context parameter to access the pageObject
// as alternative syntax with less code
export async function utilityB({ pageObject }, stringArg) {
  // add logic for utility method here
}
```

The return value is based on what the last action (`utilityB`) in the compose statement returns.

To call the `myMethod` method declared in the page object from test code, use `await context.pageObject.myMethod()` or `await pageObject.myMethod()` if you use destructuring.

For an interactive JavaScript example, see [this tutorial](https://utam.dev/tutorial/compose-utility).

## Java Example

To author a Java imperative extension, use a class with a set of **static public** methods.

The first parameter of each static public must be a `context` object that's an instance of `UtamUtilitiesContext`, which is responsible for passing the page object's context to the static method.

This example implements the `utilityA` and `utilityB` methods declared in the page object.

```java
package utam.utils.impext;

import utam.examples.pageobjects.ExamplePageObject;

public class ExampleUtils {

  public static void utilityA(UtamUtilitiesContext context) {
    // Explicit casting to the page object type
    ExamplePageObject examplePO =
        (ExamplePageObject)context.getPageObject();

    // call methods on page object here
  }

  public static List<Actionable> utilityB(UtamUtilitiesContext context,
                                          String stringArg) {
    // Explicit casting to the page object type
    ExamplePageObject examplePO =
        (ExamplePageObject)context.getPageObject();

    // call methods on page object here

    // return List<Actionable>
  }
}
```

The `UtamUtilitiesContext` object exposes the `getPageObject()` getter that returns an object of type `PageObject`. You must explicitly cast the type of the object returned by `getPageObject()` to the type of the current page object instance, which is a subclass of the `PageObject` type. In this example, the page object instance is `ExamplePageObject`.

**note:** The method implementation shouldn't interact with `Driver` or `Element` directly.

## Return Value

By default, the return value of a compose statement is the return value of the last action in the statement. The framework can infer the return value from the `apply` value in the page object. The framework can't infer the return type of an imperative extension so you sometimes have to explicitly declare the return type if you write Java utility code.

A compose method has two optional properties where you can explicitly declare the return type.

- `return` is a string that declares the return type
- `returnAll` is a boolean that declares whether the return value is a list (`true`) or not (`false`). The default value is `false`. You must declare a `return` property if you declare `returnAll`.

These properties are declared at the method level, which means they are siblings of the `name` and `compose` properties. The page object for our example declares that the method returns a list of actionable elements.

```json
{
  "methods": [
    {
      "name": "myMethod",
      "return": "actionable",
      "returnAll": true,
      "compose": [ ...
      ]
    }
  ]
}
```

For JavaScript, you don't have to declare the `return` or `returnAll` properties because the default behavior suffices. However, for Java, you must declare the `return` property if the last action in the compose statement invokes utility code that has a non-void return type.

In Java, if the last action in the compose statement invokes utility code, these rules apply for the method's return type:

- If the `return` property is absent, the return type defaults to `void`.
- If the `return` property is declared, this value is set for the return type.

A utility method should return a type that can be referenced from JSON, which is one of:

- `void`
- A primitive type (string, number, boolean) or a list or an array of primitives
- Another page object or a list or an array of page objects
- A basic element (actionable, editable, clickable) or a list or an array of basic elements

<!-- document id=a127f2375496d647257a68fbb56bee8a50a52a80e5f0e891c147fb603199e0d0 url=/developer/current/en-us/lwc/utam/references/imperative-extensions.md -->

# Imperative Extensions

Imperative extensions enable you to create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar. For example, you can't use the JSON grammar to navigate a data table where each column shows data from a different type of component with different markup.

**important:** While imperative extensions are powerful, only use them as a last resort. They violate the declarative nature of UTAM and require you to individually implement and maintain them in each programming language that you use with UTAM.

Declare imperative utility code in a `compose` statement. A page object can reference multiple utilities.

```json
{
  "methods": [
    {
      "name": "myMethod",
      "compose": [
        {
          "applyExternal": {
            "type": "utam-lst/utils/lst/relatedListContainerUtils",
            "invoke": "cardUtility1",
            "args": [
              {
                "name": "stringArg",
                "type": "string"
              }
            ]
          }
        },
        {
          "applyExternal": {
            "type": "utam-lst/utils/lst/relatedListContainerUtils",
            "invoke": "cardUtility2",
            "args": [
              {
                "name": "booleanArg",
                "type": "boolean"
              }
            ]
          }
        }
      ]
    }
  ]
}
```

An imperative extension in a `compose` statement has these properties:

- `element` (Optional.) String. A reference to the element passed as the first parameter to the utility code. The default value is `self` so if no element is set, we pass the page object itself. You can omit this property because you can access the elements from the page object reference passed to the utility code.
- `applyExternal` (Required) Object. Declares an imperative extension and has these properties:
  - `type` (Required) String. A reference to the executable code to import: either a Java class or a JavaScript ES module.
  - `invoke` (Required) String. A reference to the method name to call: a named function in JavaScript or a static method in Java.
  - `args` (Optional) Array. If the code needs parameters, provide them in an array. Each element of the array has these properties:
    - `name` (Required) String. A parameter name that is unique in the scope of the `args` array.
    - `type` (Required) String. A parameter type, which is a primitive type, locator or a function.

For examples of Java and JavaScript code implementations, see [Guide: Imperative Extensions](/guide/imperative).

<!-- document id=13b583ccd49765f42442625112edc18657290e5fd5b90ad903e854fd7ef21242 url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-define-implementation.md -->

# Implement a State Manager

After you understand the "outer" syntax of using `defineState` to create a state manager, it's time to learn more about the internal implementation of a state manager.

## State Management Primitives

### `defineState` Function

Use the `defineState` function to define a state manager. When you call `defineState`, you provide a callback function. This callback receives an object with specific instances of state manager functions (primitives) that you use to define your state manager's behavior. `defineState` returns a function that, when invoked, gives you an instance of your state manager.

## State Properties (State Values)

Properties represent the internal, consistent state of your state manager. Use the primitives `atom` and `computed` to create reactive properties that connect with the rest of LWC's reactivity system.

### `atom(myValue)`

Represents a single, reactive piece of data. Changes to an `atom` trigger updates in components that use it, and re-computation of dependent derived values.

Provide an argument _`myValue`_ to set the initial value.

The result of calling the `atom()` function is a reactive "atomic" value, which is essentially a wrapper around a piece of data that LWC can use to make components and other state managers reactive to changes in that data. Change the value of an `atom` only by using the `setAtom` primitive function.

Save the result of calling `atom` in a `const` variable, and return any `atom`s your state manager makes public in the state manager definition function's `return` statement.

**note:** You don't need to expose every `atom` in the return object. Atoms that are used only for internal state management — like the `config` atom in [Nested State Manager Example](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-example-nested.md) — can be omitted from the return statement.

**important:** You can use `atom()` to wrap any JavaScript value, but it's recommended to stick to JSON-serializable values or `undefined` for best compatibility.

### `computed([independentValues], computationFunction)`

Represents data that's derived from one or more `atom`s or other `computed` values. A `computed` property automatically recalculates after its dependencies change.

Provide as arguments an array of values _`[independentValues]`_ upon which the `computed` value is dependent, and an anonymous _`computationFunction`_ that determines the derived value. The anonymous function receives as parameters the new or current values of the values upon which it depends, which it can use to calculate the new dependent value.

**tip:** The formal explanation might read like gibberish, so here's something specific, taken from the succeeding example. `doubleCount` is twice `count`. This line is how that's implemented.

```javascript
const doubleCount = computed([count], (countValue) => countValue * 2);
```

`doubleCount` is a `computed` property. The `[count]` array is the first argument to `computed`, which means that `doubleCount` depends on `count`.

When `count` changes, the anonymous function recalculates the value of `doubleCount` as needed. It takes the same number of parameters as the _size_ of the array in the first parameter, in this case, one: `countValue`. `countValue` is the value of `count` after the change. The result of the anonymous function is `countValue * 2`, and here it's implicitly returned.

This is about the simplest `computed` value possible. For a non-trivial example, including default values and an explicit `return`, see [Nested State Manager Example](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-example-nested.md).

Save the result of calling `computed()` in a `const` variable, and return any `computed`s that your state manager makes public in the state manager definition function's `return` statement.

**note:** Like `atom` values, `computed` values used only within the state manager's implementation don't need to be included in the return object.

## Actions (Functions)

Actions are functions defined by your state manager that contain logic to modify your state `atom` properties using the `setAtom` primitive. Actions are a part of the internal implementation of your state manager, and ensure that your state manager always maintains a consistent state. Public actions allow components and other state managers to interact with your state manager.

Define actions as anonymous functions, which can accept any parameters you want. Actions can return a value of any type, or no value. Actions can be synchronous or asynchronous.

**tip:** Here's a specific action, `setCount`, taken from the full example later in this topic.

```javascript
// Create an action that directly sets a new value for the `count` atom
const setCount = (newValue) => {
  setAtom(count, newValue);
};
```

Here, the action is `setCount`, and it accepts one parameter, `newValue`, which is (unsurprisingly) the new value to set `count` to.

Save the action function in a `const` property. Return any actions that your state manager makes public in the state manager definition function's `return` statement.

**note:** Actions are a part of a state manager's implementation, and possibly part of the state manager's public API, but are otherwise "just functions". This offers flexibility, but just because you _can_ do something doesn't mean you _should._

For example, it's a best practice to always return a consistent shape for the state manager instance (same property names and value types, and the same actions). While possible, the following code would be an anti-pattern:

```javascript
if (initialValue % 2 === 0) {
  // Don't do this
  return { count, increment, divideBy2: () => setAtom(count, count.value / 2) };
}

return { count, increment };
```

This anti-pattern would cause some instances of the state manager to include an additional action. Consumers of the state manager can't rely on the extra action always being available.

## State Manager Public API

The callback function that you provide to `defineState` returns an object with references to the values and actions that your state manager makes available to its consumers. Your components access this public API via the `value` element of the state manager instance.

In this example, the function returns two values (one `atom`, one `computed`) and two actions:

```javascript
return {
  count, // the counter value (atom)
  doubleCount, // a computed, dependent value
  increment, // an action to increment the counter value by +1
  setCount, // an action to set the counter to an arbitrary value
};
```

A consumer component or template accesses the values using the `.value` element of the counter state manager instance:

```html
<section class="slds-p-around_small">
  <p>Count: {counter.value.count}</p>
  <p>Doubled: {counter.value.doubleCount}</p>
</section>
```

Actions are accessed in a similar way from the component. To use them from the template, create an action handler in your component to connect the two together.

```javascript
handleIncrement() {
  this.counter.value.increment();
}
```

<!-- prettier-ignore -->
```html
<section class="slds-p-around_small">
  <lightning-button label="Increment" onclick={handleIncrement}></lightning-button>
</section>
```

See a later section for the complete example.

## State Manager Considerations

State managers must not rely on DOM-specific APIs or data — elements, events, and so on. They're intended to help you manage data in your application. Interactions with the DOM belong in components.

## State Manager Example

This example is an expanded version of the counter state manager used in [Syntax Introduction: A Simple Counter](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-define-syntax.md). While still simple, it illustrates all three state manager implementation functions, and how to interact with the state manager from a component's user interface.

**note:** This example puts the `counterManager` state manager in a supplemental JavaScript file, separate from the `simpleCounter` component. While easy to use, it's not a best practice for a state manager you intend to share across many components — which is much of the point of state managers. The better way to define a state manager is in an [API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md). See [Share a State Manager Across Components](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-example-fromcontext.md) for an example.

```javascript
// c/simpleCounter/counterManager.js
import { defineState } from "@lwc/state";

// Use the `defineState` function to define the values
// and actions your state manager provides
const counterManager = defineState(
  // This anonymous JavaScript function is the implementation
  // for a state manager instance.
  // `atom`, `computed`, and `setAtom` are state management functions
  // available in the context of `defineState`.

  // Your state manager can accept any number of arguments to define
  // its initial state. Here, this state manager can accept one argument
  // `initialValue` to set the beginning counter value, or use a
  // default value of zero.
  ({ atom, computed, setAtom }, initialValue = 0) => {
    // Create the counter, the state for this state manager.
    // An `atom` represents a single, reactive piece of data.
    // Changes to an atom trigger updates in components or
    // re-computation of derived values.
    const count = atom(initialValue);

    // Create computed (derived) value
    const doubleCount = computed([count], (countValue) => countValue * 2);

    // Create an action modify the state by incrementing it
    const increment = () => {
      setAtom(count, count.value + 1);
    };

    // Create an action that directly sets a new value for the `count` atom
    const setCount = (newValue) => {
      setAtom(count, newValue);
    };

    // Return an object that defines the public API of counterManager
    return {
      count, // the counter value
      doubleCount, // a computed, dependent value
      increment, // an action to increment the counter value by +1
      setCount, // an action to set the counter to an arbitrary value
    };
  },
);
export default counterManager;
```

```javascript
// c/simpleCounter/simpleCounter.js
import { LightningElement } from "lwc";
import counterManager from "./counterManager";

export default class SimpleCounter extends LightningElement {
  counter = counterManager();

  handleIncrement() {
    this.counter.value.increment();
  }

  handleSetCount() {
    this.counter.value.setCount(Number(this.refs.newValue.value));
  }

  get stateDump() {
    return JSON.stringify(this.counter.value, null, 2);
  }
}
```

<!-- prettier-ignore -->
```html
<!-- c/simpleCounter/simpleCounter.html -->
<template>
  <lightning-card title="Example: Simple Counter">
    <section class="slds-p-around_small">
      <p>Count: {counter.value.count}</p>
      <p>Doubled: {counter.value.doubleCount}</p>
    </section>

    <section class="slds-p-around_small">
      <lightning-button label="Increment" onclick={handleIncrement}></lightning-button>
    </section>

    <section class="slds-p-around_small">
      <lightning-input
        type="text"
        label="Counter"
        value={counter.value.count}
        lwc:ref="newValue"
      ></lightning-input>
      <lightning-button label="Set Counter" onclick={handleSetCount}></lightning-button>
    </section>

    <section class="slds-p-around_small">
      <hr />
      <textarea rows="10" cols="40">{stateDump}</textarea>
      <hr />
    </section>
  </lightning-card>
</template>
```

<!-- document id=df5e73a84e111b6c9171001dc89d1e8e48490cd70bc5adae57647c83699a01c7 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-import-method.md -->

# Import Apex Methods

Use default import syntax in JavaScript to import an Apex method via the `@salesforce/apex` scoped packages.

## Syntax

```javascript
import apexMethodName from "@salesforce/apex/namespace.classname.apexMethodReference";
```

- `apexMethodName`—A symbol that identifies the Apex method.
- `apexMethodReference`—The name of the Apex method to import.
- `classname`—The name of the Apex class.
- `namespace`—If the class is in the same namespace as the component, don’t specify a namespace. If the class is in a managed package, specify the namespace of the managed package.

## Usage

When an Apex class name changes outside of the JavaScript source file, the class name is automatically updated in the JavaScript source file. Method and argument name changes aren’t updated in the JavaScript source file.

To call an Apex method, a Lightning web component can:

- [Wire Apex Methods to Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/apex-wire-method.md)
- [Call Apex Methods Imperatively](https://developer.salesforce.com/docs/platform/lwc/guide/apex-call-imperative.md)

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Client-Side Caching of Apex Method Results](https://developer.salesforce.com/docs/platform/lwc/guide/apex-result-caching.md)
- [_MDN Web Docs_: JavaScript import syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)
- [_npm Docs_: JavaScript scoped packages](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)

<!-- document id=db303befa8bd10c5b68f64a364edc21289e69012aed4a09bacfd1ca1be980bc0 url=/developer/current/en-us/lwc/lwc/guides/apex/apex-schema.md -->

# Import Objects and Fields from `@salesforce/schema`

If you import references to objects and fields, Salesforce verifies that the objects and fields exist (which also catches typos), prevents objects and fields from being deleted, and cascades any renamed objects and fields into your component's source code. It also ensures that dependent objects and fields are included in change sets and packages. Importing references to objects and fields ensures that your code works, even when object and field names change.

If a component gets an object via an Apex class and imports references to the object from `@salesforce/schema`, call `getSObjectValue()` to get a field value from the object.

```javascript
getSObjectValue(sobject, fieldApiName);
```

- **`{sobject}`**—The object returned by the Apex method.
- **`{fieldApiName}`**—The API name of the field. The value can be either a string or reference to a field imported from `@salesforce/schema`.
  - In your `fieldApiName` input, you can specify up to three **relationship fields** to reference parent objects and fields. Follow this format: `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`.

Let’s look at the `apexStaticSchema` component from [lwc-recipes](https://github.com/trailheadapps/lwc-recipes). The component gets its data from an Apex method that returns a single contact.

![Shows a contact, Amy Taylor, with title, VP of Engineering, and email address.](https://developer.salesforce.com/media/apex_static_schema.png)

```apex
// ContactController.cls
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static Contact getSingleContact(){
        return [SELECT Id, Name, Title, Phone, Email, Picture__c FROM Contact LIMIT 1];
    }

}
```

The JavaScript imports the `getSObjectValue` function and the `getSingleContact` method from `@salesforce/apex`. It imports references to contact fields from `@salesforce/schema`.

The Apex method is wired to the `contact` property. The `name`, `title`, and `email` properties in the template have getters that call `getSObjectValue()` to extract the value from the specified field.

```javascript
// apexStaticSchema.js
import { LightningElement, wire } from "lwc";
import { getSObjectValue } from "@salesforce/apex";
import getSingleContact from "@salesforce/apex/ContactController.getSingleContact";

import NAME_FIELD from "@salesforce/schema/Contact.Name";
import TITLE_FIELD from "@salesforce/schema/Contact.Title";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";

export default class ApexStaticSchema extends LightningElement {
  @wire(getSingleContact) contact;

  get name() {
    return this.contact.data ? getSObjectValue(this.contact.data, NAME_FIELD) : "";
  }
  get title() {
    return this.contact.data ? getSObjectValue(this.contact.data, TITLE_FIELD) : "";
  }
  get email() {
    return this.contact.data ? getSObjectValue(this.contact.data, EMAIL_FIELD) : "";
  }
}
```

<!-- prettier-ignore -->
```html
<!-- apexStaticSchema.html -->
<template>
  <lightning-card title="ApexStaticSchema" icon-name="custom:custom63">
    <template lwc:if={contact.data}>
      <div class="slds-m-around_medium">
        <p>{name}</p>
        <p>{title}</p>
        <p><lightning-formatted-email value={email}></lightning-formatted-email></p>
      </div>
    </template>
    <template lwc:elseif={contact.error}>
      <c-error-panel errors={contact.error}></c-error-panel>
    </template>
  </lightning-card>
</template>
```

**See Also**

- [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=e4fba00fbf0057956a36ec6c1e9209534a07b79b793339850372f396b894ea8c url=/developer/current/en-us/lwc/lwc/guides/data/data-table-performance.md -->

# Improve Datatable Performance

Datatables can sometimes have performance issues when loading a large amount of data and handling user interaction. This section describes ways to create performant datatables with `lightning-datatable`.

## Identify Poor Datatable Performance

Using `lightning-datatable` is a common way to display Salesforce data in a table. Everything the `lightning-datatable` component displays loads in the browser on the user’s computer. Depending on the amount and type of data being rendered, the browser must use more or less processing power (memory). Poor performance for datatables can look like:

- The datatable is slow when loading.
- There's significant lag in datatable interactions.
- The datatable doesn’t load at all.
- Loading the datatable causes the whole page to freeze and, in some cases, causes the browser to crash.

To make datatables more performant, you can use smaller datasets, load more data on infinite scroll, and reserve inline editing for critical fields.

## Improve Your Datatable Performance

Here are several ways to improve your datatable performance.

### Use Smaller Datasets When Possible

Salesforce testing shows that datatable performance is best with a maximum of 1,000 rows and 5 columns. Adding more rows or columns can degrade performance. Your own testing can help you determine the number of rows and columns that provide acceptable performance for your use case.

### Use Event Handlers to Load More Data When Needed

By enabling infinite loading, you can load a subset of data initially and then display more data when the user scrolls to the end of the table.

To enable infinite loading, specify the `enable-infinite-loading` attribute and provide an event handler by using the `onloadmore` attribute. For more information on infinite scrolling, see the **Using Infinite Scrolling to Load More Rows** section in the [`lightning-datatable` documentation in the Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable).

### Reserve Inline Editing Functionality for Critical Fields

The inline editing capability affects performance. The more columns that enable inline editing, the slower the datatable performs. Add inline editing capability only to columns that require it. For more information on inline editing, see [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-inline-edit.md).

### Simplify Your Custom Data Types

If you use custom data types, review your code to ensure that you follow best practices. Using a custom data type on `lightning-datatable` can increase code complexity and add extra nesting within a datatable cell. Performance can be impacted especially when you're working with a large data set. When creating a custom data type, consider these guidelines.

- Use simple code within the custom data type. For example, minimize the use of `setTimeout()` and promises. Don’t use `lightning-datatable` for complex interactions.
- Use fewer nesting levels within the custom data type template. The browser takes longer to render more elements in the DOM.
- To improve display time, load a maximum of 50 rows at a time. For example, use `LIMIT` to specify no more than 50 rows to be returned. Or implement pagination using `LIMIT` with the `OFFSET` clause. You can also paginate your results easily using GraphQL API. Alternatively, consider infinite loading to display more data when the user scrolls.
- If your datatable has more than 250 rows, use fewer than 20 columns to reduce the amount of data presented. Tables with too much data have poor performance, are hard to read, and can overwhelm users.

**See Also**

- [GraphQL API: Implement Pagination in LWC](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-paginate.html#implement-pagination-in-lwc)
-

<!-- document id=21f468f07da5d1d2a2f82e7f620a8fe61d4166d0106f4f11ea865b6204a5783f url=/developer/current/en-us/lwc/lwc/guides/perf/perf-intro.md -->

# Improve Performance

Enable CDN and secure browser caching to improve application performance.

**note:** The first time that a component is loaded each day, it’s slower to load because the component isn’t cached. On subsequent loads, the component loads and displays faster.

**See Also**

- [Enable Debug Mode in Salesforce](https://developer.salesforce.com/docs/platform/lwc/debug/debug-mode-enable.md)

<!-- document id=163d62f1ca8255295b46e37c75dceb0b842cca94ba0438de9e92927f7fd8f0e1 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-ingest-data-connector.md -->

# `ingestDataConnector`

Triggers the CRM Analytics data connector to run a data sync. This call is the equivalent of clicking **Run Now** in the CRM Analytics Data Manager UI.

## Syntax

```javascript
import { ingestDataConnector } from 'lightning/analyticsWaveApi';
ingestDataConnector({ connectorIdOrApiName: string }): Promise<RestoreDatasetVersion>
```

## CRM Analytics API Resource

```html
POST /wave/dataConnectors/${connectorIdOrApiName}/ingest
```

`ingestDataConnector` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid_ingest.htm).

## Parameters

This parameter is optional.

| Parameter Name         | Type   | Description                                     |
| ---------------------- | ------ | ----------------------------------------------- |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector. |

## Returns

A Promise object that resolves with the [Restore Dataset Version](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_restore_dataset_version.htm) response.

## Usage

Use `ingestDataConnector` to trigger a data sync for a CRM Analytics connector. For example, you can display a list of data connectors and enable data sync for each connector on the list. Running a data connector displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { ingestDataConnector } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class IngestDataConnector extends LightningElement {
  @api idOrApiName;

  ingest(event) {
    ingestDataConnector({ connectorIdOrApiName : this.idOrApiName } })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Success',
            message: 'Data Connector Ingested',
            variant: 'success'
          })
        );
      })
    .catch(error => {
      this.dispatchEvent(
        new ShowToastEvent({
          title: 'Error ingesting data connector',
          message: error.body.message,
          variant: 'error'
        })
      );
    });
  }
}

```

This button calls the `ingestDataConnector()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Ingest"
    icon-name="utility:play"
    icon-position="right"
    onclick={ingest}
  ></lightning-button>
</template>
```

<!-- document id=0a61058c04ef9b62713896e4f9d203292e9ea04b3a76da169cba360cf9aae8a1 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-tools-lint.md -->

# Install ESLint Rules for Lightning Web Security

ESLint rules help you develop code that works with Lightning Web Security (LWS). You can install them on your development machine and run them on your source code.

The ESLint rules are available as an `npm` package that you install locally, and use in an IDE command line.

The ESLint rules are documented in this [GitHub Repository](https://github.com/salesforce/lwsec-docs-mirror/tree/main/packages/%40locker/eslint-plugin-locker/docs/rules).

**note:** The new architecture was developed under the Locker name before the brand change to Lightning Web Security. You can see `locker` used in code and in the `npm` package names. However, the lint rules support Lightning Web Security, not the current Lightning Locker.

The LWS ESLint rules require ESLint 9 or later and use ESLint’s flat configuration format (an `eslint.config.js` file in your project root). The legacy `.eslintrc` configuration format is no longer supported.

If you previously configured LWS ESLint rules using `.eslintrc`:

1. Delete your `.eslintrc` or `.eslintrc.json` file.
2. Remove `ESLINT_USE_FLAT_CONFIG=false` from your environment, if set.
3. Create a new `eslint.config.js` file as shown in the examples.

## Add ESLint Support for Lightning Web Security

1.  On your development system, open a terminal window in your project directory.
2.  Install the node project dependencies.

    ```bash
    $ npm install
    ```

3.  Install ESLint 9 and the LWS configuration package from [https://www.npmjs.com/package/@locker/eslint-config-locker](https://www.npmjs.com/package/@locker/eslint-config-locker).

    ```bash
    $ npm install --save-dev eslint @locker/eslint-config-locker
    ```

4.  Create an ESLint flat configuration file at the root of your project. These files can be CommonJS (`eslint.config.js`) or ES modules (`eslint.config.mjs`) format as shown in these examples.

    - **Common JS format (`eslint.config.js`)**

      ```js
      const lockerConfig = require("@locker/eslint-config-locker");

      module.exports = [...lockerConfig];
      ```

    - **ES Module format (`eslint.config.mjs`)**

      ```js
      import lockerConfig from "@locker/eslint-config-locker";
      export default [...lockerConfig];
      ```

      The default export configures the base rules, which report errors only.

5.  If you want notification of warnings in addition to errors, use the `recommended` configuration instead of the default. The ESLint warnings can be helpful for debugging specific issues, but generate extra information that isn’t necessary for everyday use.

    - **Common JS format (`eslint.config.js`)**

      ```js
      const lockerRecommended = require("@locker/eslint-config-locker/recommended");

      module.exports = [...lockerRecommended];
      ```

    - **ES Module format (`eslint.config.mjs`)**

      ```js
      import lockerRecommended from "@locker/eslint-config-locker/recommended";
      export default [...lockerRecommended];
      ```

    **tip:** To focus only on warnings and errors related to LWS, spread only `@locker/eslint-config-locker/recommended` and omit other lint configurations. The Lightning Web Component (LWC) rules in `@salesforce/eslint-config-lwc/recommended` can generate extraneous output and make it hard to see violations that are specific to LWS.

If you also lint your components with `@salesforce/eslint-config-lwc`, note that version 4.0.0 and later supports flat-configuration only and requires `eslint@9` (use `@salesforce/eslint-config-lwc@3.x` for earlier versions of ESLint). Combine both `recommended` and `@salesforce/eslint-config-lwc` as flat-configuration arrays as shown here.

- **Common JS format (`eslint.config.js`)**

  ```js
  const lwc = require("@salesforce/eslint-config-lwc");
  const lockerRecommended = require("@locker/eslint-config-locker/recommended");

  module.exports = [...lwc.configs.recommended, ...lockerRecommended];
  ```

- **ES Module format (`eslint.config.mjs`)**

  ```js
  import lockerConfig from "@locker/eslint-config-locker";
  import lockerRecommended from "@locker/eslint-config-locker/recommended";
  export default [...lockerRecommended, ...lockerConfig];
  ```

  **note:** When your org upgrades to a new Salesforce release, run `npm update` so your ESLint rules match the LWS distortions in the release. For a list of distortions added in a release, see the [Salesforce Release Notes](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc.htm&type=5).

## Use ESLint Rules in VS Code

Use Visual Studio Code (VS Code) with the [Salesforce Extensions for VS Code](https://developer.salesforce.com/tools/vscode) to develop Lightning components. The ESLint rules for errors against Lightning Web Security are displayed in VS Code where your code violates them. The rules map to distortions that affect your code. The popup for a rule violation includes a link to documentation for the rule.

<!--Here you can see the popup for a lint rule violation with a [link to the documentation](https://github.com/salesforce/lwsec-docs-mirror/blob/main/packages/%40locker/eslint-plugin-locker/docs/rules/distorted-window-fetch.md) for the associated rule.

![Popup for a triggered lint rule](https://developer.salesforce.com/media/lwsec_lint_popup.png)

This popup shows a lint warning, not an error. -->

## Run Base Rules Against Your Project

1.  Install ESLint rules and configurations as described in the [Add ESLint Support for Lightning Web Security](#add-eslint-support-for-lightning-web-security) section.
2.  Run your usual command for linting your code.

    - For a Salesforce DX project, run your configured lint script, such as `npm run lint` or `yarn lint`.
    - If you’re not using a Salesforce DX project, you can run the `eslint` command on your LWC and Aura components. ESLint 9 automatically discovers the `eslint.config.js` file in your project root, so no configuration flags are required. For example, if your components are in the standard Salesforce DX path, run this command:

      ```bash
        # Lint Lightning Web Components
        $ npx eslint force-app/main/default/lwc

        # Or lint both LWC and Aura components
        $ npx eslint force-app/main/default/lwc force-app/main/default/aura
      ```

      The output returns violations found on your components.

      Here’s an example of an LWS error message in some sample CLI output.

      ```bash
      10:16  error  Document#fullscreen is prohibited in Lightning Web Security  @locker/locker/distorted-document-blocked-properties

      ✖ 1 problem (1 error, 0 warnings)

      The error Command failed with exit code 1.

      ```

      Resolve the errors and rerun the base rules against your project.

<!-- document id=307b457cf54cc29cc3b72d4a40876e7e9a5cff1b66c020047a0ddd6fde8bc105 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-installation.md -->

# Install `sfdx-lwc-jest`

Install `sfdx-lwc-jest` and its dependencies into each Salesforce DX project. `sfdx-lwc-jest` works in Salesforce DX projects only.

## Prerequisites

Before installing `sfdx-lwc-jest`, install Node.js and npm.

- [Node.js](https://nodejs.org/)

  This page lists two releases of Node.js. We recommend using the “LTS” (Long-Term Support) version, rather than the “Current” version.

- [npm](https://www.npmjs.com/get-npm)

  When you install Node.js, npm also installs. You may need to update npm though, so visit the npm website for instructions.

## Install Jest and Its Dependencies into Your Project with the Salesforce CLI

The simplest way to install Jest and its dependencies is to run the Salesforce CLI command [`sf force lightning lwc test setup`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_lightning.htm#cli_reference_force_lightning_lwc_test_setup). Run the command from the top-level directory of each Salesforce DX project. This command creates the necessary configuration files and installs the `sfdx-lwc-jest` package for you.

## Install Jest and Its Dependencies Manually

If you work in an environment where you can’t use the Salesforce CLI, you can set up your test dependencies yourself.

To install `sfdx-lwc-jest` and its dependencies, run these commands once from the top directory of each Salesforce DX project.

```bash
npm install
npm install @salesforce/sfdx-lwc-jest --save-dev
```

By default, an SFDX project includes these script entries in the `scripts` block of its `package.json` file. If your project’s file doesn’t include them, add them.

```json
{
  ...
  "scripts": {
    ...
    "test": "npm run test:unit",
    "test:unit": "sfdx-lwc-jest",
    "test:unit:watch": "sfdx-lwc-jest --watch",
    "test:unit:debug": "sfdx-lwc-jest --debug",
    "test:unit:coverage": "sfdx-lwc-jest --coverage",
    ...
  },
  ...
}
```

**See Also**

- [Github repo: sfdx-lwc-jest](https://github.com/salesforce/sfdx-lwc-jest)

<!-- document id=75b4815f3738201d33d4d5d5e353057c457463321d68e98fe76189642ce8675f url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-cli.md -->

# Install the Salesforce CLI

Before you set up your editor and environment for Salesforce DX tools, install the Salesforce CLI. If you want to test components without deploying them to an org, use [Live Preview](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-test-components.md). We recommend installing the new Live Preview experience for improved testing and previewing capabilities.

Use the Salesforce CLI to synchronize source code between your Salesforce orgs and your version control system.

1.  To install the CLI, follow the instructions for your operating system in the [Salesforce CLI Setup Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm), then return here.
2.  To work with Lightning web components, we recommend the latest version of Salesforce CLI. Check the installed version.

    ```bash
    sf plugins --core
    ```

    The command outputs version numbers. For example:

    ```bash
    @salesforce/cli 2.24.3 (core)
    ```

**See Also**

- [Verify Your Installation And Get Version Information](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm#sfdx_setup_install_cli_verify)
- [Update Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_update_cli.htm)

<!-- document id=6b64fb0352beebf2c438dbffa2407388d0694b284b532827afd9088d8066e3e8 url=/developer/current/en-us/lwc/utam/references/interfaces.md -->

# Interfaces

UTAM provides the ability to declare a page object as an interface to abstract page object APIs (declared public methods) from the implementation.

One of the most common use cases is for mobile: a page or component in a mobile application can be WebView or pure native.
Creating a page object for a WebView page is the same as creating a page for desktop. However, for a native page, you can create an interface that's shared between the iOS and Android platforms, and have implementations of the interface for both platforms.

## Interface Declaration

Declare an interface in a separate JSON file.

An interface can contain these properties:

- `interface` Boolean. To distinguish an interface from a regular page object, set the `interface` property to `true`.

- `methods` Array. Declare an interface's API as an array of objects in the `methods` property. Each method object has the following properties:

  - `name` of the method. The name should be unique within the `methods` array.

  - If the method returns a value, set the `returnType`. If the method returns an array, set the `returnAll` property to `true`. See [supported return types](/grammar/method-return-types#supported-return-types).

  - Declare method parameters, if needed, in an `args` array of objects. Each object has the following properties:

    - `name` of the parameter

    - `type` of the parameter. See [supported argument types](/grammar/arguments#argument-types).

- `root` Boolean (Optional). Set `root` to `true` when the page objects that implement the interface should be marked as root. A page object that implements the interface should also set `root` to `true`. A root page object can be loaded directly inside the browser. See [root element](/grammar/root).

- `exposeRootElement` Boolean (Optional). If set to `true`, UTAM creates a public method that returns an instance of the element with the given type. The name of the getter is `getRoot`.

- `type` (Optional). The type of the root element. See [basic element types](/grammar/element-types#basic-elements).

Here's an interface with four methods.

```json
{
  "interface": true,
  "methods": [
    {
      "name": "openMenuSection"
    },
    {
      "name": "clickTabBarItem",
      "args": [
        {
          "name": "item",
          "type": "string"
        }
      ]
    },
    {
      "name": "hasTabBarItem",
      "returnType": "boolean",
      "args": [
        {
          "name": "item",
          "type": "string"
        }
      ]
    },
    {
      "name": "getTabBarItems",
      "returnType": ["clickable"],
      "returnAll": true
    }
  ]
}
```

For every declared interface, the UTAM Java compiler generates a Java interface with method declarations:

```java
public interface NavTabBar extends RootPageObject {

  void openMenuSection();

  void clickTabBarItem(String item);

  Boolean hasTabBarItem(String item);

  List<GetTabBarItemsElement> getTabBarItems();

  interface GetTabBarItemsElement extends Clickable {}
}
```

## Interface Implementation

A page object declares that it implements a declarative interface by using the `implements` property.

```json
{
  "implements": "utam-lightning/pageObjects/global/navigationMenu",
  "elements": [],
  "methods": []
}
```

The page object must:

- Implement all methods declared in the interface

- Be in the same directory as the interface.

Let's look at an example of a page object that has different implementations for different mobile platforms.
To support multiple implementing JSON page objects for a single UTAM interface, use the `profile` property. This property enables UTAM to choose the appropriate implementation depending on the test context. Profile is an array of objects. Set a `platform` property in `profile` to define the supported platforms. The supported values for platform are:

- `ios_phone`

- `ios_tablet`

- `android_phone`

- `android_tablet`

For example, `addConnAndroidImpl.utam.json` defines a shared implementation for Android phone and tablet.

```json
{
   "implements":"utam-salesforceapp/pageObjects/authentication/addConn",
   "profile":[
      {
         "platform": ["android_phone", "android_tablet"]
      }
   ],
   ....
}
```

`addConnAndroidPhoneImpl.utam.json` is for Android phone only.

```json
{
   "implements":"utam-salesforceapp/pageObjects/authentication/addConn",
   "profile":[
      {
         "platform": "android_phone"
      }
   ],
   ....
}
```

`addConniOSImpl.utam.json` is for iOS phone and tablet.

```json
{
   "implements":"utam-salesforceapp/pageObjects/authentication/addConn",
   "profile":[
      {
         "platform": ["ios_phone", "ios_tablet"]
      }
   ],
   ...
}
```

`addConniOSTabletImpl.utam.json` is for iPad only.

```json
{
   "implements":"utam-salesforceapp/pageObjects/authentication/addConn",
   "profile":[
      {
         "platform": "ios_tablet"
      }
   ],
   ...
}
```

In the compiler configuration file, you must configure all possible profile values for your module. Otherwise, the compiler throws an error, such as:

```
utam.core.framework.consumer.UtamError: profile 'platform' does not support value 'android_tablet'
```

Here's an example of a Java compiler configuration file in `compiler.config.json` with a `profiles` property. The configuration file name can be anything. It must just match the name passed as a runtime parameter to the compiler.

```json
{
  ....
  "profiles": [
    {
      "name": "platform",
      "values": [
        "ios_phone",
        "ios_tablet",
        "android_phone",
        "android_tablet"
      ]
    }
  ]
}
```

The compiler configuration file defines the supported `platform` values.

## Interface Implementation Resolution at Run Time

When an instance of the page object is created in a test at runtime, UtamLoader decides which implementating class should be instantiated. UtamLoader references a dependency injections config file, which is a JSON file that declares pairs of an interface and an implementation for each profile.

The dependency injections config is created during page object generation and looks like this:

```json
{
  "platform": {
    "ios_tablet": [
      {
        "interface": "utam.pageObjects.auth.AddConn",
        "implementation": "utam.pageObjects.auth.AddConnIOSTabletImpl"
      }
    ],
    "android_phone": [
      {
        "interface": "utam.pageObjects.auth.AddConn",
        "implementation": "utam.pageObjects.auth.AddConnAndroidPhoneImpl"
      }
    ]
  }
}
```

This particular config tells UtamLoader that if the active profile is "ios_tablet", and `UtamLoader.load(AddConn.class)` is invoked, use the `AddConnIOSTabletImpl` implementation class.

For more details about setting active profiles and using depenency injections configs, please check out the [Java guide](/guide/java-guide) and the [JavaScript guide](/guide/js-guide).

## Default implementation

If an implementing page object doesn't have a `profile` property, it's considered **a default implementation** and is picked up by default.

```json
{
  "default": {
    "impl": [
      {
        "interface": "utam.pageObjects.auth.AddConn",
        "implementation": "utam.pageObjects.auth.AddConnCrossPlatformImpl"
      }
    ]
  }
}
```

<!-- document id=4e406a8bfd0b702551c47edc0850411b2bb1ce0cc01d947ac9eb1de6858dd8ad url=/developer/current/en-us/lwc/slds_linter/guides/use/use-interpret-results.md -->

# Interpret Your Results

Use SLDS Linter to find UI violations if you're working on SLDS 1, SLDS 2 or transitioning from SLDS 1 to SLDS 2. SARIF reports generated by SLDS Linter list all the identified UI violations for currently enabled rules and, when available, include recommendations. [Autofix your code](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-autofix-code.html) or use the recommendations to manually make changes. Open your code in VS Code and review the messages displayed in the SARIF report against the code, to determine which values must be updated or removed.

Here’s ‌the good news! You don’t have to fix all the identified violations to align with SLDS 2 guidelines. Analyze these four types of errors to understand the impact of the identified issues and how to fix them.

| Error Type          | Recommended Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Effort Required to Fix     | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Design tokens       | <ul> <li> Replace with SLDS styling hooks and retain the design tokens as fallback values.</li> <li>Possible to autofix. If your code has implemented design tokens correctly, SLDS Linter autofixes all these issues.</li> </ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Little to no manual effort | Existing code: <br><br> `/* Using --slds-g-color-border-1 as fallback value for --lwc-color-background-1 is not supported. */ .example { color: var(--lwc-color-background-1, var(--slds-g-color-border-1)); }` <br><br> Recommended code: <br><br> `.example { color: var(--slds-g-color-border-1, var(--lwc-color-background-1)); }` <br><br>The `--lwc-color-background-1` token is replaced with the `--slds-g-color-border-1` styling hook. The `--lwc` token is mentioned as the fallback value.           |
| Unsupported classes | <ul> <li> Investigate where unsupported classes are used in your code and remove them, if possible.</li><li> Not possible to autofix.</li> </ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Medium effort              | Existing code:<br><br> `<span class="slds-icon_left"> </span>` <br><br>The `slds-icon_left` class is deprecated in SLDS 2 and must be updated to a class that is supported in SLDS 2.                                                                                                                                                                                                                                                                                                                            |
| Hard-coded values   | <ul><li>Replace with styling hooks and retain the hard-coded values as fallback values.</li><li> Not possible to autofix most of these violations because SLDS Linter can’t automatically determine the context in which a hard-coded value is used.</li><li> Find the correct styling hook to represent the hard-coded value and resolve the issue. Use the [Global Styling Hooks Index](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks) on the SLDS 2 site to find the correct match.</li><li> To narrow your scope for an SLDS 2 transition, if you have limited bandwidth to manually uplift your code, first focus on hard-coded color values. When you have time, focus on uplifting other hard-coded values, like padding, spacing, and typography. Color values impact your UI the most, especially when personalization features like dark mode are used. <br> **Tip:**<br> The most critical color values to resolve are your UI’s surface color and the color of any text that appears on top of the surface.<br> To find the best styling hook match, first look at the semantic styling hooks, then look at the system palette, and finally the color palette if needed. <br>For more information, see the [Color](https://www.lightningdesignsystem.com/2e1ef8501/p/655b28-color/b/76ba78) section on the SLDS 2 site.</li></ul> | High effort                | Existing code: <br><br>`.THIS .container { color: #5c5c5c; border-color: #5c5c5c; }`<br><br>Recommended code:<br><br> `.THIS .container { color: var(--slds-g-color-on-surface-1,#5c5c5c); border-color:var(--slds-g-color-border-2,#5c5c5c); }` <br><br>In this example, the `#5c5c5c` hard-coded value for the `color` property is replaced with an `on-surface` semantic styling hook. The `#5c5c5c` hard-coded value for the `border-color` property is replaced with a `color-border` semantic styling hook |
| Unsupported hooks   | <ul><li>Not possible to autofix.</li><li> Analyze the occurrences of unsupported hooks, but don’t remove them. It could impact how your UI behaves with an SLDS 1 implementation or in backwards compatibility with SLDS 1 from an SLDS 2 implementation. <br>**Important:** <br>If you're an Independent Software Vendor (ISV) and work with customers who aren't on SLDS 2, don’t modify unsupported hooks.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Little to no effort        | Existing Code:<br><br>`.THIS .action-link { color: var(--slds-g-link-color) }` <br><br> Here the `--slds-g-link-color` styling hook is deprecated.                                                                                                                                                                                                                                                                                                                                                               |

Remember that SLDS Linter results will change as your code changes. So, regularly test your code in a sandbox or User Acceptance Testing (UAT) environment and handle the identified issues using the information in this guide and our resources on the SLDS 2 site.

**See Also**

- [Autofix Your Code](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-autofix-code.html)
- [SLDS Linter Commands](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-commands.md)
- [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-rules.md)

<!-- document id=cff1db8a382915d20b510fb2d4a34314b6cf7dcc940088d48a0541c64ecd7e3b url=/developer/current/en-us/lwc/slds-validator/guides/interpret-your-results.md -->

# Interpret Your Results

To make recommendations, SLDS Validator scans your code for specific types of violations. The recommendations made depend on your codebase and whether you’re using SLDS 1 or SLDS 2. Read this guide to understand the recommendations and options SLDS Validator provides.

## What Is SLDS?

Salesforce Lightning Design System (SLDS) is a framework that helps developers and designers build custom applications and components for the Salesforce Lightning Platform. SLDS provides a set of guidelines, CSS, and JavaScript to create user interfaces that are accessible, mobile-first, and responsive.

## What Is SLDS 2?

SLDS 2 is the latest version of SLDS. SLDS 2 has a new architecture that prioritizes CSS custom properties. Use SLDS 2 to make Salesforce your own with its AI-ready design system, configurable UI components, and an advanced theming engine. Certain types of design code are deprecated in SLDS 2. Read more on [www.lightningdesignsystem.com](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2).

## —lwc CSS Custom Property Recommendations

Migrate your `–lwc` custom properties to new global semantic styling hooks. If you don’t see a recommendation, there’s no matching global styling hook and the `–lwc` custom property is deprecated in SLDS 2.

### -lwc Example

`color: var(—lwc-brandPrimary);`

## Aura Design Token Recommendations

Aura design tokens are deprecated styling APIs that are only available in Aura. Aura design tokens don’t exist in SLDS 2. Replace your Aura design tokens with global styling hooks.

### Aura Example

`.THIS {`  
`color: t(brandPrimary);`  
`background: token(brandBackgroundPrimary);`  
`}`

## –sds Styling Hook Recommendations

`--sds` styling hooks started as a styling API and still exists as an internal styling API within SDS primitives. Replace `–sds` styling hooks with an equivalent `–slds` styling hook. Read about any exceptions in the SLDS Validator recommendation message.

### -sds Example

`.THIS {`  
**`--sds-`**  
`color: --sds-`  
`}`

## BEM Recommendations

Block, element, and modifier (BEM) is a well-known method of naming components. BEM is also a nomenclature that SLDS no longer uses. If your code is still uses a BEM-named component, you see an SLDS Validator recommendation with a replacement value.

<!-- document id=6d14d7587e0d7b23fa7c9ac959baa428f5b5e7c7d98a61dc654236e619d42a26 url=/developer/current/en-us/lwc/lwc/guides/reference/appreviewservice/reference-lightning-appreviewservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether AppReviewService functionality is available.

## Syntax

```javascript
import { getAppReviewService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_appreviewservice_compatibility.htm) and `false` otherwise.

## Usage

Use this function to disable or hide app review-related features on platforms where app review services aren’t supported. For example:

```javascript
handleBeginClick(event) {
  const myAppReviewService = getAppReviewService();
  if(myAppReviewService.isAvailable()) {
    // Perform app review related operations
  }
  else {
    // AppReviewService not available
    // Handle with message, error, beep, and so on
  }
}
```

**See Also**

- [AppReviewService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_appreviewservice_example.htm)

<!-- document id=9c69414ab870731c81d9e245fd738e5a8d76c55574330c902c4885d309dde20d url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-isavailable.md -->

# `isAvailable()`

Use this function to determine whether scanner functionality is available.

## Syntax

```
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_compatibility.htm), and `false` otherwise.

## Usage

Use this function to disable or hide scan features on platforms where scanning isn’t supported. For example:

```javascript
handleBeginScanClick(event) {
  const myScanner = getBarcodeScanner();
  if(myScanner.isAvailable()) {
    // Perform scanning operations
  }
  else {
    // Scanner not available
    // Not running on hardware with a scanner, or some other context error
    // Handle with message, error, beep, and so on
  }
}
```

This function is also useful to avoid entering complicated logic surrounding scanning when it’s guaranteed to fail. However, it isn’t _required_ to check before attempting a scan. Either way, your code should handle errors such as attempting a scan on an unsupported device.

<!-- document id=6a7edbb732ddeb21f077995cc5ad0efe5bf988729d675abee9615860f6e6080d url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether BiometricsService functionality is available.

## Syntax

```javascript
import { getBiometricsService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice_compatibility.htm) and `false` otherwise.

## Usage

```javascript
handleVerifyClick(event) {
    const myBiometricsService = getBiometricsService();
    if(myBiometricsService.isAvailable()) {
        // Perform biometrics service operations
    }
    else {
        // BiometricsService not available or consuming app hasn’t implemented it.
        // Handle with message, error, beep, and so on
    }
}

```

**See Also**

- [BiometricsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice_example.htm)

<!-- document id=b28a4217d06850fabb9042c72fe849b59c9c84801001174eb5462244adb68439 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether CalendarService functionality is available.

## Syntax

```
import { getCalendarService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice_compatibility.htm), and `false` otherwise.

## Usage

Use this function to disable or hide calendar-related features on platforms where calendars aren’t supported. For example:

```javascript
handleGetCalendarClick(event) {
  const myCalendarService = getCalendarService();
  if(myCalendarService.isAvailable()) {
    // Perform calendar-related operations
  }
  else {
    // CalendarService not available, or consuming app hasn’t implemented it
    // Not running on a device with native calendar functionality, etc.
    // Handle with message, error, beep, and so on
  }
}
```

<!-- document id=a5e3f9b5fd2fa40c27605924fc5ba67d1bd2c3b8e8f71c0f84e69efa9d279760 url=/developer/current/en-us/lwc/lwc/guides/reference/contactsservice/reference-lightning-contactsservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether ContactsService functionality is available.

## Syntax

```javascript
import { getContactsService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_contactsservice_compatibility.htm) and `false` otherwise.

## Usage

Use this function to disable or hide contacts-related features on platforms where contacts aren’t supported. For example:<!-- Future work: W-11139612, review the else clause language and update.-->

```javascript
handleFindMeClick() {
  const myContactsService = getContactsService();
  if (myContactsService.isAvailable()) {
    // Perform contacts-related operations
  }
  else {
    // ContactsService isn’t available, or consuming app hasn’t implemented it
    // Not running on a device with a contacts address book, etc.
    // Handle with message, error, beep, and so on
  }
}
```

**See Also**

- [ContactsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_contactsservice_example.htm)

<!-- document id=6e09f1e564a48d42cecbea95d1d4a0a17b09b1d8b75ee5a3bde023642135b954 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-isavailable.md -->

# `isAvailable()`

Use this function to determine whether DocumentScanner functionality is available.

## Syntax

```javascript
import { getDocumentScanner } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_documentscanner_compatibility.htm), and `false` otherwise.

## Usage

Use this function to disable or hide scan features on platforms where scanning isn’t supported. For example:

```javascript
handleGetScannerClick(event) {
    const myDocumentScanner = getDocumentScanner();
    if(myDocumentScanner.isAvailable()) {
        // Perform document scanning operations
    }
    else {
        // DocumentScanner not available, or consuming app hasn’t implemented it
        // Not running on a device with camera or OCR functionality, etc.
        // Handle with message, error, beep, and so on
    }
}
```

<!-- document id=9d3eab8d5c5a27107955b482c312ecdad4972cff36c2e37adaffb51b6005c6af url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-isavailable.md -->

# isAvailable()


Determine whether GeofencingService functionality is available.

## Syntax

```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_geofencingservice_compatibility.htm) and `false` otherwise.

## Usage

Use this function to disable or hide geofencing-based features on platforms where geofencing isn’t supported. For example:                                                                                                                                                                                                                                                                                                                                                                


```js
handleAddGeofenceClick() {
    const myGeofencingService = getGeofencingService();
    if (myGeofencingService.isAvailable()) {
        // Perform geofencing service requests
    }
    else {
        // GeofencingService isn’t available or consuming app hasn’t implemented it.
        // Handle with message, error, beep, and so on
    }
}
```

<!-- document id=58717079290e4b9d25fe860152ae9348d7dbc4691393cf4294253829fd9098f6 url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether HealthService functionality is available.

## Syntax

```javascript
import { getHealthService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice_compatibility.htm) and `false` otherwise.

## Usage

Use this function to disable or hide health data features on platforms where HealthService isn’t supported. For example:

```javascript
handleGetWeightClick() {
  const myHealthService = getHealthService();
  if (myHealthService.isAvailable()) {
    // Perform health data operations
  }
  else {
    // HealthService isn’t available, or consuming app hasn’t implemented it
    // Not running on a device with a health store, etc.
    // Handle with message, error, beep, and so on
  }
}
```

**See Also**

- [HealthService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice_example.htm)

<!-- document id=00206064d3173342c43798dc364076940f8e9e87e413a7665cfae7bf61ee03d5 url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-isavailable.md -->

# `isAvailable()`

Determines whether location service functionality is available.

## Syntax

```javascript
import { getLocationService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_locationservice_compatibility.htm), and `false` otherwise.

## Usage

Use this function to disable or hide location-based features on platforms where location services aren’t supported. For example:

```javascript
handleFindMeClick() {
  const myLocationService = getLocationService();
  if (myLocationService.isAvailable()) {
    // Perform location-based requests
  }
  else {
    // LocationService isn’t available
     // Not running on hardware with GPS, or not inside mobile app
    // Handle with message, error, beep, and so on
  }
}
```

**See Also**

- [LocationService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_locationservice_example.htm)

<!-- document id=699746078d8413fe361273584ec7ba1f8a1f7bc119dfc95de4769885291774f9 url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-isavailable.md -->

# `isAvailable()`

Use this function to determine whether NFCService functionality is available.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
isAvailable(): Boolean
```

## Parameters

None.

## Returns

Returns `true` when used on a [supported device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_nfcservice_compatibility.htm), and `false` otherwise.

## Usage

Use this function to disable or hide NFC operations on platforms where interacting with NFCs isn’t supported. For example:

```javascript
handleGetNFCClick(event) {
    const myNFCService = getNFCService();
    if(myNFCService.isAvailable()) {
        // Perform NFC operations
    }
    else {
        // NFCService not available, or consuming app hasn’t implemented it
        // Not running on a device with NFC functionality, etc.
        // Handle with message, error, beep, and so on
    }
}
```

<!-- document id=a3ab977ac97a8ff418736a1038af6b46622f6dc8c95384ff8323fe0ece469b30 url=/developer/current/en-us/lwc/lwc/guides/reference/biometricsservice/reference-lightning-biometricsservice-isbiometricsready.md -->

# `isBiometricsReady(options)`

Verify if the biometrics hardware or pin code is available to use to verify the user’s device ownership.

## Syntax

```javascript
import { getBiometricsService } from 'lightning/mobileCapabilities';
isBiometricsReady(options: BiometricsServiceOptions): Promise<Object>;
```

## Parameters

- `options`—(Required) A [`BiometricsServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-biometricsservice-data-types.md) object to configure the BiometricsService request.

## Returns

A Promise object that resolves as a Boolean value. `true` if the biometrics hardware or pin code is available for use and `false` otherwise. If an error is encountered, the error is returned via a rejected promise.

## Usage

```javascript
myBiometricsService
  .isBiometricsReady(options)
  .then((results) => {
    if (result === true) {
      console.log("✔ Biometrics ready.");
    } else {
      console.log("𐄂 Biometrics unavailable.");
    }
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

**See Also**

- [BiometricsService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_biometricsservice_example.htm)

<!-- document id=a344d1c128fd27f932dae506c1dd66137d4b7eb3abef5f7e2f59b21ebbfcb764 url=/developer/current/en-us/lwc/lwc/guides/js/js-intro.md -->

# JavaScript

Every component must have a [JavaScript file](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md). JavaScript files in Lightning web components are ECMAScript 6 (ES6) modules.

In this section, you can learn how to:

- [Share JavaScript code between Lightning web components](https://developer.salesforce.com/docs/platform/lwc/guide/js-share-code.md)
- [Use third-party libraries with Locker or Lightning Web Security](https://developer.salesforce.com/docs/platform/lwc/guide/js-third-party-library.md)
- [Call APIs from JavaScript](https://developer.salesforce.com/docs/platform/lwc/guide/js-api-calls.md)
- [Dynamically Instantiate Components](https://developer.salesforce.com/docs/platform/lwc/guide/js-dynamic-components.md)

For documentation on JavaScript functions, see the [Mozilla Developer Network (MDN) JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference).

## JavaScript for Lightning Web Components

To speed up your LWC development, it's helpful for you to be familiar with these JavaScript features.

- Arrays ([Array.prototype.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [Array.prototype.filter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter))
- [Arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions)
- [Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes)
- [Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
- Objects ([Object.keys](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys), [Object.values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values))
- [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
- [Variable declarations with `const` and `let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements#declaring_variables)

**note:** Many of our examples in [lwc-recipes](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc) and in this developer guide now use [async/await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) instead of [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). async/await helps you write code that's more intuitive and resembles synchronous code. async/await is compatible with ordinary try/catch blocks around asynchronous code.

## LWC JavaScript Best Practices

LWC is an abstraction layer on top of [Web Component APIs](https://developer.mozilla.org/en-US/docs/Web/Web_Components) that simplifies your developer experience and improves productivity. To learn about LWC best practices, see [Best Practices for Development with Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-best-practices.md).

<!-- document id=ab1865c56377e877d02c93424c31e97818494602fe404228afa456f3154542ae url=/developer/current/en-us/lwc/lightning-components-security/guides/js/js-strict-mode-intro.md -->

# JavaScript Strict Mode Enforcement

In JavaScript, strict mode is enforced in modules but optional in regular programs. However, Lightning Web Security (LWS) and Lightning Locker implicitly enable JavaScript strict mode everywhere. You don’t need to specify `"use strict"` in your code. JavaScript strict mode makes code more secure, robust, and supportable.

When strict mode is enabled and unsafe actions are taken, JavaScript throws errors that would otherwise be suppressed. Examples of unsafe actions include assigning values to non-writable properties and using a variable that hasn’t been declared. Reporting these actions can catch situations when a variable name has been mistyped.

A few common stumbling points when using strict mode are:

- You must declare all variables. Use any of the `var`, `let`, or `const` declarations in libraries or modules.
- To share code between components, you must follow the steps outlined in [Share JavaScript Code](/docs/platform/lwc/guide/js-share-code.html) for Lightning web components and [Sharing JavaScript Code Across Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/security_share_code.htm) for Aura components, respectively.
- The libraries that your components use must also work in strict mode but don’t need to specify `"use strict"` in their own code. For developing Lightning web components, see [Use Third-Party JavaScript Libraries](/docs/platform/lwc/guide/js-third-party-library.html). For developing Aura components, see [Using External JavaScript Libraries](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_libs_platform.htm).
- If you use third-party libraries that specify `"use strict"` explicitly, you can get errors under LWS. See [Third-Party Library Considerations for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-js.md#third-party-library-sets-strict-mode).

For more information about JavaScript strict mode, see the [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode).

<!-- document id=ebce2a15dcd53fbf78b19aca754d5d4d92cb366e20d7fe829675873fe6d4e557 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-patterns.md -->

# Jest Test Patterns and Mock Dependencies

While testing with Jest, follow these patterns and practices to isolate behavior and maximize the efficiency of your unit tests.

## Test a Property Change

Let’s start by looking at a simple property change. Component rerendering upon a property change is asynchronous, so the order in which something is added to the DOM isn’t always predictable. We recommend that your test waits for a value change to be reflected in the DOM before checking for the expected behavior. One technique uses a `Promise.resolve()` statement to check the value after the page element changes, as follows:

1.  Add your component to the DOM.
2.  Change the property value.
3.  Wait for the component to rerender by returning a `Promise.resolve()` value.

```javascript
it("Renders with Hello Matt", () => {
  const element = createElement("c-hello-component", {
    is: HelloComponent,
  });
  document.body.appendChild(element);

  element.person = "Matt";

  return Promise.resolve().then(() => {
    const pTag = element.shadowRoot.querySelector("p");
    expect(pTag.textContent).toEqual("Hello, Matt!");
  });
});
```

**tip:** For more information, see the blog post [Testing Lightning Web Components by Matt Goldspink at Vlocity](https://www.mattgoldspink.co.uk/testing-lightning-web-components/).

## Test a Component with Attributes

To expand on our example, let’s add an attribute. Attributes let you change one value in a test to see how a change renders. Use a `Object.assign()` statement to set an attribute before the `appendChild` call like:

```javascript
Object.assign(element, attributes);
document.body.appendChild(element);
```

For example, let’s set the background color in our initial test to red:

```javascript
it("Renders with Hello Matt", () => {
  const element = createElement("c-hello-component", {
    is: HelloComponent,
  });
  Object.assign(element, { backgroundColor: "red" });
  document.body.appendChild(element);

  element.person = "Matt";

  return Promise.resolve().then(() => {
    const pTag = element.shadowRoot.querySelector("p");
    expect(pTag.textContent).toEqual("Hello, Matt!");
  });
});
```

## Mocking

Your unit testing likely involves more than just an update to a simple UI element. Some code is dependent upon the behavior of certain dependencies, such as imported modules, Lightning base components, and event handlers. But, you want your code to be in a consistent environment, free from variable behavior and timing of server calls, database requests or remote access API. The following sections include guidance on mocking behavior of these dependencies for unit testing. Mocking is a common testing practice that isolates the behavior of the code you’re testing.
Your unit testing likely involves more than just an update to a simple UI element. Some code is dependent upon the behavior of certain dependencies, such as imported modules, Lightning base components, and event handlers. But, you want your code to be in a consistent environment, free from variable behavior and timing of server calls, database requests or remote access API. The following sections include guidance on mocking behavior of these dependencies for unit testing. Mocking is a common testing practice that isolates the behavior of the code you’re testing.

## Lightning Base Component Mocks

Salesforce provides mock components in the [sfdx-lwc-jest repo](https://github.com/salesforce/sfdx-lwc-jest/) and you can find the source for the components in the [lightning-stubs directory](https://github.com/salesforce/sfdx-lwc-jest/tree/master/src/lightning-stubs). Use these mock components for tests that include base components. The mock components match the API of the actual components but don’t have all the functionality so they serve as good resources for testing. Even though these mock components don’t fire any events, you can still invoke their event handlers.

For example, look at the [`miscToastNotification.js`](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/miscToastNotification/__tests__/miscToastNotification.test.js) example in our [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/). To simulate user input, the `inputTitleEl` constant references a mock `lightning-input` element provided by sfdx-lwc-jest. We can still query for it in the DOM and dispatch an event from it to invoke the `change` handler we wired up to it. We use a mock component to maintain control over the input values since we only want to test the behavior of the notification.

```javascript
// Select input field for simulating user input
const inputMessageEl = element.shadowRoot.querySelector('lightning-input[data-id="messageInput"]');
inputMessageEl.value = TOAST_MESSAGE;
inputMessageEl.dispatchEvent(new CustomEvent("change"));
```

Keep the following in mind as you work with our mock components.

- We recommend that your tests don’t rely on the order in which slots are rendered. For example, say that there are two named slots: `actions` and `todos`. If the expected content is present, your test passes even if the mock (or real) component swaps the order in which those slots are rendered.
- Lightning base components have some properties that aren’t reflected as attributes in the DOM. For example, in `lightning-button` you can set the property `iconPosition`, which is used to determine which SLDS class to use for the button and isn't a rendered value. Design your test cases to account for this behavior, and don’t assume that all properties are reflected as attributes.
- No events are fired from these mocks but you can call `dispatchEvent()` against them.

## Event Handler Mocks

Looking at the same [`miscToastNotification.js`](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/miscToastNotification/__tests__/miscToastNotification.test.js) example, you can see a mock event handler, too. This test defines several constant values, then the `ShowToastEventName` event triggers `jest.fn()` that inserts the constants into the `lightning-input` element.

```javascript
const TOAST_TITLE = "The Title";
const TOAST_MESSAGE = "The Message";
const TOAST_VARIANT = "warning";

// Create initial element
const element = createElement("c-misc-toast-notification", {
  is: MiscToastNotification,
});
document.body.appendChild(element);

// Mock handler for toast event
const handler = jest.fn();
// Add event listener to catch toast event
element.addEventListener(ShowToastEventName, handler);
```

At the end of the test, verify that the event handler was called as expected, and with the correct parameters.

```javascript
return Promise.resolve().then(() => {
  // Check if toast event has been fired
  expect(handler).toHaveBeenCalled();
  expect(handler.mock.calls[0][0].detail.title).toBe(TOAST_TITLE);
  expect(handler.mock.calls[0][0].detail.message).toBe(TOAST_MESSAGE);
  expect(handler.mock.calls[0][0].detail.variant).toBe(TOAST_VARIANT);
});
```

## Module Import Mocks

To create references to mock components for more control over component behavior, add [`moduleNameMapper`](https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring) settings in the `jest.config.js` file. To see an example, look at how [`jest.config.js`](https://github.com/trailheadapps/lwc-recipes/blob/master/jest.config.js) in the lwc-recipes repo references some mock components with module names.

```javascript
const { jestConfig } = require("@salesforce/sfdx-lwc-jest/config");
module.exports = {
  ...jestConfig,
  moduleNameMapper: {
    "^@salesforce/apex$": "<rootDir>/force-app/test/jest-mocks/apex",
    "^lightning/navigation$": "<rootDir>/force-app/test/jest-mocks/lightning/navigation",
    "^lightning/platformShowToastEvent$":
      "<rootDir>/force-app/test/jest-mocks/lightning/platformShowToastEvent",
    "^lightning/uiRecordApi$": "<rootDir>/force-app/test/jest-mocks/lightning/uiRecordApi",
  },
};
```

Now, let’s look at how this configuration is used in [`miscToastNotification.test.js`](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/miscToastNotification/__tests__/miscToastNotification.test.js) in the lwc-recipes repo. It has an `import` statement:

```javascript
import { ShowToastEventName } from "lightning/platformShowToastEvent";
```

Without the `moduleNameMapper` entry, this `import` statement resolves to the stub [https://github.com/salesforce/sfdx-lwc-jest/blob/master/src/lightning-stubs/platformShowToastEvent/platformShowToastEvent.js](https://github.com/salesforce/sfdx-lwc-jest/blob/master/src/lightning-stubs/platformShowToastEvent/platformShowToastEvent.js).

With the `moduleNameMapper` entry, this `import` statement resolves to the jest-mocks custom stub [https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/test/jest-mocks/lightning/platformShowToastEvent.js](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/test/jest-mocks/lightning/platformShowToastEvent.js). The mock stub has custom logic that adds other properties to the event object.

**note:** If you override the default `jest.config.js` file with a custom `setupFilesAfterEnv` option, merge the values with those values defined in `@salesforce/sfdx-lwc-jest/config`.

## `@salesforce` Scoped Imports

In your test environment, your component likely doesn’t have access to your production schema. When you import references to namespaces, mock the return value as a placeholder during the test.

In Jest tests, we use a [jest-transformer](https://github.com/salesforce/lwc-test/tree/master/packages/%40lwc/jest-transformer) to convert the `@salesforce/label` import statement into a variable declaration. The value is set to the label path. By default, `myImport` is assigned a string value of `c.specialLabel`. You can use `jest.mock()` to provide your own value for an import. This example returns the string `value set in test` instead of `c.specialLabel`.

```javascript
import myImport from "@salesforce/label/c.specialLabel";

jest.mock(
  "@salesforce/label/c.specialLabel",
  () => {
    return { default: "value set in test" };
  },
  { virtual: true },
);
```

## Looking for More Examples?

See the [lwc directory of our lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc). Many recipes have a `__tests__` directory with commented jest tests.

**See Also**

- [Write Jest Tests for Lightning Web Components That Use the Wire Service](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-wire-utility.md)
- [Write Jest Tests: Test Imperative Apex Methods](https://developer.salesforce.com/docs/platform/lwc/guide/unit-testing-using-jest-create-tests.md#test-imperative-apex-methods)

<!-- document id=cea1cae4c4e817d4ea97c364fb634853ebe083ac6ad77a46c3520b7934e436e1 url=/developer/current/en-us/lwc/utam/references/grammar.md -->

# JSON Grammar

The JSON grammar describes the elements that you can use in a JSON page object.

Here's a sample outline of a page object.

```json
{
  "elements": [],
  "methods": [],
  "shadow": {
    "elements": []
  },
  "root": true,
  "selector": {
    "css": "one-record-home"
  }
}
```

For more details, start with [Root Elements](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/root-elements.md).

<!-- document id=a33578549a86d75593a12813a8412e1ca2720cbca7069170133846ce6d15f07d url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks.md -->

# Lifecycle Hooks

A **lifecycle hook** is a callback method that triggers at a specific phase of a component instance’s lifecycle. With LWC, you can use the following lifecycle hooks.

- [`constructor()`](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-created.md)
- [`connectedCallback()` and `disconnectedCallback()`](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom.md)
- [`renderedCallback()`](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-rendered.md)
- [`errorCallback()`](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-error.md)

Lightning web components have a **lifecycle** managed by the framework. The framework creates components, inserts them into the DOM, renders them, and removes them from the DOM. It also monitors components for property changes.

This diagram shows the flow of the component lifecycle from creation through render.

![Shows the lifecycle flow of a component instance from creation through renderedCallback.](https://developer.salesforce.com/media/render.png)

This diagram shows what happens when a component instance is removed from the DOM.

![Shows lifecycle for the disconnectedCallback.](https://developer.salesforce.com/media/disconnect.png)

**See Also**

- [Wire Service Data Lifecycle](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md#wire-service-data-lifecycle)

<!-- document id=96a9d22dd7720328c9a394bba9a5ed253904307b7ec61e2dc405e0a5fe04aac8 url=/developer/current/en-us/lwc/lwc/guides/create/create-light-dom.md -->

# Light DOM

Lightning Web Components currently enforces shadow DOM on every component, encapsulating a component’s internal markup and making it inaccessible to programmatic code. When you use light DOM, your component lives outside the shadow DOM and avoids shadow DOM limitations. This approach eases third-party integrations and global styling.

Let's look at how the different DOM structures render in the DOM before we dive into details about light DOM. First, consider some markup for a shadow tree. [Native shadow DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom.md) renders components within the `#shadow-root` tag. However, Lightning Experience and Experience Cloud use [synthetic shadow](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md) instead, which mimics native shadow behavior.

With light DOM, the component content is attached to the host element instead of its shadow tree. It can then be accessed like any other content in the document host, providing similar behavior to content that's not bound by shadow DOM.

```html
<my-app>
  <my-header>
    <p>Hello World</p>
  </my-header>
</my-app>
```

For a comprehensive overview, see [Google Web Fundamentals: Shadow DOM v1](https://developers.google.com/web/fundamentals/web-components/shadowdom?hl=en#lightdom).

Light DOM provides several advantages over shadow DOM.

- **CSS theming and branding**: Light DOM supports global styling, making it easy to apply custom branding to your components and child components.
- **Third-party tooling and testing**: With light DOM, third-party tools can traverse the DOM, enabling standard browser query APIs like `querySelector` and `querySelectorAll`, without traversing the shadow root. For example, light DOM enables standard components in [LWR sites](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/intro.htm) to track events.
- **Accessibility**: Light DOM doesn't scope IDs and enables two separate components to reference an ID on the other. For example, `<label for="my-input">` can reference `<input type="text" id="my-input">` even if the elements are in separate components.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has light DOM examples. Look for components that start with `lightDom`, such as [lightDomQuery](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/lightDomQuery).

## Guidelines for Working with Light DOM

Using light DOM exposes your components to DOM scraping, so if you're working with sensitive data, we recommend using shadow DOM instead. In other words, light DOM doesn't provide the benefits that come with shadow DOM encapsulation, which prevents unauthorized access into the shadow tree. Since the DOM is open for traversal by other components and third-party tools, you are responsible for securing your light DOM components.

Consider these best practices when using both light DOM and shadow DOM in your app.

- You can nest a light DOM child component in a parent shadow DOM component and vice versa.
- We recommend encapsulating deeply nested light DOM components in a single shadow DOM component at the top level. Then, you can share styles between all the components under the shadow root.
- Be careful when querying elements or injecting styles at the document level. A shadow tree can sit between the document and your component.
- You can override shadow DOM styles via [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and [::part](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). However, the component owner is in charge of exposing the extension points, which prevents downstream consumers from styling arbitrary elements.

## What's Not Available for Light DOM

- Restricting light DOM to specific namespaces isn’t supported.
- Distributing components rendered in light DOM isn’t supported. Component references in a managed package use the `c` namespace and would result in a namespace conflict.
- Base components are always rendered in shadow DOM.
- Aura components can't use light DOM. However, an Aura component can contain an LWC component that uses light DOM.
- Lifecycle hooks on slots are never invoked since the `slot` element does not render in the DOM.
- Using slots inside a `for:each` iterator is not supported. For example:

<!-- prettier-ignore -->
  ```html
  <!-- This results in a runtime error -->
  <template for:each={items} for:item="item">
    <div key={item.id}>
      <my-repeateditem item={item}>
        <slot></slot>
      </my-repeateditem>
    </div>
  </template>
  ```

## Lightning Locker Considerations

Top-level light DOM components aren't protected by [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html) or [Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html). Always nest light DOM components somewhere within a shadow DOM component. If you expose a light DOM component at the top-level of your component hierarchy, code from other namespaces can read the content of the component, for example.

Disabling Locker, such as [in Experience Builder sites](https://help.salesforce.com/s/articleView?id=experience.networks_security_csp_scriptlevel.htm), means that you won't receive the security benefits from Locker. Make sure that you understand the ramifications of a more relaxed CSP environment on your Experience Builder site. See [CSP and Lightning Locker Design Considerations](https://help.salesforce.com/s/articleView?id=experience.networks_security_csp_tips.htm).

In [Aura-based Experience Builder sites](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_builder_intro.htm), DOM access using `this.querySelector()` and other Web APIs are blocked by Lightning Locker. If you're using light DOM in Aura-based Experience Cloud sites, ensure that there's at least one LWC shadow DOM component as an ancestor to the light DOM component. Using a shadow DOM component means you encapsulate the component’s internal markup and are subject to shadow DOM limitations.

**note:** Beginning in Winter ’23, if Lightning Web Security (LWS) is enabled in the org, any Lightning web components contained in Aura sites are protected by LWS instead of Lightning Locker. If you disable Lightning Locker for the site, you also disable Lightning Web Security.

## Compare Light DOM and Shadow DOM

Due to its strong encapsulation, shadow DOM is the recommended way to author components. It hides your component's internals so consumers can only use its public API.

Shadow DOM isn't suitable in the following cases.

- Building a highly customizable UI, where you want complete control over a web app's appearance.
- Using third-party libraries. Many popular libraries aren't compatible with shadow DOM.

Light DOM is a better fit in those cases, but note that consumers can access your component's internals as they can with your public API. Allowing such access makes it challenging to implement changes without impacting your consumer's code.

Here are pros and cons in using one over the other.

|                                              | Shadow DOM                                                                                             | Light DOM                                                                |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **Security**                                 | Strong component encapsulation protects components from unauthorized access                            | Weak encapsulation makes components open to unauthorized access          |
| **Portability**                              | Highly portable with access controlled through public APIs                                             | Susceptible to breaking changes caused by component authors or consumers |
| **Styling**                                  | Requires CSS custom properties to override styles                                                      | Easy to override styles                                                  |
| **Third-party library and tool integration** | Limited compatibility with third-party libraries or tools requiring DOM traversal or event retargeting | Simple integration with third-party libraries and tools                  |

When working with third-party libraries, such as Google Analytics or another instrumentation library, you don't have to use light DOM if your shadow DOM component exposes the right APIs. Let's say you want to instrument click interactions on a button:

```html
<!-- myButton.html example -->
<template>
  <button>{label}</button>
</template>
```

With light DOM, you can attach a click event listener on the `button` element. If you render the component in shadow DOM, the `button` element isn’t accessible from outside the component. With shadow DOM, `<button>` becomes an internal implementation detail of the `my-button` component. In this case, the correct approach to instrument this component is to add a click handler on `my-button` itself to instrument it.

<!-- prettier-ignore -->
```html
<!-- myComponent.html example -->
<template>
  <my-button label="click me" onclick={handleClick}></my-button>
</template>
```

Expose only the bare minimum you want to instrument since exposing your internal events can weaken your component's encapsulation. While the preceding example isn’t always possible, we recommend you explore your options before selecting the best fit for your use case.

## Enable Light DOM in Your Component

To enable light DOM, you start by setting the `renderMode` static property in your component class:

```javascript
import { LightningElement } from "lwc";

export default class LightDomApp extends LightningElement {
  static renderMode = "light"; // the default is 'shadow'
}
```

Then use the `lwc:render-mode` root template directive, which is required for components using light DOM.

```html
<template lwc:render-mode="light">
  <my-header>
    <p>Hello World</p>
  </my-header>
</template>
```

**note:** Changing the value of the `renderMode` static property after instantiation doesn't impact whether components render in light DOM or shadow DOM.

## Work with Light DOM

Migrating a component from shadow DOM to light DOM requires some code changes. The [shadow tree affects how you work with CSS, events, and the DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom.md). Consider the differences described in the following sections when you work with light DOM.

## Composition

Your app can contain components that use either shadow or light DOM. In this example template, `my-app` uses shadow DOM and contains several components: `my-header` uses light DOM and `my-footer` uses shadow DOM.

<!-- prettier-ignore-start -->
```html
<my-app>
  #shadow-root 
  | <my-header>
  |   <p>Hello World</p>
  | </my-header>
  | <my-footer>
  |   #shadow-root 
  |   |  <p>Footer</p>
  | </my-footer>
</my-app>
```
<!-- prettier-ignore-end -->

A light DOM component can contain a shadow DOM component. Similarly, a shadow DOM component can contain a light DOM component.

**tip:** If you have deeply nested components, consider a single shadow DOM component at the top level with nested light DOM components. This structure allows you to freely share styles between all child components within the one shadow root.

## Accessibility

Unlike synthetic or native shadow, light DOM doesn't scope IDs to an individual component. Instead, it enables a component to reference an ID on a separate component. This advantage enables you to link two elements using IDs and ARIA attributes by placing them in the same shadow root.

Consider this example with two sibling components.

```html
<!-- container.html -->
<template>
  <c-label></c-label>
  <c-input></c-input>
</template>
```

The `c-label` component contains a `<label>` element with an `id` attribute.

```html
<!-- label.html -->
<template lwc:render-mode="light">
  <label id="my-label">My label</label>
</template>
```

The `c-input` component contains an `<input>` element that references the `<label>` element from the `c-label` component.

```html
<!-- input.html -->
<template lwc:render-mode="light">
  <input type="text" aria-labelledby="my-label" />
</template>
```

## CSS

With shadow DOM, CSS styles defined in a parent component don’t apply to a child component. Contrastingly, light DOM enables styling from the root document to target a DOM node and style it.

The styles on the following native shadow component cascades into the child component's light DOM. In this case, the light DOM component is inside the native shadow component and is mounted at the closest native shadow root level. This light DOM component is scoped locally within that entire shadow root and affects any light DOM components inside that root.

<!-- prettier-ignore-start -->
```html
<template>
  <my-app>
    #shadow-root
    |  <style> p { color: green; }</style>
    |  <p>This is a paragraph in shadow DOM</p>
    |    <my-container>
    |      <p>This is a paragraph in light DOM</p>
    |    </my-container>
  </my-app>
</template>
```
<!-- prettier-ignore-end -->

Similarly, the styles on a child component rendered in light DOM are applied to its parent components until a shadow boundary is encountered when using native shadow DOM.

For synthetic shadow DOM, the shadow DOM styles don’t cascade into the light DOM child components.

**note:** In synthetic shadow DOM, styles are implemented at the global document level, but using attributes to scope the styles. This is a current limitation for synthetic shadow DOM.

LWC doesn't scope styles automatically for you. To prevent styles from cascading out of a component, we recommend using scoped styles with `*.scoped.css` files. See the **Use Scoped Styles in Light DOM** section.

To override inherited styles in Lightning web components, [use SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md) in the component stylesheet. Your styling hooks act as placeholders for your custom styles. See the [Blueprint Overview](https://v1.lightningdesignsystem.com/components/overview/) for a list of component blueprints that support component styling hooks.

**tip:** The order in which light DOM components are rendered impacts the order in which stylesheets are injected into the root node and directly influences CSS rule specificity.

## Access Elements

In shadow DOM, you can only [access elements the component owns](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md).

In contrast, you can retrieve a node from a light DOM component, which is helpful for third-party integrations and testing. For example, you can query the paragraph in your app using `document.querySelector('p')`.

```html
<!-- JS code returns "Your Content Here" -->
<template>
  <script>
    console.log(document.querySelector("my-custom-class").textContent);
  </script>
  <my-component>
    <div class="my-custom-class">Your Content Here</div>
  </my-component>
</template>
```

With shadow DOM, `LightningElement.prototype.template` returns the component-associated shadow root. The `template` element isn't available to components that use light DOM, so with light DOM, `LightningElement.prototype.template` returns `null`.

When migrating a shadow DOM component to light DOM, replace `this.template.querySelector` with `this.querySelector`. The following example uses a list of common DOM APIs to work with a light DOM component.

```javascript
import { LightningElement } from "lwc";

export default class LightDomApp extends LightningElement {
  static renderMode = "light";
  query(event) {
    const el = this.querySelector("p");
    const all = this.querySelectorAll("p");
    const elById = this.getElementById("#myId");
    const elements = this.getElementsByClassName("my-class");
    const tag = this.getElementsByTagName("button");
  }
}
```

With light DOM components, `this.querySelectorAll()` can return elements rendered by other light DOM components. To [access the parent element](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md#access-the-parent-element) in light DOM, use `this.hostElement`.

The [id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id) attribute on an element is preserved at runtime and isn’t manipulated as in synthetic shadow DOM. So you can use an `id` selector in CSS or JavaScript because it matches the element's `id` at runtime.

**note:** Alternatively, use [`this.refs`](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md) when you're working with components in light DOM and shadow DOM. `this.refs` accesses the element that's defined in the component and behaves similarly in both light DOM and shadow DOM, unlike `this.querySelector` or `this.querySelectorAll`.

## Events

With shadow DOM, if an event bubbles up and crosses the shadow boundary, some property values change to match the scope of the listener. With light DOM, events aren’t retargeted. If you click a button that's nested within multiple layers of light DOM components, the `click` event can be accessed at the document level. Also, `event.target` returns the button that triggered the event, instead of the containing component.

For example, you have a component `c-light-child` using light DOM nested in a container component `c-light-container` that's also using light DOM. The top-level `c-app` component uses shadow DOM.

<!-- prettier-ignore -->
```html
<!-- app.html (shadow DOM) -->
<template>
  <c-light-container onbuttonclick={handleButtonClick}> </c-light-container>
</template>
```

<!-- prettier-ignore -->
```html
<!-- lightContainer.html -->
<template lwc:render-mode="light">
  <p>Hello, Light DOM Container</p>
  <!-- c-light-child host -->
  <c-light-child onbuttonclick={handleButtonClick}> </c-light-child>
</template>
```

```javascript
// lightContainer.js
import { LightningElement } from "lwc";

export default class LightContainer extends LightningElement {
  static renderMode = "light";
  handleButtonClick(event) {
    // do something
  }
}
```

<!-- prettier-ignore -->
```html
<!-- lightChild.html -->
<template lwc:render-mode="light">
  <button onclick={handleClick}></button>
</template>
```

```javascript
// lightChild.js
import { LightningElement } from "lwc";

export default class LightChild extends LightningElement {
  static renderMode = "light";
  handleClick(event) {
    this.dispatchEvent(new CustomEvent("buttonclick", { bubbles: true, composed: false }));
  }
}
```

When you dispatch the custom `buttonclick` event in `c-light-child`, the handlers return these elements.

`c-light-child` host handler

- `event.currentTarget`: `c-light-child`
- `event.target`: `c-light-child`

`c-light-container` host handler

- `event.currentTarget`: `c-light-container`
- `event.target`: `c-light-child`

In contrast, if `c-light-container` uses shadow DOM, the event doesn’t escape the shadow root.

**note:** Events bubble through components even if `composed` is `false` in light DOM, since there's no shadow root.

## Slots

Light DOM emulates slots because browsers don't support them outside shadow DOM. Slots in light DOM behave similarly to [synthetic shadow slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.md#work-with-mixed-shadow-mode). LWC determines at run-time if a slot is running light DOM.

The `<slot>` element is a placeholder in a component for where slotted content gets attached. `<slot>` isn't rendered in light DOM, so if other parts of your code depend on attributes or event listeners of a `<slot>` element, LWC throws a compiler error. For example, the `slotchange` event and `::slotted` CSS pseudo-selector aren’t supported since the slot element doesn’t render in the DOM.

A `<slot>` element without the `name` property is a default (or unnamed) slot. To pass content from only a specific element into a `<slot>`, create a named slot.

### Named Slots

To create a named slot, set a `<slot>` element's `name` property to a string value. To insert slotted content in that named slot, set the `slot` property of the element with content to the same string value.

In the sample code below, the component `my-component` has a named and an unnamed slot. The named slot contains fallback content that only renders if you don't provide slotted content.

```html
<!-- myComponent.html -->
<template>
  <slot name="title">Fallback content</slot> // Named slot
  <h3>Heading text</h3>
  <slot></slot> // Unnamed/Default slot
</template>
```

Pass slotted content into `my-component` like this.

```html
<my-component>
  <p>Default slotted content</p>
  <h1 slot="title">Content for named slot</h1>
</my-component>
```

At run-time, the slotted content or fallback content is flattened to the parent element. Content is directly appended to the host element in the DOM. The `<slot>` elements in `my-component` aren’t rendered to the DOM.

```html
<my-component>
  <h1>Content for named slot</h1>
  <h3>Heading text</h3>
  <p>Default slotted content</p>
</my-component>
```

Light DOM only renders slotted elements that are assigned to slots. If an element with slotted content isn't linked to a slot, the element's lifecycle hooks are never invoked.

```html
<!-- c-parent -->
<template>
  <c-child>
    <span>This element isn't rendered in light DOM because c-child doesn't have a slot</span>
  </c-child>
</template>

<!-- c-child -->
<template>
  <p>No slot here</p>
</template>
```

### Slotted Content and Components

Consider these composition models using slots. A component in light DOM can slot in content and other components. The slots support both light DOM and shadow DOM components.

```html
<!-- my-component -->
<template>
  <slot name="content">Default content in the named slot</slot>
  <p>This makes the component a bit more complex</p>
  <slot>This is a default slot to test if content bypasses the named slot and goes here</slot>
</template>
```

Here’s how your content is rendered in the slots.

```html
<my-component>
  <!-- Inserted into the content slot -->
  <div slot="content">Some text here</div>
</my-component>

<my-component>
  <!-- Inserted into the content slot -->
  <my-shadow-lwc slot="content">Some text here</my-shadow-lwc>
</my-component>

<my-component>
  <!-- Inserted into the content slot -->
  <my-light-lwc slot="content">Some text here</my-light-lwc>
</my-component>

<my-component>
  <!-- Inserted into the default slot -->
  <my-shadow-lwc>Some text here</my-shadow-lwc>
</my-component>

<my-component>
  <!-- Inserted into the default slot -->
  <my-light-lwc>Some text here</my-light-lwc>
</my-component>
```

### Style Inheritance for Slots

Consider this light DOM component `c-light-slot-consumer` that contains a shadow DOM component `c-shadow-slot-container` and light DOM component `c-light-slot-container`.

```html
<!-- app.html -->
<template>
  <c-shadow-component></c-shadow-component>
  <c-light-slot-consumer></c-light-slot-consumer>
</template>
```

```html
<!-- lightSlotConsumer.html -->
<template lwc:render-mode="light">
  <c-shadow-slot-container>
    <p>Hello from shadow slot</p>
  </c-shadow-slot-container>
  <c-light-slot-container>
    <p>Hello from light slot</p>
  </c-light-slot-container>
</template>
```

```html
<!-- shadowSlotContainer.html -->
<template>
  <slot></slot>
</template>
```

```html
<!-- lightSlotContainer.html -->
<template lwc:render-mode="light">
  <slot name="other">
    <p>Hello from other slot</p>
  </slot>
  <slot>This is the default slot</slot>
</template>
```

If you include styles in `c-app`, all elements _within the slots_ (in both the shadow DOM and light DOM components) get the styles. However, _the shadow DOM component without slots doesn't_ receive the styles.

<!-- prettier-ignore-start -->
```html
<c-app>
  <style type="text/css">
    p {
      background: green;
      color: white;
    }
  </style>    
  <h2>Hello Light DOM</h2>
    <p>This is a paragraph in app.html</p>
    <h3>Shadow DOM</h3>
    <c-shadow-component>
        #shadow-root (open)
        | <p>Hello, Shadow DOM container</p>
    </c-shadow-component>
    <h3>Slots</h3>
    <c-light-slot-consumer>
        <c-shadow-slot-container>
            #shadow-root (open)
            | <p>Hello from shadow-slot-container</p>
        </c-shadow-slot-container>
        <c-light-slot-container>
            <p>Hello from other slot</p>
            <p>Hello from light-slot-container</p>
        </c-light-slot-container>
    </c-light-slot-consumer>
</c-app>
```
<!-- prettier-ignore-end -->

### `slot` Attribute for Light DOM Elements

When a component is rendered to the DOM at runtime, light DOM slots don't rely on the native browser `<slot>` elements or `slot` attributes.

**In LWC API v61.0 and later:**

LWC removes the `slot` attribute from an element when it's being slotted into a light DOM slot.

For example, this `<template>` passes a `<div>` with the `slot='lightSlot'` property into a light DOM slot.

```
<template>
    <c-light-child>
        <div slot='lightSlot'>I got slotted</div>
    </c-light-child>
</template>
```

```
<template render:mode="light">
    <slot name="lightSlot"></slot>
</template>
```

The `c-light-child` component renders to the DOM without the `slot` property.

```
<c-light-child>
    <div>I got slotted</div>    // div renders WITHOUT the slot property
</c-light-child>
```

To support [slot forwarding](#slot-forwarding), native and synthetic shadow slots still preserve the `slot` attribute. For example, say you have a light DOM slot that forwards a `<div>` with `slot="lightSlot"` into a shadow DOM slot.

```
<template>
    <c-light-slot>
        <div slot="lightSlot">Slotted content from template</div>
    </c-light-slot>
</template>
```

```
<template>
    <c-shadow-slot>
        <slot name="lightSlot" slot="shadowSlot"></slot>
    <c-shadow-slot>
</template>
```

```
<template>
    <slot name="shadowSlot"></slot>
</template>
```

The slotted content (`<div>`) renders in the DOM with its `slot` attribute preserved.

```
<c-light-slot>
    <c-shadow-slot>
        // The div preserves the slot attribute from c-light-slot
        <div slot="shadowSlot">Slotted content from template</div>
    </c-shadow-slot>
</c-light-slot>
```

If your CSS selectors or [`querySelector()`](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md#queryselector) methods reference the `slot` attribute, we recommend you choose a different CSS selector or use [`lwc:ref`](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md#refs) instead.

```
<!-- Do not rely on CSS selectors like this -->
const foo = this.querySelector('[slot="foo"]');

<!-- Instead, use lwc:ref -->
<c-child>
    <div slot="foo" lwc:ref="foo">hello</div>
</c-child>
```

You should also review your Jest snapshots to see if they're impacted by this change.

**In LWC API v60.0 and earlier:**

Light DOM elements render with their `slot` attributes. The example `<template>` above renders to the DOM as follows.

```
<div slot="namedSlot">hello</div>
```

### Slot Forwarding

Slot forwarding refers to passing content from one slot to another slot.

For example, say you have a `c-outer` component that pulls content from a `<span>` element into its named slot `namedSlot`. `c-outer` also has a child component, `c-inner`. You want to forward content from `namedSlot` into `c-inner`'s slot `forwardedSlot`.

![Diagram of how content is forwarded from one slot to another.](https://developer.salesforce.com/media/slot_forwarding.png '{"class": "image-lg"}')

`container.html` passes the `<span>` with slotted content into `<c-outer>`.

```html
<!-- container.html -->
<template>
  <c-outer>
    <span slot="namedSlot">Named slot content</span>
  </c-outer>
</template>
```

**In LWC API v61.0 and later:**

You can forward content from a parent's light DOM slot to a child's slot using only the `slot` attribute. You no longer have to create a wrapper around any of the slots.

For these versions of LWC, here's an example of a valid `c-outer` component.

```html
<!-- outer.html -->
<template lwc:render-mode="light">
  <c-inner>
    <slot name="namedSlot" slot="forwardedSlot"></slot>
  </c-inner>
</template>
```

`namedSlot` **receives** content from the `<span>` in `container.html` because it has the property `name="namedSlot"`. Additionally, `namedSlot` **passes** its content to the slot named `forwardedSlot` because it has the `slot="forwardedSlot` property.

The "Named slot content" string renders in the slot named `forwardedSlot` for `<c-inner>`.

```html
<!-- inner.html -->
<template>
  <slot name="forwardedSlot"></slot>
</template>
```

**In LWC API v60.0 and earlier:**

To forward light DOM slot content into another slot, you have to wrap the outermost `<slot>` element in another element and assign the `slot` attribute to the element.

Here's an example of a `c-outer` component with a `<div>` wrapper around `namedSlot`.

```html
<!-- outer.html -->
<template lwc:render-mode="light">
  <c-inner>
    <!-- wrapper div -->
    <div slot="forwardedSlot">
      <slot name="namedSlot"></slot>
    </div>
  </c-inner>
</template>
```

The same applies to default slots.

```html
<!-- outer.html -->
<template lwc:render-mode="light">
  <c-inner>
    <!-- wrapper div -->
    <div>
      <slot name="namedSlot"></slot>
    </div>
  </c-inner>
</template>
```

As a result, the "Named slot content" string renders in the `forwardedSlot` slot for `<c-inner>`.

```html
<!-- inner.html -->
<template>
  <slot name="forwardedSlot"></slot>
</template>
```

## Scoped Slots

With scoped slots, you can access data in a child component and render it in slotted content inside of a parent component. Binding data from the child component to the scoped slot allows the parent component to reference the child component’s data in the slotted content. This data is slotted in the child component’s light DOM.

In this example, the child component `<c-child>` binds its `item` data to the scoped slot `<slot>`. In the parent component `<c-parent>`, the scoped slot fragment references `{item.id}` and `{item.name}` in the markup that will be slotted to `<c-child>`.

```html
<!-- c/parent.html -->
<template> <!-- Parent component doesn’t need to be light DOM -->
    <c-child>
        <template lwc:slot-data="item">
            <span>{item.id} - {item.name}</span>
        </template>
    </c-child>
</template>


<!-- c/child.html -->
<template lwc:render-mode="light"> <!-- Child must be light DOM -->
    <ul>
        <template for:each={item} for:item="item">
            <li key={item.id}>
                <slot lwc:slot-bind={item}</slot>
            </li>
        </template>
    </ul>
</template>
```

Because the scoped slot fragment is in the parent component’s template, the parent component owns the slotted content. So if the parent component references a scoped style sheet, those styles also apply to the content of the scoped slot.

The parent component partially renders the content of the scoped slot, so it must be enclosed in `<template></template>` tags. In the example, the scoped slot content is `<span>{item.id} - {item.name}</span>`. The parent component creates this partial fragment.

The parent component also renders each `item`, and the child component controls the loop logic. `<c-child>` creates as many slots as needed using the same template fragment passed from `<c-parent>`.

**note:** To use scoped slots, the child component must use light DOM. Scoped slots in shadow DOM aren’t supported. The parent can be a light DOM or shadow DOM component.

The final HTML looks as follows.

<!-- prettier-ignore-start -->
```html
<c-parent>
  #shadow-root
  | <c-child>
  |  <ul>
  |    <li>
  |      <span>1 - One</span>
  |    </li>
  |    <li>
  |      <span>2 - Two</span>
  |    </li>
  |  </ul>
  | </c-child>
</c-parent>
```
<!-- prettier-ignore-end -->

To introduce scoped slots into your components, add the directives `lwc:slot-bind` and `lwc:slot-data`. For more information, see [Directives for Slots](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) and [Directives for Nested Templates](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md).

## Multiple Scoped Slots and Bindings

A child component can have multiple named scoped slots, but it can have only one default scoped slot.

```html
<template>
    <c-child>
        <template lwc:slot-data="defaultdata"> <!-- This is a default slot -->
            <p>{defaultdata.title}</p>
        </template>
        <template slot="slotname1" lwc:slot-data="slot1data"> <!-- This is a named slot -->
            <p>{slot1data.title}</p>
        </template>
        <template slot="slotname2" lwc:slot-data="slot2data"> <!-- This is a named slot -->
            <p>{slot2data.title}</p>
        </template>
    </c-child>
</template
```

You can bind different scoped slots to the same source of data. In the example below, the default scoped slot and the two named scoped slots render content from `slotdata`.

<!-- prettier-ignore -->
```html
<template lwc:render-mode="light">
  <!-- This is a default slot -->
  <slot lwc:slot-bind={slotdata}></slot>
  <!-- This is a named slot -->
  <slot name="slotname1" lwc:slot-bind={slotdata}></slot>
  <!-- This is a named slot -->
  <slot name="slotname2" lwc:slot-bind={slotdata}></slot>
</template>
```

You can bind a scoped slot to only one source of data. For example, binding the named scoped slot `namedslotA` to two different sets of data, `slot1data` and `slot2data`, results in a compiler error.

<!-- prettier-ignore -->
```html
<!-- Invalid usage of named scoped slot -->
<template lwc:render-mode="light">
  <slot name="namedslotA" lwc:slot-bind={slot1data}></slot>
  <slot name="namedslotA" lwc:slot-bind={slot2data}></slot>
</template>
```

If you try to bind a default scoped slot to multiple different sets of data, the compiler throws the same error.

<!-- prettier-ignore -->
```html
<!-- Invalid usage of default scoped slot -->
<template lwc:render-mode="light">
  <slot lwc:slot-bind={slot1data}></slot>
  <slot lwc:slot-bind={slot2data}></slot>
</template>
```

## Mixing Standard and Scoped Slots

Because you can only have one default slot in a component, you can’t place a standard default slot and a default scoped slot in the same component. The following code results in an error.

<!-- prettier-ignore -->
```html
<!-- c/child.html -->
<!-- Invalid usage of default slots -->
<template lwc:render-mode="light">
  <slot lwc:slot-bind={slotdata}>Default scoped slot</slot>
  <slot>Standard default slot</slot>
</template>
```

Within a child component, a named scoped slot and a standard named slot can’t share the same name. The following code results in an error.

<!-- prettier-ignore -->
```html
<!-- c/child.html -->
<!-- Invalid usage of named slots -->
<template lwc:render-mode="light">
  <slot name="slotname1" lwc:slot-bind={slotdata}>Named scoped slot</slot>
  <slot name="slotname1">Standard named slot</slot>
</template>
```

When binding a scoped slot in a parent component to data from a child component, the components must contain the same type of slot. For example, if a parent component contains a scoped slot bound to a child component, that child component must also have a scoped slot. Otherwise, the slotted content isn’t rendered. If you enable debug mode, an error is also logged in the dev console.

## Flexibility of Scoped Slots

You can nest a scoped slot inside another scoped slot.

```html
<template>
  <c-table data={data}>
    <template lwc:slot-data="row">
      <c-row row={row}> <!-- This is rendered for every row in the table -->
        <template lwc:slot-data="column">
          <span> <!-- This is rendered for every column in the row -->
            Coordinates: {row.number} - {column.number} <!-- This can refer to both `row` and `column` -->
          </span>
        </template>
      </c-row>
    <template>
  </c-table>
</template>
```

Scoped slots can reference component bindings and scope bindings.

```html
<template>
  {title}
  <c-list>
    <template lwc:slot-data="item">
      <div>{label}</div>
      <!-- label is a component binding that’s repeated in every row of the list -->
      <span>{item.id} - {item.name}</span>
    </template>
  </c-list>
</template>
```

## Use Scoped Styles in Light DOM

In light DOM, you can use scoped styles to apply CSS to elements on the component only. This behavior is similar to style encapsulation with shadow DOM.

To add scoped styles to a component, create a `*.scoped.css` file in the component folder.

```
myCmp
    ├──myCmp.html
    ├──myCmp.css
    └──myCmp.scoped.css
```

You can include either one, both, or neither of the CSS files in the example above for shadow DOM components and light DOM components.

**note:** In Aura-based containers, light DOM components can only load scoped styles. For example, in [Aura-based Experience Builder sites](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_builder_intro.htm), you must include the `*.scoped.css` file for your custom components instead of the `*.css` file.

Let's examine a light DOM component with scoped styles.

```html
<!-- lightCmp.html -->
<template lwc:render-mode="light">
  <p>This is a paragraph in c-light-cmp</p>
</template>
```

```javascript
// lightCmp.js
import { LightningElement } from "lwc";

export default class LightCmp extends LightningElement {
  static renderMode = "light";
}
```

```css
/* lightCmp.scoped.css */
p {
  background: silver;
  color: black;
}
```

The scoped style results in:

```html
<c-light-cmp class="c-lightCmp_lightCmp-host">
  <style class="c-lightCmp_lightCmp" type="text/css">
    p.c-lightCmp_lightCmp {
      background-color: silver;
      color: black;
    }
  </style>
  <p class="c-lightCmp_lightCmp">This is a paragraph in c-light-cmp</p>
</c-light-cmp>
```

If a `*.css` file is used with a `*.scoped.css` file, the `*.css` stylesheets are injected before the `*.scoped.css` stylesheets. The scoped style CSS selectors have precedence over the unscoped ones because they’re declared last.

**note:** If a scoped stylesheet and an unscoped are used on the template, both style sheets are applied. The injection order influences which styles are applied by the browser when you have duplicated selectors. See [tree proximity ignorance](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity#tree_proximity_ignorance).

```css
/* lightCmp.css */
p {
  background: yellow;
  color: #777;
}
```

In this case, `c-light-cmp` uses the scoped styles, but the styles from the unscoped stylesheet can bleed out of the component.

```html
<!-- c-app -->
<template>
  <!-- This paragraph is styled yellow from lightCmp.css -->
  <p>This is a paragraph in c-app shadow DOM</p>
  <c-light-cmp></c-light-cmp>
</template>
```

In the preceding example, the paragraph in `c-app` inherits the styles from `lightCmp.css`. To override the styles from `lightCmp.css`, include a scoped stylesheet `app.scoped.css`.

**note:** We don't recommend using the `!important` rule as it makes debugging more difficult. When you use `!important` on a style declaration in both your scoped and unscoped stylesheet, the scoped style has greater specificity and its style is applied to the component.

## Scoped Region

When you use `*.scoped.css`, the CSS selectors are scoped to all elements in the component HTML file.

```html
<!-- c-my-cmp -->
<template>
  <div>
    <span></span>
    <button class="my-button"></button>
  </div>
</template>
```

In the following CSS, all selectors match the elements in the template, and only those elements.

```css
/* myCmp.css */
div {
}
span {
}
button {
}
div > span {
}
div button {
}
.my-button {
}
```

The root element `c-light-cmp` can be targeted using `:host`, even in a light DOM component.

CSS scoping uses custom CSS classes to prevent styles from leaking out of the component.

## Target the Root Element

As light DOM styles aren't scoped by default, the `:host` pseudo selector refers to the closest shadow root host element (if any). With light DOM scoped styles, the `:host` selector refers to the root element of the light DOM component, which is the root of the scoped DOM region.

Let's say you have an unscoped and scoped stylesheet on a light DOM component.

```css
/* light.css */
:host {
  background: red;
}
```

```css
/* light.scoped.css */
:host {
  background: blue;
}
```

The component renders:

```html
<c-shadow>
  <!-- red background -->
  #shadow-root
  <c-light class="c-light_light-host">
    <!-- blue background -->
    <style>
      :host {
        background: red;
      }
      :c-light_light-host {
        background: blue;
      }
    </style>
  </c-light>
</c-shadow>
```

In the preceding example, `:host` is transformed for the scoped style.

**note:** The `:host-context()` selector isn’t supported.

## Compare Scoped Styles with Synthetic Shadow DOM

Light DOM scoped styles have some differences from LWC's synthetic shadow scoped styles.

- Light DOM scoped styles use classes for scoping, but synthetic shadow DOM uses HTML attributes.
- Light DOM scoped styles don't support `@import` within scoped stylesheets.
- Light DOM scoped styles don't apply to content that's manually injected into the template inside of [`lwc:dom="manual"`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md#directives-for-html-elements), for example, content injected using `Element.appendChild` or `Element.innerHTML`.

## Convert Components from Shadow DOM to Light DOM

To easily convert components from shadow DOM to light DOM, use the lwc-codemod tool. The tool modifies the files in a component bundle, which includes adding the `renderMode` property in the JavaScript file and the `lwc:render-mode` directive in the HTML file.

For more information, see the [lwc-codemod documentation](https://github.com/salesforce/lwc-codemod).

**See Also**

- [Supported Browsers](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md)
- [LWR Sites for Experience Cloud: Pages and Components in the LWR Template](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/template_pages.htm)
- [Named Slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot#name)

<!-- document id=7ef7d3a3df4541542534fb69e87e3f9a8c008c2ec085fdd7d4fdb271af183ba4 url=/developer/current/en-us/lwc/lwc/guides/use/use-app-builder.md -->

# Lightning App Builder

Develop components that can be used to build custom pages for Lightning Experience and the Salesforce mobile app quickly with point-and-click tools.

<!-- document id=c8b8309b0fcef10babb986d96069346f7219fbdfc69a952aa05d572a0e4ef3d1 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-component-library.md -->

# Lightning Component Library

The Lightning Component Library includes component reference information and tools for Lightning Web Security and Lightning Locker.

You can find the Component Library in two places: a public site and an authenticated one that’s linked to your Salesforce org. In the authenticated site, the Component Reference section of the Component Library has some additional features.

- Public Component Library

  - : View the [public Component Library](https://developer.salesforce.com/docs/component-library) without logging in to Salesforce. For more information about this documentation, see [Component Reference](#component-reference).

- Component Library for your org

  - : View this site by logging in to your Salesforce org and navigating to `https://<myDomainName>.lightning.force.com/docs/component-library`. Alternatively, click **Link to your org** at the top right on the public site.

    The authenticated site has more features for the Component Reference.

    - View Lightning components that are unique to your org.
    - View Lightning components that are installed in a managed package. You can filter to view components owned by your org or installed in packages.

The Component Library presents these tabs.

- Component Reference
- LWC Developer Guide
- LWS Console
- LWS Distortion Viewer
- Locker Console
- Locker API Viewer

**tip:** The LWS and Locker tools are also available in the Tools section of the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components) and [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience).

## Component Reference

The Component Reference contains usage information for base components.

- The legacy Component Reference is available as part of the [Component Library](https://developer.salesforce.com/docs/component-library), which is no longer updated and will no longer be published in Spring ’26.
- The new Lightning Component Reference is at https://developer.salesforce.com/docs/platform/lightning-component-reference.

For information about the differences between the new and legacy Component Reference, see [_Lightning Component Reference_: What's New?](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/base-components-reference.html).

## Known Limitations for the Legacy Component Reference

Here are some known issues with the [legacy Component Reference](https://developer.salesforce.com/docs/component-library/overview/components).

- Non-lightning namespace differences in the public vs authenticated Component Reference

  - : In the public site, the Component Reference for non-lightning namespaces can contain outdated content. For non-lightning components, such as `wave:waveDashboard` or `force:createRecord`, verify the specification and documentation in `https://<myDomainName>.lightning.force.com/docs/component-library`.

- Documentation for Lightning web components developed in your org isn’t supported

  - : The Component Reference doesn’t display documentation for your custom Lightning web components

- Specification panel missing content

  - : Modules don’t display descriptions or methods on the Specification page. The descriptions and methods are on the Documentation page. Modules include:

    - `lightning/empApi`
    - `lightning/flowSupport`
    - `lightning/messageService`
    - `lightning/navigation`

    Some attributes that have default values don’t display a value in the Default column. See the Description column for default values.

    Custom events aren’t displayed in Specification pages. See the component’s Documentation page for this information.

- Versioning and localization aren’t supported

  - : The Component Reference doesn’t provide a Version or Language selector like other Salesforce developer documentation. It displays documentation that corresponds to the current release only, and the content is available only in English.

## Legacy Component Reference Examples

The Examples tab shows base component sample code that renders in a runtime environment on the page.

To experiment with a Lightning web component example, modify the code and click **Run**. Aura component examples aren’t editable but do render and you can interact with them.

The runtime environments don’t use the latest versions of the base components due to technical limitations. For this reason, component changes such as new documented attributes in recent releases aren’t reflected in the examples and don’t work if you add them to the examples. The [new Component Reference site examples](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide) use the latest base components.

The runtime environments also don’t keep up with SLDS releases. The Web Content Accessibility Guidelines (WCAG) color updates that we announced in the [See Improved Color Contrast in UI Elements](https://help.salesforce.com/s/articleView?id=release-notes.rn_general_color_contrast.htm&release=246&type=5) Winter ’24 release note aren’t reflected in the examples. However, the base components that you use in your custom components and run in your Salesforce org do include the latest features of the base components and SLDS.

## Lightning Web Security Console and LWS Distortion Viewer Tools

Lightning Web Security (LWS) Console and LWS Distortion Viewer help you develop secure JavaScript code that runs with Lightning Web Security.

For more information about using these tools, see [Evaluate JavaScript in Lightning Web Security Console](/docs/platform/lightning-components-security/guide/lws-tools-console.html) and [Look Up Distortion Details in Lightning Web Security Distortion Viewer](/docs/platform/lightning-components-security/guide/lws-tools-distortion-viewer.html).

For more about Lightning Web Security and how it compares to Lightning Locker, see [Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-intro.html).

## Locker Console and Locker API Viewer Tools

The Locker Console and Locker API Viewer help you develop secure JavaScript code that is compatible and runs efficiently with Lightning Locker.

For more information about using these tools, see [Lightning Locker Tools](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/security_tools.htm) in the _Lightning Aura Components Developer Guide_.

For more about Lightning Locker and Lightning web components, see [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html) in _Security for Lightning Components_.

<!-- document id=26a833b32b66aad9aee213971aea17a27534f25a476047854e0b2722c3707dc1 url=/developer/current/en-us/lwc/lwc/guides/data/data-ui-api.md -->

# Lightning Data Service

Records loaded in Lightning Data Service are cached and shared across components. If a page is composed of components showing the same record, all components show the same version of the record. Components accessing the same record see significant performance improvements, because a record is loaded once, no matter how many components are using it.

In a Lightning web component, perform operations on data and access metadata using these technologies built on Lightning Data Service.

- Base Components:`lightning-record-edit-form`, `lightning-record-form`, and `lightning-record-view-form`
- Wire adapters and functions in the [`lightning/ui*Api`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md) modules. Wire adapters listed in the [Reference section](https://developer.salesforce.com/docs/platform/lwc/reference/reference.md) are LDS-based unless otherwise specified.
- [GraphQL API wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/graphql/reference-graphql.md)

**important:** Lightning Data Service supports all custom objects and all the [standard objects](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) that User Interface API supports. Custom metadata types are not supported. Lightning Data Service doesn’t incur any API usage calls, but it is subject to general limits like the numbers of records returned.

Lightning Data Service manages data for you; changes to a record are reflected in all the technologies built on it. Contrastingly, data from Apex is not managed; you must refresh the data.

If Lightning Data Service detects a change to a record or any data or metadata it supports, all components using a relevant `@wire` adapter receive the new value. The detection is triggered if:

- A Lightning web component mutates the record.
- The LDS cache entry expires and then a Lightning web component’s `@wire` triggers a read. The cache entry and the Lightning web component must be in the same browser and app (for example Lightning Experience) for the same user.

Lightning Data Service does a lot of work to make code perform well.

- Loads record data progressively.
- Caches results on the client.
- Invalidates cache entries when dependent Salesforce data and metadata changes.
- Optimizes server calls by bulkifying and deduping requests.

To improve performance, Lightning Data Service maintains a client-side cache of record data that has been loaded via a wire adapter. Loading data from this cache is faster than requesting it from the server. Lightning Data Service re-requests the record data from the server to satisfy requests that occur after the cache lifetime. However, you might also get updated record data even before the cache lifetime has passed. The cache lifetime is subject to change as part of ongoing improvements to Lightning Data Service.

Also, Lightning Data Service maintains a separate timeout for object and layout metadata, which are cached in a durable store. When you make layout changes to record pages on custom objects, the layout changes don’t appear immediately. The record page displays the updated layout after the timeout when you reload the page. To see your layout changes immediately, log out and log back in. Durable caching is available in orgs with secure browser caching, which is enabled by default.

Lightning Data Service is built on top of [User Interface API](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/). UI API is a public Salesforce API that Salesforce uses to build Lightning Experience and Salesforce for iOS and Android. Like its name suggests, UI API is designed to make it easy to build Salesforce UI.

UI API gives you data and metadata in a single response. Responses match layout changes made to the org by Salesforce admins. If an admin removes a field from a layout, that field isn’t included in a response to a request for layout metadata.

UI API responses also respect CRUD access, field-level security settings, and sharing settings. This means that the framework displays only records and fields for which users have CRUD access and FLS visibility. You get all these features by using the Lightning Data Service wire adapters (`lightning/ui*Api`) and the components built on it.

![Data flow from the database up to UI API, LDS, and Lightning Web Components.](https://developer.salesforce.com/media/create_data_flow.png)

**See Also**

- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)

<!-- document id=ee2a507f6c7df9ec10ddacd3470a3396c9bf5ec8eb6b2392ad83e254692dbafd url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-intro.md -->

# Lightning Locker

Lightning Locker is a security architecture for Lightning components. It provides component isolation and security that allows code from many sources to execute and interact using safe, standard APIs and event mechanisms.

In Spring ’22, Salesforce introduced [Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md), a new architecture designed to make it easier for your components to use secure coding practices. LWS is enabled by default for all orgs created in Winter ’23 and later. As of Summer ’23, LWS for Lightning web components and Aura components is generally available for all orgs.

Lightning Locker remains the default Lightning component security architecture in orgs created before Winter ’23. Unless LWS is enabled instead, Lightning Locker is enabled by default for all Lightning components on API version 39.0 and later, and you can't disable Lightning Locker for these components.

**tip:** If possible, we recommend that you enable LWS instead of remaining on Lightning Locker. First test LWS in a sandbox environment, and then in production. For a comparison of the features that LWS and Lightning Locker support, see [How Lightning Web Security Compares to Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md).

**See Also**

- [What Does Lightning Locker Affect?](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-where.md)
- [DOM Access Containment](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-dom.md)
- [How Lightning Locker Uses the Proxy Object](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-proxy.md)
- [Secure Wrappers](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-global-access.md)
- [Lightning Locker Tools](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-tools.md)

<!-- document id=a1d43f2991412b8ad4dd58d478a4cb4db5f7f40c9be8d0fa2eb7b3b1e4c86083 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-api-viewer.md -->

# Lightning Locker API Viewer Overview

Locker API Viewer shows Lightning Locker’s support of the standard DOM APIs in the `Window`, `Document`, and `Element` objects. The `SecureWindow`, `SecureDocument`, and `SecureElement` wrappers prevent use of APIs that are labeled **Not Supported**.

[Locker API Viewer](https://developer.salesforce.com/tools/locker-service-viewer) is available in the Tools area of the [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience) and the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components).

![Lightning Locker API Viewer UI with list of APIs supported by SecureDocument.](https://developer.salesforce.com/media/locker_api_viewer_guide.png '{"class": "image-framed", "title": "Lightning Locker API Viewer"}')

Locker API Viewer lets you quickly see which standard DOM APIs are supported by Lightning Locker.

There are several ways to validate your code to ensure compatibility with Aura component APIs. For more information, see [Validations for Aura Component Code](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/validation.htm).

Use the [Locker Console](https://developer.salesforce.com/tools/locker-service-console) tool to check JavaScript code’s compatibility with Lightning Locker.

**See Also**

- [Secure Wrappers](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-global-access.md)
- [Locker Console Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console.md)

<!-- document id=e02d6f5c660e82e70a69332d5e22209dfdcb17d641ce85fa78183dc8c80cf2a8 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-unsupported.md -->

# Lightning Locker Disabled for Unsupported Browsers

Lightning Locker relies on some JavaScript features in the browser: support for strict mode, the `WeakMap` object, and the `Proxy` object. If a browser doesn’t meet the requirements, Lightning Locker can’t enforce all its security features and is disabled.

Lightning Locker is enabled in the supported browsers for Lightning Experience. If your app runs in an unsupported browser, you’re likely to encounter issues that won’t be fixed. Make your life easier, and your user’s browsing experience more secure, by requiring your app to run in a supported browser.

**See Also**

- [_Lightning Web Components Developer Guide_: Supported Browsers](/docs/platform/lwc/guide/get-started-supported-browsers.html)
- [_Lightning Aura Components Developer Guide_: Browser Support for Aura Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/intro_browsers.htm)
- [_Salesforce Help_: Supported Browsers for Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.getstart_browsers_sfx.htm)
- [_Salesforce Help_: Recommendations and Requirements for All Browsers](https://help.salesforce.com/s/articleView?id=xcloud.getstart_browser_recommendations.htm)

<!-- document id=da57ad49d076291ec9fa36b83ba5b482d6ce702527cc9078452e602c9c6ff9c7 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-tools.md -->

# Lightning Locker Tools

Lightning Locker tools help you develop secure code that is compatible and runs efficiently with Lightning Locker. Access these tools in the Tools area of the [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience) and the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components).

## Lightning Locker API Viewer

Use the [Lightning Locker API Viewer](https://developer.salesforce.com/tools/locker-service-viewer) to see which standard DOM APIs are supported by Lightning Locker for the most complex wrappers: `SecureDocument`, `SecureElement`, and `SecureWindow`.

![Locker API Viewer UI with list of APIs supported by SecureDocument.](https://developer.salesforce.com/media/locker_api_viewer_guide.png '{"class": "image-framed"}')

For more information about using this tool, see [Lightning Locker API Viewer Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-api-viewer.md).

## Locker Console

Use [Locker Console](https://developer.salesforce.com/tools/locker-service-console) to check your JavaScript code’s compatibility with Lightning Locker, and compare how it runs with Lightning Locker enabled and disabled.

Evaluate JavaScript code for issues or benchmark code without creating an app.

![Locker Console UI.](https://developer.salesforce.com/media/locker_console_guide.png '{"class": "image-framed"}')

To evaluate or benchmark your JavaScript code, paste or type it into the console (1). Enable or disable Locker and Strict CSP (2). To run the code that’s displayed in the console, click **Evaluate** (3). To run code with and without Locker and view relative performance metrics, click **Benchmark**. To clear the displayed results, click **Clear Results**.

For more information about using Locker Console, see [Evaluate JavaScript Code Compatibility with Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console-evaluate.md) and [Benchmark Lightning Locker Effect on JavaScript Code](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console-benchmark.md).

<!-- document id=f4f621d19d956b07ae07823093ff646ba7a597000811a5dadd9fda8b03e7b72c url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel-considerations.md -->

# Lightning Message Service Limitations

Keep the following in mind when working with Lightning message service.

Lightning message service supports only the following experiences:

- Lightning Experience standard navigation
- Lightning Experience console navigation
- Salesforce mobile app for Aura and Lightning Web Components, but not for Visualforce pages
- Lightning components used in Aura and LWR-based Experience Builder sites.

  **note:** Lightning Message Service doesn't work with Salesforce Tabs + Visualforce sites or with Visualforce pages in Experience Builder sites.

In containers that don’t support Lightning messaging service, use the `pubsub` module. Download the module from [github.com/developerforce/pubsub](https://github.com/developerforce/pubsub).

**note:** The `pubsub` module is not officially supported or actively maintained.

When including message channels in packages that you publish on AppExchange, 1GP and 2GP packages are supported.

For Lightning web components, you can define the scope of where subscribing components receive messages in your application only when using `@wire(MessageContext)`.

If your component uses Lightning message service to publish a message, that message is constrained by the iframe boundary. To work around this limitation, use the [`sforce.one.subscribe()` and `sforce.one.unsubscribe()` methods](https://developer.salesforce.com/docs/atlas.en-us.pages.meta/pages/message_channel_subscribe.htm).

<!-- document id=675f45eca2d6eac6e12a754629a68366ac88123f0276ea944f6bf9feb0b3a27a url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-considerations.md -->

# Lightning Out (Beta) Considerations and Limitations

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

Creating an app using Lightning Out (beta) is generally like creating any app with Lightning web components. However, because your components are running outside of Salesforce, there are a few issues you want to be aware of.

The issues you must be aware of can be divided into two categories.

## Considerations for Using Lightning Out (Beta)

Because Lightning Out (beta) apps run outside of any Salesforce container, there are things you need to keep in mind, and possibly address.

- Browser Support

  - : Lightning Out (beta) supports the [same browsers as Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.getstart_browsers_sfx.htm). This support means that your Lightning Out (beta) app and components load in those browsers. However, if a component or functionality doesn't support a particular browser, the component or functionality doesn't work in Lightning Out (beta) either.

- Browser Third-Party Cookies

  - : Lightning components set cookies in a user’s browser. Since Lightning Out (beta) runs Lightning components _outside_ of Salesforce, these cookies are “third-party” cookies. To enable Lightning Out (beta) apps to work with third-party cookies, see [Lightning Out (Beta) Requirements](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-requirements.md).

- Authentication

  - : To handle authentication, you must manually provide a Salesforce session ID or authentication token when you initialize the Lightning Out (beta) app. See [Authentication from Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-authentication.md).

## Limitations with Standard Components

While the core Lightning Out (beta) functionality is stable and complete, there are a few interactions with other Salesforce features that we’re still working on.

Chief among these features is the standard components built into the Lightning Component framework. Many standard components don’t behave correctly when used in a standalone context, such as Lightning Out (beta), and Lightning Web Components for Visualforce, which is based on Lightning Out (beta). This limitation is because the components depend on resources available in the `one.app` container.

To avoid this issue with your own components, make their dependencies explicit. Use `@salesforce/resourceUrl` to reference all required static resources that aren’t embedded in the component itself.

If you’re using standard components in your apps, they might not be fully styled, or behave as documented, when they’re used in Lightning Out (beta) or Lightning Web Components for Visualforce.

The Component Reference in the Component Library has an Experiences field for each component that lists the supported containers for the component.

**See Also**

- [Use Components in Visualforce Pages](https://developer.salesforce.com/docs/platform/lwc/use/use-visualforce.md)

<!-- document id=34174fbd612e377be63b9f9615f7448403f8fcecbbfa81b3fbac85d82c1641a0 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-dependencies.md -->

# Lightning Out (Beta) Dependencies

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

To describe the components that you want to deploy outside of Salesforce, create a Lightning Out (beta) app. A Lightning Out (beta) app is a special standalone Aura app defined with the `<aura:application>` tag. Add components to the app with the `<aura:dependency>` tag.

This example Lightning Out (beta) app uses the `myAppComponent` Lightning web component in the default `c` namespace.

```xml
<aura:application access="GLOBAL" extends="ltng:outApp">
    <aura:dependency resource="c:myAppComponent"/>
</aura:application>
```

**note:** To reference a Lightning web component in a Lightning Out (beta) app, use the naming convention `<namespace:camelCaseComponentName>`.

## Using a Lightning Out (Beta) App

In the Lightning Out (beta) app, you must:

- Set the access control to `GLOBAL`.
- Extend the app from either `ltng:outApp` or `ltng:outAppUnstyled`.
- List as a dependency every component that is referenced in a call to `$Lightning.createComponent()`.

In this example, `<c:myAppComponent>` is the top-level Lightning web component that you create on the origin server using `$Lightning.createComponent()`. Create a dependency for each component you add to the page with `$Lightning.createComponent()`.

**note:** Don’t worry about components used within the top-level component. The framework handles dependency resolution for child components.

A Lightning Out (beta) app isn’t a normal Aura app, and you shouldn’t treat it like one. Use it only to specify the components that you want to deploy externally.

In particular, note the following.

- You can’t add a template to a Lightning Out (beta) app.
- Content that you add to the body of the Lightning Out (beta) app won’t render.

## Defining a Styling Dependency

You have two options for styling your Lightning Out (beta) apps: Salesforce Lightning Design System and unstyled. Lightning Design System styling is the default, and Lightning Out (beta) automatically includes the current version of the Lightning Design System onto the page that’s using Lightning Out (beta). To omit Lightning Design System resources and take full control of your styles, perhaps to match the styling of the origin server, set your Lightning Out (beta) app to extend from `ltng:outAppUnstyled` instead of `ltng:outApp`.

**See Also**

- [_Salesforce Help_: Create a Connected App](https://help.salesforce.com/articleView?id=connected_app_create.htm)
- [_Salesforce Help_: Use CORS to Access Salesforce Resources from Web Browsers](https://help.salesforce.com/articleView?id=extend_code_cors.htm)
- [_Lightning Aura Components Developer Guide_: aura:dependency](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/ref_tag_dependency.htm)
- [Style Components with Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-slds.md)

<!-- document id=28fb7aab0a81f288c6510ccfeabc2eb98f2b4aa5ce439b90fca150f87a3817df url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-markup.md -->

# Lightning Out (Beta) Markup

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

To use Lightning Out (beta) with your external app or page, first add the Lightning Out (beta) Javascript library to the page. Then, load your Lightning Out (beta) app with the `$Lightning.use()` function. Finally, to insert a Lightning web component into the page, call `$Lightning.createComponent()` from the callback function defined in `$Lightning.use()`.

For example, here's the markup for an external page that contains a custom Lightning web component. The page is available to guest users, so an `authToken` isn't included as an argument in `$Lightning.use()`.

```html
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
    </head>
    <body>
        <h1>My External Page</h1>
        <div id="lightning-out"></div>
        <script src="https://SITE_DOMAIN/SITE_URL/lightning/lightning.out.js"></script>
        <script>
            $Lightning.use(
                'c:MyLightningOutApp', // name of the Lightning Out (beta) app
                function () { // callback after the framework and app load
                    $Lightning.createComponent(
                        'c:MyCustomComponent', // top-level component of the Lightning Out (beta) app
                        {}, // attributes to set on the component
                        'lightning-out', // DOM element ID where the component is inserted
                        function (cmp) { // callback after the component loads
                            console.log('The component was created.');
                        }
                    );
                },
                'https://SITE_DOMAIN/SITE_URL' // Experience Cloud site endpoint
            );
        </script>
    </body>
</html>
```

## Add the Lightning Out (Beta) Library to the Page

To enable an origin server for use with Lightning Out (beta), include the Lightning Out (beta) JavaScript library in the app or page that hosts your Lightning Out (beta) app. Including the library requires a single line of markup.

```html
<script src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.js"></script>
```

If you plan to use Lightning Out (beta) with an Experience Cloud site, use your site endpoint URL instead.

```html
<script src="https://SITE_DOMAIN/SITE_URL/lightning/lightning.out.js"></script>
```

**important:** The Salesforce instance from which you load the Lightning Out (beta) Javascript library must match the instance specified in the `lightningEndPointURI` parameter of the `$Lightning.use()` function.

## Load and Initialize Your Lightning Out (Beta) App

Within another `<script>` tag, add the `$Lightning.use()` function. This function loads and initializes the Lightning Component framework for your Lightning Out (beta) app.

The `$Lightning.use()` function takes four arguments.

| Name                   | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appName`              | string   | Required. The name of your Lightning Out (beta) app, including the namespace. For example, `"c:expenseAppDependencies"`.                                                                                                                                                                                                                                                                                                                           |
| `callback`             | function | Required. A function to call after the Lightning Component framework and your app have fully loaded. The callback receives no arguments. Call `$Lightning.createComponent()` from this callback function.                                                                                                                                                                                                                                          |
| `lightningEndPointURI` | string   | Required. The URL for the Lightning or Experience Cloud site domain on your Salesforce instance. For example, `https://myDomainName.lightning.force.com`.                                                                                                                                                                                                                                                                                          |
| `authToken`            | string   | Required. This argument is optional if you [share the Lightning Out (beta) app with unauthenticated users](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-public-apps.md). The session ID or OAuth access token for a valid, active Salesforce session. You must obtain this token in your own code. Lightning Out (beta) doesn’t handle authentication for you. See [Authentication from Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-authentication.md). |

**note:** You can’t use more than one Lightning Out (beta) app on a page. You can call `$Lightning.use()` more than one time, but you must reference the same Lightning Out (beta) app in every call.

## Add Your Lightning Web Components to the Page

Add your components to the page with the `$Lightning.createComponent()` function. Call `$Lightning.createComponent()` from the callback function declared in `$Lightning.use()`.

The `$Lightning.createComponent()` function takes four arguments.

| Name            | Type              | Description                                                                                                                                                                                               |
| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentName` | string            | Required. The name of the Lightning web component to add to the page, including the namespace. For example, `"c:newExpenseForm"`.                                                                         |
| `attributes`    | Object            | Required. The attributes to set on the component when it’s created. For example, `{ name: theName, amount: theAmount }`. If the component doesn’t require any attributes, pass in an empty object, `{ }`. |
| `domLocator`    | Element or string | Required. The DOM element or element ID that indicates where on the page to insert the created component.                                                                                                 |
| `callback`      | function          | A function to call after the component is added to and active on the page. The callback receives the component created as its only argument.                                                              |

**note:** You can add more than one Lightning web component to a page. Within the callback function specified in `$Lightning.use()`, call `$Lightning.createComponent()` multiple times. To add the components to different parts of the page, use different DOM locators. You must specify each component in your Lightning Out (beta) app by using the `<aura:dependency>` tag.

Behind the scenes, `$Lightning.createComponent()` calls the standard Aura `$A.createComponent()` function. Except for the DOM locator, the arguments are the same. And except for wrapping the call in some Lightning Out (beta) semantics, the behavior is also the same.

**See Also**

- [_Lightning Aura Components Developer Guide_: Dynamically Creating Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_cb_dynamic_cmp_async.htm)

<!-- document id=9f11e7d1fade0ce37f243b5e3327352a99c99a23d33d0412fc0e46689133f88f url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-requirements.md -->

# Lightning Out (Beta) Requirements

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

Deploying a Lightning web component using Lightning Out (beta) has a few requirements to ensure connectivity and security.

## Remote Web Container

Verify that the remote web container, or origin server, supports these requirements.

- Ability to modify the markup served to the client browser, including both HTML and JavaScript. You must be able to add the Lightning Out (beta) markup.
- Ability to acquire a valid Salesforce session ID.
- Ability to access your Salesforce instance. For example, if the origin server is behind a firewall, it needs permission to access the Internet, at least to reach Salesforce.

## Lightning Locker

Use Lightning Locker, which is a security architecture for Lightning components. Lightning Out (beta) isn’t supported when Lightning Web Security is enabled. We recommend Lightning Web Security as the preferred security architecture for most orgs, but you must use Lightning Locker instead if you use Lightning Out (beta).

## Salesforce Org

Configure your Salesforce org.

- Create a Connected App so that the origin server can authenticate and connect.
- Add the origin server to the Cross-Origin Resource Sharing (CORS) allowlist.

## Lightning Out (Beta) App

Create a special Lightning Out (beta) app that contains dependency information for all Lightning web components hosted on the origin server.

## Browser Third-Party Cookies

To work with Lightning Out (beta), you must either set up a custom domain or your Safari users must change their cross-site tracking browser setting. This requirement applies to Safari users on desktop and mobile devices. For more details, see [Enable Browser Third-Party Cookies for Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-third-party-cookies.md).

**See Also**

- [_Security for Lightning Components_: Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html)

<!-- document id=edf35957cb702b221862fa6547b11bab1691c0c769d7440f8efe3bf457470c5c url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-limitations.md -->

# Lightning Out 2.0 Limitations

Be aware of current Lightning Out 2.0 limitations.

- Lightning Out 2.0 supports embedding only custom Lightning web components (LWC). To use a standard LWC component, wrap the component in a custom Lightning web component. The standard component may not be fully styled, or behave as documented, when it’s used in a Lightning Out 2.0 app.
- Lightning 2.0 doesn’t support embedding Aura components, including any custom or standard Aura components.
- Lightning Out 2.0 requires third-party, or cross-origin, cookies. End users must enable third-party cookies in their browser. Additionally, make sure that cross-domain Salesforce session cookies are enabled in your org. See [Prepare to Build a Lightning Out 2.0 App](https://help.salesforce.com/s/articleView?id=platform.lightning_out_prepare.htm&type=5) in _Salesforce Help_.
- You can’t load the Lightning Out 2.0 JavaScript library from a Lightning web component because Lightning Web Security (LWS) blocks ‌the insertion of HTML script elements. Instead, load the Lightning Out 2.0 JavaScript library directly from the host page.
- Lightning Out 2.0 doesn’t support page navigation for embedded LWC components. The `lightning/navigation` service isn’t supported.
- Lightning Out 2.0 apps are currently only available to authenticated Salesforce users. Unauthenticated user access isn’t supported yet.
- Lightning Out 2.0 doesn’t support authorization with the OAuth 2.0 client credentials flow because that flow doesn’t provide user context. See [Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_auth.htm&language=en_US&type=5) in _Salesforce Help_.
- To view limitations specific to passing component styles and other properties, see [Set Component Styles and Properties in a Lightning Out 2.0 App](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-component-properties.md).

**See Also**

- [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md)
- [_Salesforce Help_: Platform Cookies:](https://help.salesforce.com/s/articleView?id=xcloud.platform_cookies.htm&type=5)

<!-- document id=c41f21c4a347970649c849e61babe97b91780c14d25222b4876836488e6672d1 url=/developer/current/en-us/lwc/lwc/guides/interop/interop-intro.md -->

# Lightning Web Components and Aura Components Working Together

An interoperability layer enables Lightning web components and Aura components to work together in an app.

You can write new Lightning web components and add them to apps that contain Aura components. Or, you can iteratively migrate on your schedule by replacing individual Aura components in your app with Lightning web components.

Lightning web components and Aura components can work together, but there are limitations that you must understand.

**important:** Aura components can contain Lightning web components. However, the opposite doesn’t apply. Lightning web components can’t contain Aura components.

**See Also**

- [Lightning Web Components Video Gallery: Aura Component Interoperability](https://developer.salesforce.com/tv/lwc-video-gallery)

<!-- document id=8cd7cc2056af78e86a14a154c7d37a5a89a9a39166b2e91b057450d8ec386c08 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-release-notes.md -->

# Lightning Web Components Release Notes

Use the Salesforce Release Notes to learn about the most recent updates and changes to Lightning Web Components.

For updates and changes that impact Lightning Web Components, see [Lightning Components](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc.htm) in the Salesforce Release Notes.

For new and changed components and modules, see [Lightning Components: New and Changed Items](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc_nc.htm) in the Salesforce Release Notes.

<!-- document id=1174db59e8427a7b6f01af0b4a76f0a385fd69e5d62e1cd3da32698dd1f59a72 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-oss.md -->

# Lightning Web Components: Open Source

Lightning Web Components is open source, empowering you to explore the source code, customize the behavior for your needs, and build enterprise-ready web components on any platform, not just Salesforce.

In the past, you had to use different frameworks to build different sides of an application hosted outside Salesforce. For example, you used Aura to build the employee-facing side of an application on Salesforce. You used React, Angular, or Vue to build the customer-facing side of the application, and you deployed it on Heroku or on another platform. Today, you can use Lightning web components to build both sides of the application. The benefits are significant. You can now learn one framework instead of several. You can share code between apps. And you’re using a cutting-edge framework built on web standards and based on the latest patterns and best practices.

- GitHub repo—[github.com/salesforce/lwc](https://github.com/salesforce/lwc)
- Open-source developer site—[lwc.dev](https://lwc.dev)

The Lightning Web Components Developer Guide (which you’re reading now) documents how to develop Lightning web components that run on Lightning Platform and how to use platform features like Lightning Data Service, Lightning Locker, and Lightning Out 2.0.

Like Lightning Web Components open source, Lightning Out 2.0 lets you run Lightning web components off Lightning Platform. If your component needs to access Salesforce data, use Lightning Out 2.0. If your component doesn’t need Salesforce data or any other Salesforce feature, develop it using Lightning Web Components open source.

## Differences Between LWC Open Source and LWC on the Salesforce Platform

**important:** The code in the open-source repository is ahead of the code available on Lightning Platform. Most features released in the open-source repository are eventually released on Lightning Platform.

Lightning Web Components on the Salesforce platform is a managed version of Lightning Web Components: Open Source. When working off the Salesforce platform, you can [download LWC](https://github.com/salesforce/lwc), configure it your way, deploy your application on any hosting environment, and chose when to upgrade. When working on the Salesforce platform, Salesforce manages the configuration, deployment, and upgrade of LWC for all customers.

LWC OSS and LWC on the platform have different release schedules. The LWC engineering team usually [releases LWC OSS](https://github.com/salesforce/lwc/releases) weekly, whereas the [Salesforce platform is released](https://help.salesforce.com/articleView?id=release-notes.salesforce_release_notes.htm) three times a year. Because of this difference, the version of LWC on the Salesforce platform is 3–6 months behind the open-source version of LWC.

The open-source LWC engine is identical to the LWC engine on the Salesforce platform. The difference is how the engine is configured at the compiler level and at run time.

## Compile-time Differences on the Salesforce Platform

- Usage of experimental LWC APIs on the Salesforce platform is restricted and throws a linting error.
  - Experimental template APIs: [`lwc:dynamic`](https://github.com/trailheadapps/lwc-recipes-oss/tree/master/src/modules/recipe/compositionDynamic) (deprecated and replaced by [`<lwc:component lwc:is={componentConstructor}>`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md))
  - Experimental JavaScript APIs: `buildCustomElementConstructor`, `createElement`, `swapComponent`, `swapTemplate`, and `swapStyle`
- When pushing an LWC module to the Salesforce platform, the following linting rules are applied.
  - All the rules from [`@salesforce/eslint-config-lwc/base`](https://github.com/salesforce/eslint-config-lwc#salesforceeslint-config-lwcbase-configuration) are enforced. ESLint ignores inline configuration for those rules.
  - [Dynamic import](https://github.com/trailheadapps/lwc-recipes-oss/blob/master/src/modules/recipe/compositionDynamic/compositionDynamic.js) (`import('c/foo')`) is prohibited.
  - Access to Aura from an LWC module is prohibited (for example, `$A`).
- `@salesforce/*` imports are validated against the organization’s metadata (for example, Apex methods, labels, and schema).

## Run-time Differences on the Salesforce Platform

- Components run with `@lwc/synthetic-shadow` enabled. This mode allows [support for IE11](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md), which doesn’t implement shadow DOM. As a side effect, all the styles injected at the page level (for example, using `loadStyle` from `lightning/platformResourceLoader`) leak into components.
- `link` and `href` attributes on the SVG `<use>` element are sanitized by Locker to prevent potential malicious script injection.
- LWC modules are evaluated inside [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html) or [Lightning Web Security](/docs/platform/lightning-components-security/guide/-lws-intro.html). On top of the restrictions applied to standard web platform APIs, Locker and Lightning Web Security add a few restrictions to LWC components:

  - `this.template.host` always returns `null`.

    ```javascript
    import { LightningElement } from "lwc";

    export default class extends LightningElement {
      connectedCallback() {
        console.log(this.template.host);
        // OSS: the component host element
        // Platform: null
      }
    }
    ```

  - Accessing `shadowRoot` on a component retrieved from the template always returns `null`.

    ```javascript
    import { LightningElement } from "lwc";

    export default class extends LightningElement {
      renderedCallback() {
        const child = this.template.querySelector("c-child");
        console.log(child.shadowRoot);
        // OSS: the child component ShadowRoot
        // Platform: null
      }
    }
    ```

**See Also**

- [github.com/salesforce/lwc](https://github.com/salesforce/lwc)
- [lwc.dev](https://lwc.dev)
- [Differences Between Building Lightning Web Components on Lightning Platform and Open Source](https://developer.salesforce.com/blogs/2019/06/differences-between-building-lightning-web-components-on-lightning-platform-and-open-source.html)
- [Use Components Outside Salesforce with Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out.md)

<!-- document id=5e11fc5ce5efdf0c42ac65017f12b1f1bc2c0e2046f09cd81e3679204b26c064 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-intro.md -->

# Lightning Web Security

Lightning Web Security (LWS) is a security architecture that’s designed to make it easier for your Lightning components to use secure coding practices. LWS is enabled by default for all orgs created in Winter ’23 and later. As of Summer ’23, LWS for Lightning web components and Aura components is generally available for all orgs. Previously, [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md) was the default security architecture for Lightning components.

Lightning Web Security is modeled after the latest [TC39 standards](https://tc39.es/) to provide innovative usable security for any UI component. This approach enables teams to safely use code from third parties without fear of threats such as cross-site scripting (XSS) attacks. The result is a more secure way to control the execution of code within the UI layer without forcing developers to jump through hoops or abandon desired functionality.

The good news is that LWS doesn’t require refactoring your Lightning component code because your code already abides by the security practices that Lightning Locker also requires. Most existing Lightning components seamlessly work when you enable LWS.

Even better news is you have the option to refactor your code so that your components can take advantage of [LWS-only features](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md). Your components run in an [isolated JavaScript environment](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md#virtualization-of-the-browser) dedicated to your namespace, but they can import components and modules from other namespaces as if they’re all running in the same environment. The namespace isolation is transparent to the components because the architecture takes care of it seamlessly for you. As a result, some of the restrictions that your components observe when running in Lightning Locker aren’t necessary in Lightning Web Security.

To get started with LWS, review these topics.

- [How Lightning Web Security Works](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md)
- [Determine if Lightning Web Security Affects Your Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-components-affected.md)
- [When to Enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-when.md)
- [Enable Lightning Web Security in an Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable.md)
- [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md)
- [Considerations Before Using LWS-Only Features](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-refactor.md)

**See Also**

- [Compare Lightning Web Security and Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md)
- [_Salesforce Help_: Lightning Web Security FAQ](https://help.salesforce.com/s/articleView?id=000392327&type=1)
- [_Salesforce Developers Blog_: What ISV Partners Need to Know About Lightning Web Security](https://developer.salesforce.com/blogs/2022/12/what-isv-partners-need-to-know-about-lightning-web-security)

<!-- document id=20e1cfa23a15a6bf77e9d6e18472b2fd07ae59de048d326c0ab6f98ed1283243 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-limitations.md -->

# Lightning Web Security Limitations

Here are some known limitations for Lightning components running with Lightning Web Security (LWS).

## Accessors for `top` and `location` Global Properties

This limitation applies to Lightning web components (LWC) and Aura components.

The `top` property must be used with these accessors.

- `window.top`
- `globalThis.top`
- `self.top`

The `location` property must be used with these accessors.

- `window.location`
- `document.location`
- `globalThis.location`
- `self.location`
- `document.defaultView.location`

## Limitations for `window.top` and `window.location`

This limitation applies to LWC and Aura components.

Generally, it’s not recommended to override or [shadow](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object_prototypes#shadowing_properties) built-in global variables.

Here’s an example of an override.

```javascript
// Don't do this
window.fetch = function(...) { /* do something else */ }
```

Here’s an example of shadowing.

```javascript
// Don't do this
let location = window.location.href;
```

In LWS, properties such as `top` and `location` on the `window` global aren’t accessible to your code by default. To allow components to have access to these properties, LWS performs some code transformations behind the scenes.

For this reason it’s best to avoid shadowing of `top` and `location` properties. When shadowing those properties, your code can produce unexpected results or not work at all. For example, you can see error messages such as `Cannot access 'location' before initialization`.

One way to make sure your code is free of such patterns is to use the [ESLint `no-shadow` rule with `builtinGlobals: true`](https://eslint.org/docs/latest/rules/no-shadow#builtinglobals) option.

Rename the variables to something other than `location` or `top`. You can use `loc` instead of `location`, for example.

```javascript
// Do this instead
let loc = window.location.href;
```

## Coding Patterns Not Supported in Aura Components

These patterns produce runtime errors in Aura components:

- `async`/`await`
- dynamic import

Aura components can’t use these techniques because they’re features introduced in ES6, which isn’t supported in Aura. Use of this syntax is typically flagged by validation rules at development time.

If an Aura component uses a static resource that uses `async`/`await` or dynamic import, it’s not detected until runtime where the component encounters an error.

## Limitations for the \$A Global Variable

When Aura components run with LWS, the `$A` global variable isn’t available to the `eval()` function or the `Function` constructor.

There’s no workaround for using `$A` with `eval()`.

**tip:** Using `eval()` with `force:refreshView` to refresh a view in LWC doesn’t work with LWS. Instead, use [RefreshView API](/docs/platform/lwc/guide/data-refreshview.html).

### Workaround to Use \$A in Functions

In Aura components, you can use dependency injection for the `Function` constructor as a workaround when LWS is enabled.

Define the function to accept an extra parameter, `$A`, which you can supply wherever it is invoked and `$A` exists on the global scope.

This example constructs a new function `fn` and specifies `$A` as one of its parameters, then invokes the function passing a reference to the accessible `$A`.

```javascript
var fn = new Function("$A", "a", "b");
fn(window.$A, 1, 2);
```

### \$A is Blocked in LWC

The `$A` variable isn’t supported in Lightning web components because it’s specific to the Aura framework.

**See Also**

- [Salesforce Global Variables Blocked by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-restricted-globals.md)
- [Troubleshoot Issues Related to LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-troubleshoot.md)

<!-- document id=4f5d72e70d4212c1c59b36bb6f7e13a6e284aa94a657303a48537f2998dbf229 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-sanitize.md -->

# Lightning Web Security Sanitization

Lightning Web Security (LWS) sanitizes content strings in HTML and SVG elements that your Lightning components inserted into the DOM. LWS examines the strings and removes content that poses a potential security risk. This sanitization process helps protect against cross-site scripting (XSS) attacks.

LWS uses an allowlist of elements and attributes that can remain in the DOM tree after sanitization.

LWS distortions on properties such as `innerHTML` and `setHTML` perform sanitization of strings. LWS can apply multiple distortions to some elements.

**important:** LWS doesn’t sanitize input text. It only filters HTML strings that components inserted into the DOM. Your code must validate or sanitize any user input.

**See Also**

- [HTML Allowlist for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-html.md)
- [SVG Allowlist for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg.md)
- [How LWS Sanitizes Static Resources in SVG Elements](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg-static-resource.md)

<!-- document id=30a652a4b70a89e0642f94b56aae9df56cae9bbbe43e6ed4eb3ca7dcccbb9efa url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-agentforce-input.md -->

# `lightning__AgentforceInput` Target

Enables a component to be used in agent actions. Use this target to configure your component to accept input data from a user in any agent action.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>64.0</apiVersion>
   <isExposed>true</isExposed>
   <targets>
       <target>lightning__AgentforceInput</target>
   </targets>
   <targetConfigs>
       <targetConfig targets="lightning__AgentforceInput">
           <targetType name="lightning__customType"></targetType>
           <property name="myString" type="lightning__textType"></property>
           <property name="myBoolean" type="lightning__booleanType"></property>
       </targetConfig>
   </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs` (Optional)

Configures the component for different targets and defines component properties. For agent actions, `lightning__AgentforceInput` and `lightning__AgentforceOutput` are supported targets. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a component for action input with this attribute.

| Attribute | Description                                                                                                                                                                                                                                               | Required |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more [targets](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md#targets) in the `targets` attribute, such as `<targetConfig targets="lightning__AgentforceInput">` or `<targetConfig targets="lightning__AgentforceInput,lightning__AgentforceOutput">`. | Yes      |

### `targetType` (Optional)

Specifies the data type that an agent action input expects from the component. To create a component that takes in one type of data and expects to return a different type of data, include both `sourceType` and `targetType`. For example, a component can let you select a single record from a set of records. The `lightning__AgentforceInput` target can have both `sourceType` and `targetType`, or up to one `targetType` tag.

| Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `name`         | Name of the Lightning type that the agent action input expects from the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. <doc-content-callout header="Note" variant="note">When you specify a custom Lightning type, you restrict the component to that type. This restriction means the component can only be used with that specific custom Lightning type and can't be reused with any other. To use this component with a different custom Lightning type, create another `<targetConfig>` entry and specify the new type in its `targetType` attribute.</doc-content-callout> | Yes      |
| `itemTypeName` | Name of the Lightning type that the agent action input expects from the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. **This attribute can only exist when the name attribute is a list or a similar type.**                                                                                                                                                                                                                                                                                                                                                                    | No       |

### `sourceType` (Optional)

Specifies the data type that the agent action input provides to the component.

| Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`         | Name of the Lightning type that the agent action input provides to the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. <doc-content-callout header="Note" variant="note">When you specify a custom Lightning type, you restrict the component to that type. This restriction means the component can only be used with that specific custom Lightning type and can't be reused with any other. To use this component with a different custom Lightning type, create another `<targetConfig>` entry and specify the new type in its `targetType` attribute.</doc-content-callout> | Yes      |
| `itemTypeName` | Name of the Lightning type that the agent action input provides to the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. **This attribute can only exist when the `name` attribute is a list or a similar type.**                                                                                                                                                                                                                                                                                                                                                                  | No       |

### `property`

Specifies a public property of a component. The component author defines the property in the component’s JavaScript class by using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute | Type   | Description                                                                                                                                                                                                                                                                                                                                                                     | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`    | String | The property name. The component's JavaScript class must have an `@api` property with the same name as the property name value.                                                                                                                                                                                                                                                 | Yes      |
| `type`    | String | The property’s data type. Make sure that this value matches the type assigned to the property in the component’s JavaScript module. If the types don’t match, the value in the configuration file takes precedence. Supports [standard Lightning types](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) and custom Lightning types. | Yes      |

## Usage

To expose a component property in an agent action, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  @api myString;
  @api myBoolean;
}
```

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [Custom Lightning Types](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html)

<!-- document id=ef72590f75fce071fee34f380d069a2216f245eaaf5f6a909cac98fb33d9bf0b url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-agentforce-output.md -->

# `lightning__AgentforceOutput` Target

Enables a component to be used in agent actions. Use this target to configure your component to display output data from an agent action.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>64.0</apiVersion>
   <isExposed>true</isExposed>
   <targets>
       <target>lightning__AgentforceOutput</target>
   </targets>
   <targetConfigs>
       <targetConfig targets="lightning__AgentforceOutput">
           <sourceType name="lightning__customType"></sourceType>
           <property name="myString" type="lightning__textType"></property>
           <property name="myBoolean" type="lightning__booleanType"></property>
       </targetConfig>
   </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs` (Optional)

Configures the component for different targets and defines component properties. For agent actions, `lightning__AgentforceInput` and `lightning__AgentforceOutput` are supported targets. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a component for action output with this attribute.

| Attribute | Description                                                                                                                                                                                                                                              | Required |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify 1 or more [targets](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md#targets) in the `targets` attribute, such as `<targetConfig targets="lightning__AgentforceOutput">` or `<targetConfig targets="lightning__AgentforceInput,lightning__AgentforceOutput">`. | Yes      |

### `sourceType` (Optional)

Specifies the data type that the agent action output provides to the component. The `lightning__AgentforceOutput` target can have up to one `sourceType` tag.

| Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `name`         | Name of the Lightning type that the agent action output provides to the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. <doc-content-callout header="Note" variant="note">When you specify a custom Lightning type, you restrict the component to that type. This restriction means the component can only be used with that specific custom Lightning type and can't be reused with any other. To use this component with a different custom Lightning type, create another `<targetConfig>` entry and specify the new type in its `targetType` attribute.</doc-content-callout> | Yes      |
| `itemTypeName` | Name of the Lightning type that the agent action output provides to the component. This can be a [standard Lightning type](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) or a custom Lightning type. **This attribute can only exist when the `name` attribute is a list or a similar type.**                                                                                                                                                                                                                                                                                                                                                                  | No       |

### `property`

Specifies a public property of a component. The component author defines the property in the component’s JavaScript class by using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute | Type   | Description                                                                                                                                                                                                                                                                                                                                                                     | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`    | String | The property name. The component's JavaScript class must have an `@api` property with the same name as the property name value.                                                                                                                                                                                                                                                 | Yes      |
| `type`    | String | The property’s data type. Make sure that this value matches the type assigned to the property in the component’s JavaScript module. If the types don’t match, the value in the configuration file takes precedence. Supports [standard Lightning types](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html) and custom Lightning types. | Yes      |

## Usage

To expose a component property in an agent action, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  @api myString;
  @api myBoolean;
}
```

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [Custom Lightning Types](https://developer.salesforce.com/docs/einstein/genai/guide/lightning-types-references.html)

<!-- document id=d222cd34336348ed0efffc68bd7ebfb687af725414dd4cb9a200b7cce976d314 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-app-page.md -->

# `lightning__AppPage` Target

Enables a component to be used on an App page in Lightning App Builder. Enables a component to be used in a Lightning app, such as in a Console app.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
    </targets>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for a Lightning app page and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                        | Required |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__AppPage">` or `<targetConfig targets="lightning__RecordPage,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag. You can also include one or more `event` tags.

### `property`

Specifies a public property of a component that can be set in Lightning App Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

## `event`

Exposes an event for [Dynamic Interactions](https://help.salesforce.com/articleView?id=platform.dynamic_interactions_overview.htm), which allows it to appear on the Events tab in the Lightning App Builder component property panel.

The event tag supports these attributes.

| Attribute     | Type   | Description                                                                                                                                                                                 | Required |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String | The name of the event as defined in the `.js` file. If no label attribute is defined, the `name` value is shown in the list of available events for the component in Lightning App Builder. | Yes      |
| `description` | String | The description of the event. Appears as an i-bubble on the event label in Lightning App Builder.                                                                                           |          |
| `label`       | String | The admin-friendly label for the event.                                                                                                                                                     |          |

The `event` tag contains a required `schema` tag.

### `schema`

Provides the shape of an `event`. Content in the `schema` tag must be in JSON format.

The [Dynamic Interactions](https://help.salesforce.com/articleView?id=platform.dynamic_interactions_overview.htm) feature uses only type and properties from the schema. All other items in the schema are ignored. In the event schema, valid property types are `String`, `Integer`, and `Boolean`. For an example schema, see [Configure a Component for Dynamic Interactions in the Lightning App Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-app-builder-dynamic-interactions.md).

## `supportedFormFactors`

A set of one or more form factors or devices that the component supports. Specify the `supportedFormFactors` tag set one time inside a `targetConfig` set. The `supportedFormFactors` tag contains at least one `supportedFormFactors` tag.

### `supportedFormFactor`

Defines which form factor or device the component supports. Use one `supportedFormFactor` tag for each supported form factor.

The `supportedFormFactor` tag supports this attribute.

| Attribute | Type   | Description                                                                                                                                                                           | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`    | String | Device form factor on which the component displays. Valid values are: <ul><li>`Large`—Represents the desktop form factor.</li><li>`Small`—Represents the phone form factor.</li></ul> | Yes      |

**note:** We strongly recommend including supported form factor information in the configuration file. See [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/use/use-config-form-factors.md).

## Usage

To expose a component property in Lightning App Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```
import { LightningElement, api } from 'lwc';

export default class CompositionWithAppBuilder extends LightningElement {
    @api picklistValue;
    @api stringValue;
    @api numberValue;
}

```

```
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle
    xmlns="http://soap.sforce.com/2006/04/metadata"
    fqn="compositionWithAppBuilder"
>
    <apiVersion>66.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__AppPage, lightning__HomePage">
            <property
                name="picklistValue"
                type="String"
                datasource="Option One, Option Two, Option Three"
            />
            <property
                name="stringValue"
                type="String"
                placeholder="Type something here..."
            />
            <property
                name="numberValue"
                type="Integer"
                min="0"
                max="100"
                default="10"
            />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

```

**See Also**

- [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-app-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=b506d3aa7c4794794319f6a387d12643ce40e16b7592b332858dca237eda5622 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-ECSFSApp.md -->

# `lightning__ECSFSApp` Target

Enables a component to be used in Field Service Mobile App Builder.

## Syntax

```xml
<?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__ECSFSApp</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__ECSFSApp">
            <property name="contactName" type="String" label="Contact Name" required="true" description="A contact name property example." placeholder="Enter contact name"/>
            <property name="isActive" type="Boolean" label="Active" required="true" description="A boolean property example." default="true"/>
            <property name="priority" type="Integer" label="Priority" description="An integer property example." placeholder="Enter priority"/>
            <property name="category" type="String" label="Category" required="true" description="A picklist property example." datasource="category1,category2,category3"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for Field Service Mobile App Builder and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                       | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__ECSFSApp">` or `<targetConfig targets="lightning__ECSFSApp,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag. You can also include one or more `event` tags.

### `property`

Specifies a public property of a component that can be set in Field Service Mobile App Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. Valid values are: <ul><li>`Boolean`</li><li>`Integer`</li><li>`Picklist`</li><li>`String`</li></ul>                                                                                                                                                                                                                                                                                                                                                                       | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Field Service Mobile App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                       |          |
| `label`       | String  | Displays as a label for the attribute in Field Service Mobile App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Field Service Mobile App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the `type` attribute is `String`.                                                                                                                                                                                                                                                            |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `maxLength`   | Integer | The maximum number of characters allowed for an attribute of type `String`.                                                                                                                                                                                                                                                                                                                                                                                                                          |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `minLength`   | Integer | The minimum number of characters allowed for an attribute of type `String`.                                                                                                                                                                                                                                                                                                                                                                                                                          |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

## Usage

To expose a component property in Field Service Mobile App Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class StringPicklistComponent extends LightningElement {
  @api stringProp;
  @api picklistProp;

  properties = [];

  connectedCallback() {
    this.initializeData();
  }

  initializeData() {
    const picklistData = [
      { id: 1, stringProp: "Example string 1", picklistProp: "Option1" },
      { id: 2, stringProp: "Example string 2", picklistProp: "Option2" },
      { id: 3, stringProp: "Example string 3", picklistProp: "Option3" },
      { id: 4, stringProp: "Example string 4", picklistProp: "Option1" },
      { id: 5, stringProp: "Example string 5", picklistProp: "Option2" },
    ];

    this.properties = picklistData.filter((data) => {
      return (
        (!this.stringProp || data.stringProp.includes(this.stringProp)) &&
        (!this.picklistProp || data.picklistProp === this.picklistProp)
      );
    });
  }
}
```

```xml
<?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__ECSFSApp</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__ECSFSApp">
            <property name="stringProp" type="String" label="String Property" required="true" description="A string property example." placeholder="Enter string"/>
            <property name="picklistProp" type="String" label="Picklist Property" required="true" description="A picklist property example." datasource="Option1,Option2,Option3"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

```

**See Also**

- [_Salesforce Help_: Customize Tabs with the Field Service Mobile App Builder](https://help.salesforce.com/s/articleView?id=service.mfs_builder.htm)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=28b7d8a5b31691e98bc95025d9f45d481018d9a72a6809c74e99c1aadefb6eab url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-enablement-program.md -->

# `lightning__EnablementProgram` Target

Enables a component to be used in Program Builder as a [custom exercise type](https://help.salesforce.com/s/articleView?id=sales.enablement_custom_items_overview.htm) for an Enablement program. Components appear in the Custom Items section of the Components list in the Program Builder palette.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>61.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Screen Flows</masterLabel>
    <description>Screen Flows</description>

    <targets>
        <target>lightning__EnablementProgram</target>
    </targets>

    <targetConfigs>
        <targetConfig targets="lightning__EnablementProgram">
            <property name="title" type="String" max="80" required="true" default="" label="Name"/>
            <property name="description" type="multilinetext" required="true" default="" max="350" label="Description" />
            <property name="day" type="Integer" min="1" max="365" default="1" required="true" label="Day"/>
            <property name="category" type="String" default="Exercise" />
            <property name="subCategory" type="String" default="ScreenFlow" />
            <property name="customContent" type="String" default="" datasource="apex://ScreenFlowPicklist" label="Screen Flows" />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for a custom item on an Enablement program and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a custom item for an Enablement program with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                                         | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__EnablementProgram">` or `<targetConfig targets="lightning__EnablementProgram,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies the properties of the Program Builder's property sheet for a custom item. Use the `property` tag with these attributes.

| Attribute    | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Required |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`       | String  | The attribute name. Possible values are: <ul><li>`title`</li><li>`description`</li><li>`day`</li><li>`category`</li><li>`subCategory`</li><li>`customContent`</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                             | Yes      |
| `type`       | String  | The data type. Possible values are: <ul><li>`Integer`—Use for `day`.</li><li>`Multilinetext`—Use for `description`.</li><li>`String`—Use for `title`, `category`, `subCategory`, and `customContent`.</li></ul>                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `datasource` | String  | The data source for `customContent` that shows the default picklist field on Program Builder's property editor. Supported only if the `type` attribute is `String`. You need to create a [DynamicPickList Apex class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_VisualEditor_DynamicPickList.htm) to configure this property as a picklist. To customize the user interface for the Custom Content field, use the editor attribute and a Lightning web component instead of `datasource`.                                                   |          |
| `default`    | String  | The default value. Not applicable for `customContent`. Possible values are: <ul><li>For `category`, valid value is `Exercise`.</li><li>For `subCategory`, provide the namespace prefix and developer name as the default value, using the format `NamespacePrefix_DeveloperName`. If the namespace prefix isn't available, provide the developer name.</li><li>(Optional) For `title` and `description`, the pre-filled label to be shown in the property sheet.</li><li>(Optional) For `day`, the minimum number of days the item is due. We recommend to set this to 1.</li></ul> |          |
| `editor`     | String  | To customize the Custom Content field on Program Builder's property editor, use the `editor` attribute and a Lightning web component instead of the `datasource` attribute.                                                                                                                                                                                                                                                                                                                                                                                                         |          |
| `label`      | String  | The label as displayed in the property sheet. Applies to these properties: <ul><li>`title`</li><li>`description`</li><li>`day`</li><li>`customContent`</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                    |          |
| `max`        | Integer | Maximum value accepted for the property. Possible values are: <ul><li>For `title`, the maximum character length. The maximum allowed is 80 characters. Set this to 80 or less.</li><li>For `description`, the maximum character length. The maximum allowed is 350 characters. Set this to 350 or less.</li><li>For `day`, the maximum number of days until the item is due, relative to the program's start date. The maximum is 365. Set this to 365 or less.</li></ul>                                                                                                           |          |
| `min`        | Integer | Minimum value accepted for the property. Possible values are: <ul><li>For `day`, the minimum number of days until the item is due, relative to the program's start date. The minimum is 1, the day the exercise is assigned.</li><li>(Optional) For `title` and `description`, the minimum character length.</li></ul>                                                                                                                                                                                                                                                              |          |
| `required`   | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |          |

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [_Salesforce Help_: Custom Exercise Types in Enablement Programs](https://help.salesforce.com/s/articleView?id=sales.enablement_custom_items_overview.htm)

<!-- document id=8969581a3e94beae227528caee4733f7bb47c778c38dc1a4310d64e612abc428 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-flow-action.md -->

# `lightning__FlowAction` Target

Enables a component to be used on flow screens in Flow Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
      <target>lightning__FlowAction</target>
  </targets>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for flow screens and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a component for flow screens with these attributes.

| Attribute             | Description                                                                                                                                                                                                                                                                                                                      | Required |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets`             | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__FlowAction">` or `<targetConfig targets="lightning__FlowAction,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`.                            | Yes      |
| `configurationEditor` | Registers a custom property editor for a flow action component. A custom property editor is a Lightning web component that provides a custom UI for configuring a custom flow action component’s input attributes. See [Customize Action and Screen Component UI in Flow Builder](https://developer.salesforce.com/docs/platform/use/use-flow-custom-property-editor.md). |          |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Flow Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Required |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence. <ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li><li>`apex://namespace.Classname`—An Apex class used for an Apex-defined data type. If the class is in the same namespace as the component, don't specify a namespace. If the class is in a managed package, specify the namespace of the managed package.</li><li>`Date`—A date in ISO 8601 format.</li><li>`DateTime`—A datetime in ISO 8601 format.</li><li>`@salesforce/schema/namespace__Objectname` or `@salesforce/schema/Objectname`—An object. See [`@salesforce` modules](https://developer.salesforce.com/docs/platform/lwc/reference-salesforce-modules.md).</li></ul> | Yes      |
| `default`     | String  | The default value for the attribute. This attribute doesn’t get populated at runtime. We recommend setting the default value in the JavaScript file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |          |
| `description` | String  | Displays as an i-bubble for the attribute in Flow Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `label`       | String  | Displays as a label for the attribute in Flow Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `role`        | String  | Specifies whether the attribute is `inputOnly` or `outputOnly`. If you don't specify the `role` attribute, the default value allows input and output. If you don't set the `role` attribute, the property is exposed in a custom property editor. If you set it to `outputOnly`, the property isn't exposed in a custom property editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |

## Usage

To expose a component property in Flow Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class Example extends LightningElement {
  @api volume;
}
```

<!-- document id=cb303d4a9484554a5c7cd42232670c25a0c23ccfad15425f8243dd41caff264b url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-flow-screen.md -->

# `lightning__FlowScreen` Target

Enables a component to be used on flow screens in Flow Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
      <target>lightning__FlowScreen</target>
  </targets>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for flow screens and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a component for flow screens with these attributes.

| Attribute             | Description                                                                                                                                                                                                                                                                                                                      | Required |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets`             | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__FlowScreen">` or `<targetConfig targets="lightning__FlowScreen,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`.                            | Yes      |
| `configurationEditor` | Registers a custom property editor for a flow screen component. A custom property editor is a Lightning web component that provides a custom UI for configuring a custom flow screen component’s input attributes. See [Customize Action and Screen Component UI in Flow Builder](https://developer.salesforce.com/docs/platform/use/use-flow-custom-property-editor.md). |          |

The `targetConfig` tag includes at least one `property` tag. You can also include one or more `propertyType` tag.

### `property`

Specifies a public property of a component that can be set in Flow Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Required |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Yes      |
| `type`        | String  | The attribute’s data type. Make sure that the value used matches the type assigned to the property in the component’s JavaScript module. If the types don’t match, the value in the configuration file takes precedence. The following values are valid for all targets.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li><li>`Double`—Only valid when the property has the attribute `flowRole="flowRunetimeApiVersion"`.</li><li>`apex://namespace.Classname`—An Apex class used for an Apex-defined data type. If the class is in the same namespace as the component, don’t specify a namespace. If the class is in a managed package, specify the namespace of the managed package.</li><li>`Date`—A date in ISO 8601 format.</li><li>`DateTime`—A datetime in ISO 8601 format.</li><li>`@salesforce/schema/namespace__Objectname` or `@salesforce/schema/Objectname`—An object. See [`@salesforce` modules](https://developer.salesforce.com/docs/platform/lwc/reference-salesforce-modules.md).</li></ul> | Yes      |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |          |
| `description` | String  | Displays as an infobubble for the attribute in Flow Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |          |
| `label`       | String  | Displays as a label for the attribute in Flow Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |          |
| `role`        | String  | Specifies whether the attribute is `inputOnly` or `outputOnly`. If you don’t specify the `role` attribute, the default value allows input and output. For example, if a property is restricted to `outputOnly`, users can’t set its value from a Lightning record page. If you don’t set the role attribute, or if you set it to `inputOnly`, the property is exposed in a custom property editor. If you set it to `outputOnly`, the property isn’t exposed in a custom property editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |          |
| `flowRole`    | String  | Specifies a flow-dependent role for the property. <ul><li>`flowRuntimeApiVersion`—Configures the property to return the runtime API version of the flow in which the component is used. This property doesn’t render in Flow Builder, but conditional code can execute based on the version returned. Set `type="Double"` and `role="inputOnly"` to use this value.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

### `propertyType`

Defines a data type to extend for component properties in flow screen components. Only generic `sObject` and `sObject` collection data types can be extended.

Use the `propertyType` tag with these attributes.

| Attribute     | Type   | Description                                                                                                           | Required |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String | Specifies the data type name to reference from each `type` attribute that is defined in a component’s `property` tag. | Yes      |
| `extends`     | String | Specifies the data type to extend for component properties.                                                           | Yes      |
| `description` | String | Description of the property type.                                                                                     |          |
| `label`       | String | Label of the property type.                                                                                           |          |

### `stylingHook`

Defines a styling hook to surface in Flow Builder for a flow screen component. Users can edit the hooks directly in the Style tab while building a flow screen.

| Attribute     | Type   | Description                                                                                                                                | Required |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `name`        | String | Specifies the styling hook to surface. This value must match either a custom-defined CSS styling hook or a predefined SLDS 1 styling hook. | Yes      |
| `label`       | String | Displays as a label for the attribute in Flow Builder.                                                                                     | Yes      |
| `type`        | String | Specifies the type of editor displayed in Flow Builder. Valid values are `color`, `dimension`, or `string`.                                | Yes      |
| `description` | String | Displays as an infobubble for the attribute in Flow Builder.                                                                               |          |

### `stylingHookGroup`

Defines a group of styling hooks. This tag is optional, but it’s useful for organization if the component has many styling hooks. Nest `stylingHook` tags within a single `stylingHookGroup` to group them together.

| Attribute      | Type    | Description                                                                                                           | Required |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`         | String  | Specifies an arbitrary identifier for the group. This value must be unique within the component’s configuration file. | Yes      |
| `label`        | String  | Displays as the group’s title or tab label in Flow Builder.                                                           |          |
| `displayInTab` | Boolean | Specifies whether the group renders as one tab in a set. Defaults to `false`.                                         |          |

**note:** Any given configuration can have only one set of tabs. All groups set to `displayInTab="true"` render within the same set of tabs. All groups not displayed as tabs render before the tab set.

## Usage

To expose a component property in Flow Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class Example extends LightningElement {
  @api volume;
}
```

For more information, see these examples:

- [Custom Property Editor for a Screen Component](https://developer.salesforce.com/docs/platform/use/use-flow-custom-property-editor-lwc-example.md)
- [Generic SObject Input for Screen Components](https://developer.salesforce.com/docs/platform/use/use-flow-custom-property-editor-sobject-lwc-example.md)
- [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/create/css/create-components-css-custom-properties.md)

**See Also**

- [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/use/use-config-for-flow-screens.md)
- [Embed a Flow in a Custom Lightning Web Component](https://developer.salesforce.com/docs/platform/use/use-flow-embed-component.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=e80af0146179cd339997485c3cad7ca1cc1af037382278663694e381fb25e289 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-global-action.md -->

# `lightning__GlobalAction` Target

Enables a component to be used as a global quick action. For use only in the Field Service mobile app.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__GlobalAction</target>
   </targets>
   <targetConfigs>
        <targetConfig targets="lightning__GlobalAction">
            <actionType>ScreenAction</actionType>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for a record action and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

## `targetConfig`

Configures a page type with this attribute.

| Attribute    | Description                                                                                                                                                                                                                                                                                               | Required |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets`    | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__GlobalAction">` or `<targetConfig targets="lightning__GlobalAction,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |
| `actionType` | Specify the type of Lightning web component global action. Valid values are: <ul><li>`ScreenAction`—(Default) Runs custom code in a modal window</li><li>`Action`—Runs custom code without opening a modal window</li></ul> The default value is `ScreenAction`.                                          |          |

`lightning__GlobalAction` doesn't support component properties.

## Usage

LWC global quick actions are available for use only in the Field Service mobile app. These actions aren’t available in Lightning Experience on mobile or desktop.

To access the global action from the bottom navigation bar on the Field Service mobile app, from Setup, in the Quick Find box, enter `Publisher Layouts`, and then select **Publisher Layouts**. Add the action to the **Salesforce Mobile and Lightning Experience Actions** section of the global publisher layout.

To enable a component to be used as a quick action on a record page record, use [`lightning__RecordAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-record-action.md) instead.

**note:** You can't change the action type after you've defined it in the configuration file. For example, you can't change a component's action type from `Action` to `ScreenAction` or vice versa after you deploy your component.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [_Salesforce Help_: Create Global Quick Actions](https://help.salesforce.com/s/articleView?id=platform.creating_global_actions.htm)
- [GitHub: LWC Mobile Samples](https://github.com/forcedotcom/LWC-Mobile-Samples)

<!-- document id=f8f7eaf48951864ab3f222512b74dc14ae268e2c470787eedccacb0c7bfbd06b url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-home-page.md -->

# `lightning__HomePage` Target

Enables a component to be used on a Home page in Lightning App Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__HomePage">
            <property name="height" type="Integer" min="0" max="600" default="300" />
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
                <supportedFormFactor type="Small" />
            </supportedFormFactors>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for an app home page and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures an app home page with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                       | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__HomePage">` or `<targetConfig targets="lightning__HomePage,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Lightning App Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

## `supportedFormFactors`

A set of one or more form factors or devices that the component supports. Specify the `supportedFormFactors` tag set one time inside a `targetConfig` set. The `supportedFormFactors` tag contains at least one `supportedFormFactors` tag.

### `supportedFormFactor`

Defines which form factor or device the component supports. Use one `supportedFormFactor` tag for each supported form factor.

The `supportedFormFactor` tag supports this attribute.

| Attribute | Type   | Description                                                                                                                                                                           | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`    | String | Device form factor on which the component displays. Valid values are: <ul><li>`Large`—Represents the desktop form factor.</li><li>`Small`—Represents the phone form factor.</li></ul> | Yes      |

**note:** We strongly recommend including supported form factor information in the configuration file. See [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/use/use-config-form-factors.md).

## Usage

To expose a component property in Lightning App Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class Example extends LightningElement {
  @api height;

  get cmpHeight() {
    const height = this.height ? `height: ${this.height}px;` : "";
    return `${height}`;
  }
}
```

Bind the `height` property in your template.

<!-- prettier-ignore -->
```html
<template>
  <p style={height}>Your content here</p>
</template>
```

The component renders with a `style` value that a user provides in the Property Editor.

```html
<p style="height: 200px;">Your content here</p>
```

**See Also**

- [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-app-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [_Salesforce Help_: Create an App Home Page with the Lightning App Builder](https://help.salesforce.com/s/articleView?id=platform.lightning_app_builder_create_app_page.htm)

<!-- document id=2d6806b6b2885b9640fb5e562564ce69707c80d46867ccb426d065a68946408a url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-inbox.md -->

# `lightning__Inbox` Target

Enables a component to be used in Lightning App Builder to add to email application panes for the Outlook and Gmail integrations.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__Inbox</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__Inbox">
             <property name="integerProperty" type="Integer" min="50" max="100" default="55"/>
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
                <supportedFormFactor type="Small" />
            </supportedFormFactors>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures an app home page with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                 | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__Inbox">` or `<targetConfig targets="lightning__Inbox,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Lightning App Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

## `supportedFormFactors`

A set of one or more form factors or devices that the component supports. Specify the `supportedFormFactors` tag set one time inside a `targetConfig` set. The `supportedFormFactors` tag contains at least one `supportedFormFactors` tag.

### `supportedFormFactor`

Defines which form factor or device the component supports. Use one `supportedFormFactor` tag for each supported form factor.

The `supportedFormFactor` tag supports this attribute.

| Attribute | Type   | Description                                                                                                                                                                           | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`    | String | Device form factor on which the component displays. Valid values are: <ul><li>`Large`—Represents the desktop form factor.</li><li>`Small`—Represents the phone form factor.</li></ul> | Yes      |

**note:** We strongly recommend including supported form factor information in the configuration file. See [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/use/use-config-form-factors.md).

## Usage

To expose a component property, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class InboxExample extends LightningElement {
  @api integerProperty;
}
```

**See Also**

- [Create Components for the Outlook and Gmail Integrations](https://developer.salesforce.com/docs/platform/use/use-config-for-app-builder-email-app-pane.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=2ebcecef8f8b0a052a846fe01a52dd92e1bafc3505eac8421d0de621049b01f4 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-property-editor.md -->

# `lightning__PropertyEditor` Target

Enables a component to be used as a custom property editor in an Experience Builder component. Reference it in a `LightningTypeBundle` or in an Experience Builder component's `js-meta.xml` file.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="alignmentCPE">
   <apiVersion>58.0</apiVersion>
   <isExposed>true</isExposed>
   <masterLabel>Alignment Editor Component</masterLabel>
   <targets>
     <target>lightning__PropertyEditor</target>
   </targets>
</LightningComponentBundle>
```

## Usage

To use this component as a custom property editor in a `LightningTypeBundle`, specify the component’s fully qualified name as a component override in the `editor.json` file.

```json
{
  "editor": {
    "componentOverrides": {
      "alignment": {
        "definition": "c/alignmentCPE"
      }
    }
  }
}
```

Alternatively, to use this component as a custom property editor for a component property, reference this component in the editor attribute of the property tag.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="customArticle">
 <masterLabel>Custom Article</masterLabel>
 <apiVersion>66.0</apiVersion>
 <targets>
   <target>lightningCommunity__Page</target>
   <target>lightningCommunity__Default</target>
 </targets>
 <targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property  name="textAlignment" type="String" editor="c/alignmentCPE" label="Text Alignment"/>
  </targetConfig>
 </targetConfigs>
</LightningComponentBundle>
```

**See Also**

- [Create a LightningTypeBundle](https://developer.salesforce.com/docs/platform/use/use-experience-cloud-create-lightningtypebundle.md)
- [Create a Custom Property Editor](https://developer.salesforce.com/docs/platform/use/use-experience-cloud-create-custom-editor.md)

<!-- document id=948dd890fdce726a58405801fdd3a241da9d549a0e59ba9ab9ee313abec09162 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-record-action.md -->

# `lightning__RecordAction` Target

Enables a component to be used as a quick action on a record page. To specify the type of quick action, define a `targetConfig` with an `actionType` attribute.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordAction</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__RecordAction">
      <actionType>ScreenAction</actionType>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for a record action and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute    | Description                                                                                                                                                                                                                                                                                                          | Required |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets`    | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__RecordAction">` or `<targetConfig targets="lightning__RecordAction,lightning__RecordPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`.         | Yes      |
| `actionType` | Specify the type of Lightning web component quick action. Valid values are: <ul><li>`ScreenAction`—(Default) Runs custom code in a modal window</li><li>`Action`—Runs custom code without opening a modal window</li></ul> See [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/use/use-config-for-quick-actions.md). |          |

`lightning__RecordAction` doesn't support component properties.

## `supportedFormFactors`

A set of one or more form factors or devices that the component supports. Specify the `supportedFormFactors` tag set one time inside a `targetConfig` set. The `supportedFormFactors` tag contains at least one `supportedFormFactors` tag.

### `supportedFormFactor`

Defines which form factor or device the component supports. Use one `supportedFormFactor` tag for each supported form factor.

The `supportedFormFactor` tag supports this attribute.

| Attribute | Type   | Description                                                                                                                                                                           | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`    | String | Device form factor on which the component displays. Valid values are: <ul><li>`Large`—Represents the desktop form factor.</li><li>`Small`—Represents the phone form factor. This value isn't supported for `lightning__RecordAction` because LWC quick actions don't appear in the Salesforce mobile app.</li></ul> | Yes      |

**note:** We strongly recommend including supported form factor information in the configuration file. See [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/use/use-config-form-factors.md).

## Usage

You can use a quick action to navigate to an object page, such as the Contact home page. In this example, a headless quick action executes custom code you provide in an `@api invoke()` method.

```
import { LightningElement, api } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';

export default class NavigateToRecordHeadlessAction extends NavigationMixin(
    LightningElement
) {
    @api invoke() {
        this[NavigationMixin.Navigate]({
            type: 'standard__objectPage',
            attributes: {
                objectApiName: 'Contact',
                actionName: 'home'
            }
        });
    }
}

```

A headless quick action corresponds to the `Action` type.

```
<?xml version="1.0" encoding="UTF-8" ?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>66.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordAction</target>
  </targets>

  <targetConfigs>
    <targetConfig targets="lightning__RecordAction">
      <actionType>Action</actionType>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>

```

**note:** You can't change the action type after you've defined it in the configuration file. For example, you can't change a component's action type from `Action` to `ScreenAction` or vice versa after you deploy your component.

Creating an LWC action in Lightning Experience is similar to creating a regular quick action. For more information, see [_Salesforce Help_: Lightning Web Component Actions](https://help.salesforce.com/s/articleView?id=platform.lightning_web_component_actions.htm). If you're creating a LWC action for the Field Service mobile app, see [_Salesforce Help_: Create Quick Actions for the Field Service Mobile App](https://help.salesforce.com/s/articleView?id=service.mfs_quick_actions.htm).

To enable a component to be used as a global quick action, use [`lightning__GlobalAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-global-action.md) instead.

**See Also**

- [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/use/use-config-for-quick-actions.md)
- [Create an Email as a Quick Action](https://developer.salesforce.com/docs/platform/use/use-quick-actions-email.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=260aef7122b25d3b39009e8ab30b86c8ffb0eabbcfe1baaefe9c1a4403dcb949 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-record-page.md -->

# `lightning__RecordPage` Target

Enables a component to be used on a record page in Lightning App Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <ai>
        <description>AI component description. Example: The component enables users to add and style text content for dashboards, supporting features such as hyperlinks, bullet points, and text alignment. Ideal for adding formatted text sections such as instructions.</description>
        <property name="height" aiDescription="AI description for the height property" />
    </ai>
    <targets>
        <target>lightning__RecordPage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__RecordPage">
            <property name="height" type="Integer" min="0" max="600" default="300" />
            <objects>
              <object>Account</object>
              <object>CustomObject__c</object>
            </objects>
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
                <supportedFormFactor type="Small" />
            </supportedFormFactors>

        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

```

## `targetConfigs`

Configures the component for an app home page and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a Lightning page with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                 | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__Inbox">` or `<targetConfig targets="lightning__Inbox,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag and can include an `objects` tag.

### `property`

Specifies a public property of a component that can be set in Lightning App Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

### `objects`

Limits the component to a set of one or more objects. If you don’t use this tag set, the component supports all supported objects. This tag set works only inside a parent `targetConfig` that’s configured for `lightning__RecordPage`.

Specify the objects tag set only one time inside a `targetConfig` set.

Use `objects` with the `object` tag.

### `object`

Defines which objects the component is supported for. Use one `object` tag for each supported object.

**note:** The `object` tag doesn't support external objects.

See the [User Interface API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) for the list of supported objects.

## `supportedFormFactors`

A set of one or more form factors or devices that the component supports. Specify the `supportedFormFactors` tag set one time inside a `targetConfig` set. The `supportedFormFactors` tag contains at least one `supportedFormFactors` tag.

### `supportedFormFactor`

Defines which form factor or device the component supports. Use one `supportedFormFactor` tag for each supported form factor.

The `supportedFormFactor` tag supports this attribute.

| Attribute | Type   | Description                                                                                                                                                                           | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `type`    | String | Device form factor on which the component displays. Valid values are: <ul><li>`Large`—Represents the desktop form factor.</li><li>`Small`—Represents the phone form factor.</li></ul> | Yes      |

**note:** We strongly recommend including supported form factor information in the configuration file. See [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/use/use-config-form-factors.md).

## Usage

To expose a component property in Lightning App Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";

export default class Example extends LightningElement {
  @api height;

  get cmpHeight() {
    const height = this.height ? `height: ${this.height}px;` : "";
    return `${height}`;
  }
}
```

Bind the `height` property in your template.

<!-- prettier-ignore -->
```html
<template>
  <p style={height}>Your content here</p>
</template>
```

The component renders with a `style` value that a user provides in the Property Editor.

```html
<p style="height: 200px;">Your content here</p>
```

**See Also**

- [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-app-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [_Salesforce Help_: Create an App Home Page with the Lightning App Builder](https://help.salesforce.com/s/articleView?id=platform.lightning_app_builder_create_app_page.htm)

<!-- document id=c70cdd663f430c3ad74015d31367ed218c7bfcc35bc16dfd05d848bf39219430 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-url-addressable.md -->

# `lightning__UrlAddressable` Target

Enables you to directly navigate to a component using a specific URL.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>61.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__UrlAddressable</target>
  </targets>
</LightningComponentBundle>
```

## `targetConfigs`

`lightning__UrlAddressable` doesn't accept properties within a <targetConfig> XML tag. Instead, the component receives configuration and data when a user or code navigates to it using the `standard__component` page reference type.

The navigation attributes that determine the URL and passed data are:

| Property        | Type   | Description                                                                                                                                                                                                  | Required |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `componentName` | String | The component's name in the format `namespace__componentName` (e.g., `c__MyComponent`). This attribute is required within the attributes object of the PageReference.                                        | Yes      |
| `state`         | Object | An object containing key-value pairs that are serialized into URL query parameters to pass state information to the component. Keys must include a namespace (e.g., `c__paramName`). Values must be strings. | No       |

## Usage

Use the `lightning__UrlAddressable` target to make your component accessible via a browser URL.

This target is supported only in the following types of projects. It's **not** supported in Experience Builder sites.

- Lightning Experience
- Salesforce Mobile App
- Custom apps, such as Lightning Console Apps

For examples of how to use `lightning__UrlAddressable`, check out [Navigate to a URL-Addressable Component](https://developer.salesforce.com/docs/platform/use/use-navigate-url-addressable.md).

**See Also**

- [PageReference Types: Lightning Component Type](https://developer.salesforce.com/docs/platform/lwc/reference-page-reference-type.md#lightning-component-type)

<!-- document id=76e44f921c459c58d45840b1baa7489baaa601a561d7265ca73230455f155e31 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-utility-bar.md -->

# `lightning__UtilityBar` Target

Enables a component to be used as a utility item in an app's utility bar.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__UtilityBar</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__UtilityBar">
      <property name="greeting" type="String" description="Enter a greeting"/>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                           | Required |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__UtilityBar">` or `<targetConfig targets="lightning__UtilityBar,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in App Manager. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

## Usage

To expose a component property, define the property in the component’s JavaScript class using the `@api` decorator. You can also update the property value in the [App Manager page](https://help.salesforce.com/s/articleView?id=platform.apps_lightning_utilities.htm).

```javascript
import { LightningElement, api } from "lwc";

export default class UtilityBarExample extends LightningElement {
  @api greeting;
}
```

```html
<template>
  <lightning-card title="UtilityBarAPIComponent" icon-name="standard:scheduling_workspace">
    {greeting}
  </lightning-card>
</template>
```

**See Also**

- [Configure a Component for the Utility Bar](https://developer.salesforce.com/docs/platform/use/use-config-for-utility-bar.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=2572c38672789f929c9a50a9041830d5768243b063360785387e6413940df381 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-voice-extension.md -->

# `lightning__VoiceExtension` Target

Enables a component to be used on a Voice Extension page in Lightning App Builder.

## Syntax

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__VoiceExtension</target>
    </targets>
    <capabilities>
        <capability>lightning__ServiceCloudVoiceToolkitApi</capability>
    </capabilities>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                                   | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightning__VoiceExtension">` or `<targetConfig targets="lightning__VoiceExtension,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Lightning App Builder.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                     | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li></ul>                                                                                                                                                                   | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm). |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |          |
| `description` | String  | Displays as an i-bubble for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `label`       | String  | Displays as a label for the attribute in Lightning App Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Lightning App Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                         |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                           |          |

**See Also**

- [Enable the Voice Extension Page in Lightning App Builder](https://developer.salesforce.com/docs/atlas.en-us.voice_developer_guide.meta/voice_developer_guide/voice_example_voice_extension_flexipage.htm)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=0f2abb32a87da41c06ff85d585d2db96b45851f3828e8eacaee29d2e59de4576 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-analytics-smart-data-discovery-api.md -->

# `lightning/analyticsSmartDataDiscoveryApi` Wire Adapters and Functions

Get data and metadata for Einstein Discovery stories.

The wire adapter in this module is built on top of Lightning Data Service (LDS).

- [getStories](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-stories.md)

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=18cc3a4b404ccbb240eac861fd159f2ec269efee7c68071b3f6773a7114211c7 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-lightning-analytics-wave-api.md -->

# `lightning/analyticsWaveApi` Wire Adapters and Functions

Get data and metadata for CRM Analytics assets, execute queries, and schedule data syncs for recipes, dataflows, and data connectors.

**See Also**

- [CRM Analytics REST API Overview](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_rest_overview.htm)

<!-- document id=724f83e4777da86b9862e740b35f19b748d40da8a3ba0914b183563f7c977e96 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-cms-delivery-api-list-content.md -->

# lightning/cmsDeliveryApi Wire Adapters and Functions (Beta)

Get published content from Salesforce CMS.

**note:** This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

The wire adapter in this module is built on top of Lightning Data Service (LDS).

- [listContent](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-list-content.md)

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=c6f69c640bd41ae7c36ceae7295e96eb71d609a5b31e4d8b694a6ee3901b075f url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-cart/reference-lightning-commerce-cart-api.md -->

# `lightning/commerceCartApi` Module

Create and delete carts for buyers in a webstore.

- [`createCart(cartInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-cart-create-cart.md)
- [`deleteCart(cartInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-cart-delete-cart.md)

**See Also**

- [Commerce API Developer Guide](https://developer.salesforce.com/docs/commerce/commerce-api/overview)

<!-- document id=ef8037f2923ddb07430ed791e4ba5b7d00721791287cd04e1f264fdba075e803 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-register-guest-buyer/reference-lightning-commerce-register-guest-buyer-api.md -->

# `lightning/commerceRegisterGuestBuyerApi` Module

Register a guest buyer account against a webstore.

- [`registerGuestBuyer(guestBuyerInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-register-guest-buyer.md)

**See Also**

- [Commerce API Developer Guide](https://developer.salesforce.com/docs/commerce/commerce-api/overview)

<!-- document id=12d20685b57071da6ee7eaf1855ae2dcc4906b08c0b16fe40b23cd243e54b2b8 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-repricing/reference-lightning-commerce-repricing-api.md -->

# `lightning/commerceRepricingApi` Module

Retrieve pricing and product details for Order Management repricing scenarios.

- [`productDetails`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-repricing-product-details.md)
- [`searchProducts`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-repricing-search-products.md)

**See Also**

- [Commerce API Developer Guide](https://developer.salesforce.com/docs/commerce/commerce-api/overview)

<!-- document id=87d9f575b29aa708c20898e70ece075ecc82e93a8b0c11fb726b05846feff511 url=/developer/current/en-us/lwc/lwc/guides/reference/distributed-marketing/reference-lightning-distributed-marketing-api.md -->

# `lightning/distributedMarketing` Module

Launch the Distributed Marketing modal from a Lightning web component.

- [`openDistributedMarketing(config)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-distributed-marketing-open.md)

**See Also**

- [Distributed Marketing](https://help.salesforce.com/s/articleView?id=sf.mc_dm_distributed_marketing.htm)

<!-- document id=2365e9c3fdfa49d132ae6a7e7e866e61197cdbd44e52fac1943fff646db7229f url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-file-download-api.md -->

# `lightning/fileDownload` Module

Download a file in an LWR site in Experience Cloud.

- [`generateUrl`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-generate-url.md)

<!-- document id=b30a546c8b7622fd908cfccd25fb00b27eeaab79953c4db660d4847fe1c583c5 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-lightning-graphql-module.md -->

# `lightning/graphql` Wire Adapter (v2)

Fetch data using the GraphQL wire adapter, which comes with client-side caching and data management capabilities. `lightning/graphql` doesn’t currently support Mobile Offline use cases.

**note:** `lightning/graphql` (v2) supersedes the `lightning/uiGraphQLApi` (v1) module. We recommend that you use `lightning/graphql` (v2) where possible. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md). The terms v2 and v1 are annotations that are used only in documentation to highlight the difference and recency of the modules.

The wire adapter in this module is built on top of Lightning Data Service (LDS).

- [graphql](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.md)

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)

<!-- document id=be45aa73b7f930bff35bfda31aef8d421ecf08008a1568d19e1599cc4900bc95 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-industries-education.md -->

# `lightning/industriesEducationPublicApi` Module

Work with Benefit Assignment records.

- [`postBenefitAssignment`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-industries-education-postBenefitAssignment.md)

<!-- document id=d8786e8d0549c73931feffe98edf2eab53e4af86c6b3b6df227d9e65f062a423 url=/developer/current/en-us/lwc/lwc/guides/reference/mobile-capabilities/reference-lightning-mobilecapabilities.md -->

# `lightning/mobileCapabilities` Module

Mobile capabilities are JavaScript APIs that make mobile hardware and platform (operating system) features available in JavaScript. They require access to device hardware, platform APIs, or both. Mobile capability APIs are available only when a Lightning web component runs in a supported mobile app on a mobile device.

<!-- document id=e32679c8e9532d739d2fdd5aa9e49c3042eae6c904e5baee515440a8b1f4beb7 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refresh.md -->

# `lightning/refresh` Module

The `lightning/refresh` module provides you with the RefreshView API to refresh component data in a standard way.

`lightning/refresh` provides several methods:

- [registerRefreshContainer()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-registerrefreshcontainer.md)
- [registerRefreshHandler()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-registerrefreshhandler.md)
- [unregisterRefreshContainer()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-unregisterrefreshcontainer.md)
- [unregisterRefreshHandler()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-unregisterrefreshhandler.md)

When a refresh process completes, the [status](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshstatus-constants.md) is returned via a promise.
You can signal a refresh with [`RefreshEvent`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshevent-data-type.md) and register to receive `RefreshEvent`.

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)

<!-- document id=a5014de1ad40ea656e953b7e532df7bb08b767b127a4523db4ea0908baf859a1 url=/developer/current/en-us/lwc/lwc/guides/reference/service-knowledge/reference-lightning-service-knowledge-api.md -->

# `lightning/serviceKnowledgeApi` Module

Work with view count statistics for knowledge articles.

- [`updateViewStat(articleOrVersionId)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-knowledge-update-view-stat.md)

**See Also**

- [Salesforce Knowledge Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/knowledge_development_intro.htm)

<!-- document id=d21356de41377e7507093a35b87361afed990cd17a98481faf3d1feb66ea8701 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-managers.md -->

# `lightning/stateManager*` State Managers

Using state managers, pro-code developers can decouple data-related concerns from component logic. Moving data access out of individual components and into a dedicated state layer helps the Salesforce platform manage data more efficiently. This separation is especially useful for complex applications with many synchronized components, as data is managed separately from user interface concerns.

**note:** State management is not available in Experience Cloud at this time.

## State Managers Versus Wire Adapters

Lightning Data Service (LDS) wire adapters perform read operations and imperative functions for mutation operations (creates, updates, and deletes) on platform data. They're coupled to a specific component and are the preferred choice for standalone, context-independent units that access data at the component level.

You can't use wire adapters within state managers because wire adapters require a component context and state managers aren't components. While you can technically replace a wire adapter with a built-in state manager, this doesn't reap the architectural benefits of setting up state management.

Instead, use state managers when your goal is to build a coordinated, consolidated data-access system at the page or app level. They should bridge multiple elements and manage complex data retrieval or metadata parsing in one location. See [Best Practices for State Manager Design](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-design.md) for more detailed guidelines.

## Built-In State Managers

To support state manager composition, Salesforce provides a set of built-in state managers that wrap LDS access to the most common UI API data and metadata. These state managers follow a consistent design pattern, and participate fully in the LDS normalization, caching, and subscription mechanisms.

State managers in these modules are built on top of Lightning Data Service (LDS) and User Interface API. Use these state managers to work with Salesforce data and metadata.

- [`lightning/stateManagerLayout`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-layout.md)
- [`lightning/stateManagerObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-object-info.md)
- [`lightning/stateManagerObjectInfos`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-object-infos.md)
- [`lightning/stateManagerRecord`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-record.md)
- [`lightning/stateManagerRelatedListInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-related-list-info.md)
- [`lightning/stateManagerRelatedListRecords`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-related-list-records.md)
- [`lightning/stateManagerRelatedListsInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-related-lists-info.md)

**See Also**

- [State Management](https://developer.salesforce.com/docs/platform/state-management/state-management.md)
- [Use `lightning/stateManager*` State Managers](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md)
- [Refresh Action](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#refresh-action)
- [Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-ui-api.md)
- [User Interface API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/)

<!-- document id=40f8f578072bfc7c972fefee0e73dc33666d0066e30d2974e66f801e76ca4651 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-layout.md -->

# `lightning/stateManagerLayout`

This state manager gets layout information, metadata, and data you can use to build a user interface for one or more records.

## Syntax

Record layout details depend on the object, record type, and layout type.

```javascript
import { LightningElement } from 'lwc';
import smLayout from "lightning/stateManagerLayout";

export default class Example extends LightningElement {

  const myLayout = smLayout({
    objectApiName: string,
    layoutType: string,
    mode: string,
    recordTypeId?: string });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setObjectApiName()`
  - : Set the object API (developer) name.
- `setLayoutType()`
  - : Set the layout type: "Compact" or "Full".
- `setMode()`
  - : Set the layout mode: "Create", "Edit", or "View".
- `setRecordTypeId()`
  - : Set the record type for the object, in the form of a record type ID. When omitted, the default record type is used.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", a [`RecordLayout`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_layout.htm#ui_api_responses_record_layout).
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [Nested State Manager Example](https://developer.salesforce.com/docs/platform/state-management/state-management-example-nested.md)
- [getLayout](https://developer.salesforce.com/docs/platform/lwc/reference-get-layout.md) wire adapter
- _User Interface API Developer Guide:_ [Get Record Layout Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_layout.htm)

<!-- document id=1f06af4cb346d69a83663991c663b585f8477c18932c4ce21be43cbd809a0ecb url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-object-info.md -->

# `lightning/stateManagerObjectInfo`

This state manager retrieves metadata about a specific object. The response includes metadata describing the object’s fields, child relationships, record types, and theme.

## Syntax

`ObjectInfo` details depend on only the developer (API) name of the object.

```javascript
import { LightningElement } from 'lwc';
import smObjectInfo from "lightning/stateManagerObjectInfo";

export default class Example extends LightningElement {

  const myObjectInfo = smObjectInfo({
    objectApiName: string
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setObjectApiName()`
  - : Set the object API (developer) name.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", an [`ObjectInfo`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm#ui_api_responses_object_info).
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [getObjectInfo](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-object-info.md) wire adapter
- _User Interface API Developer Guide:_ [Get Object Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_object_info.htm)

<!-- document id=ce2cf17300304d910e0019b160a5c4dc8cd6cc956d78e05c409f3277b38ccbe5 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-object-infos.md -->

# `lightning/stateManagerObjectInfos`

This state manager retrieves metadata about multiple objects. The response includes metadata describing each object’s fields, child relationships, record type, and theme.

## Syntax

`ObjectInfo` details depend on only the developer (API) names of the objects.

```javascript
import { LightningElement } from 'lwc';
import smObjectInfos from "lightning/stateManagerObjectInfos";

export default class Example extends LightningElement {

  const myObjectInfos = smObjectInfos({
    objectApiNames: string[] // array of object names
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setObjectApiNames()`
  - : Set the object API (developer) names for the objects to retrieve metadata for. Provide an array of strings that represent supported object names.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", a `results` object with [Object Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm) metadata and [status codes](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_errors.htm). See the [example response](#example-response) later in this topic.
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

### Example Response

Get the object metadata using `data.results`. The object metadata is returned in the same order that they’re requested. If a requested object contains an error, the error code and message are returned in `data.results[].result`. The `error` object is returned only if the server call fails.

```javascript
{
  "results": [
    {
      "result": ObjectInfo1,
      "statusCode": 200
    },
    {
      "result": ObjectInfo2,
      "statusCode": 200
    },
    {
      "result": [
                {
                    "errorCode": "FORBIDDEN",
                    "message": "You don't have access to this record. Ask your administrator for help or to request access."
                }
        ],
        "statusCode": 403
    }
  ]
}
```

**See Also**

- [getObjectInfos](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-object-infos.md) wire adapter
- _User Interface API Developer Guide:_ [Get a Batch of Object Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_object_info_batch.htm)

<!-- document id=a9f7b6dae52474120e42abe9b78d1ff3d40368b13ff9ef29b0de8a6eebce61a6 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-record.md -->

# `lightning/stateManagerRecord`

This state manager gets record data.

## Syntax

Record retrieval requires a record ID, and a list of fields you want for the record.

```javascript
import { LightningElement } from 'lwc';
import smRecord from "lightning/stateManagerRecord";

export default class Example extends LightningElement {

  const myRecord = smRecord({
    recordId: string,
    fields: string[],
    optionalFields?: string[]
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setRecordId()`
  - : Set the record ID of the record to retrieve.
- `setFields()`

  - : Set the record fields to retrieve. Provide field or an array of fields to return. Specify field names in the format `ObjectApiName.FieldName`, or use `@salesforce/schema` items.

    If the context user doesn’t have access to a field, an error is returned. Use `optionalFields` if you’re not sure whether the context user has access to a field and you don’t want the state manager to return an error if they don’t.

- `setOptionalFields()`

  - : Set the record fields to retrieve. Provide field or an array of fields to return. Specify field names in the format `ObjectApiName.FieldName`, or use `@salesforce/schema` items.

    Optional fields don't cause an error if the context user doesn’t have access to a field.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`

  - : When `status` is "loaded", a [Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm).

    In the Record response, don’t use the `recordTypeInfo` property. Instead, use the `recordTypeId` property, which is returned for every record.

- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [Nested State Manager Example](https://developer.salesforce.com/docs/platform/state-management/state-management-example-nested.md)
- [getRecord](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-record.md) wire adapter
- _User Interface API Developer Guide:_ [Get a Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_get.htm)

<!-- document id=a34af4c414fcba1eb8f95843546c5c160d67f2fcf01be7bb845f337142a9e0cb url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-related-list-info.md -->

# `lightning/stateManagerRelatedListInfo`

This state manager gets the metadata for a `RelatedList`.

## Syntax

Related list details depend on the parent object developer (API) name, related list ID, and optionally the record type.

```javascript
import { LightningElement } from 'lwc';
import smRelatedListInfo from "lightning/stateManagerRelatedListInfo";

export default class Example extends LightningElement {

  const myRelatedListInfo = smRelatedListInfo({
    parentObjectApiName: string,
    relatedListId: string,
    recordTypeId?: string // optional
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setParentObjectApiName()`
  - : Set the parent object API (developer) name.
- `setRelatedListId()`
  - : Set the API name of a related list object, such as Contacts, Opportunities, or Cases.
- `setRecordTypeId()`
  - : Set the ID of the parent record type. If not provided, the default record type is used.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", a [`Related List Info`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_metadata.htm).
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [getRelatedListInfo](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-get-related-list-info.md) wire adapter
- _User Interface API Developer Guide:_ [Get Related List Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_info_md.htm)

<!-- document id=cbb0ffd69937e65299231cbb6f681871b507996510525fa80b3db67e9d21a577 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-related-list-records.md -->

# `lightning/stateManagerRelatedListRecords`

This state manager gets `RelatedList` records. [Related lists](https://help.salesforce.com/s/articleView?id=xcloud.basics_understanding_related_lists_parent.htm) display details and links to records that are associated with a specific record. For example, an account can have related lists for contacts, cases, notes, or even files.

## Syntax

Related list records depend on the parent record ID and related list ID. All other parameters are optional.

```javascript
import { LightningElement } from 'lwc';
import smRelatedListRecords from "lightning/stateManagerRelatedListRecords";

export default class Example extends LightningElement {

  const myRelatedListRecords = smRelatedListRecords({
    parentRecordId: string,
    relatedListId: string,
    fields?: string[],
    optionalFields?: string[],
    pageSize?: number,
    sortBy?: string[],
    where?: string
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setParentRecordId()`
  - : Set the ID of the parent record that you want to get related lists for, like an Account ID.
- `setRelatedListId()`

  - : Set the API name of a related list or child relationship, like Contacts, Opportunities, or Cases.

    To provide an API name of a related list custom object, use the `Custom_Objects__r` format, where `Custom_Objects` is the plural form of your custom object name, and `__r` is the related list suffix. For more information on retrieving all related lists for an object or custom object, see [`RelatedListDefinition`](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_relatedlistdefinition.htm).

- `setFields()`
  - : Set the API names of the related list’s column fields.
    To use a standard field on a custom object, use the `Custom_Object__c.FieldName` format. To use a custom field on a custom object, use the `Custom_Object__c.FieldName__c` format.
- `setOptionalFields()`
  - : Set the API names of additional fields in the related list.
- `setPageSize()`
  - : Set the number of list records to return per page. The default value is 50. Enter a value between 1 and 1999.
- `setSortBy()`
  - : Set the array of field API names to sort the related list by. Accepts only one value per request.
- `setWhere()`
  - : Set filter to apply to related list records. [Semi-joins and anti-joins filters](https://developer.salesforce.com/docs/platform/graphql/guide/filter-joins.html) are currently not supported. For example, passing in a query using `inq` results in a Malformed Join Input Object error.
- `refresh()`
  - : Re-fetch the related list records from the server. Returns a `Promise<void>`. See [Refresh Action](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#refresh-action) for behavior details.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", a [`Related List Record Collection`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_record_collection.htm).
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [getRelatedListRecords](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-get-related-list-records.md) wire adapter
- _User Interface API Developer Guide:_ [Get Related List Records with a Request Body](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_records_get.htm)

<!-- document id=f05611a4254b8961a8b9ee803e13a7b33d15cbbd7b003c582dda941717c78028 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-manager-related-lists-info.md -->

# `lightning/stateManagerRelatedListsInfo`

This state manager gets the metadata for `RelatedLists` in an object’s default layout.

## Syntax

RelatedLists details depend on a parent object developer (API) name, and optionally a record type ID.

```javascript
import { LightningElement } from 'lwc';
import smRelatedListsInfo from "lightning/stateManagerRelatedListsInfo";

export default class Example extends LightningElement {

  const myRelatedListsInfo = smRelatedListsInfo({
    parentObjectApiName: string,
    recordTypeId?: string
  });
}
```

### Configuration Functions

- `setConfig()`
  - : Provide the entire configuration as an object. This function is equivalent to the factory function when you create the state manager.
- `setParentObjectApiName()`
  - : Set the API name of a parent object that you want to get related lists for, like an Account.
- `setRecordTypeId()`
  - : Set the ID of the parent record type.

### State Manager Properties

- `status`
  - : The current status of the state manager. See [`status`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.
- `data`
  - : When `status` is "loaded", a [`Related List Summary Collection`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_related_list_summary_collection.htm).
- `error`
  - : When `status` is "error", this property contains details. See [`error`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use.md#standard-properties) for details.

**See Also**

- [getRelatedListsInfo](https://developer.salesforce.com/docs/platform/lwc/wire-adapters/reference-wire-adapters-get-related-lists-info.md) wire adapter
- _User Interface API Developer Guide:_ [Get Related Lists for an Object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_related_list_object.htm)

<!-- document id=326c082454f8053ac3f80e4f1a6e9a9aa46ad571a53b52cd9e67de3a5c235b53 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-ui-api.md -->

# `lightning/ui*Api` Wire Adapters and Functions

Wire adapters and JavaScript functions in these modules are built on top of Lightning Data Service (LDS) and User Interface API. Use these wire adapters and functions to work with Salesforce data and metadata.

- [`lightning/uiAppsApi` (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-apps.md)
- [`lightning/uiLayoutApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-layout-api.md)
- [`lightning/uiLearningPlatformApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-learning-platform-api.md)
- [`lightning/uiListsApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-lists-ui.md)
- [`lightning/uiListApi` (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-list-ui.md)
- [`lightning/uiObjectInfoApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-object-info.md)
- [`lightning/uiRecordApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-record.md)
- [`lightning/uiRelatedListApi`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-related-list.md)

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions may be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For information about how LDS and User Interface API work, see [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md).

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=cd67f4b7abb2f7bf6c4a48306fde26d8d06334538a7cd4a8ba4dfbe708502aee url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-apps.md -->

# `lightning/uiAppsApi` (Beta)

Get data and metadata for apps displayed in the Salesforce UI.

- [`getNavItems` (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-nav-items.md)

**note:** As a beta feature, `lightning/uiAppsApi` is a preview and isn’t part of the “Services” under your Main Services Agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. `lightning/uiAppsApi` is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

<!-- document id=cc2896937cc885a26ebc65e2d9c8300c07cb9459961ebdc1092dc0b9253c5a08 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-lightning-graphql-api.md -->

# `lightning/uiGraphQLApi` (v1)

Fetch data using the GraphQL wire adapter, which comes with client-side caching and data management capabilities. `lightning/uiGraphQLApi` supports Mobile Offline use cases, but it doesn’t support newer features, such as optional fields and dynamic query construction.

**note:** `lightning/graphql` (v2) supersedes the `lightning/uiGraphQLApi` (v1) module. We recommend that you use `lightning/graphql` (v2) where possible. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md). The terms v2 and v1 are annotations that are used only in documentation to highlight the difference and recency of the modules.

Fetch data using the GraphQL wire adapter, which comes with client-side caching and data management capabilities.

The wire adapter in this module is built on top of Lightning Data Service (LDS).

- [graphql](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md)
- [executeMutation](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-mutation.md)
- [refresh](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-refresh.md)

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/data/data-wire-service-about.md)

<!-- document id=bc6d52e6aa137b8a684cdd220bf31906d8a6f2735df95bbe6927fe6faf58c857 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-layout-api.md -->

# `lightning/uiLayoutApi`

Get record layout metadata and data. This module supersedes [`lightning/getRecordUi` (deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record-ui.md).

<!-- document id=c14c711dd6e9e06f15ab606832bf6747aea0fc3c5ae2a51d1aea3a24b71b6d73 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-learning-platform-api.md -->

# `lightning/uiLearningPlatformApi`

Manage data related to learning items used with Enablement programs.

<!-- document id=40fe42765199147d8c82acbf5d1a4bbdb79a500fb070063aaa28ed5eac813ea3 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-list-ui.md -->

# `lightning/uiListApi` (Deprecated)

Get the records and metadata for a list view.

**note:** As a deprecated feature, `lightning/uiListApi` no longer updates and isn’t part of the “Services” under your Main Services Agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. `lightning/uiListApi` is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

The `lightning/uiListApi` module is deprecated. Use `lightning/uiListsApi` instead.

**See Also**

- [lightning/uiListsApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-lists-ui.md)

<!-- document id=002606a73d942994c9d4509c7b40627c11ffc38ae2f943a2de0f6a3196322e0a url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-lists-ui.md -->

# `lightning/uiListsApi`

Get the metadata for a list view. This module supersedes [`lightning/uiListApi` (deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-ui.md).

- [`createListInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-create-list-info.md)
- [`deleteListInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-delete-list-info.md)
- [`getListInfoByName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-info-by-name.md)
- [`getListInfosByName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-infos-by-name.md)
- [`getListInfosByObjectName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-infos-by-object-name.md)
- [`getListObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-object-info.md)
- [`getListPreferences`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-preferences.md)
- [`getListRecordsByName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-list-records-by-name.md)
- [`updateListInfoByName`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-update-list-info.md)
- [`updateListPreferences`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-update-list-preferences.md)

<!-- document id=efeea4d7c8cecfec916ae2407dac5c6ac5102705fa3907c0e1bbb96fcf4a231e url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-object-info.md -->

# `lightning/uiObjectInfoApi`

Get object metadata, and get picklist values.

- [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-object-info.md)
- [`getObjectInfos`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-object-infos.md)
- [`getPicklistValues`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-picklist-values.md)
- [`getPicklistValuesByRecordType`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-picklist-values-record.md)

<!-- document id=fc1d50093769fe6a7c92917a850091b9fcd620bea4dd43883ce9c73515f70eff url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-record.md -->

# `lightning/uiRecordApi`

This module includes wire adapters to get record data. It also includes imperative JavaScript functions to create, delete, update, and refresh records.

- [`createRecord(recordInput)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-create-record.md)
- [`createRecordInputFilteredByEditedFields(recordInput, originalRecord)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-create-record-input-update.md)
- [`deleteRecord(recordId)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-delete-record.md)
- [`generateRecordInputForCreate(record, objectInfo)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-generate-record-input-create.md)
- [`generateRecordInputForUpdate(record, objectInfo)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-generate-record-input-update.md)
- [`getFieldValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-field-value.md)
- [`getFieldDisplayValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-field-display-value.md)
- [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record.md)
- [`getRecords`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-records.md)
- [`getRecordCreateDefaults`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-create-record-values.md)
- [`getRecordNotifyChange(recordIds)` (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-record-notify.md)
- [`getRecordUi` (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-record-ui.md)
- [`notifyRecordUpdateAvailable(recordIds)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-notify-record-update.md)
- [`updateRecord(recordInput, clientOptions)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-update-record.md)

<!-- document id=b76d17673bf3beb3fedf7dbdd2ae4f752eca2934ab1f8b43f0b0de8881a5f3df url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-ui-api-related-list.md -->

# `lightning/uiRelatedListApi`

Get related list metadata and record data.

- [`getRelatedListCount`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-list-count.md)
- [`getRelatedListInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-list-info.md)
- [`getRelatedListInfoBatch`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-list-info-batch.md)
- [`getRelatedListRecords`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-list-records.md)
- [`getRelatedListRecordsBatch`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-list-records-batch.md)
- [`getRelatedListsInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/wire-adapters/reference-wire-adapters-get-related-lists-info.md)

<!-- document id=aa885662869a06741a9ba42f077639622cfd7f46b0ac5269983683f7f10411ff url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-community-default.md -->

# `lightningCommunity__Default` Target

Enables a component in Experience Builder to expose editable properties when the component is selected. Only properties defined for the`lightningCommunity__Page` or `lightningCommunity__Theme_Layout` targets are editable in Experience Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightningCommunity__Page</target>
        <target>lightningCommunity__Default</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningCommunity__Default">
            <property name="myString" type="String" default="jsMetaValue"></property>
            <property name="backgroundColor" type="Color" default="#ff00ff"></property>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for different page types and defines component properties. For Experience Builder sites, only `lightningCommunity__Default` supports component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                                       | Required |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightningCommunity__Default">` or `<targetConfig targets="lightningCommunity__Default,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Experience Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Required |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `name`             | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes      |
| `type`             | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence. <ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li><li>`Color`—Displays a color selector. Use the `default` attribute to specify RGBA, RGB, or hex strings. For example: `<property type="Color" name="backgroundColor" default="rgba(0, 255, 255, 1)" />`.</li><li>`ContentReference`—Displays a window in Experience Builder for selecting Salesforce CMS content. You can use the `filter` attribute to restrict the window contents to specific content types. For example: `<property type="ContentReference" name="contentId" label="Content ID" filter="cms_image, cms_video" />`.</li></ul> | Yes      |
| `datasource`       | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm).                                                                                                                                                                                                                                                                                                                                                                           |          |
| `default`          | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |          |
| `description`      | String  | Displays as an i-bubble for the attribute in Experience Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |          |
| `exposedTo`        | String  | Required if you use the `screenResponsive` attribute. The valid value is `css`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |          |
| `filter`           | String  | Supported only when the `type` is `ContentReference`. Specifies the Salesforce CMS content type to display in the component in Experience Builder. Valid values are: <ul><li>`cms_document`</li><li>`cms_image`</li><li>`cms_video`</li><li>`news`</li><li>`custom_type`, where `custom_type` is the name of a custom content type</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |          |
| `label`            | String  | Displays as a label for the attribute in Experience Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |          |
| `max`              | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `min`              | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `placeholder`      | String  | Input placeholder text for the attribute when it displays in Experience Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |          |
| `required`         | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |          |
| `screenResponsive` | Boolean | Specifies if a component integer or string property is screen-size responsive. The default value is `false`. To allow the component to use the correct property value based on the user's screen-size, set `screenResponsive` to `true` and set the `exposedTo` attribute to `css`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |          |

## Usage

To expose a component property in Experience builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  @api myString;
  @api backgroundColor;
}
```

**note:** You can’t make certain changes to `<property>` tags on a custom component that’s used in a site or managed package. For more information, see the [Considerations](https://developer.salesforce.com/docs/platform/use/use-config-for-community-builder.md#considerations) section in Configure a Component for Experience Builder.

**See Also**

- [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-community-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=21191363bbc187c7d13904e8df83fe88ab4f161271573adb20e06f7f0a233faf url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-community-page.md -->

# `lightningCommunity__Page` Target

Enables a component to be used on a page in Experience Builder. Components appear in the Components panel.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightningCommunity__Page</target>
        <target>lightningCommunity__Default</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningCommunity__Default">
            <property name="buttonLabel" type="String" default="Submit" label="Button label" description="Enter a label for your button"></property>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## Usage

To expose editable properties, use this target with [`lightningCommunity__Default`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-community-default.md).
`lightningCommunity__Page` doesn't support component properties.

**See Also**

- [Configure a Component for Experience Builder Sites](https://developer.salesforce.com/docs/platform/use/use-config-for-community-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=e15aa79c47499f79aad832d39ec68ee83c8b3ec67412a941566a4c62e65696f0 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-community-page-layout.md -->

# `lightningCommunity__Page_Layout` Target

Enables a component to be used in Experience Builder as a page layout for an LWR site. Components appear in the Content Layout window.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightningCommunity__Page_Layout</target>
    </targets>
</LightningComponentBundle>
```

## Usage

`lightningCommunity__Page_Layout` doesn't support component properties. To create a region on the page, use a named slot. You can also use the [Lightning Design System utility classes](https://www.lightningdesignsystem.com/utilities/padding/) for padding or alignment.

```html
<template>
  <header class="slds-col_padded slds-p-vertical_small">
    <slot name="header"></slot>
  </header>
  <section class="slds-col_padded slds-p-vertical_small">
    <slot name="sidebar"></slot>
  </section>
</template>
```

In your component's JavaScript, include the `@slot` annotation in a JSDoc comment.

```javascript
import { LightningElement } from "lwc";
/**
 * @slot header
 * @slot sidebar
 */
export default class CustomThemeLayout extends LightningElement {}
```

The JSDoc annotation containing `@slot` followed by the name of the region is required for the platform to know which slots (or regions in Experience Builder) are exposed for your page layout component.

**See Also**

- [_LWR Sites for Experience Cloud_: Create Custom Layout Components](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_layout.htm)
- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/create/create-components-slots.md)
- [Configure a Component for Experience Builder Sites](https://developer.salesforce.com/docs/platform/use/use-config-for-community-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=e47b6d02fea0de4825a21987943ef5bee4b58a2d9747691cd2c69994eb3d7632 url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-community-theme-layout.md -->

# `lightningCommunity__Theme_Layout` Target

Enables a component to be used in Experience Builder as a theme layout for an LWR site. Components appear in Settings in the Theme area.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightningCommunity__Theme_Layout</target>
    </targets>
</LightningComponentBundle>
```

## Usage

`lightningCommunity__Theme_Layout` doesn't support component properties. To indicate the region for your main content, include a default slot `<slot></slot>` in your template. You can also use the [Lightning Design System utility classes](https://www.lightningdesignsystem.com/utilities/padding/) for padding or alignment. In this example, `F6-navigable region` indicates an [F6-navigable region](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_layout.htm).

```html
<template>
  <header data-f6-region class="slds-col_padded slds-p-vertical_small">
    <slot name="sidebar"></slot>
  </header>
  <section data-f6-region>
    <slot></slot>
  </section>
</template>
```

In your component's JavaScript, include the `@slot` annotation in a JSDoc comment.

```javascript
import { LightningElement } from "lwc";

/**
 * @slot sidebar
 */
export default class CustomThemeLayout extends LightningElement {}
```

The JSDoc annotation containing `@slot` followed by the name of the region is required for the platform to know which slots (or regions in Experience Builder) are exposed for your page layout component.

**See Also**

- [_LWR Sites for Experience Cloud_: Create Custom Layout Components](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_layout.htm)
- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/create/create-components-slots.md)
- [Configure a Component for Experience Builder Sites](https://developer.salesforce.com/docs/platform/use/use-config-for-community-builder.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)

<!-- document id=baa9a3816b2abb5c7465248d6e3945a2adeca7418c290eb0dbd67c896fcd6334 url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-lwc.md -->

# `LightningElement` Class Properties

`LightningElement` is the base class for Lightning web components.

## Unique Properties

Properties that are specific to `LightningElement` include:

- `constructor`: The constructor for the `LightningElement` class.
- `hostElement`: Accesses the `HTMLElement` of the Lightning web component in shadow DOM and light DOM. See [Access the Parent Element](https://developer.salesforce.com/docs/platform/lwc/create/create-components-dom-work.md#access-the-parent-element).
- [Template Access](https://developer.salesforce.com/docs/platform/lwc/create/create-components-dom-work.md)
  - `template`: The template for the Lightning web component. In light DOM components, use `this` instead of `this.template` to access the template as there's no shadow root.
  - `refs`: Accesses DOM elements in a specified template.
- [Lifecycle Callbacks](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md)
  - `connectedCallback`
  - `disconnectedCallback`
  - `render`
  - `renderedCallback`
  - `errorCallback`

## Inherited Properties and Methods

`LightningElement` is a wrapper of the standard [`HTMLElement` interface](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). A custom Lightning web component, which extends `LightningElement`, inherits properties and methods from `HTMLElement`.

The inherited properties and methods are:

<!-- https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/base-lightning-element.ts#L148 -->

- `accessKey`
- `addEventListener`
- `attachInternals`
- `children`
- `childNodes`
- `classList`
- `dir`
- `dispatchEvent`
- `draggable`
- `firstChild`
- `firstElementChild`
- `getAttribute`
- `getAttributeNS`
- `getBoundingClientRect`
- `getElementsByClassName`
- `getElementsByTagName`
- `hasAttribute`
- `hasAttributeNS`
- `hidden`
- `id`
- `isConnected`
- `lang`
- `lastChild`
- `lastElementChild`
- `ownerDocument`
- `querySelector`
- `querySelectorAll`
- `removeAttribute`
- `removeAttributeNS`
- `removeEventListener`
- `setAttribute`
- `setAttributeNS`
- `shadowRoot`
- `spellcheck`
- `style` (LWC API v62.0 and later)
- `tabIndex`
- `tagName`
- `template`
- `title`

LWC also reflects [`aria` properties](https://developer.salesforce.com/docs/platform/lwc/js/js-web-apis.md#wai-aria-states-and-properties) to support accessibility.

**See Also**

- [Reflect JavaScript Properties to HTML Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-html-attributes.md)
- [Component Accessibility Attributes](https://developer.salesforce.com/docs/platform/lwc/create/create-components-accessibility-attributes.md)

<!-- document id=0b3d5d83231f8be0ed9cceb352432a27acba82af56bde7afe046e1bebbd106cc url=/developer/current/en-us/lwc/lwc/guides/reference/targets/targets-lightning-static-email.md -->

# `lightningStatic__Email` Target

Enables a component to be used in Email Content Builder.

## Syntax

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightningStatic__Email</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightningStatic__Email">
            <property name="htmlValue" type="String" required="true"/>
            <property name="paddingTop" type="Integer" min="0" max="600"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## `targetConfigs`

Configures the component for Email Content Builder and defines component properties. The `targetConfigs` tag contains at least one `targetConfig` tag.

### `targetConfig`

Configures a page type with this attribute.

| Attribute | Description                                                                                                                                                                                                                                                                                             | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `targets` | Specify one or more page types in the `targets` attribute, such as `<targetConfig targets="lightningStatic__Email">` or `<targetConfig targets="lightningStatic__Email,lightning__AppPage">`. The `targets` attribute value must match one or more of the page types that you listed under `<targets>`. | Yes      |

The `targetConfig` tag includes at least one `property` tag.

### `property`

Specifies a public property of a component that can be set in Email Content Builder. The component author defines the property in the component’s JavaScript class using the `@api` decorator. See the [Usage](#usage) section.

Use the `property` tag with these attributes.

| Attribute     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Required |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`        | String  | The attribute name. This value must match the property name in the component’s JavaScript class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes      |
| `type`        | String  | The attribute's data type. The following values are valid for all targets. Make sure that this value matches the type assigned to the property in the component's JavaScript module. If the types don't match, the value in the configuration file takes precedence.<ul><li>`Boolean`</li><li>`Integer`</li><li>`String`</li><li>`Color`—Displays a color selector. Use the `default` attribute to specify RGBA, RGB, or hex strings. For example: `<property type="Color" name="backgroundColor" default="rgba(0, 255, 255, 1)" />`.</li><li>`HorizontalAlignment`—Displays a horizontal alignment selector. Use the default attribute to specify a `right`, `left`, or `center` alignment value.</li><li>`VerticalAlignment`—Displays a vertical alignment selector. Use the default attribute to specify a `top`, `middle`, or `bottom` alignment value.</li></ul> | Yes      |
| `datasource`  | String  | Renders a field as a picklist, with static values. Supported only if the `type` attribute is `String`. For example: `datasource="value1,value2,value3"`. You can also set the picklist values dynamically using an Apex class, such as: `datasource="apex://MyCustomPickList"`. For more information, see [Create Dynamic Picklists for Your Custom Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_dynamic_picklists.htm).                                                                                                                                                                                                                                                                                                                                                                  |          |
| `default`     | String  | The default value for the attribute.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |          |
| `description` | String  | Displays as an i-bubble for the attribute in Email Content Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |          |
| `label`       | String  | Displays as a label for the attribute in Email Content Builder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |          |
| `max`         | Integer | The maximum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |
| `min`         | Integer | The minimum allowed value for an attribute of type `Integer`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |
| `placeholder` | String  | Input placeholder text for the attribute when it displays in Email Content Builder. This text is the ghost text in text fields and text areas before a user starts typing. Supported only if the type attribute is `String`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |          |
| `required`    | Boolean | Specifies whether the attribute is required. The default value is `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |          |

## Usage

To expose a component property in Email Content Builder, define the property in the component’s JavaScript class using the `@api` decorator.

```javascript
import { LightningElement, api } from "lwc";
export default class CustomEmailTemplate extends LightningElement {
  @api paddingTop;

  get topPadding() {
    const paddingTop = this.paddingTop ? `padding-top: ${this.paddingTop}px;` : "";
    return `${paddingTop}`;
  }
}
```

Bind the `paddingTop` property in your template.

<!-- prettier-ignore -->
```html
<template>
  <p style={topPadding}>Your content here</p>
</template>
```

The component renders with a `style` value that a user provides in the Property Editor.

```html
<p style="padding-top: 200px;">Your content here</p>
```

**See Also**

- [Configure a Component for the Email Builder](https://developer.salesforce.com/docs/platform/use/use-config-for-email-builder-component-steps.md)
- [Add Custom HTML To a Component](https://developer.salesforce.com/docs/platform/use/use-email-builder-components-html.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md)
- [_Salesforce Help_: Use Custom Components in Email](https://help.salesforce.com/s/articleView?id=mktg.pardot_eilex_add_custom_components.htm)
- [_Salesforce Developers Blog_: Extend Email Templates with Lightning Web Components](https://developer.salesforce.com/blogs/2022/12/extend-email-templates-with-lightning-web-components)

<!-- document id=ca30e7fd89444719df3504b2fb2fcbe16c2fa474be8e1a139f4c2fa56cfb848e url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-debug-limitations.md -->

# Limitations for Debugging with Lightning Web Security Enabled

Browser limitations can affect the debugging experience in orgs where Lightning Web Security (LWS) is enabled. These limitations can only be resolved when browser vendors implement fixes and adopt new standards. Salesforce is working with the vendors.

- Some issues that you encounter in [production mode](/docs/platform/lwc/guide/debug-production-mode.html) can’t be reproduced when you enable [debug mode](/docs/platform/lwc/guide/debug-debug-mode.html).
- Some Aura errors aren’t surfaced when LWS is enabled.
- Source code line numbers and source code files referenced in console messages aren’t correct.
- Recent versions of Firefox sometimes don’t hit breakpoints when LWS is enabled. Instead, we recommend that you use Chrome and [Chrome DevTools](https://developer.chrome.com/docs/devtools).
- Some browser extensions and plugins can interfere with debugging. Try disabling them if you run into issues.

<!-- document id=6e5c15a97ee2eb49b7188994b9a875462517f3edfef067017a9a6fe2e1a7068b url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-link-editor-type.md -->

# Link a Custom Property Editor or Property Type to Your Custom Component

After you create a custom property type or editor, link it back to the appropriate property in a custom Lightning web component. Use the `editor` attribute to link a custom property editor to the component. Use the `type` attribute to link a custom property type to the component.

<!-- document id=51117a4c53a12b48361ebafe6310f30b13086b2ec47ba1d2800c31ec77d54eb7 url=/developer/current/en-us/lwc/utam/guide/linting.md -->

# Linting

UTAM provides the ability to statically analyze JSON files to prevent common bad practices, such as duplication of page objects or violations of the encapsulation pattern.

We encourage you not to disable any linting rules and to make sure that your page objects comply with recommended best practices.

**note:** This documentation is relevant for UTAM Java versions after 2.0.4 and UTAM JavaScript versions after 2.1.2. Prior to these versions UTAM also produced console output from the linter, this is no longer the case.

## Run linting

Linting is run during the page object compilation process. All warnings and errors are printed into a Static Analysis Results Interchange Format ([SARIF](https://sarifweb.azurewebsites.net/)) report generated after compilation.
SARIF is a common format to store linting results. UTAM creates `utam-lint.sarif` in the SARIF JSON format, which looks like this:

```json
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "UTAM",
          "semanticVersion": "2.1.0",
          "informationUri": "https://github.com/salesforce/utam-java",
          "rules": [
            {
              "id": "ULR01",
              "name": "Unique local selectors",
              "shortDescription": {
                "text": "Check for unique selectors inside the same file. By default, this is a warning because a list element can have the same selector."
              }
            }
            // other rules
          ]
        }
      },
      // all page objects being analyzed
      "artifacts": [
        {
          "description": {
            "text": "page object utam/pageObjects/test"
          },
          "location": {
            "uri": "src/test/resources/lint/changeDefaultConfig/test.utam.json",
            "uriBaseId": "%srcroot%",
            "index": 0
          }
        }
      ],
      // violations
      "results": [
        {
          "ruleId": "ULR02",
          "message": {
            "text": "root description is missing",
            "id": "2002"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/test/resources/lint/changeDefaultConfig/test.utam.json",
                  "uriBaseId": "%srcroot%",
                  "index": 0
                },
                "region": {
                  "startLine": 2
                }
              }
            }
          ],
          "fixes": [
            {
              "description": {
                "text": "add \"author\" property to the root description"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

## Linting report

The SARIF file is in JSON format. To view (pretty print) SARIF files in a terminal or in your IDE, use available tools, such as [sarif-fmt](https://lib.rs/crates/sarif-fmt) or [Sarif VSCode extension](https://github.com/microsoft/sarif-vscode-extension).

If at least one linting violation of level `error` occurs and the `throwError` configuration parameter is set to `true` (see the next section), the page object compiler throws an exception.

A file in SARIF format can be integrated with development tools such as GitHub to show linting rule violations:
![SARIF GitHub](https://developer.salesforce.com/docs/media/utam/sarif-github.png)

GitHub documentation is [here](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).

## Configuring linting rules and violations

All linting rules and violation types (error or warning) are configurable as `lint` properties in the compiler configuration.
If a compiler configuration doesn't have a `lint` section, default values are applied.

```json
{
  "lint": {
    "lintingOutputFile": "utam-lint.sarif",
    "disable": false,
    "throwError": false,
    "<name of the rule>": {
      "violation": "error",
      "exclude": []
    },
    "<name of the rule>": {
      "violation": "error",
      "exclude": ["my/test/component1", "my/test/component2"]
    },
    "<name of the rule>": {
      "violation": "warning"
    }
  }
}
```

- **`lintingOutputFile`**
  String, default is `"utam-lint.sarif"`. This parameter sets the path for a [SARIF](https://sarifweb.azurewebsites.net/) log file generated by the UTAM linter. The path is relative to the root of the project.

- **`disable`**
  Boolean, default is `false`. If set to `true`, linting rules are not applied after the compilation.

- **`throwError`**
  Boolean, default is `false`. If set to `true`, the linting process throws an error after reporting errors to the log.

- **`<name of the rule>`** is one of the rules listed in the next section.
  - **`violation`**
    The violation type. Possible values are: `warning`, `error`, or `disabled` (disable the rule). Starting from compiler versions 2.0.3 (utam-js) and 2.0.2 (utam-java), **the default is always `warning`.**
  - **`exclude`**
    Is an array of strings that are excluded from the rule. Each string value is a page object URI.
  - **`additionalConfiguration`**
    Is an object containing additional configuration data for the rule, if any applies. See the rule description for information
    about what additional configuration the rule supports.

## Linting rules

**note:** Rules with error codes that start with 2 are applicable for one page object only. Rules with error codes that start with 3 are relevant for multiple page objects only, such as detecting duplicates from the earlier example.

### duplicateSelectors

- Rule: page object elements in the same scope (with the same immediate parent) can't have duplicate selectors except if one of the elements is a list.
- How to fix: remove one or more duplicate elements.
- Error code: 2001
- Default violation type: `warning`

Example:

```json
{
  "elements": [
    {
      "name": "element1",
      "selector": {
        "css": "css"
      }
    },
    {
      // violation - same selector as element1
      "name": "element2",
      "selector": {
        "css": "css"
      },
      "elements": [
        {
          // not a violation - element has a different parent
          "name": "element3",
          "selector": {
            "css": "css"
          }
        },
        {
          // not a violation - element is a list
          "name": "element4",
          "selector": {
            "css": "css",
            "returnAll": true
          }
        }
      ]
    }
  ]
}
```

### requiredRootDescription

- Rule: it's a good practice to provide a description at the page object root level to explain the intended usage of the page object.
- How to fix: add a [page object description](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html#page-object-description).
- Error code: 2002
- Default violation type: `warning`

Example:

```json
{
  // violation - description is empty
  "elements": []
}
```

### requiredAuthor

- Rule: The page object description should include an author.
- How to fix: add an [author](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html#page-object-description) property to the description.
- Error code: 2005
- Default violation type: `warning`

Example:

```json
{
  // violation - description has no author
  "description": "description is a string"
}
```

```json
{
  // not a violation - author is provided
  "description": {
    "text": ["description is a string"],
    "author": "myTeam"
  }
}
```

### requiredMethodDescription

- Rule: it's a good practice to provide a description at the method level that explains the use cases. This rule isn't applied to elements; it's for compose methods only.
- How to fix: add a [method description](/docs/platform/utam/references/utam-grammar/methods.html#method-description).
- Error code: 2003
- Default violation type: `warning`

Example:

```json
{
  "description": "root description here",
  "methods": [
    {
      // violation - description is empty
      "name": "doSomething",
      "compose": []
    }
  ]
}
```

### duplicateRootSelectors

- Rule: two page objects with the same root selector usually means a violation of the encapsulation rule (1:1 mapping between a component and a page object).
- How to fix: remove the duplicate page object. Make sure that you keep all functionality.
- Error code: 3001
- Default violation type: `warning`

Example:

```json
{
  // first page object
  "root": true,
  "selector": {
    "css": "my-root"
  }
}
```

```json
{
  // second page object
  "root": true,
  "selector": {
    // violation - same root selector
    "css": "my-root"
  }
}
```

### elementCantHaveRootSelector

- Rule: if an element has the same selector as the root selector of a different page object, it should have the same type as the given page object.
- How to fix: add the proper type, which is the type of the page object with the root selector.
- Error code: 3002
- Default violation type: `warning`

Example:

```json
{
  // first page object my/test/Component
  "root": true,
  "selector": {
    "css": "my-root"
  }
}
```

```json
{
  // second page object
  "elements": [
    {
      // violation - element should have the proper type
      "name": "element1",
      "selector": {
        "css": "my-root"
      }
    },
    {
      // not a violation - element has the proper type
      "name": "element2",
      "type": "my/test/Component",
      "selector": {
        "css": "my-root"
      }
    }
  ]
}
```

### duplicateCustomSelectors

- Rule: if an element in one page object has a custom type and a custom selector (with "-"), any element with the same selector in a different page object should have the same custom type.
- How to fix: change the element type to custom.
- Error code: 3003
- Default violation type: `warning`

Example:

```json
{
  // first page object
  "elements": [
    {
      "name": "customElement",
      "type": "my/test/Component",
      "selector": {
        "css": "my-test-component"
      }
    },
    {
      "name": "basicElement",
      "selector": {
        "css": ".myClass"
      }
    }
  ]
}
```

```json
{
  // second page object
  "elements": [
    {
      // violation - set type to "my/test/Component"
      "name": "basicElement1",
      "selector": {
        "css": "my-test-component"
      }
    },
    {
      // not a violation - basic elements can have the same selectors
      "name": "basicElement2",
      "selector": {
        "css": ".myClass"
      }
    }
  ]
}
```

### requiredMetadata

- Rule: if a page object does not contain a `metadata` property, or the object value of the `metadata` property does not contain
  the specified values.
- How to fix: add a [metadata](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html) object containing mandatory fields (if any) to the page object.
- Error code: 2006
- Default violation type: `disabled`
- Note: `additionalConfiguration` should contain a `requiredProperties` array, which will contain objects defining the
  required properties in the metadata.

Example:

```json
{
  // Compiler configuration lint section
  "lint": {
    "lintingOutputFile": "utam-lint.sarif",
    "disable": false,
    "throwError": false,
    "requiredMetadata": {
      "violation": "warning",
      "exclude": [],
      "additionalConfiguration": {
        "requiredProperties": [
          {
            "name": "firstRequiredProperty"
          },
          {
            "name": "secondRequiredProperty",
            "values": ["allowedValue1", "allowedValue2", "allowedValue3"]
          }
        ]
      }
    }
  }
}
```

```json
{
  //  violation: page object has no metadata property
  "elements": [
    {
      "name": "basicElement1",
      "selector": {
        "css": ".my-test-component"
      }
    }
  ]
}
```

```json
{
  "metadata": {
    // violation: metadata object does not contain "firstRequiredProperty"
    // property with a non-empty value

    // violation: "secondRequiredProperty" value is not one of the acceptable
    // values for the property
    "secondRequiredProperty": "invalidValue"
  },
  "elements": [
    {
      "name": "basicElement1",
      "selector": {
        "css": ".my-test-component"
      }
    }
  ]
}
```

<!-- document id=fcef0f7008aa5e43f0e7085b72bfbe52895ce4810921b5de27fcfad2a0933ab7 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-list-content.md -->

# `listContent` (Beta)

Retrieves published content from an enhanced or non-enhanced CMS workspace to use in a custom Lightning web component in an Aura site in Experience Cloud.

**note:** To get Salesforce CMS content from a CMS workspace for an enhanced or non-enhanced LWR site, use the `experience/cmsDeliveryApi` module’s [`getContent`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-delivery-get-content.md) wire adapter instead.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import Id from "@salesforce/community/Id";
import { listContent } from "lightning/cmsDeliveryApi";

export default class ListContentDemo extends LightningElement {
  @wire(listContent, { communityId: Id })
  cmsRecords;
}
```

## User Interface API Resource

```html
GET /connect/communities/${communityId}/managed-content/delivery
```

See [Managed Content Delivery, Experience Cloud Site](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_managed_content_delivery.htm).

## Parameters

- `communityId`—(Required) The ID for the site where you want to use CMS content.
- `contentKeys`—List of up to 50 content keys for the CMS content. A content key is a universally unique identifier (UUID) that’s 28 characters long, such as MCA4CCV5QS2BAB5H7YRCRPTCWGZQ.
- `language`—Language for the managed content, for example, en_US corresponds to English (US). If the requested translation isn’t available, the language defaults to the context user’s language. If the context user’s language isn’t available, the language defaults to the content type’s original language.
- `managedContentType`—The developer name of the managed content type whose content you want to query.
- `page`—Number of the page you are requesting. Starts at 0. If you don’t specify a value or if you specify 0, the first page is returned.
- `pageSize`—Specifies the number of items per page. Valid values are from 1 through 250. For performance reasons, we recommend 25 or fewer items per page. If you don’t specify a value, the default size is 25.
- `showAbsoluteUrl`—Specifies whether to show absolute URLs in the response body (true) or not (false). If you don’t specify a value, the default is false.
- `topics`—Comma-separated list of up to 15 content topic names.

## Returns

- `data`—[Managed Content Version Collection](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_managed_content_version_collection.htm)
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

**See Also**

- [_Salesforce Help_: Salesforce CMS Content Key](https://help.salesforce.com/s/articleView?id=xcloud.cms_content_key.htm)
- [_Salesforce Help_: Types of CMS Content](https://help.salesforce.com/s/articleView?id=xcloud.cms_customcontenttypes.htm)

<!-- document id=c43aef1df4d495f110fa6ddd5ce74b0a1f6bb9a2caebf7d3d0dbcc715df0a14e url=/developer/current/en-us/lwc/lwc/guides/data/data-load-record.md -->

# Load a Record

Loading a record can be accomplished entirely in markup using `lightning-record-form` and passing in a record Id. If you need a custom layout, use `lightning-record-view-form`. If you need more customization than the form-based components allow, use a wire adapter like `getRecord`.

## Display a Record Using `lightning-record-form`

The simplest way to display a record is to use the `lightning-record-form`. You can display a record in two modes.

- `view`

  - : Loads the form using output fields with inline editing enabled. Editable fields have edit icons. If a user clicks an edit icon, all fields in the form become editable, and the form displays Submit and Cancel buttons.

- `read-only`

  - : Read-only mode loads the form with output fields only. The form doesn’t include edit icons or **Submit** and **Cancel** buttons.

This code displays an account record in view mode with the specified fields. Field labels and values are displayed based on your display density setting. View mode is the default when `record-id` is provided.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-record-form record-id={recordId} object-api-name={objectApiName} fields={fields}>
  </lightning-record-form>
</template>
```

**note:** To improve performance, specify fields instead of a layout whenever possible. Specify a layout only when you want the administrator, not the component, to control the fields that are provisioned. The component must handle receiving every field that is assigned to the layout for the context user.

Use your own record Id or place the example in an account record page to inherit its record Id.

```javascript
// myComponent.js
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  @api recordId;
  @api objectApiName;
  fields = ["AccountId", "Name", "Title", "Phone", "Email"];
}
```

## Example

This example uses the `recordFormDynamicContact` component from the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

## Display a Record with a Custom Field Layout Using `lightning-record-view-form`

To display a record with a custom field layout, use the `lightning-record-view-form` component. To compose the form fields, use `lightning-output-field` components. Including individual fields lets you style a custom field layout using the Lightning Design System utility classes, such as the grid system.

<!-- prettier-ignore -->
```html
<!-- recordViewCustomLayout.html -->
<template>
  <lightning-record-view-form record-id={recordId} object-api-name="Account">
    <div class="slds-grid">
      <div class="slds-col slds-size_1-of-2">
        <lightning-output-field field-name="Name"></lightning-output-field>
        <lightning-output-field field-name="Phone"></lightning-output-field>
      </div>
      <div class="slds-col slds-size_1-of-2">
        <lightning-output-field field-name="Industry"></lightning-output-field>
        <lightning-output-field field-name="AnnualRevenue"></lightning-output-field>
      </div>
    </div>
  </lightning-record-view-form>
</template>
```

Use your own record Id or place the example in an account record page to inherit its record Id.

```javascript
// recordViewCustomLayout.js
import { LightningElement, api } from "lwc";
export default class MyComponent extends LightningElement {
  // Expose a recordId property.
  @api recordId;
}
```

**note:** You can design your form to respect the org’s display density setting, or set the form density to override the display density setting. See [Change the Form Display Density](https://developer.salesforce.com/docs/platform/lwc/data/data-display-density.md).

## Display Record Data in a Custom User Interface Using `getRecord`

We’ve seen how record fields render using `lightning-output-field`. To render data in a custom user interface, use the [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) or [`getRecords`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-records.md) wire adapter.

This example uses a base component, `lightning-formatted-text`, to display an account name.

<!-- prettier-ignore -->
```html
<!-- recordViewGetRecord.html -->
<template>
  <lightning-record-view-form record-id={recordId} object-api-name={accountObject}>
    <div class="slds-grid">
      <div class="slds-col slds-size_1-of-2">
        <!-- Other record data here -->
      </div>
      <div class="slds-col slds-size_1-of-2">
        <lightning-formatted-text value={nameValue} class="slds-text-heading_large">
        </lightning-formatted-text>
      </div>
    </div>
  </lightning-record-view-form>
</template>
```

In the component’s JavaScript code, import references to the `Account` object and the `Account.Name` field.

- The [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) wire adapter loads the `Name` field for custom rendering in the `lightning-formatted-text` component instead of the standard `lightning-output-field` used by `lightning-record-view-form`.
- The [`getFieldValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-field-value.md) function gets the value of the `Name` field.

```javascript
// recordViewGetRecord.js
import { LightningElement, api, wire } from "lwc";
/* Wire adapter to fetch record data */
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";

export default class AccountViewer extends LightningElement {
  /** Id of record to display. */
  @api recordId;

  /* Expose schema objects/fields to the template. */
  accountObject = ACCOUNT_OBJECT;

  /* Load Account.Name for custom rendering */
  @wire(getRecord, { recordId: "$recordId", fields: [NAME_FIELD] })
  record;

  /** Get the Account.Name value. */
  get nameValue() {
    return this.record.data ? getFieldValue(this.record.data, NAME_FIELD) : "";
  }
}
```

## Display Data from a Parent Record Using `getRecord`

To display data from a record and its parent record, use `lightning-record-view-form` with `getRecord`, similar to the previous example. Import data from a parent record using the notation `{object}.{parentObject}.{field}`.

This example uses a base component, `lightning-formatted-email`, to display the email address of an account record’s owner.

<!-- prettier-ignore -->
```html
<!-- recordViewGetRecordParent.html -->
<template>
  <lightning-record-view-form object-api-name={objectApiName} record-id={recordId}>
    <lightning-messages></lightning-messages>
    <lightning-output-field field-name={nameField}></lightning-output-field>

    <div class="slds-form-element slds-form-element_stacked">
      <span class="slds-form-element__label">Owner Email</span>
      <div class="slds-form-element__control">
        <lightning-formatted-email value={ownerField}> </lightning-formatted-email>
      </div>
    </div>
  </lightning-record-view-form>
</template>
```

The component’s JavaScript code imports references to the `Account` object and the `Account.Owner.Email` field.

- The [`getRecord`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) wire adapter loads the `Account.Owner.Email` field for custom rendering in the `lightning-formatted-email` component instead of in the standard `lightning-output-field` used by `lightning-record-view-form`.
- The [`getFieldValue(record, field)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-field-value.md) function gets the value of the `Account.Owner.Email` field.

```javascript
// recordViewGetRecordParent.js
import { LightningElement, api, wire } from "lwc";

import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import OWNER_EMAIL_FIELD from "@salesforce/schema/Account.Owner.Email";

export default class RecordViewFormParentData extends LightningElement {
  objectApiName = ACCOUNT_OBJECT;
  nameField = NAME_FIELD;

  @api recordId;
  @api objectApiName;

  /* Load Account.Owner.Email for custom rendering */
  @wire(getRecord, {
    recordId: "$recordId",
    fields: [OWNER_EMAIL_FIELD],
  })
  record;

  /* Get the Account.Owner.Email value. */
  get ownerField() {
    return this.record.data ? getFieldValue(this.record.data, OWNER_EMAIL_FIELD) : "";
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=9cbd2e69be3daec25cb2c2ab04e7dded15ecc0b8d1ebc8561a4917594e89e94e url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-cli-test.md -->

# Local Development with LWS CLI

The Lightning Web Security (LWS) CLI brings the Salesforce LWS runtime directly to your local terminal. Instead of relying on slow deploy-and-test loops, hosted web consoles, or manual copy-pasting, the CLI provides a fast, scriptable, local environment. You can use this environment to test and debug Lightning Web Components (LWC) and JavaScript code.

**important:** LWS CLI shrinks the feedback loop rather than replacing end-to-end testing. Real user interactions, live data, cross-org behavior, and auth flows still require full deployments. However, the CLI catches most LWS issues locally in seconds, preventing problems before deployment and reducing org round trips.

## Install the Package

To install LWS CLI, open a terminal on your development environment and perform these steps.

1. Install the node project dependencies.

   ```
   npm install
   ```

2. Install LWS CLI and the LWS configuration package from [this package location](https://www.npmjs.com/package/@locker/cli).

   ```
   # Globally — `lws` is available everywhere
   npm install -g @locker/cli
   # or:
   yarn global add @locker/cli
   ```

3. Run this command to install at least one Playwright browser binary.

   ```
     # Default: just chromium
     npx playwright install chromium

     # Or all three engines (chromium, firefox, webkit)
     npx playwright install
   ```

4. Verify if LWS CLI is installed.

   ```
   lws --version
   ```

## Key Features

Here are the key features and commands of LWS CLI.

### 1. Fast Code Evaluation

Use `lws eval` to compile and run your code inside a real, sandboxed browser runtime (Chromium). In this example, LWS compiles the code, opens a real browser, starts the production sandbox, and logs `hello from inside the sandbox` within seconds.

```
lws eval "console.log('hello from inside the sandbox')"
```

The `lws eval` command:

- Blocks dangerous operations by enforcing real LWS security policies. In this example, when untrusted code attempts to delete the host page, the sandbox blocks the request with a locker-security error and terminates the process with a non-zero exit code.

  ```
  lws eval "document.body.remove()"`
  ```

  Expected output:

 <pre>
    > (function () {
    > 'use strict';
    >
    > window.evaluateInSandbox('cli', () => {
    > document.body.remove();
    > });
    > })();
    >
    > [browser:pageerror] Lightning Web Security: Cannot remove BODY.
  </pre>

- Enforces multitenant data isolation through the LWS realm boundary and API distortions. Use the `--before` and `--after` flags to run system-mode setup and teardown scripts that plant host-page state (such as setting a session token or Cross-Site Request Forgery (CSRF) credential on `window`). This prevents untrusted sandboxed code from reading this data back.

  ```
    lws eval --before "document.cookie = '_auth_token=SECRET-host-only'" \
         --after "console.log('[host] real cookie jar:', document.cookie)" \
         "document.cookie = 'session=abc'; console.log('[sandbox] reads:', document.cookie)"
  ```

  Expected output:
  <pre> 
  >  (function () {
  >    'use strict';
  
  >   window.evaluateInSandbox('cli', () => {
  >      document.cookie = 'session=abc'; console.log('[sandbox] reads:', document.cookie);
  >      });
  
  >  })();
  
  >  [browser:log] [sandbox] reads: session=abc
  >  [browser:log] [host] real cookie jar: auth_token=SECRET-host-only; LSKey-cli$session=abc </pre>

- Automatically sanitizes untrusted markup at the boundary before it hits the live Document Object Model (DOM), when the untrusted markup is written into the DOM (for example, assigning to `innerHTML`). In this example, the script attempts to inject unsafe elements: a `<script>` HTML tag and a `onerror` event handler. In such cases, LWS removes the dangerous parts while preserving safe HTML tags, such as `<img>` and `<b>`. Instead of returning an error or refusing the input, LWS delivers a safe, sanitized DOM tree without requiring the sandbox to detect the threat.

  ```
  lws eval --after "console.log('[host] sanitized DOM:', document.querySelector('div#sink').outerHTML)" \
          "const d = document.createElement('div'); d.id = 'sink'; document.body.appendChild(d);
          d.innerHTML = '<script>alert(1)</script><img src=data:, onerror=alert(2)><b>kept</b>';"
  ```

  Expected output:

    <pre>
    > (function () {
    >  'use strict';
  
    >  window.evaluateInSandbox('cli', () => {
    >    const d = document.createElement('div'); d.id = 'sink'; document.body.appendChild(d);
    >    d.innerHTML = '&ltscript&gtalert(1)&lt/script&gt&ltimg src=data:, onerror=alert(2)&gt&ltb&gtkept&lt/b&gt';
  
    > });
  
    > })();
  
    > [browser:log][host] sanitized DOM: &ltdiv id="sink"&gt&ltimg src="data:,"&gt&ltb&gtkept&lt/b&gt&lt/div&gt
   </pre>

### 2. Local LWC Rendering

To render local LWC directories instantly by using the production LWC compiler, flags, and sandbox runtime, use the `lws component` command with a directory path. Using this command is faster than running local code through the web console, which requires deploying to a scratch org and waiting for build cycles.
In this example, the `lws component` uses a local component directory. A one-second local feedback loop running the production LWC engine and sandbox runtime instantly:

- Streams browser logs
- Verifies lifecycle callbacks in `parent connected`, `child connected`, and `parent rendered` sequence
- Outputs the full compiled LWC code directly to the terminal for fast debugging

```
lws component ./test/fixtures/c/helloWorld
```

Expected output:

<pre>
>  ((lwc) => {
>  ...

>    /* eslint-disable class-methods-use-this, no-console */
>   class HelloWorld extends (...) {
>      connectedCallback() {
>        console.log('hello-world connected');
>      }
>   ...
>   });

>  [browser:log] hello-world connected
>  [browser:log] wrapped-box connected
>  [browser:log] hello-world rendered
</pre>

The `--headed` flag with the `lws component` command opens a live browser window with Chrome DevTools, which enables complete Shadow DOM inspection, breakpoint debugging, and step-through capabilities without deploying to an org. You can analyze the sources and also view the fully bundled component-compiled code.

### 3. Persistent State

The `lws repl` command preserves state across multiple input lines, so that variables, functions, and array bindings remain persistent in the same sandbox environment. This command offers an interactive JavaScript Read-Eval-Print Loop (REPL) wrapped inside the LWS security membrane.
In this example, `lws repl` opens an interactive, multiline JavaScript shell wrapped in an LWS sandbox. The state persists across lines of code within the sandbox, preserving array bindings and multiline functions until the session ends with `.exit.`

```
lws repl
```

<pre>> lws repl ready (chromium, key="cli"). Type .help for commands, .exit or Ctrl+D to quit.</pre>

`lws> 1 + 2`

<pre>> 3</pre>

`lws> let arr = [1, 2, 3]`

<pre>> [ 1, 2, 3 ]</pre>

`lws> arr`

<pre>> [ 1, 2, 3 ]</pre>

`lws> let double = function(n) { ... return n * 2 ... }`

<pre>> 'function(n) {\n  return n * 2\n}'</pre>

`lws> double(2)`

<pre>>4</pre>

`lws> .exit`

The `lws repl` command also supports `--before` and `--after` flags to run system-level setup, or to remove scripts before and after entering the REPL.

```
lws repl --before "/* pre-setup system code */" --after "/* post-teardown system code */"
```

<!-- document id=7b17807a292be06bcd516d4ab6fa52e90a47371e7cf448f3461d47eb2475b316 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-local-storage.md -->

# Local Storage Limitations

Lightning Web Security (LWS) creates synthetic storage for each sandbox. The synthetic storage prevents code in one sandbox from retrieving data that belongs to another namespace or that was set in the global scope outside LWS sandboxes.

`localStorage` and `sessionStorage` are partitioned by keys. When LWS is enabled, key values that are set outside the namespace aren’t accessible because LWS creates key names that are unique to the namespace.

To share data stored in local storage with code running in a different namespace, create a function and export it from one namespace to allow the other namespace to import and call the function.

**important:** Lightning Locker and LWS use different mechanisms for protecting local storage. Data that’s saved to local storage while Locker is enabled isn’t accessible when LWS is enabled, and vice versa. If the LWS setting changes after data is saved in local storage, the data isn’t accessible even when set by components in the same namespace. Rewrite the `localStorage` and `sessionStorage` data after enabling or disabling LWS.

**See Also**

[Storage API in Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Storage_constructor-value)

<!-- document id=f734fd3ea449399c38b578ef7b2624872c290a35fa6b95be8d9fa85fc975e350 url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice.md -->

# LocationService API

Access and track location in a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how LocationService works, see [Use Location on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_locationservice.htm).

<!-- document id=04d117b4effcb7e41dc5061b449feb596c044b1b6f3db4b6dfe51f144bec452d url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-data-types.md -->

# LocationService Data Types

LocationService defines several data types.

## `Location`

| Property Name | Type          | Description                                                                       | Example                                              |
| ------------- | ------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `coords`      | `Coordinates` | The physical location.                                                            | `{ latitude: 37.79542, longitude: -122.39357, ... }` |
| `timestamp`   | Number        | The time of the location reading, measured in milliseconds since January 1, 1970. | 1633040973009                                        |

## `Coordinates`

An object representing a specific point located on the planet Earth. Includes velocity details, if available. Includes accuracy information, to the best of the device’s ability to evaluate. Similar to a [GeolocationCoordinates](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates) in the Geolocation Web API.

| Property Name      | Type   | Description                                                                                    | Example     |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------- | ----------- |
| `latitude`         | Number | The latitude, in degrees. Ranges from -90 to 90.                                               | 37.785834   |
| `longitude`        | Number | The longitude, in degrees. Ranges from -180 to 180.                                            | -122.406417 |
| `accuracy`         | Number | Optional. Accuracy of the location measurement, in meters, as a radius around the measurement. | 5           |
| `altitude`         | Number | Optional. Meters above sea level.                                                              | 0           |
| `altitudeAccuracy` | Number | Optional. Accuracy of the altitude measurement, in meters.                                     | -1          |
| `speed`            | Number | Optional. Velocity of motion, if any, in meters per second.                                    | 0           |
| `speedAccuracy`    | Number | Optional. Accuracy of the speed measurement, in meters.                                        | -1          |
| `heading`          | Number | Optional. Direction of motion, in degrees from true north. Ranges from 0 to 360.               | 0           |
| `headingAccuracy`  | Number | Optional. Accuracy of the heading measurement, in degrees.                                     | -1          |

**note:** As illustrated in the preceding examples, `accuracy` and other fields can be set to -1 as a special value that indicates _Not Recorded_. This can be due to a number of reasons, including temporary environmental conditions or permanent hardware limitations. Check for the -1 value if you depend on these fields.

Direction, as indicated by `heading`, is measured in degrees from due north. Positive values proceed clockwise around the compass. A compass, like a circle, has 360°, and so the values 0 and 360 are equivalent. While 360° is a valid value for `heading`, due north registers as 0° when returned by LocationService.

## `LocationServiceOptions`

An object representing configuration details for a location service session.

| Property Name        | Type    | Description                                                                                                                                                              | Example |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `enableHighAccuracy` | Boolean | Whether to use high accuracy mode when determining location. Set to `true` to prioritize location accuracy. Set to `false` to prioritize battery life and response time. | `false` |

When `enableHighAccuracy` is set to `false`, accuracy is approximately to the nearest city block, or roughly 100 meters. The impact of your component on battery use is minimal.

When `enableHighAccuracy` is set to `true`, accuracy is as high as the device’s positioning hardware can achieve and your app’s permissions allow. If you’re making many requests, the impact of your component on battery use can be significant. Use high accuracy only when your feature needs it.

```javascript
{
  enableHighAccuracy: true;
}
```

## LocationServiceFailure

An object representing an error that occurred when accessing LocationService features.

| Property Name | Type                         | Description                                                                                                                                                                                                                                                            |
| ------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `LocationServiceFailureCode` | A value representing the reason for a location error. Possible failure codes include the following: <ul><li>`locationServiceDisabled`</li><li>`userDisabledPermissions`</li><li>`userDeniedPermission`</li><li>`unavailableOnHardware`</li><li>`nativeError`</li></ul> |
| `message`     | String                       | A string value explaining the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.                                                                                              |

**note:** `nativeError` is a special case, and represents an error that’s specific to the underlying platform, Android or iOS. If you receive this failure, check the `message` value for details.

<!-- document id=800e3c3b39727f804ce33b752d78e7f58ffb4cbd55178f3048ed72a16552a53d url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-console.md -->

# Locker Console Overview

Use Locker Console to check your JavaScript code’s compatibility with Lightning Locker, and compare how it runs with Lightning Locker enabled and disabled.

Access [Locker Console](https://developer.salesforce.com/tools/locker-service-console) in the Tools area of the [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience) and the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components).

Locker Console enables you to quickly evaluate JavaScript code for issues or benchmark code, without requiring you to create an app to test your component. You can evaluate only JavaScript code in Locker Console. You can't evaluate a complete component bundle or component markup.

Here's an overview of the user interface of the Locker Console tool.

![Locker Console UI.](https://developer.salesforce.com/media/locker_console_guide.png '{"class": "image-framed", "title": "Lightning Locker Console"}')

- Code Console (1)
  - : Paste or type your JavaScript code here to evaluate or benchmark it.
- Toggles (2)
  - :
    - Enable or disable Locker.
    - Enable or disable Strict CSP.
- Actions (3)
  - :
    - Click **Evaluate** to run the code that’s displayed in the code console. See [Evaluate JavaScript Code Compatibility with Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console-evaluate.md).
    - Click **Benchmark** to run your code with and without Lightning Locker and view relative performance metrics. See [Benchmark Lightning Locker Effect on JavaScript Code](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-console-benchmark.md).
    - Click **Clear Results** to clear all the displayed results.

**See Also**

- [Lightning Locker API Viewer Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-api-viewer.md)
- [Stricter CSP Restrictions](https://developer.salesforce.com/docs/platform/lightning-components-security/content-security-policy/content-security-policy-stricter.md)
- [Lightning Component Reference](https://developer.salesforce.com/docs/component-library/overview/components)

<!-- document id=530b9acc270ab4bce13602dafdf2480ab32774f9df20637759a32644000c80d7 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-tools-distortion-viewer.md -->

# Look Up Distortion Details in Lightning Web Security Distortion Viewer

To help prevent insecure behavior, Lightning Web Security (LWS) applies distortions to code running in a JavaScript sandbox. LWS Distortion Viewer describes the distortion by explaining the vulnerability of the affected API, and the distorted behavior that mitigates the vulnerability. Then you can modify your JavaScript code so that any unwanted distortions that affect your components are avoided.

LWS Distortion Viewer shows the JavaScript APIs that LWS blocks or modifies. If an API isn’t listed here, LWS allows the API’s native behavior. For more information about distortions, see [How Lightning Web Security Works](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md).

LWS Distortion Viewer is available in the Tools area of the [DX Developer Center](https://developer.salesforce.com/developer-centers/developer-experience) and the [LWC Developer Center](https://developer.salesforce.com/developer-centers/lightning-web-components).

Here’s a direct link to the tool: [https://developer.salesforce.com/tools/lws-distortion-viewer](https://developer.salesforce.com/tools/lws-distortion-viewer).

![LWS Distortion Viewer with open document](https://developer.salesforce.com/media/lws-distortion-viewer.png)

LWS Distortion Viewer lists the distortions for JavaScript APIs alphabetically by object name, along with a number that indicates the number of APIs that are distorted for the object. Select an object, and then click an API to view information about the API distortion.

**tip:** For information about solving some issues with your code after LWS distortions are applied, see [Troubleshoot Issues Related to Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-troubleshoot.md).

<!-- document id=922996cf397e3264ef79562b3fca70f7675eeb07109b55e8f051ccbac996801b url=/developer/current/en-us/lwc/lwc/guides/reference/reference-api-modules.md -->

# LWC API Modules

These API modules provide access to record data and Salesforce APIs.

## Record Data

| API Module Name                                                      | Provides wire adapters and functions to work with...                                                          | First Available in API Version |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [lightning/uiAppsApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                           | Data and metadata for apps displayed in the Salesforce UI                                                     | 50.0                           |
| [lightning/graphql](https://developer.salesforce.com/docs/platform/lwc/guide/graphql/reference-lightning-graphql-module.md)   | Retrieves and manages record data using GraphQL API. Supports optional fields and dynamic query construction. | 65.0                           |
| [lightning/uiGraphQLApi](https://developer.salesforce.com/docs/platform/lwc/guide/graphql/reference-lightning-graphql-api.md) | Retrieves and manages record data using GraphQL API. Supports Mobile Offline use cases.                       | 57.0                           |
| [lightning/uiLayoutApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                         | Record layout metadata and data                                                                               | 62.0                           |
| [lightning/uiListApi (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)              | Superseded by ui-lists-api                                                                                    | 45.0                           |
| [lightning/uiListsApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                          | Metadata for a list view                                                                                      | 52.0                           |
| [lightning/uiObjectInfoApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                     | Object metadata and picklist values                                                                           | 45.0                           |
| [lightning/uiRecordApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                         | Record data                                                                                                   | 46.0                           |
| [lightning/uiRelatedListApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                    | Related list metadata and record data                                                                         | 53.0                           |

## Experience Cloud APIs

| API Module Name                                                                  | Provides wire adapters and functions to work with...          | First Available in API Version |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------ |
| [experience/blockBuilderApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-experience-block-builder-api.md)          | Components in Marketing Cloud Next content and CMS extensions | 66.0                           |
| [experience/cmsDeliveryApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-experience-cms-api.md)                     | Content from an enhanced CMS workspace                        | 54.0                           |
| [experience/cmsEditorApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-experience-cms-editor-api.md)                | Content editor of an enhanced CMS workspace                   | 54.0                           |
| [lightning/cmsDeliveryApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-cms-delivery-api-list-content.md) | Content from Salesforce CMS                                   | 52.0                           |

## Lightning Console API

| API Module Name                                                                                                                                                                                 | Provides wire adapters and functions to work with... | First Available in API Version |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------ |
| [lightning/conversationToolkitApi](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_enhanced_lightning_conversationtoolkitapi_lwc.htm) | Enhanced Messaging channels                          | 60.0                           |
| [lightning/platformUtilityBarApi](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_lightning_utilityBarAPI.htm)                        | Utility bars, as part of Lightning Console API       | 61.0                           |
| [lightning/platformWorkspaceApi](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_lightning_workspaceAPI.htm)                          | Workspace tabs, as part of Lightning Console API     | 59.0                           |

## Other Salesforce APIs

| API Module Name                                                                                                                                                           | Provides wire adapters and functions to work with...                                                                              | First Available in API Version |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [lightning/analyticsWaveApi](https://developer.salesforce.com/docs/platform/lwc/guide/analytics/reference-lightning-analytics-wave-api.md)                                                                                         | Data and metadata for CRM Analytics assets, execute queries, and schedule data syncs for recipes, dataflows, and data connectors. | 52.0                           |
| [lightning/commerceCartApi](https://developer.salesforce.com/docs/platform/lwc/guide/commerce-cart/reference-lightning-commerce-cart-api.md)                                                                                       | Carts for buyers in a webstore, such as creating and deleting carts                                                               | 62.0                           |
| [lightning/commerceRegisterGuestBuyerApi](https://developer.salesforce.com/docs/platform/lwc/guide/commerce-register-guest-buyer/reference-lightning-commerce-register-guest-buyer-api.md)                                         | Guest buyer registration against a webstore                                                                                       | 62.0                           |
| [lightning/commerceRepricingApi](https://developer.salesforce.com/docs/platform/lwc/guide/commerce-repricing/reference-lightning-commerce-repricing-api.md)                                                                        | Pricing and product details for Order Management repricing scenarios                                                              | 62.0                           |
| [lightning/distributedMarketing](https://developer.salesforce.com/docs/platform/lwc/guide/distributed-marketing/reference-lightning-distributed-marketing-api.md)                                                                  | The Distributed Marketing modal, such as for launching the multi-step send wizard                                                 | 66.0                           |
| [lightning/empApi](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-emp-api)                                                  | Platform events, such as subscribing to a streaming channel                                                                       | 45.0                           |
| [lightning/industriesEducationPublicApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-industries-education.md)                                                                                     | Education Cloud, such as updating Benefit Assignment records                                                                      | 60.0                           |
| [lightning/mobileCapabilities](https://developer.salesforce.com/docs/platform/lwc/guide/mobile-capabilities/reference-lightning-mobilecapabilities.md)                                                                             | Mobile functionalities, such as for barcode scanning and contacts access                                                          | 48.0                           |
| [lightning/serviceCloudVoiceToolkitApi](https://developer.salesforce.com/docs/atlas.en-us.voice_developer_guide.meta/voice_developer_guide/voice_lc_toolkit_overview.htm) | Service Cloud Voice, as part of Service Cloud Voice Toolkit API                                                                   | 52.0                           |
| [lightning/serviceKnowledgeApi](https://developer.salesforce.com/docs/platform/lwc/guide/service-knowledge/reference-lightning-service-knowledge-api.md)                                                                           | Knowledge articles, such as retrieving the view count statistics                                                                  | 60.0                           |
| [lightning/uiLearningPlatformApi](https://developer.salesforce.com/docs/platform/lwc/guide/reference-ui-api.md)                                                                                                                    | Data related to learning items used with Enablement programs                                                                      | 62.0                           |

<!-- document id=ea3222f8f952a6680fc4ef66bd35acc38faddf228f0b23f9bf84d3898a883568 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-reference.md -->

# LWC MCP Tools Reference (Beta)

MCP Tools for LWC are part of several toolsets.

- `lwc-experts`-Facilitates LWC development, testing, optimization
- `aura-experts`-Assists with Aura-to-LWC migration
- `experts-validation`-Validates and scores LWC components for production readiness across accessibility, security, and other best practices

As of August 2026, MCP tools for LWC are superseded by [LWC skills](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md). We recommend that you use the corresponding LWC skills where applicable.

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## LWC MCP Tools

LWC provides these MCP tools in the `lwc-experts` toolset to assist with LWC development, testing, optimization, and best practices.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


The tools marked NON-GA are not yet generally available. Specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration to use them. See [Configure the Salesforce DX MCP Server for Your Environment](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_server.htm#sfdx_dev_mcp_configure_orgs_toolsets).

### Development Tools

Use these MCP tools to facilitate LWC development.

| Tool Name                                              | GA?    | Description                                                                                                                                                                                                             | Superseded by LWC Skill                 |
| ------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| [`guide_lwc_development`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                  | GA     | Provides comprehensive LWC development workflow and implementation guidelines                                                                                                                                           | `experience-lwc-generate`               |
| [`guide_lwc_best_practices`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)               | GA     | Offers LWC development best practices and coding standards guidance                                                                                                                                                     | `experience-lwc-generate`               |
| [`create_lwc_component_from_prd`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)          | GA     | Creates complete Lightning web components from PRD specifications                                                                                                                                                       | `experience-lwc-design-generate`        |
| [`explore_slds_blueprints`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                | NON-GA | Retrieves guidelines for the SLDS component blueprints that you need                                                                                                                                                    | `design-systems-slds-apply`             |
| [`explore_slds_styling`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                   | NON-GA | Provides usage patterns, accessibility notes, and validation checklists for semantic color styling hooks. For all other styling hooks, the tool provides the category, description, optional usage and other properties | `design-systems-slds-validate`          |
| [`guide_slds_blueprints`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                  | NON-GA | Provides comprehensive SLDS component blueprint guidelines, reference documentation, and a complete index of all available blueprints organized by category                                                             | `design-systems-slds-apply`             |
| [`guide_slds_styling`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                     | NON-GA | Provides comprehensive SLDS styling hook guidelines, reference documentation, and a complete overview of available styling hooks by category, including principles, patterns, and accessibility notes                   | `design-systems-slds-apply`             |
| [`orchestrate_lwc_component_creation`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)     | GA     | Provides step-by-step component creation guidance                                                                                                                                                                       | `experience-lwc-design-generate`        |
| [`orchestrate_lwc_component_optimization`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md) | GA     | Optimizes performance and applies best practices for LWC                                                                                                                                                                | `experience-lwc-design-generate`        |
| [`guide_component_accessibility`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)          | GA     | Provides accessibility guidelines and testing instructions                                                                                                                                                              | `experience-lwc-accessibility-validate` |
| [`guide_lwc_rtl_support`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)                  | GA     | Provides right-to-left (RTL) internationalization support and RTL development guidance                                                                                                                                  | `experience-lwc-rtl-validate`           |
| [`orchestrate_lwc_slds2_uplift`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)           | NON-GA | Provides migration guidance for upgrading to SLDS 2                                                                                                                                                                     | `design-systems-slds2-migrate`          |
| [`reference_lwc_compilation_error`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)        | GA     | Provides details for LWC compilation errors, including error patterns, possible causes, and recommended fixes                                                                                                           | N/A                                     |

### Testing Tools

Use these MCP tools to improve your testing workflow.

| Tool Name                                             | GA?    | Description                                                                                    | Superseded by LWC Skill   |
| ----------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- | ------------------------- |
| [`orchestrate_lwc_component_testing`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md) | GA     | Provides a comprehensive testing workflow and generates tests                                  | `experience-lwc-test`     |
| [`create_lwc_jest_tests`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)             | GA     | Generates comprehensive Jest test suites                                                       | `experience-lwc-generate` |
| [`review_lwc_jest_tests`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)             | GA     | Reviews and validates Jest test implementations                                                | `experience-lwc-generate` |
| [`run_lwc_accessibility_jest_tests`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)  | GA     | Provides accessibility testing utilities and Jest integration for LWC                          | N/A                       |
| [`guide_utam_generation`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)             | NON-GA | Provides UI Test Automation Model (UTAM) Page Object generation guidelines and best practices. | `experience-lwc-test`     |

### Lightning Base Components Tools

Use these MCP tools to identify the right base components for your use case.

| Tool Name                                          | GA? | Description                                                                        | Superseded by LWC Skill                    |
| -------------------------------------------------- | --- | ---------------------------------------------------------------------------------- | ------------------------------------------ |
| [`guide_lbc_usage`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-base-components.md)        | GA  | Provides an index of base components to help identify which components you can use | `experience-lwc-base-components-integrate` |
| [`explore_lbc_components`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-base-components.md) | GA  | Provides guidance on base component usage                                          | `design-systems-slds-apply`                |

### Lightning Data Service (LDS) Tools

Use these MCP tools to review LDS development guidelines and discover LDS wire adapters and UI API type definitions for LWC development.

| Tool Name                                         | GA? | Description                                                                                                                                                                          | Superseded by LWC Skill                     |
| ------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| [`guide_lds_development`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)             | GA  | Provides LDS development guidelines and component integration                                                                                                                        | `experience-lds-best-practices-apply`       |
| [`guide_lds_data_consistency`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)        | GA  | Provides data consistency patterns and best practices for using LDS-based components and wire adapters                                                                               | `experience-lds-best-practices-apply`       |
| [`guide_lds_referential_integrity`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)   | GA  | Provides referential integrity patterns for LDS data management                                                                                                                      | `experience-lds-best-practices-apply`       |
| [`explore_lds_uiapi`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)                 | GA  | Explores and documents Lightning Data Service UI API capabilities                                                                                                                    | `experience-lds-best-practices-apply`       |
| [`orchestrate_lds_data_requirements`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md) | GA  | Analyzes and clarifies LDS data requirements to produce PRD-ready specifications                                                                                                     | `experience-lds-data-requirements-generate` |
| [`guide_lds_graphql`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)                 | GA  | Provides guidelines on implementing GraphQL patterns to work with Salesforce data through the GraphQL wire adapter                                                                   | `experience-lds-graphql-generate`           |
| [`fetch_lds_graphql_schema`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)          | GA  | Provides static GraphQL schema information, containing all the common types referred to by Salesforce GraphQL schemas.                                                               | N/A                                         |
| [`create_lds_graphql_read_query`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)     | GA  | Provides guidelines for creating GraphQL read queries                                                                                                                                | `experience-lds-graphql-generate`           |
| [`create_lds_graphql_mutation_query`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md) | GA  | Provides guidance for creating GraphQL mutation queries.                                                                                                                             | `experience-lds-graphql-generate`           |
| [`test_lds_graphql_query`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)            | GA  | Tests a GraphQL query against a connected Salesforce org and returns the result. Invoked only from the `create_lds_graphql_read_query` and `create_lds_graphql_mutation_query` tools | N/A                                         |

### Figma to LWC Conversion Tool

Use this tool to speed up your Figma to LWC conversion.

| Tool Name                                        | GA? | Description                                                                                                                                                                                                                                          | Superseded by LWC Skill          |
| ------------------------------------------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [`guide_figma_to_lwc_conversion`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-design.md) | GA  | Converts Figma designs to LWC specifications. Fetching data directly from Figma using this tool isn't currently supported. We recommend that you use the [Framelink Figma MCP server](https://www.framelink.ai/docs/quickstart) along with this tool | `experience-lwc-design-generate` |

### SLDS Guideline Tool

Use this tool to build accessible and responsive UI that follows SLDS gudelines.

| Tool Name                                      | GA? | Description                                                                                                         | Superseded by LWC Skill          |
| ---------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [`guide_figma_to_lwc_conversion`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-slds.md) | GA  | Provides SLDS guidelines and best practices, covering accessibility, responsive design, and correct component usage | `experience-lwc-design-generate` |

### Migration Tools

Use these MCP tools to assist with Aura-to-LWC or Lightning Out migrations, and validate migration completeness.

| Tool Name                                                | GA? | Description                                                             | Superseded by LWC Skill |
| -------------------------------------------------------- | --- | ----------------------------------------------------------------------- | ----------------------- |
| [`verify_aura_migration_completeness`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-migration.md) | GA  | Provides a migration completeness checklist and validates results       | N/A                     |
| [`guide_lo_migration`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-migration.md)                 | GA  | Converts a Lightning Out (beta) host page into a Lightning Out 2.0 page | N/A                     |

### Lightning Web Security (LWS) Tools

Use this security tool to analyze LWC code and provide guidance on best practices.

| Tool Name                               | GA? | Description                                                                         | Superseded by LWC Skill            |
| --------------------------------------- | --- | ----------------------------------------------------------------------------------- | ---------------------------------- |
| [`guide_lws_security`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-security.md) | GA  | Analyzes components based on product security and Lightning Web Security guidelines | `experience-lwc-security-validate` |

## Aura MCP Tools

These Aura MCP tools in the `aura-experts` toolset assist with Aura-to-LWC migration.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


The tools marked NON-GA are not yet generally available. Specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration to use them. See [Configure the Salesforce DX MCP Server for Your Environment](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_server.htm#sfdx_dev_mcp_configure_orgs_toolsets).

| Tool Name                                     | GA? | Description                                                                                        | Superseded by LWC Skill       |
| --------------------------------------------- | --- | -------------------------------------------------------------------------------------------------- | ----------------------------- |
| [`create_aura_blueprint_draft`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md)  | GA  | Creates a comprehensive Product Requirements Document (PRD) blueprint for Aura component migration | `experience-aura-lwc-migrate` |
| [`enhance_aura_blueprint_draft`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md) | GA  | Enhances an existing draft PRD with expert analysis and identify any migration unknowns            | `experience-aura-lwc-migrate` |
| [`transition_prd_to_lwc`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md)        | GA  | Provides migration guidance for creating LWC components from Aura specifications                   | `experience-aura-lwc-migrate` |
| [`orchestrate_aura_migration`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md)   | GA  | Orchestrates the complete Aura-to-LWC migration workflow                                           | `experience-aura-lwc-migrate` |

## LWC Validation Tools

These LWC validation MCP tools in the `experts-validation` toolset validates and scores LWC components for production readiness across accessibility, security, and other best practices.

| Tool Name                                  | GA? | Description                                                                       | Superseded by LWC Skill |
| ------------------------------------------ | --- | --------------------------------------------------------------------------------- | ----------------------- |
| [`validate_and_optimize`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-validate.md) | GA  | Performs a one-time analysis for guidance to validate and optimize your component | N/A                     |
| [`score_issues`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-validate.md)          | GA  | Computes the readiness score (0-100) and quality grade                            | N/A                     |

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)

<!-- document id=e11c0a644ec6afe85f5a2bdf52bf4a51ad7463f64c2f53ed14212e183abb072b url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-considerations.md -->

# LWC MCP Tools Usage Considerations

When using the MCP tools for LWC development, consider these usage guidelines.

- MCP tools are no longer recommended for AI-assisted LWC development. Consider using [LWC skills](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md) instead.
- MCP tools use generative AI, which can produce inaccurate or harmful responses. Before using the generated output, review it for accuracy and safety.
- Some MCP tools can invoke other tools depending on your prompts, but the tools aren't guaranteed to run. Check that the tool is enabled in your [DX MCP server configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_server.htm).
- When writing your prompt, you can explicitly request a specific LWC MCP tool that's been enabled. Refer to the MCP tool by name and describe the task you need the tool to perform in natural language. For example, "Use the guide_lwc_best_practices tool to review this component".

**See Also**

- [Use DX MCP Tools for LWC (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md)

<!-- document id=8703728864780b66715725f51ae5085fe063d9f1d650193e6a8019a838a86587 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-lwc.md -->

# LWC Migration for Record Home Pages

As part of the LWC enablement program at Salesforce, a majority of record home pages for standard objects have been converted to LWC, including details, highlights, and related lists. This change applies to Lightning Experience and the Salesforce mobile app. This change doesn’t apply to the Field Service mobile app.

Converting record home pages to use LWC results in faster page load and rendering, which is noticeable especially in large page layouts for creating, editing, or viewing a record.

For more information on objects and record pages supported for LWC, see [Supported Objects for LWC](https://developer.salesforce.com/docs/platform/lwc/reference/reference-objects-lwc.md).

A record home page has this URL pattern.

```html
https://my-domain-name.my.salesforce.com/lightning/r/ObjectApiName/RecordId/ViewOrEdit
```

For example, you can view an account’s record home page like this.

```html
https://my-dev-org.my.salesforce.com/lightning/r/Account/xxxxxxxxxxxxxxxQAD/view
```

When you work with an LWC-enabled record pages:

- Create from Lookup modal now supports Dynamic Forms.
- Create from Lookup modal now displays using LWC.
- Create from Lookup modal is now URL addressable.

**See Also**

- [_Salesforce Developers’ Blog:_ Unlocking Aura-to-LWC Migration at Salesforce](https://developer.salesforce.com/blogs/2023/01/unlocking-aura-to-lwc-migration-at-salesforce)

<!-- document id=f9f0886c9c4de12a9ad6f893b101dcac1307573754be7ddc6615f144d27fdc7e url=/developer/current/en-us/lwc/lwc/guides/js/js-third-party-strict-mode.md -->

# LWS-Compliant JavaScript Libraries

Most third-party libraries run as expected when Lightning Web Security (LWS) is enabled.

However, some libraries need minor changes. See [Third-Party Library Considerations for LWS](/docs/platform/lightning-components-security/guide/lws-js.html).

If the library isn’t compliant, ask the library maintainers to update the code to comply with LWS, or, if the project is open-source, contribute the changes yourself. Another option is to fork the repository, make the changes, and build your own version of the library. It's your responsibility to make sure any third-party libraries work with your Lightning components before deployment.

<!-- document id=278cd812a989d6c3e750fde3545e3db5cbe9d62c277705f495a503f3d2003c14 url=/developer/current/en-us/lwc/lwc/guides/use/use-context.md -->

# Make a Component Aware of Its Context

A component can be aware of its record context, its object context, and its width in a region in Lightning App Builder.

<!-- document id=01433ae77b9f17b1901ee488390ee6d883316f90cbac9fdeb93b45a21fc1c183 url=/developer/current/en-us/lwc/lwc/guides/use/use-object-context.md -->

# Make a Component Aware of Its Object Context

In some use cases, it's helpful to make a component aware of its object context. For example, you want to provide the object context so that the component can return some information based on which object is being viewed on a page. To make a component aware of its object context, use the `objectApiName` property on a Lightning record page. The page then sets the property to the API name of the current object.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [`wireGetObjectInfo`](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/wireGetObjectInfo) component that returns the object information for a selected object.

## Access Object Context in Lightning Experience

In the component’s JavaScript class, use the `@api` decorator to create a public `objectApiName` property.

```javascript
// testClass.js
import { LightningElement, api } from "lwc";
export default class TestClass extends LightningElement {
  @api objectApiName;
}
```

When your component is invoked in a record context in Lightning Experience or in the mobile app, the `objectApiName` is set to the API name of the object associated with the record being viewed, for example: `Warehouse__c`.

**important:** The `objectApiName` is set only when you place or invoke the component in an explicit record context. In all other cases, the `objectApiName` isn’t set, and your component shouldn’t depend on it.

## Access Object Context in Experience Builder Sites

Experience Builder sites don’t automatically bind `objectApiName` to a component’s template.

After you include the `@api` decorator to create a public `objectApiName` property on your component, add `objectApiName` in an expression in the component’s `*.js-meta.xml` file. All the page types specified in the `targets` parameter have access to the object name.

**note:** This approach works only for components where the `{!objectApiName}` is in the route.

```xml
<targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property
      name="objectApiName"
      type="String"
      label="Object Name"
      description="Automatically bind the page's object name to the component variable"
      default="{!objectApiName}"
    />
  </targetConfig>
</targetConfigs>
```

When your component is invoked in an object context in an Experience Builder site, the expression `objectApiName` is set to the 18-character ID of the object.

**See Also**

- [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-interfaces.md)

<!-- document id=b9d291aa6b5fd4a18f07d4bada0a2a7d4cf6667c6ca27f2c950d7f7db22b4ab9 url=/developer/current/en-us/lwc/lwc/guides/use/use-record-context.md -->

# Make a Component Aware of Its Record Context

In some use cases, it's helpful to make a component aware of its record context. For example, you want to provide the record context so that the component can return and display child record information on a viewed record page. To make a component aware of its object context, use the `recordId` property on a Lightning record page. The page then sets the property to the ID of the current record.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [`wireGetRecordDynamicContact`](https://github.com/trailheadapps/lwc-recipes/blob/master/force-app/main/default/lwc/wireGetRecordDynamicContact) component that returns some data on a contact record that's being viewed.

## Access Record Context in Lightning Experience

In the component’s JavaScript class, use the `@api` decorator to create a public `recordId` property.

```javascript
// testClass.js
import { LightningElement, api } from "lwc";
export default class TestClass extends LightningElement {
  @api recordId;
}
```

When your component is invoked in a record context in Lightning Experience or in the mobile app, recordId is set to the 18-character ID of the record, for example: `001xx000003DGSWAA4`.

## Access Record Context from a Child Component

Place the component with the `recordId` property directly on a record context for it to be auto-populated. If you have a child component that requires the `recordId` value, retrieve the record ID on the container component and pass it to the child.

<!-- prettier-ignore -->
```html
<!-- myApp.html -->
<template>
    <c-component record-id={recordId}> </c-component>
</template>
```

Include the `recordId` property in your JavaScript class.

```javascript
// myApp.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  @api recordId;
}
```

In the child component `c/component`, you can retrieve record data by using the [`getRecord` wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-record.md) or another wire adapter depending on your use case. For example, you can pass the record ID to a child component that loads a map based on an account's billing address.

**important:** The `recordId` is set automatically only when you place or invoke the component in an explicit record context. In all other cases, the `recordId` isn’t set, and your component can’t depend on it. You can set the `recordId` yourself in such cases. For example, components used for [quick actions](https://developer.salesforce.com/docs/platform/lwc/use/use-quick-actions.md) can explicitly set the `recordId` if they need access to the record ID when used on a record page.

## Access Record Context in Experience Builder Sites

Experience Builder sites don’t automatically bind `recordId` to a component’s template.

After you include the `@api` decorator to create a public `recordId` property on your component, add `recordId` in an expression in the component’s `*.js-meta.xml` file. All the page types specified in the `targets` parameter have access to the record ID.

```xml
<targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property
      name="recordId"
      type="String"
      label="Record ID"
      description="Specify {!recordId} in the Record ID field on the component property in Experience Builder."
    />
  </targetConfig>
</targetConfigs>
```

To bind the page's record ID to the component variable:

1. In Experience Builder, open the Components panel and drag your component to the editable area.
2. Select the component on the main page canvas or on the Page Structure panel. When you select the component, the component's Record ID property displays in the floating property editor.
3. In the Record ID property field, enter `{!recordId}`.

For more information, see [Edit Pages and Components in Experience Builder](https://help.salesforce.com/s/articleView?id=sf.community_builder_edit_pages.htm).

When your component is invoked in a record context in an Experience Builder site, the expression `"{!recordId}"` is set to the 18-character ID of the record.

**See Also**

- [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-interfaces.md)

<!-- document id=b71c813aa72af2996ec1972c05b25c109a91d9da5f44b7b9e240aeccef4f6a29 url=/developer/current/en-us/lwc/lwc/guides/use/use-width-aware.md -->

# Make a Component Width-Aware

When you add a component to a region on a page in the Lightning App Builder, use `@api flexipageRegionWidth` to pass the region’s width to the component. Then with some strategic CSS, you can tell the component to render in different ways in different regions at run time.

For example, the List View component renders differently in a large region than in a small region because it’s a width-aware component.

![List view in large and small regions](https://developer.salesforce.com/media/lab_width_aware_comps.png)

In the component’s JavaScript class, use the `@api` decorator to create a public `flexipageRegionWidth` property. This property receives the width value of the region that the component resides in on the page.

```javascript
// testClass.js
import { LightningElement, api } from "lwc";

export default class TestClass extends LightningElement {
  @api flexipageRegionWidth;
}
```

Use the `flexipageRegionWidth` property in the HTML template. When the value of `flexipageRegionWidth` changes, the component rerenders.

<!-- prettier-ignore -->
```html
<!-- testClass.html -->
<template>
  <div class={flexipageRegionWidth}>...</div>
</template>
```

Use CSS to define the component’s behavior when it renders in different region widths. Valid CSS class values are `SMALL`, `MEDIUM`, and `LARGE`. This sample CSS snippet tells the component to render with a red background when it’s in a large region. It renders with a blue background when it’s in a small region.

```css
/* testClass.css */

div.LARGE {
  background: red;
  ...;
}
div.SMALL {
  background: blue;
  ...;
}
```

<!-- document id=97c037cc9c638b10d1cb9146bba390090b8d2d53ac716f4ed0830ffb58e37344 url=/developer/current/en-us/lwc/lwc/guides/data/data-table-custom-types-editable.md -->

# Make a Custom Data Type Editable

To make your custom data type editable in `lightning-datatable`, create an additional template to implement the UI for inline editing of the data type.

These high-level steps add inline edit capability.

1.  Create an edit template.
2.  Add the edit template to the custom type definition.
3.  Make the custom type editable in the column definition.

Let’s implement inline editing for the `customNumber` type in the example from [Define Your Custom Type by Extending LightningDatatable](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#define-custom-type).

**note:** This documentation uses the term _`lightning-datatable` component_ and _datatable_ interchangeably.

## Create an Edit Template

In the same folder where you defined the custom type templates, create a template `customNumberEdit.html` to use for editing the `customNumber.html` custom type.

```ascii
myCustomTypeDatatable
   ├──customName.html
   ├──customNumber.html
   ├──customNumberEdit.html
   ├──myCustomTypeDatatable.js
   └──myCustomTypeDatatable.js-meta.xml
```

The edit template for a custom type uses an input component that matches the output component in the custom type template. The `lightning-input` component is recommended. In the example, the output component `lightning-formatted-number` is used in the `customNumber` template, so we use `lightning-input type="number"` in its edit template. The `lightning-input type="number"` component enables users to change the number in the custom type cell.

**tip:** For information about components you can use in the edit template, see **Inline Edit Considerations for Custom Types** later in this page.

<!-- prettier-ignore -->
```html
<!--customNumberEdit.html-->
<template>
  <div class="slds-p-around_x-small">
    <lightning-input
      type="number"
      value={editedValue}
      required={required}
      label={columnLabel}
      min={typeAttributes.min}
      data-inputable="true"
      class="slds-float_right"
    >
    </lightning-input>
  </div>
</template>
```

Use these attributes to pass values between the input component and the extended datatable component.

| Attribute        | Type    | Description                                                                                                                                                                                                                                 |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `editedValue`    | string  | The current value of the custom cell being edited.                                                                                                                                                                                          |
| `columnLabel`    | string  | The `label` value retrieved from the column definition.                                                                                                                                                                                     |
| `required`       | boolean | The requiredness value retrieved from the column definition. The default value is false. If the column definition sets `required` to true, the field shows a validation error if a user interacts with the field and doesn’t enter a value. |
| `typeAttributes` | object  | The object containing the type attribute values for the cell. Access the values using the`typeAttributes.attributeName` syntax.                                                                                                             |

The example sets the `min` attribute to ensure that users enter a non-negative number when inline editing the custom number. In the next section, you add `min` to the custom type definition.

The `data-inputable="true"` attribute is required for accessibility support in the standard cell layout.

## Add the Edit Template to the Custom Type Definition

Import the edit template in `myCustomTypeDatatable.js`, and add the property `editTemplate: customNumberEditTemplate` in the `customNumber` definition in the `customTypes` object. The `editTemplate` property specifies the template for inline editing of the custom type.

```javascript
//myCustomTypeDatatable.js
import LightningDatatable from "lightning/datatable";
import customNameTemplate from "./customName.html";
import customNumberTemplate from "./customNumber.html";
import customNumberEditTemplate from "./customNumberEdit.html";

export default class MyCustomTypeDatatable extends LightningDatatable {
  static customTypes = {
    customName: {
      template: customNameTemplate,
      standardCellLayout: true,
      typeAttributes: ["accountName"],
    },
    customNumber: {
      template: customNumberTemplate,
      editTemplate: customNumberEditTemplate,
      standardCellLayout: true,
      typeAttributes: ["status", "min"],
    },
    // Other types here
  };
}
```

Change the `standardCellLayout` value to true to support accessibility and keyboard navigation. See **Accessibility of Editable Custom Types** later in this page for more information.

Add the `min` attribute to `typeAttributes` in the type definition.

## Make the Custom Type Editable in the Column Definition

In your datatable’s column definition, add the `editable: true` property to the custom type.

Here we show the `myDatatable.js` example from **Implement Your Datatable with the Custom Types** in [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md) with the `editable: true` property applied to the Employees column, which uses type `customNumber`.

```nolang
/* myDatatable.js */
import { LightningElement, wire, track } from 'lwc';
import getAccountList from '@salesforce/apex/AccountController.getAccountList';

const COLS = [
    { label: 'Account Name', type: 'customName',
     typeAttributes: {
        accountName: { fieldName: 'Name' }
    },
    },
    { label: 'Industry', fieldName: 'Industry',
     cellAttributes: {
        class: {fieldName: 'industryColor'},
    }
    },
    { label: 'Employees', type: 'customNumber', fieldName: 'NumberOfEmployees', editable: true,
     typeAttributes: {
            status: {fieldName: 'status'},
            min: 0
    },
    cellAttributes: {
        class: 'slds-theme_alert-texture'
    }
}];

```

If you add attributes to the input component in the edit template, add them to the column definition as well. Here we added the `min` attribute to `typeAttributes` for the Employees column.

## Handling Changed Values of Custom Types

Edited fields of custom types are displayed with a yellow highlight just as with the standard data types. The changed value for the cell is temporarily stored in the `editedValue` property.

Persist the changed value from the datatable as you do for standard types, using the `onsave` action and `draft-values` attribute. See [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/data/data-table-inline-edit.md) and the section **Working with Inline Editing** in the [`lightning-datatable`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-datatable) reference documentation.

## Accessibility of Editable Custom Types

To support accessibility features such as keyboard navigation for your editable custom data type:

- Add the attribute `data-inputable="true"` to the input component in the edit template.
- Set `standardCellLayout: true` for the custom type definition in `customTypes`.

These attributes enable the datatable’s action mode and navigation mode to work on your custom data type. Get into action mode by pressing the Enter key or Space Bar on the cell displaying your editable custom data type. In navigation mode, when you press the Tab key in the datatable you can navigate to cells displaying your editable custom data type because they're actionable.

Alternatively, to support accessibility and keyboard navigation for a custom data type, use a slot for the custom data type. See [Accessibility for Custom Data Types](https://developer.salesforce.com/docs/platform/lwc/data/data-table-custom-types.md#accessibility-for-custom-data-types).

The `aria-label` attribute is applied to the input component using the value of the `label` attribute.

## Validation and Error Handling for Edited Cells of Custom Type

The `lightning-input` component handles basic client-side input validation for you. For example, if you specify a `step`, `min`, or `max` attribute for a number input, the component validates the input against those attribute values and returns an error if it’s not valid. You can also perform more complex client-side validation for your custom type.

To further validate user input for the custom type on the client, use a child component in the custom edit template.

Set `data-inputable="true"` on the input component and include the `validity()` getter in its JS to expose the validity API for the input component.

```javascript
@api
get validity() {
    return this.customInput.validity;
}

```

Expose the `showHelpMessageifInvalid()` method from the input component in the edit template so the custom data type can display a custom message when changed data is invalid.

```javascript
@api
showHelpMessageIfInvalid() {
    this.customInput.showHelpMessageIfInvalid()
}


```

For more information, see the reference documentation for [`lightning-input`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-input).

## Inline Edit Considerations for Custom Types

- Only Lightning base components with a single input field are supported as the input component in custom edit templates. Components such as `lightning-input type="datetime"` that have multiple inputs whose API evaluates to a single input are also supported.
- The `lightning-input-field` component is designed for use in `lightning-record-edit-form` only and isn’t supported for use in a datatable. Use `lightning-input` instead.
- Server-side [validation rules](https://help.salesforce.com/s/articleView?id=platform.fields_about_field_validation.htm) aren't supported for custom data types yet.

<!-- document id=ec24496b7b053bfb597b2a46ee001935b97b6f51faeae2b869d80fe7ced3edcc url=/developer/current/en-us/lwc/lwc/guides/apex/apex-continuations.md -->

# Make Long-Running Callouts with Continuations

Use the `Continuation` class in Apex to make a long-running request to an external web service. Process the response in a callback method. Continuations are the preferred way to manage callouts because they can provide substantial improvements to the user experience.

Using continuations has some advantages, including the capability to make callouts in parallel.

The framework queues up actions before sending them to the server. This mechanism is largely transparent to you when you’re writing code but it enables the framework to minimize network traffic by batching multiple actions into one request (XHR). The batching of actions is also known as boxcar’ing, similar to a train that couples boxcars together. Since continuations can be long-running requests, the framework essentially treats continuations as background actions. Continuations aren't boxcar'ed with other requests so they don't block other actions while they are running.

An asynchronous callout made with a continuation doesn’t count toward the Apex limit of synchronous requests that last longer than five seconds. Since Winter ‘20, all callouts are excluded from the long-running request limit so continuations no longer offer an advantage for working with limits compared to regular callouts. However, we recommend using continuations to manage callouts due to the improved user experience.

**See Also**

- [Batching of Apex Actions](https://developer.salesforce.com/docs/platform/lwc/guide/apex-batched-actions.md)
- [_Apex Reference Guide_: Continuation Class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_System_Continuation.htm)
- [_Apex Developer Guide_: Named Credentials as Callout Endpoints](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_named_credentials.htm)

<!-- document id=4046e5f3fcb241eb521a6ecb63c37c79ed56d0789d8507c145b4f1394c0a411f url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-getters-dependencies.md -->

# Manage Attribute Dependencies in a Getter

An attribute in HTML turns into a property assignment in JavaScript. In both cases, the order of assignment is not guaranteed. To check for the existence of other attributes, use a getter.

Use a getter reference in the template. Don’t use the `@api` getter, and don’t use an `@api` setter that relies on a value from another `@api` property.

Let’s assume we have a datatable component that displays a check mark on selected rows. We have two separate attributes `rows` and `selectedRows`, which have a dependency on the other.

```html
<template>
  <c-datatable selected-rows="1,2" rows="1,2,3,4"> </c-datatable>
</template>
```

Since the order in which the attributes are received isn’t guaranteed, use getters to check the dependency.

```javascript
export default class Datatable extends LightningElement {
  @track state = {};

  @api
  get rows() {
    return this.state.rows;
  }

  set rows(value) {
    this.state.rows = value;

    // Check to see if the rows have
    // been marked as selected.
    if (this.state.selectedRows && !this.selectedRowsSet) {
      this.markSelectedRows();
      this.selectedRowsSet = true;
    }
  }

  @api
  set selectedRows(value) {
    this.state.selectedRows = value;

    // If rows haven’t been set,
    // then we can't mark anything
    // as selected.
    if (!this.state.rows) {
      this.selectedRowsSet = false;
      return;
    }

    this.markSelectedRows();
  }

  get selectedRows() {
    return this.state.selectedRows;
  }

  markSelectedRows() {
    // Mark selected rows.
  }
}
```

Using getters and setters ensures that the public API contract is easily enforced. A component shouldn’t change the value of a property that’s annotated with `@api`.

Normalize data in the setter if something depends on that value at set time, for example, to append a CSS class programmatically on an element. Return the original value in the getter. Normalization can also be done in the getter so that the template has access to a value even if the consumer doesn’t set anything.

```javascript
@track state = {
    selected : false
};

privateSelected = 'false';

@api
get selected() {
    return this.privateSelected;
}
set selected(value) {
    this.privateSelected = value;
    this.state.selected = normalizeBoolean(value)
}
```

<!-- document id=ac4a9fc9dcff6be79bbc92e08571771c412d0b269bac36346cf3659fff38b74b url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management.md -->

# Manage State Across LWC Components with State Managers

State management in Lightning Web Components (LWC) helps you group and manage data and its related logic more effectively within your apps. A state manager provides a structured way to handle application state, making it easier to share data across components, manage complex data interactions, and separate data concerns from presentation logic.

**note:** State management is not available in Experience Cloud at this time.

As apps grow in complexity, it can be challenging to manage the flow of data, ensure that components react appropriately to changes, and keep your codebase clean. LWC state management offers an idiomatic, LWC-native solution to these problems by introducing the concept of state managers.

A state manager is essentially a dedicated JavaScript module that encapsulates a related set of data (the "state") and the functions (or "actions") that operate on that data. This approach allows you to decouple your data logic from your component's rendering logic, leading to more organized, maintainable, and testable code.

A state manager implementation consists of the following elements.

- A function you provide to `defineState()` that defines the state manager implementation.
- A set of named properties that hold the state. These properties can be simple values or values derived from other state (computed values).
- A set of named actions (functions) that can modify the state.

State managers work within the LWC Framework’s [reactivity system](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md). Changes to a state manager's exposed values automatically trigger updates in components that reference those values, including re-rendering those components when needed.

<!-- document id=8d6f65cf8f25099fd5f444990008362dd0f4047604ad96a5f34a808334893932 url=/developer/current/en-us/lwc/utam/references/method-return-types.md -->

# Method Return Types

The UTAM compiler needs to know the return type for every method to generate the method signature in the type declaration (TypeScript) or in the interface code (Java). For example:

**JavaScript**

```js
returnPrimitive(): Promise<string>;
```

**Java**

```java
List<SomeCustomType> returnCustomList();
```

Depending on the method, the return type can be:

- Set explicitly in the [interface method declaration](#abstract-method-return-type) or [inside a compose statement](#compose-statement-return-type)

```json
{
  "returnType": "string",
  "returnAll": true
}
```

The return type of the last compose statement is considered the compose method's return type.

- [Inferred from the compose statement context](#inferring-the-return-type)

- Otherwise, the method is assumed to return void.

**important:** Do not set the return type at the level of a compose method's declaration.

## Supported return types

The `returnType` property can have one of the following values. Each of them except `void` can be combined with `"returnAll" : true` to return a list (Java) or an array (JavaScript).

| returnType       | returned value                                                      |
| ---------------- | ------------------------------------------------------------------- |
| custom type      | string with at least one '/', for example `utam/pageObject/Input`   |
| basic type       | supported only for [abstract methods](#abstract-method-return-type) |
| `boolean`        | boolean primitive (Boolean object in Java)                          |
| `frame`          | an element of `frame` type                                          |
| `number`         | number primitive (Integer object in Java)                           |
| `pageObject`     | page object instance of unspecified type (not root page object)     |
| `rootPageObject` | root page object instance of unspecified type                       |
| `string`         | string primitive (String object in Java)                            |
| `void`           | Default if explicit `returnType` isn't set and can't be inferred    |

## Inferring the return type

In some cases, the UTAM compiler can infer a statement's return type from the context.

- If a statement uses a matcher, the return type is always boolean

```json
{
  "element": "document",
  "apply": "getUrl",
  "matcher": {
    "type": "stringContains",
    "args": [{ "value": "homePage" }]
  }
}
```

- A statement that applies a [basic action](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md) to a [basic element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#basic-elements) from the same JSON (not a chain)

In this example, `getText` is known to return a string. If `basicElementsList` is an element of a basic type whose selector is marked with `returnAll` to return a list of elements, UTAM deduces that the return type is `List<String>` (Java) or `string[]` (JavaScript).

```json
{
  "element": "basicElementsList",
  "apply": "getText"
}
```

- A statement that invokes an element getter for an element from the same JSON (not a chain)

This JSON statement invokes a getter for the same basic element from the previous example. Assuming that the element is declared with `"type" : "actionable"`, UTAM knows to return `List<Actionable>`.

```json
{
  "elements": [
    {
      "name": "basicElementsList",
      "type": "actionable",
      "selector": {
        "css": ".action",
        "returnAll": true
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "basicElementsList"
        }
      ]
    }
  ]
}
```

The behavior is the same if you invoke a [custom element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#custom-elements) getter. In this example, the UTAM compiler deduces that the return type for the `test` method is `Custom`.

```json
{
  "elements": [
    {
      "name": "customElement",
      "type": "utam/pageObjects/custom",
      "selector": {
        "css": "my-utam"
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "customElement"
        }
      ]
    }
  ]
}
```

## Compose statement return type

The `returnType` should be explicitly set when it's not `void` and the statement isn't using a matcher.

### Statement applies an action to a custom element

In this example, the `test` method invokes the public `returnsString` method on the `custom` page object so the `returnType` should be explicitly set.

```json
{
  "elements": [
    {
      "name": "customElement",
      "type": "utam/pageObjects/custom",
      "selector": {
        "css": "my-utam"
      }
    }
  ],
  "methods": [
    {
      "name": "test",
      "compose": [
        {
          "element": "customElement",
          "apply": "returnsString",
          "returnType": "string"
        }
      ]
    }
  ]
}
```

### Statement applies an action to a `document`

The UTAM compiler doesn't recognize return types for methods applied to the `document` element. You need an explicit `returnType`.

```json
{
  "methods": "getCurrentUrl",
  "compose": [
    {
      "element": "document",
      "apply": "getUrl",
      "returnType": "string"
    }
  ]
}
```

### Statement applies an action to a `frame` element

The UTAM compiler doesn't recognize return types for methods applied to the `frame` element.

Even though `getClassAttribute` is a basic action, frame isn't recognized as a basic element and the compiler doesn't know the return type. You need an explicit `returnType`.

```json
{
  "elements": [
    {
      "name": "privateFrame",
      "type": "frame",
      "selector": {
        "css": "iframe"
      }
    }
  ],
  "methods": [
    {
      "name": "getFrameClass",
      "compose": [
        {
          "returnType": "string",
          "element": "privateFrame",
          "apply": "getClassAttribute"
        }
      ]
    }
  ]
}
```

### Chain statement

When a statement is "chained" (invoked on the result of the previous statement), the UTAM compiler doesn't know the return type. It almost always should be set explicitly (except for void or a matcher).

```json
{
  "elements": [
    {
      "name": "customElement",
      "type": "utam/pageObjects/custom",
      "selector": {
        "css": "my-utam"
      }
    }
  ],
  "methods": [
    {
      "name": "getFrameClass",
      "compose": [
        {
          // return type can be omitted
          // because it's a "can infer return" cases
          "element": "customElement"
        },
        {
          "returnType": "utam/pageObjects/anotherPageObject",
          "element": "anotherPageObjectInsideCustomElement",
          "chain": true
        },
        {
          "returnType": "string",
          "apply": "getTextFromAnotherPageObject",
          "chain": true
        }
      ]
    }
  ]
}
```

## returnType inside a predicate

In a `waitFor` statement, the return type is the `returnType` of the last statement inside the predicate.

In this example, the last predicate statement returns "string", so the predicate statement is also assumed to return string.

```json
{
  "methods": [
    {
      "name": "returnWaitRootPageObject",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "apply": "someMethod",
                  "returnType": "string"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

All the rules for inferring a return type inside the predicate also apply. A return type is inferred whenever possible.

## Abstract method return type

When you create an [interface](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/interfaces.md), the JSON compiler can't infer any return types, so each method's return type should be declared explicitly. Otherwise, the method is assumed to return void.

An interface must declare all public methods including element methods as well as compose methods. Here's an example:

```json
{
  "interface": true,
  "methods": [
    {
      "name": "doNothingAndReturnVoid"
    },
    {
      "name": "getInnerText",
      "returnType": "string"
    },
    {
      "name": "customElementsList",
      "returnType": "utam/pageObjects/customType",
      "retrunAll": true
    }
  ]
}
```

### returnType for basic elements

An element method might need to return basic types. Such a `returnType` isn't supported for a compose method because in a regular page object it's done via element declaration.

- set return type to return element marked with `"type" : ["actionable","clickable"]`

  ```json
  {
    "name": "getButton",
    "returnType": ["actionable", "clickable"]
  }
  ```

- set return type to return list of elements marked with `"type" : "editable"`

  ```json
  {
    "name": "getAllButtons",
    "returnType": "actionable",
    "returnAll": true
  }
  ```

## returnSelf statement

In a compose method, it can be useful to return an instance of the current page object instead of returning `void`, so that methods can be invoked in a chain inside a test or inside another compose method.

An `"apply": "returnSelf"` statement in a compose method or the `beforeLoad` method means that the generated method will have `return this` as its last statement. The method returns an instance of the current page object.

```json
{
  "elements": [
    {
      "name": "myElement",
      "selector": {
        "css": ".css"
      },
      "type": ["actionable", "clickable"]
    }
  ],
  "methods": [
    {
      "name": "focus",
      "compose": [
        {
          "element": "myElement",
          "apply": "focus"
        },
        {
          "apply": "returnSelf"
        }
      ]
    },
    {
      "name": "hasFocus",
      "compose": [
        {
          "element": "myElement",
          "apply": "isFocused"
        }
      ]
    }
  ]
}
```

This method returns the same page object so it can be chained. For example:

- Java

  ```java
  assert pageObject.focus().hasFocus();
  ```

- JavaScript

  ```js
  await (await pageObject.focus()).hasFocus();
  ```

The `returnSelf` statement must be the last statement inside the method and can't have any other JSON properties.

<!-- document id=e8e57023f1870d5e63b3033db45b189991f632364bd4d60e743370cd262ff4ee url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-access-controls.md -->

# Migrate Access Controls

Migrate access controls for an Aura component to the appropriate value for `<isExposed>` in a Lightning web component’s configuration file. Migrate access controls for an attribute in an Aura component to the appropriate combination of a JavaScript property decorator and value for `<isExposed>`.

To manage access to an Aura bundle’s resources, such as a component or attribute, use the `access` system attribute. For example, this component has global access, which means that the component can be added to a managed package and used in another org. The Aura component can also be used in Lightning App Builder or Experience Builder in another org if it implements the appropriate interface.

```xml
<aura:component access="global">
    ...
</aura:component>
```

The mechanism for access control is different in a Lightning web component, where access is defined by JavaScript property decorators and the component’s configuration file.

## Component

Here’s how the access values for an Aura component map to a Lightning web component.

- public

  - : Available within your org only.

    Set `<isExposed>false</isExposed>` in the component’s configuration file.

- global

  - : Available in all orgs. The component can be added to a managed package and used in another org. The Aura component can also be used in Lightning App Builder or Experience Builder in another org.

    Set `<isExposed>true</isExposed>` in the component’s configuration file.

## Attribute

Here’s how the access values for an Aura attribute map to a Lightning web component.

- private

  - : Available within the component only.

    Use a JavaScript field.

- public

  - : Available within your org only.

    Do both of these steps in a Lightning web component.

    1.  Use a JavaScript field with an `@api` decorator.
    2.  Set `<isExposed>false</isExposed>` in the component’s configuration file.

- global

  - : Available in all orgs.

    Do both of these steps in a Lightning web component.

    1.  Use a JavaScript property with an `@api` decorator.
    2.  Set `<isExposed>true</isExposed>` in the component’s configuration file.

**See Also**

- [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md)
- [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)
- [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md)
- [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-interfaces.md)

<!-- document id=aa555c5ee6005b57a95c433d22ca896c620957524f1f58e73a439874abfdcc84 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-apex.md -->

# Migrate Apex

Aura components and Lightning web components both use an Apex controller to read or persist Salesforce data. There are no syntax differences for the two programming models.

Lightning web components can also use the JavaScript `@wire` decorator to wrap calls to an Apex method or the User Interface API.

**See Also**

- [Work with Salesforce Data](https://developer.salesforce.com/docs/platform/lwc/data/data.md)

<!-- document id=1eead51298c84695a0198d650959623ca82068daff1dc0a394a47e8f774d5564 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-attributes.md -->

# Migrate Attributes

Migrate attributes from `<aura:attribute>` tags in an Aura component to JavaScript properties in a Lightning web component.

Let’s look at a `myAttribute` attribute in an Aura component.

```html
<aura:component>
  <aura:attribute name="myAttribute" default="Hello" />
</aura:component>
```

In a Lightning web component, we use a JavaScript property called `myAttribute` instead.

```javascript
// myComponentName.js
import { LightningElement, api } from "lwc";
export default class MyComponentName extends LightningElement {
  @api myAttribute = "Hello";
}
```

The `@api` decorator defines `myAttribute` as a public property. See [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md).

Reference the property in the component’s HTML file.

```html
<!-- myComponentName.html -->
<template> {myAttribute} </template>
```

Boolean attribute values in Lightning web components are set in markup without indicating `true` and `false` values. The value is set by the attribute’s presence (`true`) or absence (`false`). In JavaScript, boolean property values can be set with dynamic computed values. If a boolean property’s value computes to `false`, it is removed from the DOM. See [Boolean Properties](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-boolean.md).

**important:** A Lightning web component must fully support the converted Aura component’s attributes. If it doesn’t, expect errors and breakages.

**See Also**

- [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)

<!-- document id=9ea013cd11b623524543db30af4a15373770266d903b0ef59cb2b93f67bdceb6 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-introduction.md -->

# Migrate Aura Components to Lightning Web Components

Aura components and Lightning web components can exist in the same application. This section helps you to migrate components and apply your existing skills by mapping concepts from Aura components to Lightning web components.

- [Migration Strategy](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-strategy.md)
- [Pick a Component to Migrate](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-decide.md)
- [Migrate Component Bundle Files](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-bundles.md)
- [Migrate Markup](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-markup.md)
- [Migrate Events](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-events.md)
- [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-interfaces.md)
- [Migrate CSS](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-css.md)
- [Migrate JavaScript](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-javascript.md)
- [Migrate Apex](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-apex.md)
- [Migrate Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-quick-actions.md)

For a graphical illustration of how to map concepts from Aura components to Lightning web components, see [this Medium post](https://medium.com/@rajasneha20/lightning-web-components-migration-cheatsheet-c8ef6352ee04).

The [Lightning Web Components for Aura Developers](https://trailhead.salesforce.com/content/learn/modules/lightning-web-components-for-aura-developers) Trailhead module is another resource to help you learn about Lightning web components.

**See Also**

- [Use MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-intro.md)
- [Use the Aura-to-LWC Migration Tools](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-aura.md)

<!-- document id=c5562d089f4d593dafecff98f6b8b7d2477e3b0e9020528cdf7caa23e60924a6 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-base-components.md -->

# Migrate Base Components

Base components are building blocks that Salesforce provides in the `lightning` namespace. Base components have a different syntax when you use them in the two programming models.

## Migrate Base Component Markup

This Aura component uses the `lightning:formattedText` base component.

```xml
<aura:component>
    <lightning:formattedText linkify="true" value="I like salesforce" />
</aura:component>
```

To migrate this markup to a Lightning web component:

- Replace `<aura:component></aura:component>` with `<template></template>`.
- Change the colon that separates the namespace and component name to a dash.
- Verify that the base component for Aura is also available as a Lightning web component. See the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference//).
- Change the camel case component name (`formattedText`) to a dash-separated name (`formatted-text`).
- Remove the `true` or `false` value on the boolean attribute. If present, a boolean attribute denotes that its value is `true`.
- Change the self-closing tag to a full closing tag (`</lightning-formatted-text>`).

Here’s the equivalent Lightning web component.

```html
<template>
  <lightning-formatted-text linkify value="I like salesforce"></lightning-formatted-text>
</template>
```

## Migrate Base Component Event Handlers

Most event handlers on Aura base components have a Lightning web component equivalent. This Aura component uses the `lightning:button` base component with the `onclick` event handler.

```xml
<aura:component>
    <lightning:button
      label="Submit"
      title="Submit record data"
      onclick="{! c.handleClick }" />
</aura:component>
```

To retrieve the label on the button that fired the `click` event, use `event.getSource()`.

```javascript
({
  handleClick: function (cmp, event, helper) {
    alert("You clicked: " + event.getSource().get("v.label"));
  },
});
```

Here’s the equivalent Lightning web component.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button label="Submit" title="Submit record data" onclick={handleClick}>
  </lightning-button>
</template>
```

To get a reference to the component that dispatched the event, use the `event.target` property, which exposes public properties on the base component. For example, return the label on a clicked `lightning-button` component using `event.target.label`,

```javascript
import { LightningElement } from "lwc";
export default class MigrateButton extends LightningElement {
  clickedButtonLabel;

  handleClick(event) {
    this.clickedButtonLabel = event.target.label;
  }
}
```

If the base Aura component is wrapped with an HTML element so you can listen to an HTML event on the component, move the event handler to the base web component. For example, `lightning:input` supports several event handlers and it doesn’t support `onkeydown`. However, Aura enabled you to create a `div` wrapper to handle the `keydown` event.

```xml
<div onkeydown="{!c.handleKeyDown}">
  <lightning:input type="search" value="{!v.value}" onchange="{!c.handleChange}" />
</div>
```

Here’s the equivalent Lightning web component.

<!-- prettier-ignore -->
```html
<lightning-input
  value={val}
  label="Enter some text"
  onchange={handleChange}
  onkeydown={handleKeyDown}
>
</lightning-input>
```

Not all event handlers in Aura base components have a Lightning web component equivalent. For each base component’s specification, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference//).

## Migration Considerations

Base components for LWC provide a richer set of features than their Aura counterparts. Some base components might require more changes to migrate. Component differences are noted in [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-map-aura-lwc-components.md).

The [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) includes examples, documentation, and specification for the base components. In a component’s reference page, to compare the Lightning web component and its Aura counterpart, click **View as Aura Component** or **View as Lightning Web Component**.

**See Also**

- [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components.md)
- [Base Components: Migrate `ui` components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-ui-components.md)
- [Boolean Properties](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-boolean.md)
- [Lightning Aura Components Developer Guide: Working with Lightning Base Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/lightning_overview.htm)
- [Lightning Aura Components Developer Guide: Working with Lightning Base Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/lightning_overview.htm)

<!-- document id=fc4c0465ec49bcb2357055d7adb44b50b21963880554d7abcb2ce70a1fe4499a url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-bundles.md -->

# Migrate Component Bundle Files

The component bundle file structure is different for the Aura programming model versus the Lightning Web Components programming model.

Here's how the files map between the two programming models.

| Resource      | Aura File             | Lightning Web Components File | See Also                                                                                                                                                                                                 |
| ------------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Markup        | `sample.cmp`          | `sample.html`                 | [Component HTML File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-html-file.md)                                                                                                                                          |
| Controller    | `sampleController.js` | `sample.js`                   | [Component JavaScript File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md)                                                                                                                                   |
| Helper        | `sampleHelper.js`     | `sample.js`                   | [Lightning Components Developer Guide: Helpers](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_helper.htm)                                                                |
| Renderer      | `sampleRenderer.js`   | `sample.js`                   | [Lightning Components Developer Guide: Renderers](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_dom_modify_framework.htm)                                                |
| CSS           | `sample.css`          | `sample.css`                  | [Component CSS File](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-file.md)                                                                                                                                        |
| Documentation | `sample.auradoc`      | Not currently available       | [Lightning Components Developer Guide: Component Documentation](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_documentation.htm)                                 |
| Design        | `sample.design`       | `sample.js-meta.xml`          | [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md)                                                                                                                                 |
| SVG           | `sample.svg`          | Not currently available       | [Lightning Components Developer Guide: Custom Icons](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder.htm#components_config_for_app_builder) |

**note:** The controller, helper, and renderer files in an Aura component map to one JavaScript file in a Lightning web component.

<!-- document id=1a12cd934f3eecabfd7f98f0507b81a7c55791930d61bec7f7bfc52a171ea97d url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-conditionals.md -->

# Migrate Conditionals

Migrate `<aura:if>` tags in an Aura component to `lwc:if`, `lwc:elseif`, and `lwc:else` in a Lightning web component.

Here’s the syntax in an Aura component.

```html
<aura:if isTrue="{!v.something}">
  <div>Conditional Code</div>
  <aura:set attribute="else">
    <div>Conditional Code</div>
  </aura:set>
</aura:if>
```

Here’s the syntax in a Lightning web component.

<!-- prettier-ignore -->
```html
<template>
  <div lwc:if={something}>Conditional Code</div>
  <div lwc:elseif={something}>Conditional Code</div>
</template>
```

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  something = true;
}
```

**See Also**

- [Render DOM Elements Conditionally](https://developer.salesforce.com/docs/platform/lwc/create/create-conditional.md)

<!-- document id=6c1b4e00817987419aad1de79964498d9d574dd91ba0d87659ea83fa5715d071 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-css.md -->

# Migrate CSS

Lightning web components use standard CSS syntax. Remove the proprietary `THIS` class that Aura components use.

Here's a CSS file for an Aura component.

```css
.THIS .red {
  background-color: red;
}

.THIS .blue {
  background-color: blue;
}

.THIS .green {
  background-color: green;
}
```

## Remove `THIS` Keyword

The CSS file for the migrated Lightning web component is identical except for the removal of `THIS`.

```css
.red {
  background-color: red;
}

.blue {
  background-color: blue;
}

.green {
  background-color: green;
}
```

## Migrate CSS for Lightning Base Components

Migrating the CSS file is currently not supported across all base components. Let’s say you are migrating the following `lightning:button` Aura markup.

```xml
<lightning:button label="Reset" class="buttonColor buttonText"/>
```

The `lightning:button` uses the following CSS selectors.

```css
.THIS .buttonColor {
  background-color: red;
}

.THIS .buttonText {
  color: lightgray;
}
```

When you use the `lightning-button` base component, the custom classes are applied to the outer elements of the component, which means that the following `lightning-button` markup doesn’t display the expected styling.

```html
<!-- Custom styling does not work here -->
<lightning-button label="Reset" class="buttonColor buttonText"></lightning-button>
```

**note:** Your custom CSS is automatically scoped to your own component to prevent styling of a base component’s internals. We recommend that you use Lightning Design System classes or the variants on a base component where possible.

In this case, we recommend that you use the variant attribute on `lightning-button`. For example, use the `destructive` variant to make the background color red.

```html
<lightning-button label="Reset" variant="destructive"></lightning-button>
```

Let’s take a look at another example where migrating CSS can work for a base component. For example, you have the following `lightning:formattedAddress` markup.

```xml
<div class="mailingAddress">
  <lightning:formattedAddress
    street="1 Market St."
    city="San Francisco"
    country="US"
    province="CA"
    postalCode="94105"
  />
</div>
```

The component uses the following CSS selectors.

```css
.THIS .mailingAddress a {
  color: red;
}
```

Use the `class` attribute to apply the custom styling.

```html
<!-- Custom styling works here -->
<lightning-formatted-address
  class="mailingAddress"
  street="121 Spear St."
  city="San Francisco"
  country="US"
  province="CA"
  postal-code="94105"
></lightning-formatted-address>
```

```css
.mailingAddress {
  color: red;
}
```

**See Also**

- [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css.md)

<!-- document id=b80cd7b220778c6d7953d8a1b950716b87cabd1c75ebfd153f52b489058b6a3e url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-event-handlers.md -->

# Migrate Event Handlers

There's no equivalent in Lightning web components for the `<aura:handler>` tag in Aura component markup that configures an event handler.

**See Also**

- [Migrate Events](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-events.md)

<!-- document id=69bdec5ab1ead91b0073e5e0a2d408e8c4c7b129c50ad1482b2f666d7f3c9cc4 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-events.md -->

# Migrate Events

Migrate component events in Aura components to standard DOM events in Lightning web components.

Here’s an overview for working with events in Lightning web components.

- Create an event

  - : Instead of the proprietary `Event` object in Aura components, use the `Event` or `CustomEvent` standard DOM objects. There's no equivalent in Lightning web components for the `<aura:registerEvent>` tag in Aura component markup to register that a component can fire an event.

- Fire an event

  - : Instead of `event.fire()` in an Aura component, use `this.dispatchEvent(myEvent)`, which is a standard DOM method, in Lightning web components.

- Handle an event

  - : An Aura component uses the `<aura:handler>` tag in markup to define a handler. Alternatively a component can declare a handler action when it references another component in its markup. This Aura component uses `c:child` in its markup and declares a `handleChildEvent` handler for the `sampleComponentEvent` that `c:child` fires.

    ```html
    <c:child sampleComponentEvent="{!c.handleChildEvent}" />
    ```

    A Lightning web component can similarly declare a declarative handler. The event name in the declarative handler is prefixed by `on`.

    <!-- prettier-ignore -->
    ```html
    <c-child onsampleComponentEvent={handleChildEvent}></c-child>
    ```

    The event handler function, `handleChildEvent`, is defined in the JavaScript file of the component.

    In a Lightning web component, you can also programmatically set up a handler using the standard `addEventListener()` method in the component's JavaScript file.

- Retrieve an event payload

  - : Use the `event.detail` property to retrieve the event payload unless otherwise stated.

## Migrate Application Events

Use the [Lightning message service (`lightning/messageService`)](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel.md) to communicate with components within a single page or across multiple pages. You can also use the [pub-sub pattern](https://developer.salesforce.com/docs/platform/lwc/events/events-pubsub.md) to communicate between components within a single page.

## Migrate Standard Aura Events

This table maps standard Aura events, such as for navigating to a component or to display the record create panel, to usage in Lightning web components. Events that are not listed don’t currently have an equivalent in Lightning Web Components.

| Aura Component                           | Lightning Web Component                                                                                                                                                                                             | Description                                                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `aura:locationChange`                    | The `hashchange` browser event fires when a window's hash changes. To handle this event, use the [`onhashchange`](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onhashchange) event handler. | Fired when the hash part of the URL in the browser's location bar has been modified.                             |
| `aura:valueChange`                       | Use properties with custom getter and setter methods.                                                                                                                                                               | Fired when a property value has changed.                                                                         |
| `aura:valueDestroy`                      | Use the `disconnectedCallback()` lifecycle hook. See [Component Lifecycle](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md).                                                                                                    | Fired when a component is destroyed.                                                                             |
| `aura:valueInit`                         | To replace the `init` event handler, use the `connectedCallback()` lifecycle hook. See [Migrate Initializers](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-initializers.md).                                                                  | Fired when a component has been initialized.                                                                     |
| `aura:valueRender`                       | Use the `renderedCallback()` or `render()` lifecycle hook. See [Component Lifecycle](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md).                                                                                          | Fired when a component has been rendered.                                                                        |
| `force:createRecord`                     | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Displays the record create panel.                                                                                |
| `force:editRecord`                       | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Displays the record edit panel.                                                                                  |
| `force:navigateHome` (deprecated)        | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to a record home page.                                                                                 |
| `force:navigateToComponent` (deprecated) | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to a component.                                                                                        |
| `force:navigateToList`                   | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to a list view.                                                                                        |
| `force:navigateToObjectHome`             | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to an object home page.                                                                                |
| `force:navigateToRelatedList`            | Use the [navigation service.](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md)                                                                                                                                                               | Navigates to a related list.                                                                                     |
| `force:navigateToSObject`                | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to a record.                                                                                           |
| `force:navigateToURL`                    | Use the [navigation service](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).                                                                                                                                                               | Navigates to a URL.                                                                                              |
| `force:refreshView`                      | Use the [RefreshView API](https://developer.salesforce.com/docs/platform/lwc/data/refreshview/data-refreshview.md).                                                                                                                                                 | Reloads the view without a page reload.                                                                          |
| `force:showToast`                        | Import the `lightning/platformShowToastEvent` module. See [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/use/use-toast.md)                                                                                                                | Displays a toast message to alert users of a success, error, or warning.                                         |
| `lightning:openFiles`                    | Use the navigation service. See [Open Files](https://developer.salesforce.com/docs/platform/lwc/use/use-open-files.md).                                                                                                                                             | Opens one or more file records.                                                                                  |
| `lightning:tabClosed`                    | Use the [`lightning__tabClosed`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabClosed.htm) Lightning message channel.                                    | Fires when a Console workspace or subtab has been successfully closed.                                           |
| `lightning:tabCreated`                   | Use the [`lightning__tabCreated`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabCreated.htm) Lightning message channel.                                  | Fires when a Console workspace or subtab has been successfully created.                                          |
| `lightning:tabFocused`                   | Use the [`lightning__tabFocused`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabFocused.htm) Lightning message channel.                                  | Fires when a Console workspace or subtab is focused.                                                             |
| `lightning:tabRefreshed`                 | Use the [`lightning__tabRefreshed`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabRefreshed.htm) Lightning message channel.                              | Fires when a Console workspace or subtab has been successfully refreshed.                                        |
| `lightning:tabReplaced`                  | Use the [`lightning__tabReplaced`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabReplaced.htm) Lightning message channel.                                | Fires when a Console primary tab or subtab has been successfully replaced.                                       |
| `lightning:tabUpdated`                   | Use the [`lightning__tabUpdated`](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lwc_tabUpdated.htm) Lightning message channel.                                  | Fires when a Console workspace or subtab has been updated, which includes label, icon, or other content changes. |
| `ltng:afterScriptsLoaded`                | Import the static resource and import methods from the `lightning/platformResourceLoader` module. See [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md).                                      | Fired when `ltng:require` has loaded all scripts listed in `ltng:require.scripts`                                |

**See Also**

- [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md)

<!-- document id=ba5c9bf925ffb614b9b6b0a2c21aa4360ceadf9ac1812a2b5ce79018c2bf261a url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-expressions.md -->

# Migrate Expressions

Migrate expressions from markup in an Aura component to JavaScript in a Lightning web component.

Here’s the syntax in an Aura component.

```html
<aura:if isTrue="{! (!v.something ? v.optionA : v.optionB) }">
  <div>Conditional Code</div>
</aura:if>
```

In a Lightning web component, use `lwc:if` and move the expression into JavaScript. Now the code can be unit tested, which is a very, very good thing. Here’s the HTML file.

<!-- prettier-ignore -->
```html
<template>
  <div lwc:if={condition}>Conditional Code</div>
</template>
```

**tip:** Dynamic content in a Lightning web component's HTML file doesn't have quotes around the getter reference and there's no exclamation point or value provider (`v.`) syntax. Don't use the expression syntax from Aura components even though your fingers might be used to typing it!

Here’s an expression in an Aura component.

```xml
<aura:if isTrue="{!v.condition}">
```

Here’s similar HTML in a Lightning web component.

<!-- prettier-ignore -->
```html
<div lwc:if={condition}>Conditional Code</div>
```

Here’s the JavaScript file.

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName {
  get condition() {
    return something ? true : false;
  }
}
```

**See Also**

- [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md)

<!-- document id=526a1c9fbefc9b7f2ee1d6ef9e48e77f98cf6a55811d10849033e5d8d5665818 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-facets.md -->

# Migrate Facets

Migrate a facet in an Aura component to a slot in a Lightning web component.

A facet in an Aura component is an attribute with a type of `Aura.Component[]`. For example:

```html
<aura:component>
  <aura:attribute name="firstName" type="Aura.Component[]" />
  <aura:attribute name="lastName" type="Aura.Component[]" />

  <p>First Name: {!v.firstName}</p>
  <p>Last Name: {!v.lastName}</p>
</aura:component>
```

In a Lightning web component, we use slots instead of the facets. This template defines two named slots.

```html
<!-- namedSlots.html -->
<template>
  <p>First Name: <slot name="firstName">Unknown</slot></p>
  <p>Last Name: <slot name="lastName">Unknown</slot></p>
</template>
```

This code consumes the `<c-namedslots>` component.

```html
<!-- slotsWrapper.html -->
<template>
  <c-named-slots>
    <span slot="firstName">Willy</span>
    <span slot="lastName">Wonka</span>
  </c-named-slots>
</template>
```

This HTML is the rendered output.

```html
<p>First Name: <span>Willy</span></p>
<p>Last Name: <span>Wonka</span></p>
```

**See Also**

- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md)
- [Compose Aura Components from Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/interop/interop-aura-composition.md)

<!-- document id=0084f2ed7157d956692bd8fdd37207aa20339d710ee0b5078acb7831e108f09a url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-migrate-experiencepropertytypebundle.md -->

# Migrate from `ExperiencePropertyTypeBundle` to `LightningTypeBundle`

If you created any custom property types using `ExperiencePropertyTypeBundle`, update the relevant custom Lightning web components to reference the new `LightningTypeBundle` instead.

1. Create a new `LightningTypeBundle` and give it a different name from the original `ExperiencePropertyTypeBundle`. (See [Object-Based Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-object.html) in the Lightning Types Developer Guide.)
2. Copy the `schema.json` file from the `ExperiencePropertyTypeBundle` to the new `LightningTypeBundle`.
3. For an `ExperiencePropertyTypeBundle` that has a `design.json` file, create a new `editor.json` file in the `LightningTypeBundle` and place it in the `experienceBuilder` folder. To create the `editor.json` file, copy the contents of the `design.json` file to `editor.json` and replace:
   - `propertySheet` with `editor`
   - `propertyRenderers` with `componentOverrides`
   - `view` with `layout`
4. Update the `type` attribute in the custom Lightning web component's `js-meta.xml` file to point to the new `LightningTypeBundle`.
5. Deploy the new `LightningTypeBundle` and updated custom Lightning web component to your org.
6. If the `ExperiencePropertyTypeBundle` is not part of a managed package, delete it using `destructiveChanges.xml` (See [Deleting Components from an Organization](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy_deleting_files.htm) in the Metadata API Developer Guide.)

Here's an example of an `ExperiencePropertyTypeBundle`'s `design.json` file.

```json
{
  "propertySheet": {
    "propertyRenderers": {
      "borderStyle": {
        "definition": "c/borderStyleDropdownCPE"
      }
    },
    "view": {
      "definition": "lightning/tabSetLayout",
      "children": [
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Borders"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderStyle"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderWeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderRadius"
              }
            }
          ]
        },
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Size"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutHeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutWidth"
              }
            }
          ]
        }
      ]
    }
  }
}
```

Here's the equivalent `LightningTypeBundle` `editor.json` file.

```json
{
  "editor": {
    "componentOverrides": {
      "borderStyle": {
        "definition": "c/borderStyleDropdownCPE"
      }
    },
    "layout": {
      "definition": "lightning/tabSetLayout",
      "children": [
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Borders"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderStyle"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderWeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderRadius"
              }
            }
          ]
        },
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Size"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutHeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutWidth"
              }
            }
          ]
        }
      ]
    }
  }
}
```

**See Also**

- _Metadata API Guide_: [ExperiencePropertyTypeBundle (Beta)](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_experiencepropertytypebundle.htm)
- _Metadata API Guide_: [LightningTypeBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_lightningtypebundle.htm)

<!-- document id=c4efdfb2910fb68457ffaf6480d33dd2bc9721d5d1b14f0925f9c5aca6108540 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-gvps.md -->

# Migrate Global Value Providers

Migrate global value providers in an Aura component to scoped module imports in a Lightning web component.

| Aura            | Lightning Web Components                                                  | Description                                                                                      |
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `$Browser`      | [`@salesforce/client/formFactor`](https://developer.salesforce.com/docs/platform/lwc/create/create-client-form-factor.md) | Returns information about the form factor of the hardware the browser is running on.             |
| `$ContentAsset` | [`@salesforce/contentAssetUrl`](https://developer.salesforce.com/docs/platform/lwc/create/create-content-assets.md)       | References images, stylesheets, and JavaScript used as asset files in your Lightning components. |
| `$Label`        | [`@salesforce/label`](https://developer.salesforce.com/docs/platform/lwc/create/create-labels.md)                         | Accesses labels stored outside your code.                                                        |
| `$Locale`       | [`@salesforce/i18n`](https://developer.salesforce.com/docs/platform/lwc/create/create-i18n.md)                            | Returns information about the current user’s preferred locale.                                   |
| `$Resource`     | [`@salesforce/resourceUrl`](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md)                | References images, stylesheets, and JavaScript code you’ve uploaded in static resources.         |

**See Also**

- [Access Static Resources, Labels, Internationalization Properties, User IDs, and Form Factors](https://developer.salesforce.com/docs/platform/lwc/create/create-global-value-providers.md)

<!-- document id=c2284a9fa81965e7596ae284d4fb891fb7b070648758f6ca7b79cb709df2e949 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-initializers.md -->

# Migrate Initializers

Replace an `init` event handler in an Aura component with the standard JavaScript `connectedCallback()` method in a Lightning web component.

We use the `init` event in an Aura component to initialize a component after component construction but before rendering.

```javascript
<aura:handler name="init" value="{!this}" action="{!c.doInit}" />
```

The `doInit` function in the component's controller performs any necessary initialization.

```javascript
({
  doInit: function (cmp) {
    // initialize component
  },
});
```

In a Lightning web component, use `connectedCallback()` instead in the component's JavaScript file.

```javascript
// mySampleInit.js
import { LightningElement } from "lwc";
export default class MySampleInit extends LightningElement {
  connectedCallback() {
    // initialize component
  }
}
```

**See Also**

- [Run Code When a Component Is Inserted or Removed from the DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-dom.md)

<!-- document id=a44bd85f666b92248200fcd20c36c3fb6fee679c08701938854b2eb5766c0465 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-interfaces.md -->

# Migrate Interfaces

Implementing an Aura interface enables you to receive context data or to surface your custom component in different contexts, such as in the Lightning App Builder or Experience Builder.

To receive context data in a Lightning web component, import the corresponding module. To surface a component in different contexts, use the `targets` metadata in your `*.js-meta.xml` configuration file. For supported tags, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md).

Many Aura interfaces require both JavaScript changes and configuration file changes to achieve LWC functionality. Aura interfaces that aren’t listed don’t currently have an LWC equivalent.

## `clients:availableForMailAppPage`

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__Inbox</target>
</targets>
```

Indicates that the component can be used in Lightning App Builder to add to email application panes for the Outlook and Gmail integrations.
See [Create Components for the Outlook and Gmail Integrations](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder-email-app-pane.md).

## `clients:hasEventContext`

```javascript
import { LightningElement, api } from 'lwc';
  @api dates;
  @api location;
```

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__Inbox</target>
</targets>
```

Indicates that the component takes context information about an event when used with the Outlook and Gmail integrations. See [Create Components for the Outlook and Gmail Integrations](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder-email-app-pane.md).

## `clients:hasItemContext`

```javascript
import { LightningElement, api } from 'lwc';
  @api mode;
  @api people;
  @api source;
  @api subject;
  @api messageBody;
```

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__Inbox</target>
</targets>
```

Indicates that the component takes context information about an email or calendar event when used with the Outlook and Gmail integrations. See [Create Components for the Outlook and Gmail Integrations](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder-email-app-pane.md).

## `flexipage:availableForAllPageTypes`

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__AppPage</target>
  <target>lightning__RecordPage</target>
  <target>lightning__HomePage</target>
  <target>lightning__UtilityBar</target>
</targets>
```

Indicates that the component is available for record pages, the utility bar, and any other type of pages. Specify each page type explicitly as a target. See [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder.md) and [Configure a Component for the Utility Bar](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-utility-bar.md).

## `flexipage:availableForRecordHome`

```xml
<targets>
  <target>lightning__RecordPage</target>
</targets>
```

Indicates that the component is available for record pages only. See [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-app-builder.md).

## `force:appHostable`

```xml
 <targets>
     <target>lightning__Tab</target>
  </targets>
```

Indicates that the component can be used as a custom tab in Lightning Experience or the Salesforce mobile app. See [Configure Components for Custom Tabs](https://developer.salesforce.com/docs/platform/lwc/use/use-config-custom-tab.md).

## `force:hasRecordId`

```javascript
import { LightningElement, api } from 'lwc';
  @api recordId;
```

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__RecordPage</target>
</targets>
```

Indicates that the component takes a record Id as an attribute. See [Make a Component Aware of Its Record Context](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md).

## `force:hasSObjectName`

```javascript
import { LightningElement, api } from 'lwc';
  @api objectApiName;
```

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__RecordPage</target>
</targets>
```

Indicates that the component takes the API name of the current record’s object type. See [Make a Component Aware of Its Object Context](https://developer.salesforce.com/docs/platform/lwc/use/use-record-context.md).

## `force:lightningQuickAction`

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__RecordAction</target>
</targets>
<targetConfigs>
  <targetConfig targets="lightning__RecordAction">
    <actionType>ScreenAction</actionType>
  </targetConfig>
</targetConfigs>
```

Indicates that the component is a quick action. See [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md).

**note:** LWC quick actions are currently supported only on the record page.

## `force:lightningQuickActionWithoutHeader`

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__RecordAction</target>
</targets>
<targetConfigs>
  <targetConfig targets="lightning__RecordAction">
    <actionType>ScreenAction</actionType>
  </targetConfig>
</targetConfigs>
```

Indicates that the component is a quick action with no header. See [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md).

**note:** LWC quick actions are currently supported only on the record page.

## `forceCommunity:availableForAllPageTypes`

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightningCommunity__Page</target>
</targets>
```

Indicates that the component can be used in Experience Builder. See [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-community-builder.md).

## `lightning:availableForFlowScreens`

```javascript
import { LightningElement, api } from 'lwc';
import { FlowAttributeChangeEvent, FlowNavigationNextEvent } from 'lightning/flowSupport';
  @api name;
  @api quantity;

  handleChange(event) {
    this.name = event.target.name;
    this.quantity = event.target.quantity;
  }
```

In `*.js-meta.xml`:

```xml
<targets>
  <target>lightning__FlowScreen</target>
</targets>
<targetConfigs>
  <targetConfig targets="lightning__FlowScreen">
      <property name="name" type="String" label="Name" />
      <property name="quantity" type="Integer" />
  </targetConfig>
</targetConfigs>
```

Indicates that the component can be used in a flow screen. See [Configure a Component for Flow Screens](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-flow-screens.md).

## `lightning:hasPageReference`

```javascript
import { CurrentPageReference } from 'lightning/navigation';
  @wire(CurrentPageReference) pageRef;
```

Indicates that the component accepts a PageReference. See [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).

## `lightning:isUrlAddressable`

In `*.js-meta.xml`:

```xml
<isExposed>true</isExposed>
<targets>
  <target>lightning__UrlAddressable</target>
</targets>
```

Indicates that the component is directly addressable via URL with the pattern `/lightning/cmp/componentName`. You can also navigate to the component using the `standard__component` page reference type. See [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md).

## `lightning:utilityItem`

In `*.js-meta.xml`:

```xml
<targets>
    <target>lightning__UtilityBar</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__UtilityBar">
      <property name="greeting" type="String" description="Enter a greeting"/>
    </targetConfig>
  </targetConfigs>
```

Indicates that the component can be used as a utility item in an app's utility bar. See [Configure a Component for the Utility Bar](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-utility-bar.md).

<!-- document id=c4a23750f9797dba3c33c7e6b75921b0932a46fa471a3e8dac73435559aa33c3 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-iterations.md -->

# Migrate Iterations

Migrate `<aura:iteration>` tags in an Aura component to `for:each` in a Lightning web component.

Here’s the Aura syntax.

```html
<aura:iteration items="{!v.items}" itemVar="item"> {!item} </aura:iteration>
```

Here’s the Lightning web component syntax.

<!-- prettier-ignore -->
```html
<template for:each={items} for:item="item">
  <p key={item.id}>{item}</p>
</template>
```

Note that you must use a `key` to assign a unique value to each item in the list. See [Render Lists](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md).

You can’t initialize list options in a Lightning web component template like you can in Aura component markup. You must initialize list options in JavaScript. See the [`lightning-dual-listbox`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-dual-listbox) component for an example.

<!-- document id=2f6eeb65a3fd8d022cd2fbdcbd1055cdce4d168d83c0e5cc4832e6509076943f url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-javascript.md -->

# Migrate JavaScript

Move JavaScript code from your client-side controller, helper, and renderer to the single JavaScript file in a Lightning web component.

A client-side controller in an Aura component is a JavaScript object in object-literal notation containing a map of name-value pairs. A JavaScript file in Lightning web components is an ES6 module so you're using standard JavaScript rather than the proprietary format used in Aura components.

This is not a line-by-line conversion, and it's a good opportunity to revisit your component's design.

To share JavaScript code between Lightning web components and Aura components, put the code in an ES6 module. For more information, see [Share JavaScript Code Between LWC and Aura](https://developer.salesforce.com/docs/platform/lwc/interop/interop-share-javascript.md).

**See Also**

- [Component JavaScript File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md)
- [Trailhead: Modern JavaScript Development: Learn about JavaScript ES6 features and what you can do with them](https://trailhead.salesforce.com/en/content/learn/modules/modern-javascript-development?trail_id=learn-to-work-with-javascript)

<!-- document id=f41c921f3abeb072675be4f74f74d7a2130b6ce2ff66c64747aa1b8df175abe8 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-markup.md -->

# Migrate Markup

An Aura `.cmp` file contains markup, including Aura-specific tags. Let's look at how this markup maps to equivalent concepts in Lightning web components.

- [Migrate Attributes](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-attributes.md)
- [Migrate Iterations](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-iterations.md)
- [Migrate Conditionals](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-conditionals.md)
- [Migrate Expressions](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-expressions.md)
- [Migrate Global Value Providers](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-gvps.md)
- [Migrate Initializers](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-initializers.md)
- [Migrate Facets](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-facets.md)
- [Migrate Registered Events](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-registered-events.md)
- [Migrate Event Handlers](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-event-handlers.md)
- [Migrate Access Controls](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-access-controls.md)

**See Also**

- [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-introduction.md)
- [Migrate Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-base-components.md)

<!-- document id=bf85ee9da171f6b73cd11731c1e23beb47f0d96feaa22da6c408feb0b5094afe url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-quick-actions.md -->

# Migrate Quick Actions

Migrate an Aura quick action by updating the `*.js-meta.xml` file on your Lightning web component. There are two types of Aura quick actions:

- A modal with standard action controls, such as a Cancel button, which implements the `force:lightningQuickAction` interface
- A modal without additional controls, which implements the `force:lightningQuickActionWithoutHeader` interface

Here's the Aura syntax for the `force:lightningQuickAction` interface.

```xml
<aura:component implements="force:lightningQuickAction">
    <!-- your code here -->
</aura:component>
```

Here's the Aura syntax for the `force:lightningQuickActionWithoutHeader` interface.

```xml
<aura:component implements="force:lightningQuickActionWithoutHeader">
    <!-- your code here -->
</aura:component>
```

**note:** LWC quick actions are currently supported only on the record page.

To configure your `*.js-meta.xml` file, see these resources:

- [`force:lightningQuickAction`](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-interfaces.md#forcelightningquickaction)
- [`force:lightningQuickActionWithoutHeader`](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-interfaces.md#forcelightningquickactionwithoutheader)

## LWC Quick Actions

LWC quick actions can be a _screen action_ or a _headless action_. A screen quick action appears in a modal window. A headless quick action executes custom code without a modal window.
You can also use a headless quick action to [navigate to another page](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-quick-action.md) using the `lightning/navigation` module.
For more information, see [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md).

A common use case for using an LWC quick action is to provide custom functionality that's not available with [standard quick actions](https://help.salesforce.com/s/articleView?id=platform.actions_overview.htm) or [default actions](https://help.salesforce.com/s/articleView?id=platform.default_actions_overview.htm).
For example, you want to display a modal with information, and then include a button that displays a create record modal. In an Aura quick action, you can call `force:recordCreate` when the button is clicked. When you migrate to an LWC quick action, you can use the `lightning/navigation` module to achieve the same behavior.

## Quick Action Navigation Differences

A custom quick action can open an Aura-based modal or an LWC-based modal.

Aura-based modals are opened by triggering an Aura quick action. LWC-based modals are opened by triggering an LWC quick action. However, an Aura quick action can also open an LWC-based modal via the `force:recordCreate` event if an [LWC-enabled object](https://developer.salesforce.com/docs/platform/lwc/reference/reference-objects-lwc.md) is passed to the event.

An Aura-based modal cannot be URL addressable, which means the browser doesn't track the modal in its history. An LWC-based modal is URL addressable, and you can use the browser's Back button to go back to the modal.

After you create the record successfully, you are either returned back to the original record page that triggered the quick action or redirected to the newly created record page. This behavior is known as _post-save navigation_ behavior.

## Post-Save Navigation

Post-save navigation is determined by several factors, whether the modal is Aura- or LWC-based and whether the modal is stacked. Modals that are opened by Aura quick actions are not stacked, which means that a modal is closed when another is opened.

For example, let's say you have an Aura component that implements `force:lightningQuickAction`. The component contains a button that calls `force:recordCreate` for the case object, which is an LWC-enabled object.

```javascript
createRecord: function(component, event, helper) {
    var createRecordEvent = $A.get("e.force:createRecord");
    createRecordEvent.setParams({
        "entityApiName": "Case"
    });
    createRecordEvent.fire();
}
```

When the event is fired, the Aura-based modal is closed automatically. It then displays the **Create Case** modal, which is an LWC-based modal that's not stacked. After you save the new case record, you are redirected to the newly created record page.

To achieve the same behavior with an LWC quick action, use the `lightning/navigation` module.

```javascript
createRecord() {
  this[NavigationMixin.Navigate]({
    type: 'standard__objectPage',
    attributes: {
      objectApiName: 'Case',
      actionName: 'new'
    }
  }, true);
}
```

For more information, see [Quick Action Navigation](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-quick-action.md).

## Differences in Post-Save Navigation

Salesforce enforces the [Enabled LWC Stacked Modals release update](https://help.salesforce.com/s/articleView?id=release-notes.rn_general_lwc_modals.htm&release=252) in Spring '25.
This table shows post-save navigation behavior with the release update enabled as compared to its previous behavior.

|                                     | Enable LWC Stacked Modal Release Update | LWC Stacked Modal Release Update Not Enabled | Example                                                                                                                                                   |
| ----------------------------------- | --------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default Action**                  | Returns back                            | Returns back                                 | On an account page, click the New Case action. A modal for new case creation is displayed.                                                                |
| **LWC Quick Action (stacked)**      | Returns back                            | Returns back                                 | Add an LWC quick action to a contact page. The quick action opens a modal, which contains a button that opens another modal using `lightning/navigation`. |
| **LWC Quick Action (not stacked)**  | Redirects to newly created record page  | Redirects to newly created record page       | Add an LWC quick action to a contact page. The quick action opens a modal.                                                                                |
| **Aura Quick Action (not stacked)** | Redirects to newly created record page  | Returns back                                 | Add an Aura (Lightning Component) quick action to a contact page. The quick action creates a case using a `lightning:recordEditForm` base component.      |

## Customize Post-Save Navigation Behavior

To customize post-save navigation in an LWC quick action, use the `lightning/navigation` module. Consider these differences between Aura and LWC quick actions.

- Aura quick actions—Modals opened by Aura quick actions redirect you to the newly created record page after record save. If you used `force:createRecord`, consider using LWC quick actions instead so you can configure post-save navigation to return you back to the original record page that triggered the quick action.
- LWC quick actions—When using the `lightning/navigation` module, the newer modal overlays and stacks on the previous modal by default. To automatically close the previous modal when navigating, set replace to `true`. When replace is `true`, post-save navigation redirects you to the newly created record.

**See Also**

- [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md)

<!-- document id=26c876f89508ff2c50cde27cc37e722eba81b0eaeef71766d21cfdda541b336f url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-registered-events.md -->

# Migrate Registered Events

There's no equivalent in Lightning web components for the `<aura:registerEvent>` tag in Aura component markup to register that a component can fire an event.

**See Also**

- [Migrate Events](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-events.md)

<!-- document id=1a7bfd25844228fedf340180c203aa663f85a4641a873a5dd092569a5c764720 url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-strategy.md -->

# Migration Strategy

The programming model for Lightning Web Components is fundamentally different than the model for Aura components. Migrating a component is not a line-by-line conversion, and it's a good opportunity to revisit your component's design. Before you migrate an Aura component, evaluate the component’s attributes, interfaces, structures, patterns, and data flow.

An AI coding assistant can play a valuable role in your migration strategy. It can help analyze your Aura components, suggest optimal migration paths, and generate LWC code based on your requirements. By leveraging AI-powered tools, you can accelerate the migration process, reduce manual effort, and catch potential issues early. The coding assistant can also provide guidance on best practices, map Aura patterns to LWC equivalents, and answer questions as you step through the migration.

Here are several AI coding assistants you can use to facilitate Aura-to-LWC migration.

- [Salesforce DX MCP server with Aura and LWC MCP tools](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-intro.md)
- [Agentforce Vibes Extension](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-overview.html)
- [VS Code with Copilot MCP Client](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_get_started.htm)

## Migrate A Component

The easiest components to migrate are simple components that only render UI. You get more gains in performance and developer productivity by migrating larger trees of components (components within components) rather than an individual component. However, it's a useful learning experience to migrate one component and see how concepts in the Aura programming model map to concepts in the Lightning Web Components programming model.

To identify a component for migration, you can ask:

```bash
Which Aura component should I migrate to LWC first?
```

The AI coding assistant can suggest the order of migration based on the identified dependencies. For example, it can suggest in order:

- Migrate a UI-only component without any dependencies. When migrating to LWC, use base component equivalents where possible.
- Migrate a utility component that renders without UI and contain `aura:method` tags. When migrating to LWC, create a standard JavaScript module.
- Migrate an Aura component that emits events.
- Migrate an Aura component that work with record data or Salesforce API. Use an equivalent LWC wire adapter or API module.
- Migrate parent Aura components that contain child components after the latter have been migrated.

**note:** An Aura component can contain LWC children (but not the other way around), so migrating leaf children first lets you progressively replace internals without breaking pages.

After migrating one component, you'll be in a better position to determine whether it makes sense for you and your org to:

- Undertake a larger migration effort
- Use Lightning web components for new components only
- Stick with Aura components for now

The choice is down to you and differs for everyone, depending on use cases and available resources. Whatever decision you make, migrating a component is a valuable learning exercise.

## Review Your Components

Reviewing your components help you scope the migration workflow.

- Inventory all Aura components in your org
- Identify dependencies between components
- Review current test coverage
- Plan migration order (dependencies first)

## Run the Aura and LWC MCP Tools

Running [the MCP tools](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-aura.md) facilitate and speed up your Aura-to-LWC migration.

- Run a migration analysis on each component
- Review generated migration plan
- Update parent components to use new LWC children
- Verify event handling and data flow

## Optimize and Test Your Migration

We recommend that you optimize and test your components after the migration.

- Test new LWC components thoroughly
- Run full regression testing
- Train your team on LWC patterns
- Monitor performance improvements

**See Also**

- [Use the Aura-to-LWC Migration Tools](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-aura.md)

<!-- document id=a337f20481aaef22d480a23f86e9f1aa3fe9f3c40c41ca98698243a74abe2e35 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-js-mime.md -->

# MIME Types Permitted

Lightning Locker analyzes the MIME types used in Blob objects. Locker permits some MIME types, sanitizes some MIME types, and blocks the rest.

Lightning Locker allows these MIME types.

- `application/octet-stream` — Default value for binary files
- `application/json` — JSON format
- `application/pdf` — Portable Document Format (.pdf)
- `video/` — All `video/*` mime types
- `audio/` — All `audio/*` mime types
- `image/` — All `image/*` mime types
- `font/` — All `font/*` mime types
- `text/plain` — Text (.txt)
- `text/markdown` — Markdown (.md)
- `application/zip` — Zip archive (.zip)
- `application/x-bzip` — Bzip archive (.bz)
- `application/x-rar-compressed` — RAR archive (.rar)
- `application/x-tar` — Tape archive (.tar)

Locker sanitizes `text/html`, `image/svg+xml`, and `text/xml` MIME types. These types are permitted but Locker removes potentially malicious code.

Any other types are blocked with the error message `Unsupported MIME type`.

To send binary files that aren't explicitly permitted, specify the MIME type as `application/octet-stream`.

Lightning Locker doesn't support the specification of MIME type parameters.

**tip:** Lightning Web Security (LWS) requires you to specify the MIME type. See [Specify a MIME Type for Blob Objects in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-mime.md).

<!-- document id=7c2051cd0e439cfd7eff2a8bcc1421d6e3c2d70d88d6420fd4203f0bc40bacfd url=/developer/current/en-us/lwc/utam/guide/mobile-inspector.md -->

# Mobile Inspector

When you write a test for a native page of a Salesforce mobile hybrid application, it's often confusing to know which page objects (POs) to use. To make this page object selection process easier, use UTAM's mobile inspector. It presents you with the appropriate set of POs for the page that you're currently browsing, and identifies which page elements are affected by the methods in a selected PO.

## Workflow for Inspector

This section shows you how to use the inspector.

### Step 1: Download Page Object Artifact

The inspector reads UTAM POs contained in an artifact download from an artifact repository. An artifact is either a zip file (`.zip`, `.jar`) or a gzipped tar file (`.tar.gz`, `.tgz`).

**important:** The inspector doesn't automatically download these artifacts. Before you can use the browser extension, you must obtain an artifact as a prerequisite step.

Get UTAM POs from an artifact published to [NPM](https://www.npmjs.com/).

To get the artifact for JavaScript page objects, run this command from the command line:

```bash
npm pack salesforce-pageobjects
```

This command downloads a gzipped tar file of the artifact to the current directory.

For more information about the PO artifacts for Java and JavaScript, see [Downloads](https://developer.salesforce.com/docs/platform/utam/guide/test-sf-applications.md).

### Step 2: Install Inspector

Since the inspector is just a standard Appium Inspector with Salesforce-specific features built on top of it, you can use the Appium [installation instructions](https://github.com/appium/appium-inspector#installation) and launch it. Get the most recent published version of this app at the [Releases](https://github.com/salesforce/appium-inspector-salesforce/releases/) section of the repository.

### Step 3: Load Page Objects into the Inspector

After starting a new session with the test application, navigate to the UTAM Page Object Tree Tab.

![Inspector PageObject Window](https://developer.salesforce.com/docs/media/utam/utam-pageobject-window.png)

### Step 4: Identify Page Objects for a Native Page

To inspect the [Salesforce published Page Objects](https://www.npmjs.com/package/salesforce-pageobjects) that you’ve downloaded, you must configure the values for Page Object Module Name and Page Object Full Path. The module name for the [Salesforce mobile app](https://developer.salesforce.com/tools/mobile-debugging) is _SalesforceApp_, and for the [Mobile Publisher Playground Application](https://help.salesforce.com/s/articleView?id=sf.s1_branded_apps_playground_preview_exp_site.htm&type=5) is _playgroundapp_. The path is the full path of the unzipped package folder. For example, if you have a local package salesforce-pageobjects-2.0.0.tgz at: `${Home}/pageobjects`, after unzipping it, the full path value is `${Home}/pageobjects`.

To inspect the customer Page Object package, you only need to configure the full path of the direct parent folder of all page object json files. For example, if you have customer Page Objects under `${Home}/pageobjects/src/main/resources/spec`, the full path value is `${Home}/pageobjects/src/main/resources/spec`.

Now, you can start inspecting by clicking the **Start Inspect** button to find all the available Page Objects for the test device platform (iOS or Android) in the configured package.

![Inspect Result](https://developer.salesforce.com/docs/media/utam/inspecting-result.png)

Target a page or component by navigating the test application in your local simulator or emulator. Find out the UTAM Page Objects for the current page by clicking the **Find Current PO** button. Inspector finds all the matched root Page Object and children Page Objects. Moreover, it exposes all methods (both for Java and JavaScript) for a test script to interact with the elements on the page.

![Inspect Current Page](https://developer.salesforce.com/docs/media/utam/inspecting-current.png)

<!-- document id=67ef0e4f9891c348c44763a920f780fb7846e0e2b8d3a389b5dd35bb36bf5eb8 url=/developer/current/en-us/lwc/lwc/guides/create/mobile.md -->

# Mobile-Ready Components

Lightning Web Components supports using components on desktop and mobile devices. On desktop, a variety of web browsers are supported. On mobile, supported environments include Salesforce distributed mobile apps. The differences between these two environments is more than just the screen size. There are new limitations, and also extended capabilities on mobile. To build components that perform well across mobile experiences, follow our guidelines for mobile-ready components.

Complete details are available in the _[Mobile and Offline Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/),_ an essential companion to this guide when doing mobile development.

**See Also**

- [`lightning/mobileCapabilities` Module](https://developer.salesforce.com/docs/platform/lwc/reference/mobile-capabilities/reference-lightning-mobilecapabilities.md)
- [Create Mobile-Ready Components](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/ux.htm)
- [Use Mobile Device Features in Mobile Apps](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/capabilities.htm)

<!-- document id=8c1f96c29a70f9faececebd46d9e5769bfd48082aa2daff24200437ff15a021c url=/developer/current/en-us/lwc/lwc/guides/use/use-dialog-modal.md -->

# Modal Windows

Open a modal window in response to a user action, such as clicking a button or link. The modal blocks interaction with everything else on the page until the user acts upon or dismisses the modal.

The `lightning/modal` module provides the `LightningModal` component to create a modal window that overlays the current window.

`LightningModal` implements the [SLDS modals blueprint](https://www.lightningdesignsystem.com/components/modals/).

Unlike most base components, when you use this component you don’t add a `<lightning-modal>` tag to your component template or extend `LightningElement`. There is no `lightning-modal` component. Instead, you create a modal by extending `LightningModal`.

The `LightningModal` component provides helper components for specifying the modal content. Use the required `lightning-modal-body` component to provide the main content displayed in the modal. Use the optional `lightning-modal-header` component to add a title to the top of the modal, and the optional `lightning-modal-footer` component to add a footer to the bottom.

## Create a Modal

To create a modal component, import `LightningModal` from `lightning/modal`. Don’t import from `LightningElement`.The component has access to the normal LWC resources as well as the special container, helper components, methods, and events of the `lightning/modal` module.

Let’s create a simple modal called `myModal` that looks like this.

![The modal dialog myModal](https://developer.salesforce.com/media/use_dialog_modal_mymodal.png '{"class": "image-xl", "title": "myModal component"}')

Here’s the JavaScript for `myModal`. It imports only `api`, not `LightningElement`, from `lwc`. Instead, it imports `LightningModal` and extends `LightningModal` to its own class. It defines an `options` array to accept content that’s provided when the modal is opened by another component. The `handleOptionClick` function handles button clicks in the modal. When the user clicks the Option 1 or Option 2 button, `this.close(id)` returns the option that they chose and the modal closes.

```javascript
/* c/myModal.js */

import { api } from "lwc";
import LightningModal from "lightning/modal";

export default class MyModal extends LightningModal {
  // Data is passed to apis via .open({ options: [] })
  @api options = [];

  handleOptionClick(e) {
    const { target } = e;
    const { id } = target.dataset;
    // this.close() triggers closing the modal
    // the value of `id` is passed as the result
    this.close(id);
  }
}
```

Here’s the `myModal.html` template, which includes a header and the modal body.

<!-- prettier-ignore -->
```html
<!-- c/myModal.html -->
<template>
  <lightning-modal-header label="My Modal Heading"></lightning-modal-header>
  <lightning-modal-body>
    Let's make some buttons! <br />
    <template for:each={options} for:item="option">
      <lightning-button
        onclick={handleOptionClick}
        data-id={option.id}
        key={option.id}
        label={option.label}
      >
      </lightning-button>
    </template>
  </lightning-modal-body>
</template>
```

## Open a Modal Window

Here’s a component `myApp` that opens the `myModal` component when you click the **Open My Modal** button. It displays the result returned when the modal’s Option 1 or Option 2 buttons are clicked.

![myApp Component](https://developer.salesforce.com/media/use_dialog_modal_myapp.png '{"class": "image-sm", "title": "myApp component"}')

Here’s the `myApp` template.

<!-- prettier-ignore -->
```html
<!-- c/myApp.html -->
<template>
  <lightning-button 
      onclick={handleOpenClick} 
      aria-haspopup="dialog" 
      label="Open My Modal">
  </lightning-button>
  <p>Result: {result}</p>
</template>
```

The component `myApp.js` imports `MyModal` from the `myModal` component. The button handler opens the `myModal` component using the component’s `open` method and provides data to be used in the modal’s `options` property.

```javascript
/* c/myApp.js */

import { LightningElement } from "lwc";
import MyModal from "c/myModal";

export default class MyApp extends LightningElement {
  result;
  async handleOpenClick() {
    this.result = await MyModal.open({
      // maps to developer-created `@api options`
      options: [
        { id: 1, label: "Option 1" },
        { id: 2, label: "Option 2" },
      ],
    });
    console.log(this.result);
  }
}
```

The `result` value is returned from `MyModal` and displayed by the `myApp` component.

For more details about using `LightningModal`, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal).

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has `miscModal` and `myModal` components that demonstrate the use of `LightningModal`.

**See Also**

- [Component Reference: `lightning-modal-body`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-body)
- [Component Reference: `lightning-modal-header`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-header)
- [Component Reference: `lightning-modal-footer`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-footer)

<!-- document id=db3d71884d0fc13fdc18af9427e575f3b44fe7acd1e6823c567a7082d9bee72b url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-modal.md -->

# Navigate From a Modal

Open a modal that overlays the current window in response to a user action, such as a button click. Your custom modal component extends the `LightningModal` class and can contain a child component that triggers the navigation.

To navigate from the modal, use the `NavigationMixin` function in the `lighting/navigation` module and pass in a `PageReference` object. Use `NavigationMixin` only with a Lightning web component that extends `LightningElement`.

**note:** You can't use the `NavigationMixin` function directly in a custom component that extends `LightningModal`.

Let's say you have three components - a parent component, a modal component that's opened by the parent component, and a child component that is nested in the modal component. Define your `PageReference` object in the child component, and pass in the object via an event to `Modal.open()`. You can then handle the event in the parent component, which opens the modal and calls the `NavigationMixin` function to navigate.

## Dispatch an Event with the `PageReference` Object

A modal can contain a child component that triggers the navigation. This example creates a component that contains a button, which dispatches an event when clicked.

<!-- prettier-ignore -->
```html
<!-- navToHome.html -->
<template>
    <lightning-card title="NavToHome" icon-name="custom:custom96">
        <lightning-button
            label="Go to Record Home"
            class="slds-var-m-around_medium"
            onclick={navigateToHome}
        ></lightning-button>
    </lightning-card>
</template>
```

In the JavaScript file, define the `PageReference` object and dispatch a custom event with this object. This example navigates to the record home page using the `standard__namedPage` page type.

```javascript
// navToHome.js
import { LightningElement } from "lwc";

export default class NavToHome extends LightningElement {
  navigateToHome() {
    const pageRef = {
      type: "standard__namedPage",
      attributes: {
        pageName: "home",
      },
    };

    const evt = new CustomEvent("navigate", {
      bubbles: true,
      composed: true,
      detail: pageRef,
    });
    this.dispatchEvent(evt);
  }
}
```

You can then use this `navToHome` child component in a modal component `myModal` that extends `LightningModal`. This example uses the modal base components to create a user interface for the modal.
The modal base components are:

- [`lightning-modal-body`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-body)
- [`lightning-modal-header`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-header)
- [`lightning-modal-footer`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal-footer)

<!-- prettier-ignore -->
```html
<!-- myModal.html -->
<template>
    <lightning-modal-header label="Navigate from a Modal Example" ></lightning-modal-header>
    <lightning-modal-body>
        Modal content here
        <c-nav-to-home onnavigate={handleClose}></c-nav-to-home>
    </lightning-modal-body>
    <lightning-modal-footer>
        <lightning-button
            label="Close"
            onclick={handleClose}
        ></lightning-button>
    </lightning-modal-footer>
</template>
```

Your JavaScript file extends the `LightningModal` component and closes the modal when you navigate away from the modal.

```javascript
import { api } from "lwc";
import LightningModal from "lightning/modal";

export default class MyModal extends LightningModal {
  @api header;
  @api content;

  handleClose() {
    console.log("myModal onnavigate");
    this.close("return value");
  }
}
```

## Handle the Event and Navigate

The parent component opens the modal and handles the navigation. This example shows a component that contains a button, which opens the modal when clicked.

<!-- prettier-ignore -->
```html
<!-- openModal.html -->
<template>
    <lightning-card title="MiscModal" icon-name="custom:custom19">
        <div class="slds-var-m-around_medium">
            <lightning-button
                onclick={handleShowModal}
                aria-haspopup="true"
                label="Show modal"
            >
            </lightning-button>
        </div>
    </lightning-card>
</template>
```

In the JavaScript file, handle the custom `onnavigate` event and call `NavigationMixin` to navigate to the record home.

```javascript
import { LightningElement } from "lwc";
import MyModal from "c/myModal";
import { NavigationMixin } from "lightning/navigation";

export default class MiscModal extends NavigationMixin(LightningElement) {
  content = "The modal content";
  header = "The modal header";

  handleHeaderChange(event) {
    this.header = event.target.value;
  }

  handleContentChange(event) {
    this.content = event.target.value;
  }

  async handleShowModal() {
    this.result = await MyModal.open({
      size: "small",
      description: "MiscModal displays the message in a popup",
      header: this.header,
      content: this.content,
      onnavigate: (e) => {
        this[NavigationMixin.Navigate](e.detail);
      },
    });
  }
}
```

**tip:** This example is adapted from the [miscModal](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscModal) component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

**See Also**

- [Component Reference: lightning/modal](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-modal)
- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md)
- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/events/events-create-dispatch.md)

<!-- document id=8bfe9e057b753484e81b104b8a969a9e3d0ecd087f5e7144d501b6b022811c10 url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-default.md -->

# Navigate to a Record’s Create Page with Default Field Values

To launch a record’s create page with prepopulated field values, use `lightning/pageReferenceUtils` and `lightning/navigation` together.

The [`lightning/pageReferenceUtils`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-page-reference-utils) module provides the `encodeDefaultFieldValues()` and `decodeDefaultFieldValues()` functions, which encode default field values into a string and decode them. Assign an encoded string to the `pageReference.state.defaultFieldValues` attribute in a `standard__objectPage` page reference.

With standard actions, the default field values pass through the URL to the object as a string, and the redirect and replace is handled for you. With override actions, you are responsible for decoding the string of default field values from the URL.

**tip:** In the lwc-recipes sample repo, see the [`navToNewRecordWithDefaults`](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/navToNewRecordWithDefaults) component.

**note:** If you’re launching a flow from a Quick Action in a Salesforce Console app, and the flow contains a custom LWC that navigates to a record create page with default values, those default values are sometimes not saved.

## Launch a Contact Record with Default Field Values Using a Standard Action

This example launches a record’s create page with prepopulated default values.

This example HTML includes the link to create a contact.

<!-- prettier-ignore -->
```html
<!-- navToNewRecordWithDefaults.html -->
<template>
  <lightning-button
    name="new-with-defaults"
    label="Go to New Contact with Defaults"
    class="slds-m-around_medium"
    onclick={navigateToNewContactWithDefaults}>
  </lightning-button>
</template>
```

To encode the default field values into a string, pass them to `encodeDefaultFieldValues()`. Assign the encoded string to the `state.defaultFieldValues` property in the page reference.

```javascript
// navToNewRecordWithDefaults.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";

export default class NavToNewRecordWithDefaults extends NavigationMixin(LightningElement) {
  navigateToNewContactWithDefaults() {
    const defaultValues = encodeDefaultFieldValues({
      FirstName: "Morag",
      LastName: "de Fault",
      LeadSource: "Other",
    });

    console.log(defaultValues);

    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Contact",
        actionName: "new",
      },
      state: {
        defaultFieldValues: defaultValues,
      },
    });
  }
}
```

## Send Dynamic Fields and Values

To dynamically create or modify your default values before passing them to the `Navigate` function, specify the values in `connectedCallback()`.

Here's how you can update the previous example to send several dynamic fields and values.

```javascript
//navToNewRecordWithDynamicValues.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";

export default class NavToNewRecordWithDynamicValues extends NavigationMixin(LightningElement) {
  // An object that stores default values for the sObject
  obj = {
    FirstName: "Morag",
    LastName: "de Fault",
  };

  companyName = "Demo";
  newFieldName = "Company";

  connectedCallback() {
    // Dynamically adding a static field name and value
    this.obj.LeadSource = "Other";
    this.obj.LastName = "Some other name";

    // Dynamically adding a dynamic field name and value
    this.obj[this.newFieldName] = this.companyName;
  }

  navigateToNewContactWithDefaults() {
    const defaultValues = encodeDefaultFieldValues(this.obj);
  }
}
```

## Handle Default Field Values Using an Override Action

To override standard action behavior with a custom solution, wrap your module inside an Aura component.

<!-- prettier-ignore -->
```html
// auraOverrideWrapper.cmp
<aura:component implements="lightning:actionOverride">
  <c:lwcNewAccountOverride></c:lwcNewAccountOverride>
</aura:component>
```

The `lwcNewAccountOverride` component includes a form for a new account record page that displays default field values.

<!-- prettier-ignore -->
```html
<!-- lwcNewAccountOverride.html -->
<template>
  <lightning-record-edit-form object-api-name="Account" onsuccess={handleAccountCreated}>
    <lightning-input-field field-name="Name" value={dfv_AccountName}> </lightning-input-field>
    <lightning-input-field field-name="NumberOfEmployees" value={dfv_NumberOfEmployees}>
    </lightning-input-field>
    <lightning-input-field field-name="OwnerId" value={dfv_OwnerId}> </lightning-input-field>
    <lightning-input-field field-name="CustomCheckbox__c" value={dfv_CustomCheckbox}>
    </lightning-input-field>

    <lightning-button class="slds-m-top_small" type="submit" label="Create"> </lightning-button>
  </lightning-record-edit-form>
</template>
```

With override actions, you are responsible for decoding the string of default field values from the URL.

This example uses `CurrentPageReference` to read the default field values from `state` and get the encoded string. It then passes the string to `decodeDefaultFieldValues()` to decode it and handle the account creation.

This example is similar to prepopulating field values using `lightning-record-edit-form`, except that here the `defaultFieldValues` are dynamically generated when navigating to the form.

To perform an override with `currentPageReference.state.defaultFieldValues`, encode the string with `encodeDefaultFieldValues()` in the same component, such as from `connectedCallback()`. See the previous sections for examples on encoding the string.

```javascript
// lwcNewAccountOverride.js
import { LightningElement, wire } from "lwc";
import { CurrentPageReference } from "lightning/navigation";
import { decodeDefaultFieldValues } from "lightning/pageReferenceUtils";

export default class LwcNewAccountOverride extends LightningElement {
  @wire(CurrentPageReference)
  setCurrentPageReference(currentPageReference) {
    // defaultFieldValues must correspond to an encoded string
    if (currentPageReference.state.defaultFieldValues) {
      const dfvObject = decodeDefaultFieldValues(currentPageReference.state.defaultFieldValues);
      this.dfv_AccountName = dfvObject.Name;
      this.dfv_NumberOfEmployees = dfvObject.NumberOfEmployees;
      // Handling required for boolean because we don't support boolean field types
      this.dfv_CustomCheckbox = dfvObject.CustomCheckbox__c === "true";
      this.dfv_OwnerId = dfvObject.OwnerId;
    }
  }

  dfv_AccountName = "";
  dfv_NumberOfEmployees = "";
  dfv_OwnerId = "";
  dfv_CustomCheckbox = false;

  // Run code when account is created
  handleAccountCreated() {}
}
```

**important:** All encoded default field values are passed to the record create page as strings. For example, `35000` is passed into the page as a string instead of a number, and the Boolean values `true` and `false` are passed as strings.

To use this code, from Setup, enter `Object Manager`. On the Account object, create a checkbox field with the API name `CustomCheckbox__c`. Then select **Buttons, Links, and Actions** and edit the **New** action. For **Lightning Experience Override**, select **Lightning component** and select the `c:auraOverrideWrapper` component.

**See Also**

- [Component Reference: lightning-page-reference-utils](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-page-reference-utils/)

<!-- document id=bda389dcd64d1cbdc8856cc9d29e5204593647c63b0d8d139233479d7240f90c url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-url-addressable.md -->

# Navigate to a URL-Addressable Component

You can navigate to a component that defines the `lightning__UrlAddressable` target in the component's `.js-meta.xml` configuration file. `lightning__UrlAddressable` is supported only in Lightning Experience and the Salesforce mobile app. It's also supported in custom apps, such as in a Lightning console app. This target isn't supported in Experience Builder sites, since it interferes with custom domain and CDN support.

To make the component available for navigation, set the `<isExposed>` tag to true. The `<apiVersion>` tag has no impact on the `lightning__UrlAddressable` target and can be set to an earlier version.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>61.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__UrlAddressable</target>
    </targets>
</LightningComponentBundle>
```

To navigate to the component, use the `standard__component` page reference type. Include the required `attributes` and optional `state` objects.

```javascript
this[NavigationMixin.Navigate]({
  type: "standard__component",
  attributes: {
    componentName: "c__MyComponent",
  },
  state: {
    c__optionalState: "stateValue",
  },
});
```

The `standard__component` page reference type has the `componentName` attribute that takes in a component name in the format `namespace__componentName`.

You can pass any key and value in the `state` object. The key must include a namespace, and the value must be a string. If you don’t have a registered namespace, add the default namespace of `c__`, like with `c__MyComponent`.

## Pass State Information to a Component

A component with the `lightning__UrlAddressable` target has a URL with the format `/lightning/cmp/c__MyComponent?c__mystate=value`. You can pass a property value to your URL-addressable component when navigating like this.

```javascript
// navToComponentWithState.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class NavToComponentWithState extends NavigationMixin(LightningElement) {
  navigateToComponent() {
    this[NavigationMixin.Navigate]({
      // Pass in pageReference
      type: "standard__component",
      attributes: {
        componentName: "c__myComponent",
      },
      state: {
        c__propertyValue: "2000",
      },
    });
  }
}
```

In your URL-addressable component, `myComponent`, use a getter to return the property value from the `state` object.

```javascript
// myComponent.js
import { LightningElement, wire, api } from "lwc";
import { CurrentPageReference } from "lightning/navigation";

export default class MyComponent extends LightningElement {
  @wire(CurrentPageReference)
  currentPageRef;

  @api propertyValue;

  get propertyValue() {
    return this.currentPageRef.state.c__propertyValue;
  }
}
```

## Example: Navigate to a Component From an App Page

This example shows a component `navToComponent` with a button that opens a URL-addressable component. Its `.js-meta.xml` configuration file includes the `lightning__AppPage` target only. It assumes that you've added the `navToComponent` component to an app page using Lightning App Builder.

<!--prettier-ignore-->
```html
<!-- navToComponent.html -->
<template>
  <lightning-button
  label="Go to Component"
  class="slds-var-m-around_medium"
  onclick={navigateToComponent}
  ></lightning-button>
</template>
```

The component's JavaScript passes in a page reference to the [`[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference, [replace])` method](use-navigate-basic.md) using the `standard__component` type.

```javascript
// navToComponent.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class NavToComponent extends NavigationMixin(LightningElement) {
  navigateToComponent() {
    this[NavigationMixin.Navigate]({
      // Pass in pageReference
      type: "standard__component",
      attributes: {
        componentName: "c__myComponent",
      },
    });
  }
}
```

## Example: Navigate to a Component in a Lightning Console App

This example shows a component `workspaceOpenTab` with a button that opens a URL-addressable component in a new workspace tab. Its `.js-meta.xml` configuration file includes the `lightning__AppPage` target only. It assumes that you've added the `workspaceOpenTab` component to a Lightning console app.

<!--prettier-ignore-->
```html
<!-- workspaceOpenTab.html -->
<template>
  <div class="slds-m-around_medium">
      <lightning-button label="Open Tab" onclick={handleOpen}>
      </lightning-button>
  </div>
</template>
```

The component's JavaScript calls the [`openTab()` method](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_opentab.htm) from `lightning/platformWorkspaceApi`.

```javascript
// workspaceOpenTab.js
import { LightningElement, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { IsConsoleNavigation, openTab } from "lightning/platformWorkspaceApi";

export default class WorkspaceOpenTab extends NavigationMixin(LightningElement) {
  @wire(IsConsoleNavigation) isConsoleNavigation;

  async handleOpen() {
    if (!this.isConsoleNavigation) {
      return;
    }
    try {
      await openTab({
        pageReference: {
          type: "standard__component",
          attributes: {
            componentName: "c__myComponent",
          },
          state: {
            c__stateKey: "stateValue",
          },
        },
        icon: "utility:sparkles",
        label: "My Component",
      });
    } catch (error) {
      // handle error
    }
  }
}
```

`myComponent` displays the URL and page reference information that's defined by the `workspaceOpenTab` component. The `myComponent.js-meta.xml` configuration file includes the `lightning__UrlAddressable` target.

```html
<!-- myComponent.html -->
<template>
  <div class="slds-var-m-around_medium">
    <p>Component URL: {connectedCallbackUrl}</p>
    <p>Current page reference:</p>
    <pre><code>{currentPageRefFormatted}</code></pre>
  </div>
</template>
```

The component's JavaScript uses the `CurrentPageReference` wire adapter to return page reference information. In this example, the URL returns `https://MyDomainName.my.salesforce.com/lightning/cmp/c__myComponent?c__mystate=value&uid=_uniqueId_`.

```javascript
// myComponent.js
import { LightningElement, wire } from "lwc";
import { CurrentPageReference } from "lightning/navigation";

export default class MyComponent extends LightningElement {
  @wire(CurrentPageReference)
  currentPageRef;

  connectedCallbackUrl;

  connectedCallback() {
    this.connectedCallbackUrl = window.location.href;
  }

  get currentPageRefFormatted() {
    return JSON.stringify(this.currentPageRef, undefined, 2);
  }
}
```

In a Lightning console app, navigating to a component displays the component in a new tab. To prevent the app from opening a new tab if the tab with the component is already opened, pass in a `uid` value to the `state` object.

```javascript
this[NavigationMixin.Navigate]({
  type: "standard__component",
  attributes: {
    componentName: "c__MyComponent",
  },
  state: {
    c__mystate: "value",
    uid: "1",
  },
});
```

**See Also**

- [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-page-types.md)
- [_Salesforce Console Developer Guide_: Methods for Workspace Tabs and Subtabs in Lightning Experience](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_lightning_workspaceAPI.htm)

<!-- document id=fcb7f02bdad4f441ab552f0dba5f4e7e1441a6917169e470d8c58c83c7dfdb75 url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-page-types.md -->

# Navigate to Different Page Types

The navigation service supports different kinds of pages in Lightning. Each `PageReference` type supports a different set of attributes and state properties. Both APIs support these `PageReference` types.

## Example: Navigate to a Page

Let’s look at an example of how to create a button that navigates to a page.

Our sample has a `welcome` component, which is a page in a Salesforce app. At the bottom of the page, there’s a `navtab` component with the label **Next**. The `navtab` component can be used at the bottom of each page to let the user navigate through the app.

<!-- prettier-ignore -->
```html
<!-- welcome.html -->
<!-- lots and lots of code removed for brevity -->

<div class="slds-m-vertical_large">
  <c-navtab tab-name="lightning_components" label="Next"></c-navtab>
</div>
```

The `c-nav-tab` component customizes the `lightning-button` component to navigate to the next page in the app. The consumer specifies a `tab-name` and a `label`.

<!-- prettier-ignore -->
```html
<!-- navTab.html -->
<template>
  <lightning-button variant="brand" label={label} title={label} onclick={navigateNext}>
  </lightning-button>
</template>
```

```javascript
// navTab.js
import { LightningElement, api } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class Navtab extends NavigationMixin(LightningElement) {
  @api tabName;
  @api label;
  navigateNext() {
    this[NavigationMixin.Navigate]({
      type: "standard__navItemPage",
      attributes: {
        apiName: this.tabName,
      },
    });
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has lots of navigation examples. Check out the components named `nav*`.

## More Page Type Examples

This code shows examples of navigating to different [types of pages](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md) in Lightning. These examples show how to create page reference objects of different types and navigate to those pages. You can also pass page references to the `[NavigationMixin.GenerateUrl](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference)` API to retrieve a `promise` that resolves to a URL for the page.

```javascript
// navigationToPagesExample.js
import { LightningElement, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class NavigationToPagesExample extends NavigationMixin(LightningElement) {
  navigateToObjectHome() {
    // Navigate to the Case object home page.
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Case",
        actionName: "home",
      },
    });
  }

  navigateToListView() {
    // Navigate to the Contact object's Recent list view.
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Contact",
        actionName: "list",
      },
      state: {
        // 'filterName' is a property on the page 'state'
        // and identifies the target list view.
        // It may also be an 18 character list view id.
        filterName: "Recent", // or by 18 char '00BT0000002TONQMA4'
      },
    });
  }

  navigateToNewRecordPage() {
    // Opens the new Account record modal
    // to create an Account.
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Account",
        actionName: "new",
      },
    });
  }

  navigateToRecordViewPage() {
    // View a custom object record.
    this[NavigationMixin.Navigate]({
      type: "standard__recordPage",
      attributes: {
        recordId: "a03B0000002tEurIAE",
        objectApiName: "namespace__ObjectName", // objectApiName is optional
        actionName: "view",
      },
    });
  }

  navigateToRecordEditPage() {
    // Opens the Account record modal
    // to view a particular record.
    this[NavigationMixin.Navigate]({
      type: "standard__recordPage",
      attributes: {
        recordId: "001B000000ZBz22IAD",
        objectApiName: "Account", // objectApiName is optional
        actionName: "edit",
      },
    });
  }

  navigateToRelatedList() {
    // Navigate to the CaseComments related list page
    // for a specific Case record.
    this[NavigationMixin.Navigate]({
      type: "standard__recordRelationshipPage",
      attributes: {
        recordId: "500xx000000Ykt4AAC",
        objectApiName: "Case",
        relationshipApiName: "CaseComments",
        actionName: "view",
      },
    });
  }

  navigateToTabPage() {
    // Navigate to a specific CustomTab.
    this[NavigationMixin.Navigate]({
      type: "standard__navItemPage",
      attributes: {
        // CustomTabs from managed packages are identified by their
        // namespace prefix followed by two underscores followed by the
        // developer name. E.g. 'namespace__TabName'
        apiName: "CustomTabName",
      },
    });
  }

  navigateToWebPage() {
    // Navigate to a URL
    this[NavigationMixin.Navigate](
      {
        type: "standard__webPage",
        attributes: {
          url: "http://salesforce.com",
        },
      },
      true, // Replaces the current page in your browser history with the URL
    );
  }
}
```

**See Also**

- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md)
- [Navigate to a URL-Addressable Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-url-addressable.md)

<!-- document id=ac978075d0ccad9f81747f17783e05cd0bf1ad088e049f05916a241f3eb6bce3 url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate.md -->

# Navigate to Pages, Records, and Lists

To navigate in Lightning Experience, Experience Builder sites, and the Salesforce mobile app, use the navigation service, `lightning/navigation`.

[The `lightning/navigation` service](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-basic.md) is supported only in Lightning Experience, Experience Builder sites, and the Salesforce mobile app. It isn’t supported in other containers, such as Lightning Components for Visualforce, or Lightning Out 2.0 and Lightning Out (beta). This is true even if you access these containers inside Lightning Experience or the Salesforce mobile app.

To generate a URL for a component so you can navigate directly to it, use [the `lightning__UrlAddressable` target](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-url-addressable.md) on your component. This target is supported only in Lightning Experience and the Salesforce mobile app. It's also supported in custom apps, such as in a Lightning console app. This target isn't supported in Experience Builder sites, since it interferes with custom domain and CDN support.

To handle navigation in a Lightning Web Runtime (LWR) app, use the `lwr/navigation` module instead. For more information, see [Client-Side Routing in LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-client-overview.html).

**See Also**

- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md)
- [Component Reference: lightning-navigation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation)
- [Test the Navigation Service](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md#test-the-navigation-service)

<!-- document id=216163099d9bb141ec82b12dbaae2a710a40da646d8e2427cb4d02666ebe728e url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-example-nested.md -->

# Nested State Manager Example

This more complex state manager illustrates the use of nested state managers. In this case, the nested state managers are provided by the Salesforce platform. (Documentation for these built-in state managers is forthcoming.)

This example is excerpted from the `platform-state-managers` example in [State Management Examples](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-examples.md). The code is the same, but the comments are a bit more detailed.

```javascript
import { defineState } from "@lwc/state";
import smRecord from "lightning/stateManagerRecord";
import smLayout from "lightning/stateManagerLayout";

/**
 * Extracts the fields referenced by a layout.
 *
 * @param {*} layout layout definition
 * @returns fields referenced by the layout, as a string[]
 */
function extractFields(layout) {
  if (!layout) {
    return;
  }

  const fields = [];

  for (const section of layout.sections) {
    for (const row of section.layoutRows) {
      for (const item of row.layoutItems) {
        for (const component of item.layoutComponents) {
          if (component.componentType === "Field") {
            fields.push(`${layout.objectApiName}.${component.apiName}`);
          }
        }
      }
    }
  }

  return fields;
}

// Define the state manager
export default defineState(({ atom, computed, setAtom }, recordId, objectApiName) => {
    // This atom captures the current configuration of the state manager instance.
    // We wrap it in an atom to make it easier for other data to react to changes
    // in the config. It is NOT exposed as one of the properties of this state
    // manager.
    const config = atom({ recordId, objectApiName });

    // Actions to set or change the config
    const setRecordId = (recordId) =>
      setAtom(config, { recordId, objectApiName: config.value.objectApiName });
    const setObjectApiName = (objectApiName) =>
      setAtom(config, { recordId: config.value.recordId, objectApiName });

    // The following constructs implement a data waterfall that corresponds roughly
    // to what happens in a layout-driven detail panel like you see on record home.
    // (The real detail panel is FAR more complex; this is a VERY simplified version
    // of the data logic from that component.)
    //
    // 1. The `recordId` and `objectApiName` supplied as config to this state manager are
    //    used to retrieve a minimal copy of the record so that we can find its
    //    `recordTypeId`.
    // 2. The `objectApiName` and `recordTypeId` from (1) are used to retrieve the layout
    //    that should be used for the record.
    // 3. The `recordId`, `objectApiName`, and fields referenced in the layout are used
    //    to retrieve a complete copy of the record that can be displayed.

    // `initialRecord` is a nested state manager that is used to retrieve a minimal copy
    // of the record (step 1 above). `computed()` is used here so that the configuration
    // for `smRecord` will automatically be updated anytime the config changes.
    const initialRecord = smRecord(
      computed([config], ({ recordId, objectApiName } = {}) => {
        // If the state manager does not yet have a `recordId` or `objectApiName` then
        // pass an empty config to `smRecord`; the empty config will cause `smRecord` to wait.
        if (!recordId || !objectApiName) {
          return {};
        }

        // Once we have `recordId` and `objectApiName`, tell `smRecord` to get the record.
        // The `Id` field is requested here because we have to specify at least one field.
        // The data we really want (the `recordTypeId`) is included by default.
        return {
          recordId,
          fields: [`${objectApiName}.Id`],
        };
      }),
    );

    // `layout` is another nested state manager that we use to retrieve the layout. Its inputs
    // are derived from the output of `initialRecord`, so `computed()` is used to update
    // the config every time `initialRecord` changes.
    const layout = smLayout(
      computed([initialRecord], ({ data: recordData }) => {
        // If `initialRecord` has not retrieved the record yet then return an empty config
        // so `smLayout` will wait.
        if (!recordData) {
          return {};
        }

        // Once `initialRecord` has data available, use its `apiName` and `recordTypeId` to ask
        // for the Compact View layout.
        return {
          objectApiName: recordData.apiName,
          recordTypeId: recordData.recordTypeId,
          layoutType: "Compact",
          mode: "View",
        };
      }),
    );

    // `finalRecord` is used to retrieve the full set of field values that the layout needs.
    // `computed()` is used here so that the config for this second `smRecord` will be re-evaluated
    // whenever `initialRecord` or `layout` changes.
    const finalRecord = smRecord(
      computed([initialRecord, layout], ({ data: recordData }, { data: layoutData }) => {
        // Tell `smRecord` to wait if we don't have the necessary information yet.
        if (!recordData || !layoutData) {
          return {};
        }

        // Once we have all the information, ask for all the layout's fields for the
        // record.
        return {
          recordId: recordData.id,
          fields: extractFields(layoutData),
        };
      }),
    );

    // `data` is a just a more consumable form of the field values in `finalRecord`.
    // As such, we want to update it every time `finalRecord` changes.
    const data = computed([finalRecord], ({ data: recordData }) => {
      if (!recordData) {
        return;
      }

      const fieldValues = {};
      for (const [field, value] of Object.entries(recordData.fields)) {
        fieldValues[field] = value.displayValue || value.value;
      }

      return fieldValues;
    });

    // `error` is an aggregation of errors from `initialRecord`, `layout`, and `finalRecord`.
    const error = computed(
      [initialRecord, layout, finalRecord],
      ({ error: initialRecordError }, { error: layoutError }, { error: finalRecordError }) =>
        initialRecordError || layoutError || finalRecordError,
    );

    // `status` lets consumers of this state manager understand what's going on.
    const status = computed(
      [initialRecord, layout, finalRecord],
      (
        { status: initialRecordStatus },
        { status: layoutStatus },
        { status: finalRecordStatus },
      ) => {
        // We configure `initialRecord` as soon as this state manager is configured, so we
        // can assume its "unconfigured" status means that this state manager is also
        // unconfigured.
        if (initialRecordStatus === "unconfigured") {
          return "unconfigured";
        }
        // any errors => error
        else if (
          initialRecordStatus === "error" ||
          layoutStatus === "error" ||
          finalRecordStatus === "error"
        ) {
          return "error";
        }
        // everything loaded => loaded
        else if (
          initialRecordStatus === "loaded" &&
          layoutStatus === "loaded" &&
          finalRecordStatus === "loaded"
        ) {
          return "loaded";
        }
        // other status combinations mean something is still loading
        else {
          return "loading";
        }
      },
    );

    // This is the external shape that consumers of this state manager will see.
    return {
      // Data properties
      data,
      error,
      status,

      // Actions
      setObjectApiName,
      setRecordId,
    };
  };
);
```

<!-- document id=1af1cf87ff56c63f61e73df1dc6e041635e24aba3d5b95cc29c75a28a00cbfde url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice.md -->

# NFCService API

Interact with NFC tags from a Lightning web component.

The **Syntax** sections in the following topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this.

```javascript
createRecord(recordInput: Record): Promise<Record>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

**note:** [TypeScript support](/docs/platform/lwc/guide/ts.html) is in developer preview. We're working on adding type definitions for components and modules in the `lightning` namespace.


For more information about how NFCService works, see [Interact with NFC Tags on a Mobile Device](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_nfcservice.htm).

<!-- document id=f01bf5361c5c6d34c2fc23043eb3045e22bd37e04f0e7b3ac3db02cd80cd596c url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-data-types.md -->

# NFCService Data Types

NFCService defines and uses several data types.

## NFCMessage

An object returned by an NFC `read()` operation.

| Property Name     | Type                 | Description                                                                                                   | Example                                                                     |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `totalByteLength` | Number               | The size, in number of bytes, of the data received by the `read()` operation.                                | 256                                                                         |
| `records`         | `NFCMessageRecord[]` | An array containing a single `NFCMessageRecord` object, which in turn contains the payload from the NFC tag. | `[NFCMessageRecord]`                                                        |
| `tagInfo`         | `NFCTagInfo`         | The metadata about the tag. See [`NFCTagInfo`](#nfctaginfo).                                                  | `{ serialNumber: "04:EE:A0:5A", isNdefWritable: false, ndefCapacity: 512 }` |

## NFCTagInfo

An object within an `NFCMessage` object, containing the metadata read from an NFC tag.

| Property Name    | Type    | Description                                                                                                                                          | Example       |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `serialNumber`   | String  | The serial number of the tag.                                                                                                                       | "04:EE:A0:5A" |
| `isNdefWritable` | Boolean | For a tag that can contain NDEF data, indicates whether the tag’s NDEF data can be overwritten. If the tag doesn’t support NDEF, this value is null. | false         |
| `ndefCapacity`   | Number  | The maximum NDEF message size, in bytes, that the tag can hold. If the tag doesn’t support NDEF, this value is null.                                 | 512           |

## NFCMessageRecord

An object within an `NFCMessage` object, containing the payload read from an NFC tag.

| Property Name | Type        | Description                                                                                                                                                                                                                           | Example |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `parsed`      | `NFCRecord` | Contains the parsed values of the raw data read from the NFC tag. The parsing operation only occurs if the value of the `typeNameFormat` property on the `NFCRecord` object is "WELLKNOWN". Otherwise, this property’s value is null. |         |
| `raw`         | `NFCRecord` | Contains the raw base64 data string read from the NFC tag.                                                                                                                                                                            |         |

## NFCRecord

An object containing one record of data from an NFC tag scan.

| Property Name    | Type             | Description                                                                                                                           | Example                                                                                                      |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `typeNameFormat` | `TypeNameFormat` | The Type Name Format field of the payload, as defined by the NDEF specification.                                                      | "WELLKNOWN" See [TypeNameFormat](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-constants.md) for a list of possible values. |
| `type`           | String           | The type of the payload, as defined by the NDEF specification.                                                                        | "T" (when payload is of type text); "U" (when payload is of type URI)                                        |
| `identifier`     | String           | The identifier of the payload, as defined by the NDEF specification, or an empty string if no identifier data was present in the tag. |                                                                                                              |
| `payload`        | String           | The content of the record, encoded in base64 format.                                                                                  | "V2XigJlyZSBTYWxlc2ZvcmNlLCBG9tZXIgY29tcGFueS4"                                                              |

## TextPayload

An object containing raw text input, to be converted into an `NFCRecord`.

| Property Name | Type   | Description                                                                                          | Example                                   |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `text`        | String | The raw text payload to be converted.                                                                | "We’re Salesforce, the customer company." |
| `langId`      | String | The [ISO 639-1](https://quickref.me/iso-639-1.html#list-of-iso-639-1-codes) language ID of the text. | "en"                                      |

## NFCServiceOptions

An object containing configuration details for an NFC interaction.

| Property Name     | Type    | Description                                                                                                                                                                                                                                                                                                                                                                 | Example                                 |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `instructionText` | String  | Optional. Provides instructions to display in the user interface. Defaults to no text.                                                                                                                                                                                                                                                                                      | "Hold your phone near the tag to read." |
| `successText`     | String  | Optional. Provides a message to display in the user interface when an NFC operation is successfully completed. Defaults to no text.                                                                                                                                                                                                                                          | "Tag read successfully!"                |
| `allowEmptyTags`  | Boolean | Optional. Indicates whether reading from an empty tag is considered an error. Defaults to `false`, so attempting to read an empty tag returns a `TAG_EMPTY` error. To get the tag metadata even for empty tags, set this property to `true`. The `read()` operation then returns an `NFCMessage` object whose `tagInfo` property is populated instead of a `TAG_EMPTY` error. | true                                    |

## NFCServiceFailure

An object representing an error that occurred when accessing NFCService features.

| Property Name | Type                    | Description                                                                                                                                                                     |
| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`        | `NFCServiceFailureCode` | A value representing the reason for an error. See [`NFCServiceFailureCode`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-constants.md#nfcservicefailurecode) for the list of possible values. |
| `message`     | String                  | A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.        |

**See Also**

- [NFCService Constants](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-constants.md)

<!-- document id=0ca8c5bfdca7a1a519e3d00fa032aba8bfa8a7cc29621f79aa7ec4d8e8708813 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-notify-record-update.md -->

# `notifyRecordUpdateAvailable(recordIds)`

Informs Lightning Data Service that record data has changed so that Lightning Data Service can take the appropriate actions to keep wire adapters updated with the latest record data. Call this function to notify Lightning Data Service that a record has changed outside its mechanisms, such as via imperative Apex or by calling User Interface API via a third-party framework. This function supersedes `getRecordNotifyChange(recordIds)`.

## Syntax

```javascript
import { notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';

notifyRecordUpdateAvailable(items: Array<{recordId: string}>)
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                         | Required?                               |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `items`        | Object | An array of objects with an object shape of `{ recordId: string }`. The record ID can be either 15 or 18 characters long, and it must be from a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that is resolved when Lightning Data Service has completed its processing. Updated information is sent to all affected wire adapters before the Promise is resolved. Use the Promise to determine when Lightning Data Service has completed its processing. The resolved value of the Promise is void.

## Usage

Calling `notifyRecordUpdateAvailable(recordIds)` signals that the data for the provided _recordIds_ has changed, so that the Lightning Data Service cache and wires can be updated.

**note:** Unlike [getRecordNotifyChange(recordIds) (Deprecated)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-record-notify.md), `notifyRecordUpdateAvailable(recordIds)` considers the record data wired by all instantiated components. For every wire that uses record data from one of the supplied _recordIds_, Lightning Data Service obtains fresh data for the wire and re-emits updated values to the wire if the data has changed. Values are not re-emitted to wires whose data has not changed, per the usual semantics of `@wire`.

This example calls `notifyRecordUpdateAvailable()` after the record is updated via calling an Apex method imperatively.

```javascript
import { LightningElement, wire } from 'lwc';
import { getRecord, notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
import apexUpdateRecord from '@salesforce/apex/Controller.apexUpdateRecord';

export default class Example extends LightningElement {
  @api recordId;

  // Wire a record
  @wire(getRecord, { recordId: '$recordId', fields: ... })
  record;

  async handler() {
    // Do something before the record is updated
    showSpinner();

    // Update the record via Apex
    await apexUpdateRecord(this.recordId);

    // Notify LDS that you've changed the record outside its mechanisms
    // Await the Promise object returned by notifyRecordUpdateAvailable()
    await notifyRecordUpdateAvailable([{recordId: this.recordId}]);
    hideSpinner();
  }
}
```

To ensure that `notifyRecordUpdateAvailable()` is called after the record update via Apex, use the `async`/`await` pattern or a Promise chain.

**note:** If you’re using an `@wire` to get record data via an Apex method, simply call [`refreshApex()`](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md), which uses the configuration bound to the `@wire` to get the data and update the cache.

`notifyRecordUpdateAvailable()` signals to LDS that some records are stale and refreshes those records that are in the LDS cache.


**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an [ldsNotifyRecordUpdateAvailable](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/ldsNotifyRecordUpdateAvailable) component that demonstrates `notifyRecordUpdateAvailable` usage .

**See Also**

- [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/data/data-table-inline-edit.md)

<!-- document id=13c3d7d2cd7ec0db2524ecd0bd0eb52eab2b90b907a459fc8d0220910415f4c2 url=/developer/current/en-us/lwc/utam/guide/nullable-vs-ispresent.md -->

# Nullable Versus isPresent

Consider these two cases that validate the absence of an element:

1. Log in to an application with minimal access rights and check that a "Setup" button isn't present.
2. After entering login credentials, check that the login form is no longer on the screen.

The key difference is that for the first use case, the button element was _never in the DOM_. We call it a nullable element. For the second use case, the login form element _was present in the DOM but no longer is_. We call it a stale element.

The following sections provide examples for both types of use cases.

## Check nullable element presence

When a test invokes an element's getter method, the framework attempts to find the element and return its value. In the first use case, a test invokes the getter for the Setup button.

Unless the element is marked as `nullable`, an error is thrown if the element isn't found.

If the element is marked as `nullable`, the getter returns `null` if the element isn't found.

```json
{
  "shadow": {
    "elements": [
      {
        "name": "setupButtonHTMLElement",
        "type": "clickable",
        "public": true,
        "nullable": true,
        "selector": { "css": "button.setup" }
      },
      {
        "name": "setupButtonCustomElement",
        "type": "utam-my/pageObjects/button",
        "public": true,
        "nullable": true,
        "selector": { "css": "my-button" }
      }
    ]
  }
}
```

A test or an imperative extension can check or assert a getter's returned value for `null` and act accordingly.

JavaScript example:

```js
const setupButton = await page.getSetupButtonHTMLElement();
const setupButtonCustom = await page.getSetupButtonCustomElement();
// assert for null
expect(setupButton).toBeNull();
expect(setupButtonCustom).toBeNull();
// OR check for null and apply action
if (setupButton) {
  // do something if element is present
  ...
}
if (setupButtonCustom) {
  // do something if element is present
  ...
}
```

Java example:

```java
SetupButton setupButton = page.getSetupButtonHTMLElement();
Button setupButtonCustom = page.getSetupButtonCustomElement();
// assert for null
assert setupButton == null;
assert setupButtonCustom == null;
// OR check for null and pply action
if (setupButton != null) {
  // do something if element is present
  ...
}
if (setupButtonCustom != null) {
  // do something if element is present
  ...
}
```

If the elements weren't marked as `"nullable": true`, the `page.getSetupButtonHTMLElement()` or `page.getSetupButtonCustomElement()` getters would throw an exception if the element isn't present.

## Check nullable list presence

The `nullable` behavior is the same for a list of elements.

```json
{
  "shadow": {
    "elements": [
      {
        "name": "setupButtonHTMLElementsList",
        "type": "clickable",
        "public": true,
        "nullable": true,
        "selector": { "css": "button.setup", "returnAll": true }
      },
      {
        "name": "setupButtonCustomElementsList",
        "type": "utam-my/pageObjects/button",
        "public": true,
        "nullable": true,
        "selector": { "css": "my-button", "returnAll": true }
      }
    ]
  }
}
```

A test or an imperative extension can check or assert a getter's returned value for `null` and act accordingly.

JavaScript example:

```js
const setupButtons = await page.getSetupButtonHTMLElementsList();
const setupButtonsCustom = await page.getSetupButtonCustomElementsList();
// assert for null
expect(setupButtons).toBeNull();
expect(setupButtonsCustom).toBeNull();
```

Java example:

```java
List<SetupButton> setupButtons = page.getSetupButtonHTMLElement();
List<Button> setupButtonsCustom = page.getSetupButtonCustomElement();
// assert for null
assert setupButtons == null;
assert setupButtonsCustom == null;
```

## Compose checking presence of a nullable element

For better encapsulation, keep the element private and declare a compose method to check that its getter returns not null:

```json
{
  "elements": [
    {
      // same element, but not public
      "name": "setupButton",
      "nullable": true,
      "selector": { "css": "button.setup" }
    }
  ],
  "methods": [
    {
      "name": "isSetupButtonPresent",
      "compose": [
        {
          "element": "setupButton",
          "matcher": {
            "type": "notNull"
          }
        }
      ]
    }
  ]
}
```

Note the syntax in the compose method. We used `element` and omitted `apply` to call the getter method.

The generated `isSetupButtonPresent` method calls the getter for the `setupButton` element, checks if its value isn’t null, and returns a boolean value.

A test or an imperative extension can assert or check the element's presence and act accordingly.

```js
if (await homePage.isSetupButtonPresent()) {
  // do something
}
```

## Compose checking presence with containsElement

Another option is to check for an element's presence using the `containsElement` action first and then act accordingly.

```json
{
  "elements": [
    {
      // same element, but not public
      "name": "myButton",
      "type": "clickable",
      "selector": { "css": "button.my" }
    }
  ],
  "methods": [
    {
      "name": "isMyButtonPresent",
      "compose": [
        {
          "element": "root",
          "apply": "containsElement",
          "args": [
            // first arg - selector to search for
            {
              "type": "locator",
              "value": { "css": "button.my" }
            },
            // second arg - expand or not the shadow root of the parent, false is default
            { "value": false }
          ]
        }
      ]
    },
    {
      "name": "clickMyButton",
      "compose": [
        {
          "element": "myButton",
          "apply": "click"
        }
      ]
    }
  ]
}
```

Example of usage from a test:

- JavaScript

```js
if (await homePage.isMyButtonPresent()) {
  await clickMyButton();
}
```

- Java

```js
if (homePage.isMyButtonPresent()) {
  clickMyButton();
}
```

## isPresent returns false for a Stale Element

A `getMyElement().isPresent()` call returns `true` for an existing element or throws an error for a non-nullable absent element. The `isPresent()` call returns `false` when an element **becomes** absent or stale because the page was refreshed.

```java
myForm = homePage.getForm();
// do something in the form until it's gone
assert myForm.isPresent() == false;
```

The `isPresent` call returns false when the form element became stale. Consider our second use case earlier where the login form is no longer on the screen after the login is complete.

### Save an element instance in a variable

Remember that invoking an element's getter triggers finding the element inside its parent. To use `isPresent`, save an instance of the element before it becomes stale to avoid an error that the element isn't found when its getter is invoked. The `myForm = homePage.getForm()` calls saves the form before it becomes stale.

### Calling isPresent on a nullable element can throw NullPointerException

If an element is marked as nullable, a test should check for a null value before calling any method, including `isPresent`, on it.

```java
myForm = homePage.getForm();
// assuming the form is nullable
assert myForm != null && myForm.isPresent() == false;
```

## Wait for absence of a stale element

If an element was present but it takes time for it to become absent, use `waitForAbsence`. For example, an application might do some processing after we save changes in a form but doesn't hide the form immediately.

- JavaScript example

```js
const myForm = await homePage.getForm();
await myForm.waitForAbsence();
```

- Java example

```java
PageObject myForm = homePage.getForm();
myForm.waitForAbsence();
```

## Wait for presence in beforeLoad

If a test must wait for a certain element to be present inside a page object root, it's a best practice to make the wait a part of loading the page object by overriding the page object's load method.

A page Object is "loaded" when a test either call `UtamLoader.load(Class)` or invokes a getter method that returns the page object from inside its enclosing page object.

In this example, the page object overrides page loading by waiting for an element with a given selector using the `containsElement` action:

```json
{
  "beforeLoad": [
    {
      "apply": "waitFor",
      "args": [
        {
          "type": "function",
          "predicate": [
            {
              "element": "root",
              "apply": "containsElement",
              "args": [
                // first arg - selector to search for
                {
                  "type": "locator",
                  "value": { "css": "i-am-slow" }
                },
                // second arg - expand the shadow root of the parent
                { "value": true }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

**note:** We can't use a nullable element in this example. A `beforeLoad` statement can invoke methods only against root or a document object because the page isn't fully loaded yet.

The predicate in the `waitFor` statement has to return a truthy value (not null, not false and doesn’t throw) for the method to complete without an error.

In our example, the root element should contain an element with the given selector inside its shadowRoot.

## Wait for nullable element presence

In some cases, it can take some time for an element to render. Such a wait isn't always allowed in a `beforeLoad` override such as in the previous example. For example, the element might not be inside root or its loading might not be stateless.

```json
{
  "elements": [
    {
      "name": "parent",
      "selector": { "css": ".containsSlowElement" },
      "elements": [
        {
          "name": "slowElement",
          "selector": { "css": "i-am-slow" }
        }
      ]
    }
  ],
  "methods": [
    {
      "name": "waitForSlowElement",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "slowElement"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

The predicate in the `waitFor` statement has to return a truthy value (not null, not false and doesn’t throw) for the method to complete without an error.

In this example, the method repeatedly calls the slowElement getter until it stops throwing an error that element isn't found or until a timeout is reached.

## Wait for nullable list presence

To wait for a list of elements, we can use the same approach as in the previous example. The only exception is that the element is marked with `returnAll`. This example also uses a custom type:

```json
{
  "elements": [
    {
      "name": "parent",
      "selector": { "css": ".containsSlowElement" },
      "elements": [
        {
          "name": "slowCustomElements",
          "selector": { "css": "i-am-slow" },
          "type": "utam-my/pageObjects/custom"
        }
      ]
    }
  ],
  "methods": [
    {
      "name": "waitForSlowElementsList",
      "compose": [
        {
          "apply": "waitFor",
          "args": [
            {
              "type": "function",
              "predicate": [
                {
                  "element": "slowCustomElements"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

As in the previous example, this method repeatedly calls the `slowCustomElements` getter until it stops throwing an error that the element isn't found or until a timeout is reached.

<!-- document id=0338e4c7c4c59274a8804348416f3070ca22521dae214fa6bea4efde3448cf87 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-proxies.md -->

# Objects Passed Between Components Are Proxied

Objects that are passed between components in different namespaces or into the global DOM can have compatibility issues. To maintain namespace isolation and reduce incompatibility, Lightning Web Security (LWS) uses proxy wrappers around the objects. When LWS attempts to unwrap the values, it’s sometimes unsuccessful. You can see in the browser console that the values are null or proxied, for example.

Similarly, custom events fired by a component with `detail` values that are intended for a browser extension cross the component sandbox boundary, so LWS proxies them. The browser extension can receive null `detail` values because of the proxy wrapper.

To avoid issues related to proxies, pass values as JSON strings and parse them later.

In this example, the component in namespace `foo` serializes event data into JSON strings. The component in namespace `bar` parses the data before handling.

```javascript
// namespace foo
window.addEventListener(
  "message",
  (event) => {
    let dataObj = JSON.stringify(event.data);
  },
  false,
);

// namespace bar
let dataStr = JSON.parse(data);
window.postMessage(dataStr, targetOrigin);
```

**See Also**

- [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.md)

<!-- document id=f1c9f8adc94f7b125ec41535f28abc6a4300b6bb80499fb0b2b1e61fce4dd9c9 url=/developer/current/en-us/lwc/lwc/guides/use/use-open-files.md -->

# Open Files

To open one or more file records in Lightning Experience and the Salesforce app, use the navigation service, `lightning/navigation`. The navigation service opens the preview of one or more files in a modal dialog in Lightning Experience, or triggers a file download in the Salesforce app on mobile devices.

## Open Files with a Page Reference

The navigation service uses a [`PageReference`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md), which describes a page, or in this case, a file.

Use a page reference with `'type': 'standard__namedPage'` and a `pageName` attribute of `filePreview`.

The `filePreview` named page value supports the ContentDocument and ContentHubItem (external files) objects. The `filePreview` named page value is supported in Lightning Experience and all versions of the mobile app. It isn’t supported in other containers, such as Lightning Components for Visualforce, Lightning Out 2.0 and Lightning Out (beta), or Experience Cloud sites. The page value isn’t supported even if you access these containers inside Lightning Experience or the Salesforce mobile app.

## Example: Open a File Record

This example opens the record with ID `069xx0000000001AAA` in Lightning Experience and the Salesforce app.

<!-- prettier-ignore -->
```html
<!-- openFileSample.html -->
<template>
  <div>
    <a onclick={navigateToFiles}>Navigate To Files</a>
  </div>
</template>
```

```javascript
// openFileSample.js
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class OpenFileSample extends NavigationMixin(LightningElement) {
  navigateToFiles() {
    this[NavigationMixin.Navigate]({
      type: "standard__namedPage",
      attributes: {
        pageName: "filePreview",
      },
      state: {
        recordIds: "069xx0000000001AAA,069xx000000000BAAQ",
        selectedRecordId: "069xx0000000001AAA",
      },
    });
  }
}
```

The `recordIds` property is a comma-separated list of all record IDs available for download.

In Lightning Experience, the record specified in `selectedRecordId` downloads first. The user can switch to the other records by clicking the arrows in the app. The desktop file previewer offers image and SVG-based multi-page office documents preview, presentation mode, and quick access to file actions like share, download, upload, and delete.

In the Salesforce app, a single file downloads when the event is fired. If `selectedRecordId` is specified, that file downloads. If `selectedRecordId` isn’t specified, the first file in the `recordIds` list downloads. Depending on the device, a native preview of the file displays.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [navToFilesHome](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/navToFilesHome) component that demonstrates navigating to Files home.

**See Also**

- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/reference/reference-page-reference-type.md)
- [Salesforce Object Reference Guide: ContentDocument](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentdocument.htm)
- [Salesforce Object Reference Guide: ContentHubItem](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contenthubitem.htm)

<!-- document id=781027be8e7c0fa7e6faf43b44f56822239419a0131cd9008b1d2ca26cd76472 url=/developer/current/en-us/lwc/lwc/guides/use/use-dialog.md -->

# Open Modal Windows and Notifications

A component can use Lightning base components to open new modal windows for general purposes, and notification modals that are styled for more specialized uses.

Use notification modals to alert users, request confirmation from them, prompt a response, or simply provide information.

Most Lightning base components have HTML tags that you nest in your custom component's template. The components you use to create modal windows are different. You use them by extending them to your component class.

- [Modal Windows](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-modal.md)
- [Alert Modals](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-alert.md)
- [Confirm Modals](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-confirm.md)
- [Prompt Modals](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-prompt.md)
- [Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/guide/use-toast.md)

<!-- document id=81dbfcc7e00e335e54e4fb90e5f42613435fa8579a277bcd1349834b181138d4 url=/developer/current/en-us/lwc/lwc/guides/reference/distributed-marketing/reference-lightning-distributed-marketing-open.md -->

# `openDistributedMarketing(config)`

Launches the Distributed Marketing modal, containing the audience, campaign, or flow that you supply. The method opens the multi-step Distributed Marketing wizard, which includes these steps shown in order of appearance:

- Campaign
- Audience
- Personalize
- Preview & Send

The `lightning/distributedMarketing` module re-exports the static method on the internal `DiscoModal` component.

## Syntax

```typescript
import { openDistributedMarketing } from 'lightning/distributedMarketing';
openDistributedMarketing(config: DmLauncherConfig): void
```

The method opens the modal and returns `void`. It throws a `DiscoError` synchronously if the configuration fails validation. See [Error Handling](#error-handling).

## Parameters

The method accepts a single `config` object of type `DmLauncherConfig` with these parameters.

| Parameter               | Type       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audience`              | `string[]` | Yes      | A non-empty array of Salesforce record IDs that seeds the Distributed Marketing audience. Each ID must be a valid 15- or 18-character ID for a Contact, Lead, Prospect, or CampaignMember. You can mix types within the array as long as each ID resolves to one of these sObjects.                                                                                                                                   |
| `campaignId`            | `string`   | No       | A valid Campaign ID. When provided, the Campaign Picker is pre-filtered to this campaign, which saves the user from searching for it. Required when `flowId` is provided.                                                                                                                                                                                                                                             |
| `flowId`                | `string`   | No       | A valid flow definition ID. When provided, the modal fetches the flow directly and bypasses campaign and flow discovery in the Campaign Picker. You must provide `campaignId` with `flowId`. Passing `flowId` without `campaignId` throws an error. Use `flowId` when the specified campaign has multiple flows. If you don't pass a `flowId`, the modal doesn't auto-select a flow, and the user picks one manually. |
| `skipAudienceSelection` | `boolean`  | No       | When `true`, the Audience Picker step is skipped and the modal uses the supplied `audience` as-is. Because the audience can't be edited in the modal when this option is set, `audience` must be non-empty. Defaults to `false`.                                                                                                                                                                                      |
| `actionableListId`      | `string`   | No       | A valid actionable list Id. When provided, the modal sends to the whole list. List must be under the max list size, currently 2000.                                                                                                                                                                                                                                                                                   |
| `defaultContent`        | `string`   | No       | Omitted or 'LastSent' (default): Load the last published content for the selected template. 'None': start from the base template                                                                                                                                                                                                                                                                                      |

## Validation Rules

The method enforces these rules synchronously, before the modal opens.

- The `config` object must be provided.
- `audience` must be an array with at least one element.
- Every `audience` ID must be a syntactically valid Salesforce ID whose key prefix maps to a Contact, Lead, Prospect, or CampaignMember.
- `campaignId`, when provided, must be a valid Campaign ID.
- `flowId`, when provided, requires `campaignId` and must be a valid flow definition ID.
- When `skipAudienceSelection` is `true`, `audience` must still be non-empty. Otherwise, validation surfaces an error.
- `actionableListId`, when provided, must be a syntactically valid Salesforce Id. `audience` must not be provided when `actionableListId` is. `skipAudienceSelection` is ignored.
- `defaultContent` accepts `'LastSent'` or `'None'`. When omitted, defaults to `'LastSent'`.

## Modal Configuration

The modal builds its step list dynamically, based on the configuration that you pass in.

| Configuration                                                               | Steps shown                                                                                     |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `audience` only                                                             | Campaign Picker → Audience Picker → Personalize → Preview & Send                                |
| `audience` and `campaignId` (campaign has one flow)                         | Audience Picker → Personalize → Preview & Send                                                  |
| `audience` and `campaignId` (campaign has two or more flows)                | Campaign Picker (pre-filtered) → Audience Picker → Personalize → Preview & Send                 |
| `audience` and `campaignId` with `flowId`                                   | Audience Picker → Personalize → Preview & Send (Campaign Picker skipped; flow loaded directly)  |
| `audience` and `skipAudienceSelection: true`                                | Campaign Picker → Personalize → Preview & Send (Audience Picker skipped)                        |
| `audience` and `campaignId` with `flowId` and `skipAudienceSelection: true` | Personalize → Preview & Send                                                                    |
| `actionableListId`                                                          | Same permutations as `audience` except no audience picker                                       |
| `defaultContent`                                                            | Independent of other params. Only affects content initially selected for the selected template. |

**note:** The Audience Picker step is currently available only for campaigns. To include it, pass a `campaignId` in the config. If your component is on a campaign record page, the `campaignId` isn't provided automatically—read the campaign's `recordId` from the record context and pass it as `campaignId`. For more information, see [Use Record Context in a Lightning Web Component](https://developer.salesforce.com/docs/platform/use/use-record-context.md). Otherwise, the Audience Picker step isn't included in the modal's steps.

## Usage

`openDistributedMarketing` is an imperative function, not a `@wire` adapter. Call it in response to a user action.

Launch the modal with only an audience.

```javascript
import { openDistributedMarketing } from "lightning/distributedMarketing";

openDistributedMarketing({
  audience: ["003xx0000001abcAAA", "00Qxx0000001xyzAAA"],
});
```

Pre-filter to a campaign.

```javascript
openDistributedMarketing({
  audience: contactIds,
  campaignId: "701xx0000000001AAA",
});
```

Launch directly into a specific flow.

```javascript
openDistributedMarketing({
  audience: contactIds,
  campaignId: "701xx0000000001AAA",
  flowId: "300xx0000000001AAA",
});
```

Skip the Audience Picker step for a mass action, such as a list view action.

```javascript
openDistributedMarketing({
  audience: selectedCampaignMemberIds,
  skipAudienceSelection: true,
});
```

## Error Handling

All validation errors are thrown synchronously as `DiscoError` instances before the modal opens. Two error names are used.

| Error Name                   | Thrown When                                                                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_REQUIRED_PARAMETER` | The `config` object itself is missing.                                                                                     |
| `INVALID_PARAMETER`          | Any other validation failure occurs. Multiple failures are concatenated into a single message, separated by a pipe (`\|`). |

Wrap the call in a `try` and `catch` block when the configuration is derived from dynamic or untrusted input.

```javascript
try {
  openDistributedMarketing(config);
} catch (e) {
  // e.name: 'MISSING_REQUIRED_PARAMETER' | 'INVALID_PARAMETER'
  // e.message: human-readable, pipe-separated list of validation failures
  console.error("DM launch failed:", e);
}
```

## Example

This sample launcher component shows a single button. When a user clicks it, the component launches the Distributed Marketing modal with up to 2,000 campaign members from a specific campaign, pre-filters by that campaign, and skips the Audience Picker step.

Because the component passes a `campaignId` filter and the example campaign has only one flow, the single flow is auto-selected and the Campaign Picker step is skipped. The Audience Picker step is created in the modal steps, but `skipAudienceSelection` advances past it automatically. Users can go back and adjust their audience. As configured, the button advances the modal directly to the Personalize step.

The HTML template renders the launch button.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <div class="slds-p-around_medium">
    <lightning-button
      variant="brand"
      label="Launch DM"
      title="Launch DM"
      stretch
      onclick={handleLaunch}
    >
      Launch DM (via public API)
    </lightning-button>
  </div>
</template>
```

To query campaign members for the target campaign, use the `lightning/graphql` adapter. This example queries up to 2,000 campaign members, and passes the campaign member IDs to `openDistributedMarketing` when the user clicks the button.

```javascript
// myComponent.js
import { LightningElement, wire } from "lwc";
import { graphql, gql } from "lightning/graphql";
import { openDistributedMarketing } from "lightning/distributedMarketing";

const CAMPAIGN_MEMBER_QUERY = gql`
  query getCampaignMembers {
    uiapi {
      query {
        CampaignMember(where: { CampaignId: { eq: "701xx000003GaNPAA0" } }, first: 2000) {
          edges {
            node {
              Id
            }
          }
        }
      }
    }
  }
`;

export default class MyCustomComponent extends LightningElement {
  campaignMemberIds = [];

  @wire(graphql, { query: CAMPAIGN_MEMBER_QUERY })
  wiredCampaignMembers({ data, errors }) {
    if (data) {
      const edges = data?.uiapi?.query?.CampaignMember?.edges ?? [];
      this.campaignMemberIds = edges.map((edge) => edge.node.Id);
    }
    if (errors) {
      console.error("GraphQL CampaignMember error:", errors);
    }
  }

  handleLaunch() {
    try {
      openDistributedMarketing({
        audience: this.campaignMemberIds,
        campaignId: "701xx000003GaNPAA0",
        skipAudienceSelection: true,
      });
    } catch (error) {
      console.error("Error launching DM modal:", error);
    }
  }
}
```

The `js-meta.xml` file exposes the component for Lightning record pages, Experience Cloud site pages, and Flow screens. For more information, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference-configuration-tags.md).

```xml
<!-- myComponent.js-meta.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>66.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightningCommunity__Default</target>
    <target>lightningCommunity__Page</target>
    <target>lightning__FlowScreen</target>
  </targets>
</LightningComponentBundle>
```

<!-- document id=ba491e957a27d6df47237601fef58eaaa739b9a2f6e48a394a8ff65d1141556e url=/developer/current/en-us/lwc/utam/guide/generator-override-content.md -->

# Override generated content

Add a generator rule file (name matches the pattern in the`rulesFileMask` option) next to an HTML or JavaScript source file to modify the generated content.

```txt
<inputRootDir>
├── generator.config.json
├── src/
   └── modules/
      ├── my-component/
         └── my-component.html
         └── my-component.rules.json
```

Generation parameters from the component-level rules override the rules defined at the project level. In addition to [Runner parameters](https://developer.salesforce.com/docs/platform/utam/guide/generator-get-started.md#generation-runner-parameters) and [HTML interpretation parameters](/tools/generator-guide), you can customize generated content by adding elements of UTAM page object grammar directly to the configuration file. In our example, the configuration file is `my-component.rules.json`.

**note:** The supported parameters were updated in version 2.1.0. Please do not use earlier versions.

## Root selector

By default, the generator adds a root selector if the [object is recognized as a root](https://developer.salesforce.com/docs/platform/utam/guide/generator-rules.md#marking-page-object-as-a-root). Otherwise, you can add a selector to a rules file following the [selector UTAM grammar](/grammar/element-selectors).

Example of configuring root selector in `my-component.rules.json`:

```json
{
  "selector": {
    "css": "my-root"
  }
}
```

If a root selector was generated and you want to remove it, set `"root": false` in `my-component.rules.json`.

## Description and metadata

By default, the generator adds a root description in this format:

```json
{
  "description": {
    "author": "UTAM generator",
    "text": ["Page Object: <name of file>", "<root if present>"]
  }
}
```

You can add both the description and the metadata to a rules file. For the syntax, see the [description and metadata UTAM grammar](/docs/platform/utam/references/utam-grammar/descriptions-metadata.html).

Example of configuring description and metadata in `my-component.rules.json`:

```json
{
  "description": "very useful page object",
  "metadata": {
    "some": "value"
  }
}
```

## Root properties

You can add more root properties to the generation rules by using UTAM JSON grammar.

- [exposeRootElement](/docs/platform/utam/references/utam-grammar/root-elements.html#actionable-root-element)
- [type](/docs/platform/utam/references/utam-grammar/page-object-elements.html)
- [beforeLoad](/docs/platform/utam/references/utam-grammar/explicit-waits.html#beforeload)
- [platform](/docs/platform/utam/references/utam-grammar/platform-context.html)
- [implements](/docs/platform/utam/references/utam-grammar/interfaces.html#interface-implementation)

Example of configuring root properties in `my-component.rules.json`:

```json
{
    "beforeLoad": [ ... ],
    "implements": "some/other/type",
    "type": "actionable",
    "exposeRootElement": true,
    "platform": "Web"
}
```

## shadowRoot

The generator determines if the source HTML has a shadowRoot based on the following rules.

A `<template>` HTML element or custom HTML element (with a dash in the tag name) is considered a shadow boundary if they are not marked as `lwc:render-mode="light"`. For example for following HTML snippets:

```html
<template>
  <div class="wrapper">
    <!-- content -->
  </div>
</template>
```

```html
<div>
  <my-generated-component>
    <button id="number"></button>
  </my-generated-component>
</div>
```

The generator produces a shadow boundary:

```json
"shadow": {
     "elements": [
        { }
    ]
}
```

Let's use the following HTML as a source for generation:

```html
<template>
  <button>button</button>
</template>
```

By default, the generated code is:

```json
{
  "shadow": {
    "elements": [
      {
        "public": true,
        "name": "button",
        "type": ["actionable", "clickable"],
        "selector": { "css": "button" }
      }
    ]
  }
}
```

To move all generated elements outside shadowRoot, set `"shadowRoot": false` in the configuration file. The generated code is:

```json
{
    "elements": [
        {
            "public": true,
            "name": "button",
            ...
        }
    ]
}
```

To move elements inside shadowRoot, set `"shadowRoot": true`.

## Add generated elements

If the generator didn't pick up some of the elements, it's possible to add them using `"elements": []` or `"shadow: { "elements" : []}` syntax from [UTAM grammar](/docs/platform/utam/references/utam-grammar/page-object-elements.html).

For example, if the originally generated `my-component.utam.json` is:

```json
{
    "elements" : [
        {
            "name" : "generated",
            "public": true,
            "selector" : { ... }
        }
    ]
}
```

Add a `configured` element in the `my-component.rules.json` rules file.

```json
{
    "shadow": {
        "elements": [
            {
                "name": "configured",
                "selector": {...}
            }
        ]
    }
}
```

The generated `my-component.utam.json` is now:

```json
{
    "elements" : [
        {
            "name" : "generated",
            "public": true,
            "selector" : { ... }
        }
    ],
    "shadow": {
        "elements": [
            {
                "name": "configured",
                "selector": {...}
            }
        ]
    }
}
```

Note that configured elements are added to existing ones, they don’t replace them. To replace the generated version, check out [remove generated element](#remove-generated-elements).

## Change generated elements

Generated elements are based on generation rules that aren’t always optimal or aware of the business function.
Sometimes, it makes sense to change generated element properties using the `replaceElements` configuration parameter. The format of `replaceElements` is an array where each element points to the generated name of the generated element and defines a subset of properties to change consistent with the element grammar format:

- `name` is a generated element whose properties should be changed
- 'element' compose changes to be applied to the element with the give name
  - [selector](/docs/platform/utam/references/utam-grammar/element-selectors.html) changes the auto-generated selector
  - [type](/docs/platform/utam/references/utam-grammar/page-object-elements.html) changes the type of the generated element
  - `nullable` defines whether the element is [nullable](https://developer.salesforce.com/docs/platform/utam/guide/nullable-vs-ispresent.md)
  - `description` adds documentation to the element getter
  - `public` defines if the element should have a public getter
  - [filter](/docs/platform/utam/references/utam-grammar/element-filters.html) sets an element's filter
  - `shadow` nested shadow elements
  - `elements` nested elements

For example, if the originally generated `my-component.utam.json` is:

```json
{
  "elements": [
    {
      "name": "div",
      "selector": { "css": ".generatedCss" }
    }
  ]
}
```

Use `replaceElements` in a `my-component.rules.json` rules file.

```json
{
    "replaceElements": {
        [
            "name" : "div",
            "element": {
                "name": "updatedName",
                "selector" : { "css": ".configuredCss" },
                "public" : true,
                "nullable": true,
                "description": "element description",
                "filter": { ... },
                "shadow": { ... },
                "elements": [
                    //nested elements
                ]
            }
        ]
    }
}
```

The generated `my-component.utam.json` is now:

```json
{
    "elements" : [
        {
            "name": "updatedName",
            "selector" : { "css": ".configuredCss" },
            "public" : true,
            "nullable": true,
            "description": "element description",
            "filter": { ... },
            "shadow": { ... },
            "elements": [
                    //nested elements
            ]
        }
    ]
}
```

## Remove generated elements

Redundant elements can be removed using `replaceElements` parameter from the [previous section](#change-generated-elements).
To remove a generated element, set a rule that sets value for the generated element with the given name as `undefined`.

For example, if the originally generated `my-component.utam.json` is:

```json
{
  "elements": [
    {
      "name": "div",
      "selector": { "css": ".generatedCss" }
    }
  ]
}
```

Given generation rules `my-component.rules.json`:

```json
{
  "replaceElements": [
    {
      "name": "div"
      // do not set "element"
    }
  ]
}
```

The generated `my-component.utam.json` is now empty because the rules defined that an element with the name `div` should be removed:

```json
{}
```

## Add compose methods

To add compose methods to the generated JSON file, add `methods` to the generation rules. These methods follow the same syntax as a regular [compose method in UTAM grammar](/grammar/methods).

### `methods`

- Type: [compose method](/docs/platform/utam/references/utam-grammar/methods.html)
- Default: undefined

Here's an example of rules:

```json
{
  "methods": [
    {
      "name": "getRootText",
      "compose": [
        {
          "element": "root",
          "apply": "getText"
        }
      ],
      "description": {
        "text": ["get record label text"]
      }
    }
  ]
}
```

This exact method is added to the generated JSON.

<!-- document id=95c8aaca768040161b9dc4b083a350fbc10c79ba7ad6842d32bae1caf365a21b url=/developer/current/en-us/lwc/slds-validator/guides/overview.md -->

# Overview

SLDS Validator is a Visual Studio (VS) Code extension that scans your code, validates it against a database of Salesforce Lightning Design System (SLDS) guidelines, and offers recommendations on how to improve your code. SLDS Validator:

- Evaluates your HTML, Cascading Style Sheets (CSS), and component markup (CMP) code inline as you write it in VS Code.
- Simplifies working with SLDS in Aura and Lightning.

With the SLDS Validator extension, you get:

- SLDS 1 and SLDS 2 support
- Validation with recommended tokens and utility classes
- Syntax highlighting
- Code completion
- Context awareness
- Bulk report generation

<!-- document id=35765a49d69339557f2c81af499d62684f7eb5b81c404ae22fbc1c77f4f6c5a5 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-overview-custom-property-types.md -->

# Overview: Creating Custom Property Types and Editors

This walkthrough is for anyone who's creating a custom property type or editor for the first time or who needs a refresher.

Let's say that you have a Lightning web component for Experience Builder called Standard Article, and you want to create one with more intuitive property editors, called Custom Article. Both components require properties for title, date updated, content, text alignment, background color, and layout borders and size. The Standard Article component, which doesn't use custom property types or editors, looks like this.

![Property panel for the Standard Article component](https://developer.salesforce.com/media/use-experience-cloud-standard-article.png)

Before you begin to build a custom component, consider your requirements for data validation and user experience for the component's properties. These requirements determine which property types and editors you need to create and whether a standard solution is sufficient, rather than a custom one.

In this example, the Custom Article component demonstrates how you can improve the user experience with custom property types and editors. Download the [sample components](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples) to see how the `articleDate`, `textAlignment`, and `layoutProperties` are configured in the Standard Article and Custom Article components.

![Property panel for the Custom Article component](https://developer.salesforce.com/media/use-experience-cloud-custom-article.png)

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)

<!-- document id=86ed5e12325f0ef4c91edae5046d0017d654d6ea3d09d5afb1f0a440daf03a76 url=/developer/current/en-us/lwc/utam/references/page-object-elements.md -->

# Page Object Elements

Elements can have different types.

## Element types

If a component has an HTML element that you need in the page object, declare an element as an object in an `elements` array.
You can put an element object in an `elements` array at the root, inside a shadow, or nested inside a basic element.

These are the element types:

- [Basic element](/grammar/page-object-elements#basic-elements) represents standard HTML element like anchor or div and should be added only if it’s needed for user interactions or to scope other elements.
- [Custom element](/grammar/page-object-elements#custom-elements) represents a nested/child component, and therefore has a `type` property that references another page object that matches this nested/child component.
- [Container element](/grammar/page-object-elements#container-elements) represents `slot` or `lwr-dynamic` that can act as a container to inject other components whose types are unknown to the component developer.
- [Frame element](/grammar/page-object-elements#frame-elements) represents a frame or an iframe.

An element has properties.

- Each element type has `name`, `type`, and `selector` properties.
- Each element type can be marked as `public`.
- If it takes time for the element to load, use an explicit wait using the `wait` property.
- If the page object needs to wait on the element to load, use the `load` property. This element cannot have arguments.
- Any element type can be marked as [nullable](/docs/platform/utam/guide/nullable-vs-ispresent.html).

There are limitations for different elment types:

- Frame cannot have nested elements.
- Only basic or custom elements can have a [filter](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-filters.md).

## Basic Elements

A basic element can have these properties:

- `name` (Required) String. The element name, which UTAM uses in the getter method name. The value must be unique within the JSON file.
- `type` (Optional) A String for a single type or an array of strings. A list of the types of user interaction that this basic element supports. If omitted, it defaults to a base element type, which supports the methods listed in the Base Element Actions table in [actions](/grammar/basic-actions#base-element-actions).

  To allow more interaction, add one or more of these values to the type array:

  - `actionable` Exposes the methods listed in the [Actionable Type Actions table](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md#actionable-type-actions).
  - `clickable` Exposes the methods listed in the [Clickable Type Actions table](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md#clickable-type-actions).
  - `editable` Exposes the methods listed in the [Editable Type Actions table](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md#editable-type-actions).
  - `draggable` Exposes the methods listed in the [Draggable Type Actions table](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/basic-actions.md#draggable-type-actions).
  - `touchable` Exposes the methods for mobile device interactions listed in the [Touchable Type Actions table](/grammar/basic-actions#touchable-type-actions).

- `selector` (Required) Object. Locates the element inside its immediate parent. See [Selector properties](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-selectors.md#selector-properties).
- `filter` (Optional) Object. Picks an element from a list or filters a list at run time. See [Element Filters](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-filters.md).
- `nullable` (Optional, default is `false`). Boolean. If set to `true` and the element can't be found inside its parent, the getter method returns `null`. If set to `false`, an error is thrown if the element isn't found. For examples, see [Guide: Nullable Versus isPresent](/guide/presence).
- `public` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a public method that returns an instance of the element with the given type. The name of the getter is generated automatically from the `name` property as `get<Name>` (the value of the `name` property is capitalized).
- `wait` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a public method that [waits for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#wait-for-an-element).
- `load` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a private method that [waits for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#load-an-element) and automatically adds it to the [beforeLoad](/grammar/before-load) method of the page object.
- `shadow` (Optional) Object. A shadow boundary. Contains only an `elements` property, which is a nested tree of objects.
- `elements` (Optional) Array. Contains a nested tree of element objects that are located inside this basic element.

```json
{
  "elements": [
    {
      "name": "myElement",
      "type": ["clickable", "editable"],
      "public": true,
      "selector": {
        "css": ".element"
      },
      "elements": []
    }
  ]
}
```

If an element has one basic type only, it can be defined as a string instead an array of strings. For example, this root element has the `actionable` type only:

```json
{
  "exposeRootElement": true,
  "type": "actionable"
}
```

UTAM generates a public method that returns an instance of the element to interact with.

Java:

```java
public MyElementElement getMyElement() {
    // return element
}
```

JavaScript:

```js
//declaration
getMyElement(): Promise<_BaseUtamElement>;

// implementation
async getMyElement() {
    const driver = this.driver;
    const root = await this.getRootElement();
    let element = await _utam_get_myElement(driver, root, );
    return new _ActionableUtamElement(driver, element);
}
```

## Custom Elements

A custom element has the same properties as a [basic element](#basic-elements), except that the `type` property is required and must reference another page object.

- `type` (Required) String. A reference to a UTAM page object. The format is:

  ```
  <package name>/pageObjects/<component namespace>/<page object name>
  ```

  For JavaScript, the `<package name>` and the `<page object name>` are required and can include only alphanumeric characters and dashes. The path between these segments is optional. Each path segment can contain only alphanumeric characters (no dashes).

  For Java, the `<package name>` must start with `utam-` and the `/pageObjects/` segment is required. The `<page object name>` must be a valid class name (it can't include dashes). It can start with a lowercase character, because the compiler transforms it to uppercase.

  For Java, the UTAM compiler transforms the `type` value to match Java syntax rules.

  - `<package name>`: transform `-` into `.`
  - Path: transform `/` into `.`; transform uppercase characters into lowercase.
  - `<page object name>`: transform lowercase first letter to uppercase, because Java class names always start with an uppercase character.

    ```java
    // JSON
    "type": "utam-navex/pageObjects/one/navigationBar"

    // UTAM compiler transforms to:
    utam.navex.pageobjects.one.NavigationBar
    ```

This example declares a custom element called `todo-item`, which lives in the `utam-tutorial` package.

```json
{
  "root": true,
  "selector": { "css": "body" },
  "elements": [
    {
      "name": "todoApp",
      "type": "utam-tutorial/todoApp",
      "selector": { "css": "example-todo-app" },
      "public": true,
      "shadow": {
        "elements": [
          {
            "name": "todoItem",
            "selector": { "css": "example-todo-item" },
            "public": true,
            "type": "utam-tutorial/todoItem"
          }
        ]
      }
    }
  ]
}
```

**important:** Elements should only be nested inside custom element if it mimics component code. In most cases custom element only references another page object type and everything is encapsulated inside the page object.

The generated `getTodoItem()` method returns an object scoped inside its parent element.

JavaScript:

```js
getTodoApp(): Promise<_ActionableUtamElement>;
getTodoItem(): Promise<_todoItem>;
```

## Container Elements

There are certain requirements to declare a container element for a slot. For more information, see the guidelines in the [slots guide](/docs/platform/utam/guide/slots.html).

Let's look at an example where we would need to declare a container element.
For example, here is a component that has a placeholder for content in an output field. In component source code, a placeholder is a `slot`.

<!-- prettier-ignore -->
```html
<template>
    <div class="slds-form-element__control">
        <span
            class={computedOutputFieldContainerClass}
            oninlineeditbehavioroverride={handleInlineEditBehaviorOverride}>
            <!-- slot for a field -->
            <slot name="outputField"></slot>
        </span>
    </div>
</template>
```

In this case, declare an element with `"type": "container"`. The compiler generates a method with a parameter for the type of the component being loaded.

A container element has these properties:

- `name` (Required) String. An element name that's unique to this JSON file.
- `type` (Required) String. The value must be `container`.
- `public` (Optional, default is `false`) Boolean. Must be set to `true` so that UTAM generates a public method.
- `selector` (Optional, default is `"css": ":scope > *:first-child"`). A [selector](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-selectors.md#selector-properties) injected as a root for the container content.
- `nullable` (Optional, default is `false`). Boolean. If set to `true` and the element can't be found inside its parent, the getter method returns `null`. If set to `false`, an error is thrown if the element isn't found. For examples, see [Guide: Nullable Versus isPresent](/guide/presence).
- `wait` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a public method that [waits for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#wait-for-an-element).
- `shadow` (Optional) Object. A shadow boundary. Contains only an `elements` property, which is a nested tree of objects.
- `elements` (Optional) Array. Contains a nested tree of element objects that are located inside this basic element.

As with any other element, if there's a `#shadow-root` between the basic element and the nested container element, enclose the container element in a `shadow` object. Note that slots are usualy **not** inside shadow root.

Most containers would not have a hardcoded selector because content is unknown, except for named slots. If a selector is omitted, a default CSS selector of `:scope > *:first-child` will be used in the generated code.

For our example, the container element is:

```json
{
  "elements": [
    {
      "name": "outputFieldContent",
      "type": "container",
      "public": true,
      "selector": {
        "css": "[slot='outputField']"
      }
    }
  ]
}
```

UTAM generates this JavaScript code.

```js
async function _utam_get_outputFieldContent(driver, root) {
    let _element = root;
    const _locator = core.By.css("[slot='outputField']");
    return _element.findElement(_locator);
}

async getOutputFieldContent(ContainerCtor) {
        const driver = this.driver;
        const root = await this.getRootElement();
        let element = await _utam_get_outputFieldContent(driver, root, );
        element = new ContainerCtor(driver, element);
        return element;
}
```

From the test, we can load any page object inside our container.

```js
const textFieldPageObject = await myPageObject.getOutputFieldContent(TextField);
```

If the selector inside the container is marked with `"returnAll": true`, the generated container method returns an array (in JavaScript) or a list (in Java) of objects.

### Elements nested inside container

Container can have nested elements if it mimics component code, for example when source component provides default content of the slot. In most cases container does not have nested elements.

For example if component has following code that puts default content inside slot:

```html
<template if:false="{showThankYou}">
  <slot>
    <div class="form-icon">
      <lightning-icon icon-name="utility:form"></lightning-icon>
    </div>
  </slot>
</template>
```

then UTAM Page Object can have following nested element:

```json
{
  "name": "content",
  "type": "container",
  "public": true,
  "elements": [
    {
      "name": "utilityIcon",
      "selector": { "css": "lightning-icon" },
      "public": true,
      "type": "utam-lightning/pageObjects/icon"
    }
  ]
}
```

## Frame Elements

To load a frame or an iframe, use a frame element with the following properties:

- `name` (Required) String. The element name, which UTAM uses in the getter method name. The value must be unique within the JSON file.
- `type` (Required) String. Set to `frame` and extends Basic element type.
- `public` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a public method that returns an instance of the element with the given type. The name of the getter is generated automatically from the `name` property as `get<Name>` (the value of the `name` property is capitalized).
- `selector` (Required) Object. Locates the element inside its immediate parent. See [Selector properties](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-selectors.md#selector-properties). Note that `returnAll` inside a selector isn't allowed for a frame.
- `nullable` (Optional, default is `false`). Boolean. If set to `true` and the element can't be found inside its parent, the getter method returns `null`. If set to `false`, an error is thrown if the element isn't found. For examples, see [Guide: Nullable Versus isPresent](/guide/presence).
- `wait` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a public method that [waits for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#wait-for-an-element).
- `load` (Optional, default is `false`) Boolean. If set to `true`, UTAM generates a private method that [waits for the element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#load-an-element) and automatically adds it to the [beforeLoad](/grammar/before-load) method of the page object.

Here's an example of a frame element:

```json
{
  "name": "myPublicFrame",
  "public": true,
  "type": "frame",
  "selector": {
    "css": "iframe"
  }
}
```

The generated code returns an object of the special `FrameElement` type that can be used as a parameter in methods to switch between frames.

## Wait for an element

If an element has `wait` set to `true`, UTAM generates a public method that waits for the element with the name `waitFor<ElementName>`.
The method uses [predicate syntax](/grammar/explicit-waits#grammar) and wraps the invocation of the element getter into a fluent wait.

For example for the following element:

```json
{
  "name": "mySlowElement",
  "selector": {
    "css": ".slow"
  },
  "wait": true
}
```

The generated JavaScript code is:

```js
async waitForMySlowElement() {
    const _result0 = await this.waitFor(async () => {
        const _result0 = await this.__getMySlowElement();
        return _result0;
    });
    return _result0;
}
```

If marked as `public`, the element will have both public getter and `waitFor` methods.

## Load an element

If an element has `load` set to `true`, UTAM generates a private method that waits for the element with the name `waitFor<ElementName>`.
The method uses [predicate syntax](/grammar/explicit-waits#grammar) and wraps the invocation of the element getter into a fluent wait.
This wait method is then automatically invoked in the page object's [beforeLoad](/grammar/before-load) method.

For example for the following element:

```json
{
  "name": "mySlowElement",
  "selector": {
    "css": ".slow"
  },
  "load": true
}
```

The generated JavaScript code is:

```js
async __waitForMySlowElement() {
    const _result0 = await this.waitFor(async () => {
        const _result0 = await this.__getMySlowElement();
        return _result0;
    });
    return _result0;
}

async __beforeLoad__() {
    await this.__waitForMySlowElement();
}

```

**note:** If the `wait` property for this element is also set to true, the `waitFor<ElementName>` method will also be public.
Additionally, `load` can't be set to true for an element with arguments or a container element.

<!-- document id=a3f6a9b1b03eaf9fc482d0af1e17258c5c5b5031b0eb2eadc7ed7b39648401aa url=/developer/current/en-us/lwc/utam/guide/page-load-interception.md -->

# Page Object Load Interception

For a page to be ready for further interaction after loading, we often must wait for an event, such as DOM is ready, or for the presence of an element indicating that loading is complete.

By default, the load method **finds** a root element inside its parent. For a root page object (located directly in the driver or browser root), the default behavior is to **wait** for the root element to become present.
You can override the default method that is invoked when a page object is loaded.

The load method is `__beforeLoad__()` in JavaScript or `load()` in Java. It's invoked every time a page object is created:

- when `UtamLoader.load` is invoked for a root page object
- when an instance is created inside an enclosing parent by invoking a getter method (for example `parent.getMyPageObject()`)

Now, let's look at some examples of overriding the default loading by using `beforeLoad` in a page object. The `beforeLoad` array sets the criteria to be satisfied before the load method completes.

**important:** Statements inside the `beforeLoad` array can reference only `root` or `document` elements because other elements aren’t loaded yet.

## Wait for DOM readyState

Set the `apply` method as `waitForDocumentReady` to exit from the method only when the DOM is "ready" (`document.readyState === 'complete'`).

```json
{
  "beforeLoad": [
    {
      "element": "document",
      "apply": "waitForDocumentReady"
    }
  ]
}
```

**tip:** Functionality related to browser interactions like navigation, entering and exiting frames, or waiting for DOM state is a part of the Document object and is described in the [JSON grammar reference](/docs/platform/utam/references/utam-grammar/grammar.html).

## Wait for Navigation to a URL

This example is relevant if the page we're loading is associated with a URL.

```json
{
  "beforeLoad": [
    {
      "element": "document",
      "apply": "waitFor",
      "args": [
        {
          "type": "function",
          "predicate": [
            {
              "element": "document",
              "apply": "getUrl",
              "matcher": {
                "type": "stringContains",
                "args": [
                  {
                    "value": "my/homePage"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

## Wait for a Spinner to Disappear

Consider the use case of a user creating a record and clicking a save button. While the transaction completes and the next page loads, a spinning wheel is displayed.

This example waits for the spinning element to no longer be present **directly in the driver root**.

```json
{
  "beforeLoad": [
    {
      "element": "document",
      "apply": "waitFor",
      "args": [
        {
          "type": "function",
          "predicate": [
            {
              "element": "document",
              "apply": "containsElement",
              "args": [
                {
                  "value": { "css": "my-spinner" },
                  "type": "locator"
                }
              ],
              "matcher": {
                "type": "isFalse"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

The predicate in the `waitFor` statement has to return a truthy value (not null, not false and doesn’t throw) for the method to complete without an error.

## Wait for a Page Object to Contain an Element

This example waits for the `root` element to contain an element with the given selector inside its shadowRoot.

```json
{
  "beforeLoad": [
    {
      "apply": "waitFor",
      "args": [
        {
          "type": "function",
          "predicate": [
            {
              "element": "root",
              "apply": "containsElement",
              "args": [
                // first arg - selector to search for
                {
                  "value": { "css": "i-am-slow" },
                  "type": "locator"
                },
                // second arg - expand the shadow root of the parent
                { "value": true }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

<!-- document id=874a5eab4e5136cbe16f8f249342d90b7116fb13988945b54a6aacc0d7b6053f url=/developer/current/en-us/lwc/utam/references/root-elements.md -->

# Page Object Root

Any page object that is unique inside the current browser view can be used as a root. A root page object can be loaded directly inside the browser.

## Root Properties

The root of a page object can contain these properties:

- `elements` (Optional) Array. A nested tree of element objects. An element object can be one of these types:
  - [Basic element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#basic-elements)&mdash;A UI element required for user interaction or to scope another element.
  - [Custom element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#custom-elements)&mdash;A nested page object.
  - [Container element](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#container-elements)&mdash;A `slot` or `div` into which other components are injected.
- `methods` (Optional) Array. Each object declares a public method. The only supported method type is `compose`. A [compose method](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/methods.md) combines several element actions, like clearing a text field (`clear`) and entering a value (`setText`).
- `root` (Optional) Boolean. To load a page object from a test, set `root` to `true` and add a `selector` element that points to its most outer (root) element. If a component can be loaded only inside its immediate parent (for example, a navigation item can be loaded only inside a navigation bar), don’t mark it as `root`.
- `selector` (Optional) Object. If `root` is `true`, add a `selector` that points to its most outer (root) element. The root selector must match the HTML tag name. See [selector](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-selectors.md).
- `shadow` (Optional) Object. A shadow boundary at the root of the page object. Contains only an `elements` property, which is a nested tree of objects. A page object can have `elements` scoped both inside and outside its shadow root.
- `exposeRootElement` (Optional) Boolean. See [Actionable Root](#actionable-root-element).
- `type` (Optional) String. See [Actionable Root](#actionable-root-element).
- `description` (Optional) String or Object. See [Page Object Description](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/descriptions-metadata.md#page-object-description).
- `metadata` (Optional) Object. See [Page Object Metadata](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/descriptions-metadata.md#page-object-metadata).
- `platform` (Optional) String. See [Platform Context](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/platform-context.md).
- `beforeLoad` (Optional) Array. See [beforeLoad](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/beforeload.md).

Here's a sample outline of a page object.

```json
{
  "elements": [],
  "methods": [],
  "shadow": {
    "elements": []
  },
  "root": true,
  "selector": {
    "css": "one-record-home"
  }
}
```

## Actionable Root Element

To make the root element actionable, expose it via a public method. Add these properties to the root element:

- `exposeRootElement` Boolean. If set to `true`, UTAM creates a public method that returns an instance of the element with the given type. The name of the getter is `getRoot`.
- `type` (Optional) See [basic element types](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/page-object-elements.md#basic-elements).

```json
{
  "exposeRootElement": true,
  "type": ["editable"],
  "elements": [],
  "methods": []
}
```

The UTAM generator converts this JSON into a public method. The method returns an instance of the page object root element for the test to interact with.

```js
async getRoot() {
    const driver = this.driver;
    const root = await this.getRootElement();
    return new _EditableUtamElement(driver, root);
}
```

**note:** The word `root` is reserved and can't be used as an element name.

<!-- document id=3847def792e149f59c2d67c259349e3e2e0a46a449480d4087471fe18c60cda1 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-page-reference-type.md -->

# PageReference Types

To navigate in Lightning Experience, Experience Builder sites, or the Salesforce mobile app, define a `PageReference` object. The `PageReference` type generates a unique URL format and defines attributes that apply to all pages of that type. For Experience Builder sites, depending on the page type, the `PageReference` property requirements can differ between LWR sites and Aura sites.

**tip:** Use the `PageReference` object with the `NavigationMixin` function from the `lightning/navigation` module. For information about using a PageReference to navigate, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

These page reference types are supported.

- App
- External Record Page
- External Record Relationship Page
- Knowledge Article
- Lightning Component
- Login Page
- Managed Content Page (Salesforce CMS)
- Named Page (Experience Builder sites)
- Named Page (Standard)
- Navigation Item Page
- Object Page
- Quick Action Page Type
- Record Page
- Record Relationship Page
- Standard Flow
- Web Page

**note:** `PageReference` objects are supported on a limited basis for Experience Builder sites, as noted for each type. They aren’t supported in Lightning Out 2.0 and Lightning Out (beta).

Navigating using the `PageReference` objects supersedes the legacy way of using an Aura event to navigate. For example, navigate to web pages using the `lightning/navigation` module with the `standard__webPage` page type instead of using `force:navigateToURL`. See [Migrate Events](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-events.md).

## App Type

A standard or custom app available from the App Launcher in an org. Use this type to create custom navigation components that take users to a specific app or to a page within an app. Connected apps aren’t supported.

**note:** If you’re navigating users to a different app using a `pageRef`, the app opens in the same window by default. To open a link in a new tab, see the [navigation service documentation](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-basic.md).

### Type

```javascript
standard__app;
```

### Containers

Lightning Experience

### Type Attributes

| Property    | Type          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Retired? |
| ----------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `appTarget` | String        | App that you're navigating to. Pass either the `appId` or `appDeveloperName` to the `appTarget`. <ul><li>The `appId` is the `DurableId` field on the `AppDefinition` object.</li><li>To form the `appDeveloperName` value, concatenate the app's namespace with the developer name. To find the app's developer name, navigate to the App Manager in Setup and look in the Developer Name column.</li></ul> For standard apps, the namespace is `standard__`. For custom apps, it's `c__`. For managed packages, it's the namespace registered for the package. | Yes      |
| `pageRef`   | PageReference | Identifies a specific location in the app you're navigating to. Pass in the `pageRef` and applicable attributes for that `pageRef` type.                                                                                                                                                                                                                                                                                                                                                                                                                        | No       |

### Example Navigating to an App

```javascript
{
    type: 'standard__app',
    attributes: {
        appTarget: 'standard__Sales',
    }
}
```

### Example Navigating to a Record in an App

```javascript
{
    type: 'standard__app',
    attributes: {
        appTarget: 'standard__LightningSales',
        pageRef: {
            type: 'standard__recordPage',
            attributes: {
                recordId: '001xx000003DGg0AAG',
                objectApiName: 'Account',
                actionName: 'view'
            }
        }
    }
}
```

### URL Format

```html
/lightning/app/{appTarget}{...pageRef}
```

### URL Format Examples

Navigate to the app’s homepage using the `appId`

```html
/lightning/app/06mRM0000008dNrYAI
```

Navigate to an object record’s page in the app using the `appId`

```html
/lightning/app/06mRM0000008dNrYAI/o/Case/home
```

Navigate to the app’s homepage using the `appDeveloperName`

```html
/lightning/app/standard__LightningSales
```

Navigate to an object record’s page in the app using the `appDeveloperName`

```html
/lightning/app/standard__LightningSales/o/Case/home
```

## External Record Page Type

A page that interacts with an external record. Currently supports CMS Connect pages.

### Type

```javascript
comm__externalRecordPage;
```

### Experience

Experience Builder Aura Sites

### Type Attributes

| Property     | Type   | Description                                                              | Required? |
| ------------ | ------ | ------------------------------------------------------------------------ | --------- |
| `recordId`   | String | External record ID.                                                      | Yes       |
| `objectType` | String | External record type. Currently only supports `cms` for CMS Connect.     | Yes       |
| `objectInfo` | Object | Additional information used to identify the record for the `objectType`. | Yes       |

### Example

```javascript
{
    type: "comm__externalRecordPage",
    attributes: {
        recordId: "26",
        objectType: "cms",
        objectInfo: {
            cmsSourceName: "blog",
            cmsTypeName: "feed",
        }
    },
    state: {
        recordName: "coffee-on-the-world-map",
    }
}
```

### URL Format

```html
/{baseUrl}/{recordId}/{recordName}
```

## External Record Relationship Page Type

A page that interacts with an external relationship on a particular record in the org. Currently only supports Quip Related List page.

### Type

```javascript
comm__externalRecordRelationshipPage;
```

### Experience

Experience Builder Aura Sites

### Type Attributes

| Property     | Type   | Description                                                         | Required? |
| ------------ | ------ | ------------------------------------------------------------------- | --------- |
| `recordId`   | String | The 18 character record ID.                                         | Yes       |
| `objectType` | String | External record type. Currently only supports `quip` for Quip docs. | Yes       |

### Example

```javascript
{
    type: "comm__externalRecordRelationshipPage",
    attributes: {
        recordId: "001xx000003DGg0AAG",
        objectType: "quip",

```

### URL Format

```html
/{baseUrl}/{recordId}
```

## Lightning Component Type

A Lightning web component or [Aura component](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation_page_definitions.htm#lightning-component-type). To make an addressable Lightning web component, use the `lightning__isUrlAddressable` target with the `lightning__AppPage` target. The `lightning__AppPage` target enables the component to be used on an app page, which is displayed when you navigate to `/lightning/cmp/c__componentName`.

### Type

```javascript
standard__component;
```

### Containers

Lightning Experience, Salesforce Mobile App

### Attributes

| Property        | Type   | Description                                                            | Required |
| --------------- | ------ | ---------------------------------------------------------------------- | -------- |
| `componentName` | String | The Lightning component name in the format `namespace__componentName`. | Yes      |

### Example

```javascript
{
    type: 'standard__component',
    attributes: {
        componentName: 'c__MyComponent'
    },
    state: {
        c__counter: '5'
    }
}
```

You can pass any key and value in the `state` object. The key must include a namespace, and the value must be a string. When you include the `state` like in the example, the URL format is `/lightning/cmp/c__MyComponent?c__counter=5`. The component name is case-sensitive. For more information, see [Navigate to a URL-Addressable Component](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-url-addressable.md).

## Knowledge Article Page Type

A page that interacts with a Knowledge Article record.

### Type

```javascript
standard__knowledgeArticlePage;
```

### Containers

Lightning Experience, Experience Builder sites, Salesforce Mobile App

### Attributes

| Property      | Type   | Description                                                                                                        | Required |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | -------- |
| `articleType` | String | The `articleType` API name of the Knowledge Article record.In Experience Builder sites, `articleType` is ignored.  | Yes      |
| `urlName`     | String | The value of the `urlName` field on the target KnowledgeArticleVersion record. The `urlName` is the article's URL. | Yes      |

### Example

```javascript
{
    type: 'standard__knowledgeArticlePage',
    attributes: {
        articleType: 'Briefings',
        urlName: 'February-2017'
    }
}
```

## Login Page Type

A page for authentication into an Experience Builder site.

### Type

```javascript
comm__loginPage;
```

### Containers

Experience Builder sites

### Attributes

| Property     | Type   | Description                                                                                            | Required |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------ | -------- |
| `actionName` | String | A login-related action to be performed. Possible values are:<ul><li>`login`</li><li>`logout`</li></ul> | Yes      |

### Example

```javascript
{
    type: 'comm__loginPage',
    attributes: {
        actionName: 'login'
    }
}
```

## Managed Content Page (Salesforce CMS) Type

A CMS content page in an Experience Builder site with a unique name.

### Type

```javascript
standard__managedContentPage;
```

### Containers

Experience Builder sites

### Attributes

| Property          | Type   | Description                                         | Required |
| ----------------- | ------ | --------------------------------------------------- | -------- |
| `contentTypeName` | String | The name of the Salesforce CMS content type.        | Yes      |
| `contentKey`      | String | The unique content key that identifies CMS content. | Yes      |

### Example

```javascript
{
    type: 'standard__managedContentPage',
    attributes :{
        'contentTypeName': 'news',
        'contentKey': 'MCOMALJDRAYFFSFPNBQONYXVFHOA'
    }
}
```

## Named Page Type (Experience Builder Sites)

A standard page used in Experience Builder sites with a unique name. If an error occurs, the error view loads and the URL isn’t updated.

### Type

```javascript
comm__namedPage;
```

### Containers

Experience Builder sites

### Attributes

| Property | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Required |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`   | String | The unique name of the Experience Builder page. The value for `name` is the **API Name** value for a supported page. The **API Name** field can only be defined when a new page is being created, and must be unique. If the **API Name** isn’t defined upon page creation, it’s automatically generated. The value of `home` is reserved for the landing page of any Experience Builder site in your org. Supported pages in Experience Builder sites are: <ul><li>Home</li><li>Account Management</li><li>Contact Support</li><li>Error</li><li>Login</li><li>My Account</li><li>Top Articles</li><li>Topic Catalog</li><li>Custom page</li></ul> | Yes      |

### Example

```javascript
{
    type: 'comm__namedPage',
    attributes: {
        name: 'Home'
    }
}
```

## Named Page Type (Standard)

A standard page with a unique name. If an error occurs, the error view loads and the URL isn’t updated.

### Type

```javascript
standard__namedPage;
```

### Containers

Lightning Experience, Salesforce Mobile App

### Attributes

| Property   | Type   | Description                                                                                                                                                | Required |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `pageName` | String | The unique name of the page. Possible values are:<ul><li>`home`</li><li>`chatter`</li><li>`today`</li><li>`dataAssessment`</li><li>`filePreview`</li></ul> | Yes      |

### Example

```javascript
{
    type: 'standard__namedPage',
    attributes: {
        pageName: 'home'
    }
}
```

## Navigation Item Page Type

A page that displays the content mapped to a custom tab. Visualforce tabs, web tabs, Lightning Pages, and Lightning Component tabs are supported.

### Type

```javascript
standard__navItemPage;
```

### Containers

Lightning Experience, Salesforce Mobile App

### Attributes

| Property  | Type   | Description                        | Required |
| --------- | ------ | ---------------------------------- | -------- |
| `apiName` | String | The unique name of the custom tab. | Yes      |

### Example

```javascript
{
    type: 'standard__navItemPage',
    attributes: {
        apiName: 'MyCustomTabName'
    }
}
```

For an example, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

## Object Page Type

A page that interacts with a standard or custom object in the org and supports standard actions for that object.

### Type

```javascript
standard__objectPage;
```

### Containers

Lightning Experience, Experience Builder sites, Salesforce Mobile App

### Attributes

| Property        | Type   | Description                                                                                                                                 | Required |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `actionName`    | String | The action name to invoke. Valid values include `home`, `list`, and `new`.In Experience Builder sites, `list` and `home` are the same.      | Yes      |
| `objectApiName` | String | The API name of the standard or custom object. For custom objects that are part of a managed package, prefix the custom object with `ns__`. | Yes      |

### State

| Property             | Type   | Description                                                                                                                                                                                                                                                                                       | Required? |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `filterName`         | String | ID or developer name of the object page. Default is `Recent`. Supported actions are: `list`.                                                                                                                                                                                                      | No        |
| `defaultFieldValues` | String | List of key-value pairs for the default field values that you’re passing. This list is generated by the [`lightning/pageReferenceUtils`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-page-reference-utils) module. Supported actions are: `new`. | No        |
| `nooverride`         | String | To use a standard action, assign this property any value, such as `1`. To use an override action, don’t include this property at all. Supported actions are: `home`, `list`, `new`.                                                                                                               | No        |

### Standard Object Example

```javascript
// Opens the case home page.
{
    type: 'standard__objectPage',
    attributes: {
        objectApiName: 'Case',
        actionName: 'home'
    }
}
```

For an example, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

### Navigate to a Specific List View Example

```javascript
// Navigates to account list with the filter set to Recent.
{
    type: 'standard__objectPage',
    attributes: {
        objectApiName: 'ns__Widget__c',
        actionName: 'list'
    },
    state: {
        filterName: 'Recent'
  }
}
```

### Navigate to a Record Create Page with Default Field Values

```javascript
// Navigates to a new account page using these default field values:
//{
//    Name: 'Salesforce, #1=CRM',
//    OwnerId: '005XXXXXXXXXXXXXXX',
//    AccountNumber: 'ACXXXX',
//    NumberOfEmployees: 35000,
//    CustomCheckbox__c: true
//}
{
    type: 'standard__objectPage',
    attributes: {
        objectApiName: 'Account',
        actionName: 'new'
    },
    state: {
        defaultFieldValues : 'AccountNumber=ACXXXX,CustomCheckbox__c=true,Name=Salesforce%2C%20%231%3DCRM,NumberOfEmployees=35000,OwnerId=005XXXXXXXXXXXXXXX',
        nooverride: '1'
    }
}
```

## Quick Action Page Type

A Lightning record page that invokes a standard or custom quick action.

### Type

```javascript
standard__quickAction;
```

### Containers

Lightning Experience

### Attributes

| Property  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Required |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `apiName` | String | The API name of the quick action. For object-specific quick actions, prefix with the object name (like `Account.CreateContact`). For global quick actions, prefix with `Global.` (such as `Global.SendEmail`). To see a list of API names for an object, query the [`PlatformAction`](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_platformaction.htm) object. For example, the query `Select ApiName FROM PlatformAction WHERE SourceEntity IN ('Contact') AND Type ='QuickAction' AND ActionListContext= 'Record'` returns a list of API names for the quick actions available on contacts. | Yes      |

### State

| Property             | Type   | Description                                                                                                                                                                  | Required |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `recordID`           | String | If a quick action executes inside a record page, the `state` object automatically sets `recordId` to that record number. Otherwise, you have to manually set `recordID`.     | No       |
| `defaultFieldValues` | Object | Use this object to pre-populate fields for the `Global.SendEmail` quick action. Make sure the fields you want to pre-populate aren't read-only in the quick action's layout. | No       |

### Example

```javascript
{
    type: 'standard__quickAction',
    attributes: {
        apiName: 'Global.SendEmail'
    },
    state: {
        recordId: '001xx000003DGg0AAG',
        defaultFieldValues: encodeDefaultFieldValues({
            Subject: 'Pre-populated Subject',
            HtmlBody: 'Pre-populated email body'
        })
    }
}
```

For an example, see [Create an Email as a Quick Action](https://developer.salesforce.com/docs/platform/lwc/use/use-quick-actions-email.md). To learn how to create a quick action from Salesforce Setup, see [_Salesforce Help_: Quick Actions](https://help.salesforce.com/s/articleView?id=platform.actions_overview.htm). Learn how to configure a Lightning web component for a quick action in [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-quick-actions.md)

## Record Page Type

A page that interacts with a record in the org and supports standard actions for that record.

### Type

```javascript
standard__recordPage;
```

### Containers

Lightning Experience, Experience Builder sites, Salesforce Mobile App

### Attributes

| Property        | Type   | Description                                                                                                                                      | Required                                                                                                    |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `actionName`    | String | The action name to invoke. Valid values include `clone`, `edit`, and `view`.Experience Builder sites don’t support the values `clone` or `edit`. | Yes                                                                                                         |
| `objectApiName` | String | The API name of the record’s object. Optional for lookups.                                                                                       | <ul><li>For Experience Builder LWR sites only: **yes**.</li><li>For all other containers: **no**.</li></ul> |
| `recordId`      | String | The 18 character record ID.                                                                                                                      | Yes                                                                                                         |

- State

| Property     | Type   | Description                                                                                                                           | Required? |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `nooverride` | String | To use a standard action, assign this property any value, such as `1`. To use an override action, don’t include this property at all. | No        |

### Example: Navigate to a Record Page

```javascript
{
        type: 'standard__recordPage',
        attributes: {
            recordId: '001xx000003DGg0AAG',
            objectApiName: 'PersonAccount',
            actionName: 'view'
        }
}
```

For an example, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

## Record Relationship Page Type

A page that interacts with a relationship on a particular record in the org. Only related lists are supported.

### Type

```javascript
standard__recordRelationshipPage;
```

### Containers

Lightning Experience, Experience Builder sites, Salesforce Mobile App

### Attributes

| Property              | Type   | Description                                                                     | Required                                                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `actionName`          | String | The action name to invoke. Only `view` is supported.                            | Yes                                                                                                         |
| `objectApiName`       | String | The API name of the object that defines the relationship. Optional for lookups. | <ul><li>For Experience Builder LWR sites only: **yes**.</li><li>For all other containers: **no**.</li></ul> |
| `recordId`            | String | The 18 character record ID of the record that defines the relationship.         | Yes                                                                                                         |
| `relationshipApiName` | String | The API name of the object’s relationship field.                                | Yes                                                                                                         |

### Example

```javascript
{
    type: 'standard__recordRelationshipPage',
    attributes: {
        recordId: '500xx000000Ykt4AAC',
        objectApiName: 'Case',
        relationshipApiName: 'CaseComments',
        actionName: 'view'
    }
}
```

For an example, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

## Standard Flow Type

A page that runs an active screen or autolaunched flow.

### Type

```javascript
standard__flow;
```

### Containers

Lightning Experience

### Type Attributes

| Property  | Type   | Description                                                   | Required? |
| --------- | ------ | ------------------------------------------------------------- | --------- |
| `devName` | String | The flow name (`flowName` or `namespace__flowName`).          | Yes       |
| `retURL`  | String | The relative URL to redirect users to when the flow finishes. | No        |

### Example

You can pass input variable values to the flow in the state object. The key must be prefixed by `flow__`. Record variables, Apex-Defined variables, and collection variables are not supported.

```javascript
{
"type": "standard__flow",
"attributes": {
    "devName": "MyFlow"
},
"state": {
    "flow__myInputVar": "inputVarValue"
    "retURL" : "lightning/page/home"
}
}
```

### URL Format

```
/lightning/flow/{flowName}?flow__myInputVar=inputVarValue&retUrl=lightning%2Fpage%2Fhome
```

## Web Page Type

An external URL.

**tip:** If you use your Lightning web component in an Aura-based Experience Builder site, note that certain Salesforce URLs have site-specific processing. For example, `/apex/` URLs are translated to `/sfdcpage/`. The Visualforce page is embedded within the site in an iframe, which is the same behavior as with [the `force:navigateToURL` Aura event](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-events.md). Use `window.open` if you want to go straight to the URL, such as opening `/apex/` directly in a new tab.

### Type

```javascript
standard__webPage;
```

### Containers

Lightning Experience, Experience Builder sites, Salesforce Mobile App

### Attributes

| Property | Type   | Description                               | Required |
| -------- | ------ | ----------------------------------------- | -------- |
| `url`    | String | The URL of the page you’re navigating to. | Yes      |

### Example

```javascript
{
    type: 'standard__webPage',
    attributes: {
        url: 'http://salesforce.com'
    }
}
```

For an example, see [Navigate to Different Page Types](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-page-types.md).

**See Also**

- [Navigate to Pages, Records, and Lists](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate.md)
- [Open Files](https://developer.salesforce.com/docs/platform/lwc/use/use-open-files.md)
- [Component Reference: lightning-navigation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-navigation)
- [LWR Sites for Experience Cloud: Lightning Navigation](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_comp_navigation.htm)

<!-- document id=23ff4e80edcda0e373c0efffb297fbf3adb288737bd8af4150d96c179e0469eb url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-pagination.md -->

# Pagination

Page through your query results and control the number of results you want to return each time.

The GraphQL wire adapter follows the [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm) for pagination.

To specify the number of records to return, use the `first` argument. The default number is 10.

If `hasNextPage` is true, you can supply the value of `endCursor` to the `after` argument of a subsequent query to request the next page of results.

**note:** Backward pagination arguments `last` and `before` are currently not supported.

To create a query with cursor information, use the [`query` parameter of the GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md).

```javascript
query operationName {
  uiapi {
    query {
      Account (first: 8, after: "endCursorFromPreviousQuery") {
        edges {
          node {
            Id
            Name {
              value
            }
          }
        }
        totalCount
        pageInfo {
          endCursor
          startCursor
          hasNextPage
          hasPreviousPage
        }
      }
    }
  }
}
```

This example response contains cursor information.

```nolang
{
  "data": {
    "uiapi": {
      "query": {
        "Account": {
          "edges": [
            {
              "node": {
                "Id": "001RM000005ZclBYAS",
                "Name": {
                  "value": "GenePoint"
                }
              }
            },
            {
              "node": {
                "Id": "001RM000005Zcl6YAC",
                "Name": {
                  "value": "United Oil"
                }
              }
            }
          ], // 6 more node objects here removed for brevity
          "totalCount": 8,
          "pageInfo": {
            "endCursor": "djE6Nw==",
            "startCursor": "djE6MA==",
            "hasNextPage": true,
            "hasPreviousPage": false
          }
        }
      }
    }
  },
  "errors": []
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many GraphQL API examples. Look for components that start with `graphql`, such as [graphqlPagination](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/graphqlPagination).

**See Also**

- [_GraphQL API Developer Guide_: Pagination](https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html#pagination)
- [_GraphQL API Developer Guide_: Use GraphQL API with Lightning Web Components](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html)

<!-- document id=bcf35427717f532507a48c9a2aab78ad31db923f727e7e60c8cb3646d26f345e url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-attributes.md -->

# Pass Configuration and Data to a Base Component

While many base components use slots to display content, some require you to pass configuration information and data to an attribute on a base component. Let's compare these two different approaches below.

**note:** For simple and maintainable code, we recommend using slots. For more information about slots, see [Pass Markup to a Base Component Slot](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-slot.md).

## Using the Attributes Pattern

Attributes enable you to configure the base component to achieve specific behaviors. Base components that use the attributes pattern result in a flatter structure in the template. For example, you use the [`lightning-map`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-map) base component like this. Notice that the `map-markers` attribute takes in the map configuration information.

<!-- prettier-ignore -->
```html
<template>
    <lightning-map map-markers={mapMarkers}> </lightning-map>
</template>
```

However, using the attributes pattern in some cases can lead to complex code. For example, if [`lightning-button-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-group/) uses an attribute to pass in button configuration information, your code can be hard to read and maintain. In this case, you pass in the configuration information to the `lightning-button-group` component. And you pass the data and metadata for each button in the group as an object. Finally, you pass an array of these objects into an attribute on the button group component.

```javascript
// Don't do this
config = [
       {
          label: "Refresh",
       },
       {
          label: "Edit",
       },
       {
          label: "Save",
          iconName: "utility:save",
          iconPosition: "end"
       },
	     {  label: "Edit"  }
       {
          type: "button-menu",
          iconName: "utility:down"
          items: [
               ...
           ]
       }
   ]
```

Since there are many base components that are button-based, such as the `lightning-button-icon-stateful` and `lightning-button-stateful`, the attribute for the configuration information must support that and its metadata as well. This can increase code complexity and impact code readability. That's why `lightning-button-group` and many other base components uses the [composition structure](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-compose.md) instead.

Using an attribute can be helpful in certain cases, as shown by base components such as [`lightning-checkbox-group`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-group) and [`lightning-select`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select). Generally, consider using an attribute if you want:

- Granular control for rendering elements within the component
- Easier validation checks on the metadata
- Rendering of native HTML inline for performance boost

## Rendering of Native HTML Inline

Rendering native HTML inline can provide a performance boost, especially if you want to render the same element many times within a base component.

The `lightning-select` base component uses the `<select>` element and iteratively renders each option based on the configuration you provide. The base component internal markup looks like this, shortened for brevity.

<!-- prettier-ignore -->
```html
<!-- lightning-select -->
<!-- For demonstrative purposes -->
<div class="slds-form-element__control">
    <div class="slds-select_container">
        <select
            autocomplete={autocomplete}
            class="slds-select"
            disabled={disabled}
            id="select"
            multiple={multiple}
            name={name}
            onblur={handleBlur}
            onchange={handleChange}
            onfocus={handleFocus}
            required={required}
            accesskey={accessKey}
            size={size}
            aria-invalid={computedAriaInvalid}
            part="select">
            <template for:each={options} for:item="option">
                <template if:true={option.disabled}>
                    <option disabled key={option.value} value={option.value}>{option.label}</option>
                </template>
                <template if:false={option.disabled}>
                    <option key={option.value} value={option.value}>{option.label}</option>
                </template>
            </template>
        </select>
    </div>
</div>
```

**note:** Base components' internal markup is for demonstrative purposes only. The markup is an internal implementation that can change anytime.

When you use `lightning-select` in your custom component, the base component renders this markup in the DOM.

```html
<select class="slds-select" id="select-3" name="tickets" part="select">
  <option value="">choose quantity...</option>
  <option value="1">one</option>
  <option value="2">two</option>
  <option value="3">three</option>
</select>
```

In this case, providing an attribute for passing in configuration information and data allows developers to work with a flatter component surface.

**See Also**

- [Base Component Composition](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-compose.md)

<!-- document id=b35b27a7b37c06c0939c919418d0aa285a721e3563fe0778e0641d6fd1a21cbf url=/developer/current/en-us/lwc/lwc/guides/create/create-use-third-party-pass-data.md -->

# Pass Data to a Custom Element

Custom elements are the building blocks of third-party web components. Pass data to a custom element using an attribute, property, or the [`lwc:spread` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-spread-properties.md). When passing data, LWC sets the data as attributes by default, and sets properties only if they exist.

The constructor that initializes your shadow content using `this.attachShadow({ mode: 'closed' })` is only invoked once. Consider these guidelines when working with an attribute or property.

## Pass Data Using An Attribute

After a third-party web component is rendered, attribute changes are ignored. To observe attributes and ensure the third-party web component renders your changes, use the `observedAttributes()` static getter and `attributeChangedCallback()` method. The `attributeChangedCallback()` callback runs when an observed attribute is changed. To handle serializing and deserializing of the attribute data, use a getter and setter such as in this example.

```javascript
class extends HTMLElement {
    static observedAttributes = ["myAttr"];
    attributeChangedCallback(attr, oldVal, newVal) {
      if (attrName === "myAttr") {
        this.shadow.getElementById("myElement").myAttr = newVal === "true";
      }
    }
    set myAttr(bool) {
      this.setAttribute("myAttr", bool.toString());
    }
    get myAttr() {
      return this.getAttribute("myAttr") === "true";
    }
}
```

See [an example](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-custom-elements.md) that increments a button with an attribute change.

## Pass Data Using Properties

To work with properties, use a getter and setter.

```javascript
class extends HTMLElement {
  _message = 'Hello';
  set message(value) {
    this._message = value;
  }
  get message() {
    return this._message;
  }
}
```

For example, you have a custom element with a property that's passed to the custom element using the [`lwc:spread` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-spread-properties.md).

<!-- prettier-ignore -->
```html
<!-- myMessage.html -->
<template>
  <c-message lwc:external lwc:spread={props}></c-message>
</template>
```

The custom element displays a button. To add an event listener to the button, use `addEventListener()`.

```javascript
// myMessage.js
import { LightningElement } from "lwc";

customElements.define(
  "c-message",
  class extends HTMLElement {
    constructor() {
      super();
      this.shadow = this.attachShadow({ mode: "closed" });
      this.shadow.innerHTML = `<button>click</button>`;
      this.shadow.querySelector("button").addEventListener("click", (event) => {
        console.log(`message: ${this.message}`);
      });
    }

    set message(value) {
      this._message = value;
    }
    get message() {
      return this._message;
    }
  },
);

export default class MyMessage extends LightningElement {
  props = {
    message: "Hello custom element",
  };
}
```

## Pass Data to a Child Component

Consider a parent component that contains a child component that defines a custom element. Pass the properties to a child component using the [`lwc:spread` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-spread-properties.md).

<!-- prettier-ignore -->
```html
<!-- myApp.html -->
<template>
  <c-cmp lwc:spread={myProps}></c-cmp>
</template>
```

Use an object with key-value pairs.

```javascript
// myApp.js
import { LightningElement } from "lwc";

export default class MyApp extends LightningElement {
  myProps = {
    name: "Guest",
    greeting: "Hello",
  };
}
```

In your child component, create an instance of the custom element.

```html
<!-- myCmp.html -->
<template>
  <c-custom-el lwc:external> {greeting}, {name} </c-custom-el>
</template>
```

Call the `constructor()` in your JavaScript and expose your properties to the parent component.

```javascript
// myCmp.js
import { LightningElement, api } from "lwc";

customElements.define(
  "c-custom-el",
  class extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "closed" }).innerHTML = "<slot></slot>";
    }
  },
);
export default class MyCmp extends LightningElement {
  @api name;
  @api greeting;
}
```

The custom element renders like this.

<!-- prettier-ignore -->
```html
<my-app>
  #shadow-root (open)
  |  <my-cmp> 
  |    #shadow-root (open) 
  |    |  <c-custom-el>
  |    |    #shadow-root (closed)
  |    |    | Hello, Guest
  |    |  </c-custom-el>
  |  </my-cmp>
</my-app>
```

## Pass Markup to a Slot in the Custom Element

Passing markup to a slot in a third-party web component behaves similarly to [a slot in an LWC component](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md).

**note:** Slotting implementation for synthetic shadow is not supported in third-party web components.

Consider a third-party web component with some markup.

```javascript
customElements.define(
  "c-custom-slot",
  class extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "closed" }).innerHTML = `
    <h1>My title</h1>
    <div>
        <p>Some content here</p>
    </div>
    <slot></slot>
    `;
    }
  },
);
```

The following slotted content appears in the `<slot>` element.

```html
<template>
  <c-custom-slot lwc:external>
    <div class="slotted">slot content</div>
  </c-custom-slot>
</template>
```

The component renders in the DOM like this.

<!-- prettier-ignore -->
```html
<c-custom-slot>
  #shadow-root (closed)
  |  <h1>My title</h1>
  |  <div><p>Some content here</p></div>
  |  <slot>
  |    <div class="slotted">slot content</div>
  |  </slot>
</c-custom-slot>
```

Similarly, you can use a named slot like this.

```javascript
// mySlot.js
import { LightningElement, api } from "lwc";

customElements.define(
  "c-slotting",
  class extends HTMLElement {
    constructor() {
      super();
      this.shadow = this.attachShadow({ mode: "closed" });
      this.shadow.innerHTML = `<slot name="myslot"></slot>`;
    }
  },
);
export default class MySlot extends LightningElement {}
```

Include the named slot in your markup.

```html
<!-- mySlot.html -->
<c-slotting lwc:external>
  <p>slotted incorrectly</p>
  <p slot="myslot">slotted correctly</p>
</c-slotting>
```

The component renders in the DOM like this.

<!-- prettier-ignore -->
```html
<my-slot>
  #shadow-root (open)
  |  <c-slotting>
  |    #shadow-root (closed)
  |    |  <p>slotted incorrectly</p>
  |    |  <p slot="myslot">slotted correctly</p>
  |  </c-slotting>
</my-slot>
```

In native shadow components, slotted content is preserved in top-level `CustomElementConstructor` elements.

For example, this top-level `<slot>` element in an `index.html` file includes slotted content.

<!-- prettier-ignore -->
```html
<c-custom-slot>
  <div class="slotted">Pre-existing slot content</div>
</c-custom-slot>
```

The component renders in the DOM like this. It retains the original slotted content.

<!-- prettier-ignore -->
```html
<c-custom-slot>
  #shadow-root (closed)
  |  <slot>
  |    <div class="slotted">Pre-existing slot content</div>
  |  </slot>
</c-custom-slot>
```

## Work with Events in Third-Party Web Components

Events in third-party web components behave similarly with [events in LWC](https://developer.salesforce.com/docs/platform/lwc/events/events.md). The event bindings support only lowercase events. To use events with non-lowercase names, add an event listener using the [addEventListener() API](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).

Add your event listeners in the `constructor()`.

```javascript
customElements.define(
  "c-element-with-events",
  class extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "closed" });
      this.shadow.innerHTML = `CLICK ME!`;
      this.addEventListener("click", this.handleClick);
    }
    handleClick() {
      this.dispatchEvent(new CustomEvent("lowercaseevent"));
      this.dispatchEvent(new CustomEvent("camelEvent"));
    }
  },
);
```

## Third-Party Web Component Considerations

A custom element that isn't registered renders as an instance of the native `HTMLUnknownElement` interface, which extends `HTMLElement` without adding any properties or methods. The browser then treats the external component as a native component no different from a `span` or a `div`.

For registered components, the engine renders the associated third-party web component and defers the upgrading to the browser.

For more information, see [HTML Spec: Upgrading elements after their creation](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-upgrades-examples).

Additionally, consider these upgrade behaviors on third-party web components.

- If a third-party web component is not upgraded, LWC sets its attributes on mount and on update.
- If there's a delayed upgrade, the attribute is set instead of the property.
- After the upgrade, the property is set instead of the attribute, if the property exists.

**See Also**

- [MDN lifecycle callback examples](https://github.com/mdn/web-components-examples/blob/main/life-cycle-callbacks/main.js)

<!-- document id=2b6970f3c6a9bf1606a51085a8304411b2adb759719adbcf71fede4de06b2ad7 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-slots.md -->

# Pass Markup into Slots

Add a slot to a component’s HTML file so a parent component can pass markup into the component. A component can have zero or more slots.

A slot (`<slot></slot>`) is a placeholder for markup that a parent component passes into a component’s body.

**important:** You can’t pass an Aura component into a slot. If you nest a Lightning web component in an Aura component, you also can’t pass it into a slot.

**note:** To use slots as drop regions in Experience Builder for an LWR site, see [Create Custom Layout Components](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_layout.htm) in the _LWR Sites for Experience Cloud_ guide.

## Unnamed Slots

This example has an unnamed slot. An unnamed slot uses the `<slot>` element as a placeholder for any markup that a parent component passes into the body of `c-slot-demo`.

```html
<!-- slotDemo.html -->
<template>
  <h1>Add content to slot</h1>
  <div>
    <slot></slot>
  </div>
</template>
```

Here’s the markup for a parent component that uses `c-slot-demo`.

```html
<!-- slotWrapper.html -->
<template>
  <c-slot-demo>
    <p>content from parent</p>
  </c-slot-demo>
</template>
```

When `c-slot-demo` is rendered, the unnamed slot is replaced with the markup passed into the body of `c-slot-demo`. Here’s the rendered output of `c-slot-wrapper`.

```html
<h1>Add content to slot</h1>
<div>
  <slot>
    <p>content from parent</p>
  </slot>
</div>
```

If a component has more than one unnamed slot, the markup passed into the body of the component is inserted into all the unnamed slots. However, a component usually has zero or one unnamed slot.

## Named Slots

This example component has two named slots and one unnamed slot.

```html
<!-- namedSlots.html -->
<template>
  <p>First Name: <slot name="firstName">Default first name</slot></p>
  <p>Last Name: <slot name="lastName">Default last name</slot></p>
  <p>Description: <slot>Default description</slot></p>
</template>
```

You can set a dynamic value for the `slot` attribute of an HTML element. Here, the `<span>` element has a `slot` attribute set to the variable `dynamicName`.

<!-- prettier-ignore -->
```html
<template>
  <c-item>
    <span slot={dynamicName}></span>
  </c-item>
</template>
```

The dynamic value passed into the `slot` attribute is coerced to a string. For example, if you pass the number 4 to the attribute, it is converted to the string `"4"`. If you pass in a data type that can’t be converted into a string, such as a `Symbol()`, a TypeError is thrown.

This change doesn’t impact attributes of `<slot>` elements. For example, you still must pass a static string into the attribute `name` for a `<slot>` element.

```html
<template>
  <slot name="”staticName”"> </slot>
</template>
```

Here’s the markup for a parent component that uses `c-named-slots`.

```html
<!-- slotsWrapper.html -->
<template>
  <c-named-slots>
    <span slot="firstName">Willy</span>
    <span slot="lastName">Wonka</span>
    <span>Chocolatier</span>
  </c-named-slots>
</template>
```

The `c-slots-wrapper` component passes:

- `Willy` into the `firstName` slot
- `Wonka` into the `lastName` slot
- `Chocolatier` into the unnamed slot

Here’s the rendered output.

```html
<c-named-slots>
  <p>
    First Name:
    <slot name="firstName"><span slot="firstName">Willy</span></slot>
  </p>
  <p>
    Last Name:
    <slot name="lastName"><span slot="lastName">Wonka</span></slot>
  </p>
  <p>
    Description:
    <slot><span>Chocolatier</span></slot>
  </p>
</c-named-slots>
```

## Access Elements Passed Via Slots

The `<slot></slot>` element is part of a component’s shadow tree. To access elements in its shadow tree, a component calls `this.template.querySelector()` and `this.template.querySelectorAll()`.

However, the DOM elements that are passed into the slot aren’t part of the component’s shadow tree. To access elements passed via slots, a component calls `this.querySelector()` and `this.querySelectorAll()`.

This example shows how to pass DOM elements to a child component from the child’s context. Provide the selector name, such as an element, for `this.querySelector()` and `this.querySelectorAll()`.

```javascript
// namedSlots.js
import { LightningElement } from "lwc";

export default class NamedSlots extends LightningElement {
  renderedCallback() {
    this.querySelector("span"); // <span>push the green button.</span>
    this.querySelectorAll("span"); // [<span>push the green button</span>, <span>push the red button</span>]
  }
}
```

In this example, the `querySelector` accepts the element `span`.

**note:** Don’t pass an `id` to a query method like `querySelector`. When an HTML template is rendered, `id` values can be transformed into globally unique values. If you use an `id` selector in JavaScript, it doesn’t match the transformed `id`.

## Render Slots Conditionally

To render a slot conditionally, nest the slot in a `<template>` tag with the `lwc:if`, `lwc:else`, and/or `lwc:elseif` directives.

<!-- prettier-ignore -->
```html
<template>
  <template lwc:if={expression}>
    <div class="my-class">
      <slot></slot>
    </div>
  </template>
  <template lwc:else>
    <slot></slot>
  </template>
</template>
```

The template compiler treats the conditional directives as a valid use case, and it knows that `<slot>` isn't rendered twice.

If you use the legacy `if:true` and `if:false` directives, the compiler warns you about duplicate slots because it's not clear if `<slot>` will only render once. For example, the `expression` getter can have an inconsistent return value each time.

## Run Code on `slotchange`

All `<slot>` elements support the `slotchange` event. The `slotchange` event fires when a direct child of a node in a `<slot>` element changes. For example, this occurs when new content is appended or deleted. Only `<slot>` elements support this event.

Changes within the children of the `<slot>` element don’t trigger a `slotchange` event.

In this example, the `<slot>` element handles the `slotchange` event.

<!-- prettier-ignore -->
```html
<!-- container.html -->
<template>
  <slot onslotchange={handleSlotChange}></slot>
</template>
```

```javascript
// container.js
handleSlotChange (e) {
   console.log("New slotted content has been added or removed!");
}
```

The component `c-child` is passed into the slot.

<!-- prettier-ignore -->
```html
<c-container>
  <c-child></c-child>
  <template lwc:if={addOneMore}>
    <c-child></c-child>
  </template>
</c-container>
```

If the flag `addOneMore` is set to True, the console prints the first time the component is rendered.

<!-- prettier-ignore -->
```html
<!-- child.html -->
<template>
  <button onclick={handleClick}>Toggle Footer</button>
  <template lwc:if={showFooter}>
    <footer>Footer content</footer>
  </template>
</template>
```

The `slotchange` event is not triggered even if `showFooter` is true and the footer element is appended.

**See Also**

- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom.md)
- [Handle Events](https://developer.salesforce.com/docs/platform/lwc/events/events-handling.md)
- [Compose Components Using Slots Vs Data](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-best-composition.md)
- [_MDN Web docs_: \<slot>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)

<!-- document id=fedb19631bf46c61863322e093e65e5ba0b667634825cd1412680267dbbbae14 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-slot.md -->

# Pass Markup to a Base Component Slot

Passing a base component to a slot on another base component is a common pattern to compose visual elements. Alternatively, some base components use an attribute to enable developers to pass in configuration information and data. Understanding the differences can be helpful as you work with base components or build your own custom components.

## Using the Default Slot

Many base components contain an unnamed slot, which acts as a placeholder for any markup you pass in to the base component. The unnamed slot is also known as the default slot. For slot information on a base component, see the Specification tab for a base component in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

Creating a base component with an unnamed slot enables you to use a base component that composes other base components. For example, the `lightning-accordion` base component contains a `<slot></slot>` tag that enables you to pass in the `lightning-accordion-section` component within the slot of `lightning-accordion`.

<!-- prettier-ignore -->
```html
<!-- lightning-accordion -->
<template>
    <div part="accordion">
        <slot></slot>
    </div>
</template>
```

**note:** Base components' internal markup is for demonstrative purposes only. The markup is an internal implementation that can change anytime.

To use `lightning-accordion`, you can easily nest `lightning-accordion-section` within `lightning-accordion` to display content within the accordion.

<!-- prettier-ignore -->
```html
<!-- c-custom-component -->
<lightning-accordion>
    <lightning-accordion-section name="A" label="Section A">
        <!-- More content here -->
    </lightning-accordion-section>
    <lightning-accordion-section name="B" label="Section B">
        <!-- More content here -->
    </lightning-accordion-section>
</lightning-accordion>
```

## Using A Named Slot

`lightning-accordion-section` has an `actions` named slot that accepts an actionable component like `lightning-button` or `lightning-button-menu`. To manage the content that's passed into the slot, `lightning-accordion-section` uses the `slotchange` event or a custom event to notify the parent component of changes to the child components.

For more information on how base components manage slot content, see [Compose Components Using Slots Vs Data](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md).

Another base component that uses both default and named slots include, `lightning-card`, which contains a default slot and three named slots.

You can pass markup and other base components to the slots.

<!-- prettier-ignore -->
```html
<!-- c-custom-component -->
<lightning-card title="Base Component Example" icon-name="standard:account">
    <div class="slds-var-m-around_medium">
        <p>Hello, {greeting}!</p>
        <lightning-input
            label="Name"
            value={greeting}
            onchange={handleChange}
        ></lightning-input>
    </div>
    
    <div slot="footer">
        Content for the footer slot here
    </div>
</lightning-card>
```

Using slots results in maintainable code that's intuitive and easy to understand. For most cases, using slots would be recommended over using an attribute for passing in configuration information or data.

**note:** Many base components use slots to facilitate composition of visual elements. See [Base Component Composition](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-compose.md).

**See Also**

- [Pass Configuration or Data to a Base Component](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-attributes.md)
- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md)
- [Slots vs Data](https://developer.salesforce.com/docs/platform/lwc/create/create-components-best-composition.md)

<!-- document id=0bd72b32b5ef722a40e7fa9e816765ccbf0331db1b794c4cb5af0476a4d35872 url=/developer/current/en-us/lwc/lwc/guides/reference/paymentsservice/reference-lightning-paymentsservice.md -->

# Payments Service API

Collect payments from customers using Tap to Pay.

The **Syntax** sections in the next topics use TypeScript formatting. We use this formatting to make the API syntax easier to understand. For example, functions can be described by the function name, parameter name and type, and a return type like this one.

```js
CollectPayment(collectPaymentOptions: options): Promise<CollectPaymentResponse>
```

Optional parameters are appended with `?` like `objectInfo?: ObjectInfo`. For more information, see the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/functions.html).

<!-- document id=711c746e31a66165073b5a6eb48ebf618d33b4999ed7f7d238f3162df8f5cece url=/developer/current/en-us/lwc/lwc/guides/migrate/migrate-decide.md -->

# Pick a Component to Migrate

To decide whether to migrate a component, first understand how Aura components and web components work together, and then evaluate how and where the component is used.

Before you pick a component to migrate, make sure that you [understand the concept of facets in Aura components](https://developer.salesforce.com/docs/platform/lwc/interop/interop-aura-composition.md).

Let’s review the most important facts about how Lightning web components and Aura components work together.

- Lightning web components and Aura components can co-exist in the same runtime.
- An Aura component can contain a Lightning web component.
- A Lightning web component can’t contain an Aura component.
- If an Aura component has facets that contain other Aura components, you must migrate those other Aura components too.

<!-- document id=49a23cf48e0f9ce41b3c21d011b4a8c18bfe0b499873cd23c6210366a398ac91 url=/developer/current/en-us/lwc/utam/references/platform-context.md -->

# Platform Context

In a hybrid mobile application, some pages are WebView and some pages are native. WebView allows you to display web content inside a native app. A WebView page leverages the device's browser engine to render HTML and process JavaScript locally. A native page is built with a platform SDK such as iOS or Android, using tools and languages for the specific platform.

Appium is an open-source tool for automating native, mobile web, and hybrid applications. Appium allows you to write tests against multiple platforms, such as iOS and Android, using the same API. For a hybrid mobile application test using Appium, the driver needs to enter the appropriate Appium context: WebView context for a WebView page or native context for a native page. For more details, see [appium.io: Appium Context](https://appium.io/docs/en/2.0/guides/context/).

The `platform` field at the root of a page object defines the page context type. The value can be:

- `web` for a WebView page. This is the default value.

- `native` for a native page on iOS or Android platforms.

The UTAM framework uses the `platform` property to set WebView or native context at the page object bootstrap stage. Then, a test can interact appropriately with elements on the page.

Here's the JSON for a WebView page object (`platform` defaults to `web`):

```json
{
  "selector": {
    "css": "div#main"
  },
  "elements": []
}
```

Here's the JSON for a native page object on Android:

```json
{
  "platform": "native",
  "selector": {
    // native selector here
  },
  "elements": []
}
```

<!-- document id=7e76c75e2cd09cdbf881de25e111e471d03989854756c0d38f5bc7be76e2c222 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-lightning-industries-education-postBenefitAssignment.md -->

# `postBenefitAssignment(benefitAssignmentId, providerId)`

Updates Benefit Assignment records with Provider lookup, and creates Contact Contact Relationship and Party Role Relationship records for Mentoring participants.

## Syntax

```javascript
import { postBenefitAssignment } from 'lightning/industriesEducationPublicApi';

postBenefitAssignment({ benefitAssignmentId: string, providerId: string }): Promise<MentoringBenefitAssignment>
```

## Parameters

| Parameter Name        | Type   | Description                                                                    | Required?                               |
| --------------------- | ------ | ------------------------------------------------------------------------------ | --------------------------------------- |
| `benefitAssignmentId` | String | The ID of the benefit assignment record.                                       | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `providerId`          | String | The ID of the provider offering that's associated with the benefit assignment. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that resolves with the [MentoringBenefitAssignment](https://developer.salesforce.com/docs/atlas.en-us.edu_cloud_dev_guide.meta/edu_cloud_dev_guide/connect_responses_mentoring_benefit_assignment_details.htm) response.

## Usage

Call this function to update Benefit Assignment records with Provider lookup, and to create Contact Contact Relationship and Party Role Relationship records for Mentoring participants.

This example calls `postBenefitAssignment()` based on a Benefit Assignment ID and a Provider Offering ID. Replace the IDs with your own.

```javascript
import { LightningElement, api } from "lwc";
import { postBenefitAssignment } from "lightning/industriesEducationPublicApi";

export default class MentoringPostBenefitAssignment extends LightningElement {
  results;
  error;

  async callPostBenefitAssignment() {
    await postBenefitAssignment({
      benefitAssignmentId: "000000000000000000",
      providerId: "000000000000000000",
    })
      .then((response) => {
        this.results = response;
      })
      .catch((e) => {
        this.error = e;
      });
  }

  connectedCallback() {
    this.callPostBenefitAssignment();
  }

  @api
  getWiredData() {
    return this.results;
  }

  @api
  getWiredError() {
    return this.error;
  }

  @api
  clearWiredData() {
    this.results = undefined;
  }

  get wireResults() {
    return this.results || this.error;
  }

  get wireDataString() {
    return this.wireResults ? JSON.stringify(this.wireResults, null, 2) : "";
  }
}
```

This component displays the response of the `postBenefitAssignment()` call.

<!--prettier-ignore-->
```html
<template>
   <template if:true={wireResults}>
       <div>Wire data retrieved</div>
       <div class="scroller">
           <pre>{wireDataString}</pre>
       </div>
   </template>
</template>

```

**note:** For TypeScript users, the type definition for this module is provided by the [`@salesforce/lightning-types`](https://www.npmjs.com/package/@salesforce/lightning-types) npm package.


**See Also**

- [Get Started with Education Cloud](https://help.salesforce.com/s/articleView?id=sfdo.EC_Get_Started.htm&type=5)

<!-- document id=e3140c519bdd1dcfa0b3f5161c6de7556bfac72b4e2253e5121e28e941c365db url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-post-wave-folders.md -->

# `postWaveFolders`

Creates a CRM Analytics folder.

## Syntax

```javascript
import { postWaveFolders } from 'lightning/analyticsWaveApi';
postWaveFolders( waveFolder : BaseWaveFolderInput ): Promise<WaveFolder>
```

## CRM Analytics API Resource

```html
POST /wave/folders
```

`postWaveFolders` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                       | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `waveFolder`   | Object | The folder to create. Use a [Base Wave Folder Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_base_wave_folder_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

A Promise object that resolves with the [Wave Folder](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_folder.htm) response.

## Usage

Use `postWaveFolders` to create a CRM Analytics folder. For example, create a blank folder to contain analytics assets, like dashboards and components.

This example adds a create button to a page. The page must contain form elements for the information required to create the folder, like the name, label, and asset icon. Creating a folder displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { postWaveFolders } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class PostWaveFolders extends LightningElement {
  folder = {
    name: "MyTestFolder",
    label: "My Test Folder",
  };

  create(event) {
    postWaveFolders({ waveFolder: this.folder })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Folder Created",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error creating folder",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `postWaveFolders()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Create"
    icon-name="utility:play"
    icon-position="right"
    onclick={create}
  ></lightning-button>
</template>
```

<!-- document id=17dd7deebc29398d454629b0d381b7a1240099e225bb91c1071bb91d31e802c7 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-repricing/reference-lightning-commerce-repricing-product-details.md -->

# `productDetails`

Gets pricing and product details for a specific product in a webstore. Use this wire adapter in Order Management repricing scenarios.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { productDetails } from 'lightning/commerceRepricingApi';

@wire(productDetails, { webstoreId: string, skuOrProductId: string, version: string })
propertyOrFunction
```

## Commerce API Resource

```
GET /commerce/order-management/webstores/{webstoreId}/products/{skuOrProductId}
```

`productDetails` uses this [Commerce API resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm).

## Parameters

- `webstoreId`—(Required) The ID of the webstore. The ID prefix is `0ZE`.
- `skuOrProductId`—(Required) The SKU or product ID to look up.
- `version`—(Required) The API version for the adapter, for example, `v62.0`. Without this parameter, the wire doesn't fire.
- `effectiveAccountId`—(Optional) The effective account ID for buyer-specific pricing and entitlements.
- `currencyCode`—(Optional) The ISO currency code for pricing, for example, `USD`.
- `locale`—(Optional) The locale for localized product content, for example, `en-US`.
- `excludeAttributeSetInfo`—(Optional) Set to `true` to exclude attribute set information from the response. Available in API version 44.0 and later.
- `excludeMedia`—(Optional) Set to `true` to exclude media from the response. Available in API version 44.0 and later.
- `excludeQuantityRule`—(Optional) Set to `true` to exclude the purchase quantity rule from the response. Available in API version 44.0 and later.
- `excludeVariationInfo`—(Optional) Set to `true` to exclude variation information from the response. Available in API version 44.0 and later.
- `excludePrices`—(Optional) Set to `true` to exclude prices from the response. Available in API version 44.0 and later.
- `excludeBundleChildrenInfo`—(Optional) Set to `true` to exclude bundle children information from the response. Available in API version 56.0 and later.

## Returns

- `data`—A `ProductDetailsOutputRepresentation` object with these fields:
  - `productId`—The product ID.
  - `stockKeepingUnit`—The SKU.
  - `name`—The product name.
  - `description`—The product description.
  - `productClass`—The product class. Valid values: `Bundle`, `Simple`, `Variation`, `VariationParent`, `Set`.
  - `totalChildrenCount`—The number of children for a bundle product.
  - `fields`—A map of requested product fields.
  - `variants`—A list of product variants.
  - `imageGroups`—A list of product media image groups.
  - `unitPrice`—The unit price.
  - `listPrice`—The list price.
  - `attributes`—A list of variation attributes.
  - `currencyIsoCode`—The ISO currency code.
  - `productQuantityRule`—The purchase quantity rule.
  - `childItems`—A list of bundle child items.
  - `success`—Indicates whether the request was successful.
  - `errors`—A list of errors, if any. Each error has `errorCode`, `message`, and `errorEntityId` fields.
- `error`—[`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

```javascript
import { LightningElement, wire } from 'lwc';
import { productDetails } from 'lightning/commerceRepricingApi';

export default class ProductDetailsExample extends LightningElement {
  webstoreId = '0ZExx0000000001';
  skuOrProductId = '01t000000000001';

  @wire(productDetails, {
    webstoreId: '$webstoreId',
    skuOrProductId: '$skuOrProductId',
    version: 'v62.0',
    effectiveAccountId: '$effectiveAccountId',
  })
  product;

  get productName() {
    return this.product?.data?.name;
  }

  get unitPrice() {
    return this.product?.data?.unitPrice;
  }
}
```

## Error Handling

If the wire adapter encounters an error, `data` is `undefined` and `error` contains the error details.

**See Also**

- [`searchProducts`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-repricing-search-products.md)

<!-- document id=281d54235b9a3a0ef40159b87abef954ca6921091d4dc419c3e9ce878ff18202 url=/developer/current/en-us/lwc/lwc/guides/debug/debug-production-mode.md -->

# Production Mode

By default, the framework runs in production mode. This mode is optimized for performance.

In production mode, JavaScript code is optimized and “minified” to reduce the size of the code to as few bytes as possible. Production mode removes line breaks, spaces, tabs, and code comments, and shortens the names of functions and variables. Because of this process, the JavaScript code served to the browser is obfuscated.

Each time your code gets minified, the optimization process can produce different output. For example, the variable `name` could be minified to `a` in one build, and then `b` in a later build. Although your minified code can vary, the logic from your original code stays the same.

**note:** Minification is a performance optimization, not intellectual property protection. Code that’s minified is hard to read, but it’s not encrypted or otherwise prevented from being viewed.

## Proxy Objects Visible in Production Mode

Production mode also uses JavaScript proxies for certain things, such as data that is provisioned through decorators `@api`, `@wire`, and `@track`. The `@api` and `@wire` decorated properties are considered read-only. By using JavaScript proxies, the framework can ensure that those properties can’t be modified. For `@track` decorated properties, the framework uses proxies to observe data mutation so it can react to changes. When debugging in production mode, you see the proxy object instead of the object you’re interested in.

Lightning Locker and Lightning Web Security use proxy objects on standard web APIs to prevent changes to global objects in the DOM.

## Production Mode Debugging

You can use the “pretty print” option in Chrome DevTools to get minimal code formatting in production mode. Click the `{}` pretty print icon at the bottom of the **Sources** panel to open a new tab with formatting applied.

![Pretty print button](https://developer.salesforce.com/media/debug_prettyprint_button.png)

The code still isn’t fully readable because of the changed names of variables and functions, but it’s good for a first check. You can set breakpoints, inspect values during runtime, and work with the debugger in Chrome DevTools.

Here’s what you see in production mode by default, using sample code from [lwc-recipes](https://github.com/trailheadapps/lwc-recipes). Line 1 stretches on for over 1200 characters in this example.

![Minified code in production mode](https://developer.salesforce.com/media/debug_source_minified.png)

Here’s what you see in production mode after you select pretty print.

![Pretty print source code](https://developer.salesforce.com/media/debug_prettyprint.png)

**See Also**

- [Debug Mode](https://developer.salesforce.com/docs/platform/lwc/debug/debug-debug-mode.md)

<!-- document id=9c388916c038847515304393444fbc4aa81a41827e8df5c4d3fb00e5a138ce19 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-prog-click.md -->

# Programmatic Click to Open Same-Origin URLs

In Spring '27 and later, when Lightning Web Security (LWS) is enabled, opening same-origin Salesforce URLs in a new tab by using `window.open(URL)` or `window.open(URL, '_blank')` results in a `LockerSecurityError`. Use this recommended programmatic anchor click for same-origin downloads and navigation.

```
const a = document.createElement('a');
a.href = url;              // /apex/... clears the href denylist
a.target = '_blank';       // or omit for same-tab
a.rel = 'noopener noreferrer';
a.click();                 // keep it detached; do NOT append to body/head
```

### Navigate in the Same Tab

To navigate in the same tab, set the target to `a.target= '_top'`, `a.target= '_self'`, or `a.target= '_parent'`. For example, a link on the homepage takes the user directly to a record.
Alternatively, you can use `window.open(url, '_top')`.

**important:** Using `window.open(URL)` without a target defaults to `_blank`, which in turn results in the `LockerSecurityError` error.

<!-- document id=af1e1bb3378d97a5e19cb70c16edcba32dba6e08a826447a5fc05c907fdccca8 url=/developer/current/en-us/lwc/lwc/guides/use/use-dialog-prompt.md -->

# Prompt Modals

Use a prompt modal to ask users to provide information before they continue. The prompt is displayed in a dialog on top of the page content using an overlay.

To display a prompt in Lightning Experience, import `LightningPrompt` from the `lightning/prompt` module, and call `LightningPrompt.open()` with your desired attributes.

`LightningPrompt` is an alternative to the native `window.prompt()` function, which isn’t supported for cross-origin iframes in Chrome and Safari. Unlike the native prompt function, `LightningPrompt.open()` doesn't halt execution on the page, it returns a Promise. Use `async`/`await` or `.then()` for any code you want to execute after the modal is closed.

![A prompt notification with a striped gray header and a text input box over a darkened org.](https://developer.salesforce.com/media/dialog_prompt_example.png '{"class": "image-full", "title": "A prompt notification"}')

This example component creates a button that opens the prompt modal UI that you see in the screenshot.

<!-- prettier-ignore -->
```html
<!-- c/myApp.html -->
<template>
  <lightning-button 
      onclick={handlePromptClick} 
      label="Open Prompt Modal"> 
  </lightning-button>
</template>
```

Import `LightningPrompt` from `lightning/prompt` in the JavaScript file of the component that opens the prompt modal. Create and dispatch a `LightningPrompt` event with `message`, `theme`, `label`, and `defaultValue` attributes. If the user enters text and clicks **OK** in the prompt, the `.open()` function returns a promise that resolves to the input value. If the user clicks **Cancel**, the function returns a promise that resolves to `null`.

```javascript
import { LightningElement } from "lwc";
import LightningPrompt from "lightning/prompt";

export default class MyApp extends LightningElement {
  handlePromptClick() {
    LightningPrompt.open({
      message: "This is the prompt message.",
      //theme defaults to "default"
      label: "Please Respond!", // this is the header text
      defaultValue: "Optional initial input value",
    }).then((result) => {
      // prompt modal has been closed
    });
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [miscNotificationModules](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/miscNotificationModules) component that demonstrates prompt modals.

For information about the attributes for `LightningPrompt`, see the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-prompt?type=Specifications.

**See Also**

- [Component Reference: `lightning/prompt`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-prompt)

<!-- document id=b474f21c37039045a915dcd496109d0911f2962338f7134fd178f62b43306b00 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-undefined.md -->

# Properties Evaluate as `undefined` in Lightning Web Security

Lightning Web Security (LWS) can cause a value to evaluate as `undefined`.

Here are some conditions that cause properties to evaluate as `undefined` in components running with LWS.

## `undefined` Value Is in the Global Scope

If your code or a third-party library that you’re using stores values in the `window` object, it’s accessing the global scope. Lightning Web Security enforces [JavaScript strict mode](https://developer.salesforce.com/docs/platform/lightning-components-security/js/js-strict-mode-intro.md), which prevents the creation of global variables. The browser throws an error if you try to create a global variable.

LWS distortions permit changes to the virtual `window` object only in the component’s namespace sandbox. If a component attempts to access global scope properties that were created in another namespace, the value returned by LWS is `undefined`.

LWS sandboxing makes it appear that you can access global properties, but you’re actually accessing a virtual copy of the `window` object. Within a namespace sandbox, LWS lets you access global properties, but storing anything in global scope is considered bad practice. LWS allows it, but if the object with mutations is passed to code running outside the namespace sandbox, the changed properties aren’t accessible.

Instead, pass any shared data that can be accessed by functions or objects from other namespaces as function or constructor arguments.

**note:** Third-party libraries shouldn’t explicitly set strict mode when LWS is enabled. See [Third-Party Library Considerations for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-js.md).

## `undefined` Value Is Passed by Function Argument

If you discover that some values passed as arguments are `undefined` after you enable LWS, the problem can be due to object mutations or modifications on data that your components don’t own.

Data ownership is defined at the namespace level, which means that code defined within a namespace can freely modify its own data. However, if your code receives data from another namespace and modifies that data, the modifications aren’t always reflected outside your namespace.

**tip:** If the object being mutated is a plain JavaScript object, array, or typed array, LWS allows the mutation on the original object, and the change is reflected outside the namespace. We recommend using these objects instead of maps, in particular.

For global `window` objects and objects constructed from custom classes, LWS doesn’t allow mutations if the object isn’t owned by the namespace. A property that was added outside the namespace sandbox evaluates as `undefined`.

In this example `redFunction` is defined in namespace A and `blueFunction` is defined in namespace B.

```javascript
//module in namespace A

function redFunction(arg) {
  arg.foo = "bar"; // mutation on the arg object
  console.log(arg.foo); // "bar"
}

//module in namespace B

function blueFunction() {
  var someObject = {};
  redFunction(someObject); // blueFunction expects foo property added by redFunction
  console.log(someObject.foo); // undefined
}
```

When `blueFunction` uses `redFunction`, it doesn’t receive the mutation for the `foo` property that was done in namespace A. The namespaces can communicate by passing data to each other, but mutations don’t persist beyond the namespace boundary.

If your code mutates objects received from other namespaces, refactor your code.

See [Avoid Mutating Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.md) for examples of how to refactor your code.

**note:** It’s best to design your functions with immutability in mind to make them [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent). For more information on the immutability coding paradigm, see this [Redux guide](https://redux.js.org/tutorials/essentials/part-1-overview-concepts#immutability).

**See Also**

- [Avoid Mutating Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.md)
- [Avoid Using Map Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-map.md)

<!-- document id=6f8117f0bd5021bda84c42c3bdc386a35556fd3fe98265f1d821f918fdc4f2c6 url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-names.md -->

# Property and Attribute Names

Property names in JavaScript are in camel case while HTML attribute names are in kebab case (dash-separated) to match HTML standards.

For example, a JavaScript property named `itemName` maps to an HTML attribute named `item-name`.

```javascript
// child.js
import { LightningElement, api } from "lwc";

export default class extends LightningElement {
  @api itemName;
}
```

```html
<!-- parent.html -->
<template>
  <c-child item-name="Child item"></c-child>
</template>
```

## JavaScript Property Names

Don’t start a property name with these characters.

- `on` (for example, `onClick`)
- `aria` (for example, `ariaDescribedby`)
- `data` (for example, `dataProperty`)

Don’t use these reserved words for property names.

- `slot`
- `part`
- `is`

## HTML Attribute Names

HTML attributes in a template can't contain uppercase characters. Attribute names can start with:

- A lowercase alphabetic character
- An underscore (`_`)
- A dollar sign (`$`)
- An optional hyphen followed by an alphabetic character(`-a`)

Attribute names can include duplicate underscores (`__`) or an underscore followed by a hyphen(`_-`).

A hyphen followed by an underscore (`-_`) is allowed if the hyphen isn’t the first character in the attribute name. For example, these are valid attribute names:

- `_myattribute`
- `$myattribute`
- `my_-attribute`

If you have a JavaScript property that starts with an uppercase character and you want to set it via an HTML attribute, you must use special syntax. The uppercase character of the property name is lowercased and prefixed with a hyphen, `-upper`. The leading hyphen tells the engine that the first alpha character in the attribute name is declared with a leading uppercase character in the JavaScript class. For example, the JavaScript property `@api Upper` corresponds to the HTML attribute `-upper`.

## Access HTML Global Attributes in JavaScript

Using [HTML global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes), which are attributes like `class` and `title` that are common to all HTML elements, isn’t recommended. If you do use a global HTML attribute, decorate it with `@api`.

Some HTML global attributes don’t follow the Lightning Web Components camel case and kebab case convention. If you create a getter or setter for one of these HTML global attributes, in JavaScript, use the case in this list.

| HTML Global Attribute | Property in JavaScript |
| --------------------- | ---------------------- |
| `accesskey`           | `accessKey`            |
| `bgcolor`             | `bgColor`              |
| `colspan`             | `colSpan`              |
| `contenteditable`     | `contentEditable`      |
| `crossorigin`         | `crossOrigin`          |
| `datetime`            | `dateTime`             |
| `for`                 | `htmlFor`              |
| `formaction`          | `formAction`           |
| `ismap`               | `isMap`                |
| `maxlength`           | `maxLength`            |
| `minlength`           | `minLength`            |
| `novalidate`          | `noValidate`           |
| `readonly`            | `readOnly`             |
| `rowspan`             | `rowSpan`              |
| `tabindex`            | `tabIndex`             |
| `usemap`              | `useMap`               |

For example, to access the HTML `maxlength` attribute of `textarea` in JavaScript, use `maxLength`.

Also, to access the `for` HTML attribute from JavaScript, use `htmlFor`.

## Access ARIA Attributes in JavaScript

ARIA attributes support assistive technologies. To access these attributes in JavaScript, use camel case. For example, to access `aria-checked`, use `ariaChecked`. To access `aria-errormessage`, use `ariaErrorMessage`.

**See Also**

- [Public Properties](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-public.md)

<!-- document id=4aaa8f5cc0ffdbb6ffdac6fa01ce9a3b628c0617728431b9bc230e6895adef6b url=/developer/current/en-us/lwc/lwc/guides/reactivity/reactivity-public.md -->

# 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()`](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-rendered.md) lifecycle hook executes.

::video{src="https://youtube.com/embed/F7J5yn3MIXw" title="The @api Decorator" type="youtube" }

**tip:** [Decorators](https://github.com/tc39/proposal-decorators) are a JavaScript language feature. The [`@api`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-decorators.md) decorator is unique to Lightning Web Components. A field can have only one decorator.

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.

```javascript
// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  @api itemName = "New Item";
}
```

The value of `itemName` displays in the template.

```html
<!-- todoItem.html -->
<template>
  <div class="view">
    <label>{itemName}</label>
  </div>
</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.

**note:** 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`.

```html
<!-- todoApp.html -->
<template>
  <div class="listing">
    <c-todo-item item-name="Milk"></c-todo-item>
    <c-todo-item item-name="Bread"></c-todo-item>
  </div>
</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).

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

**tip:** See the [CompositionBasics](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/compositionBasics) example in the `lwc-recipes` repository.

**See Also**

- [Render Lists](https://developer.salesforce.com/docs/platform/lwc/create/create-lists.md)

<!-- document id=873ece2adeb5767f06906f48ac538bab5433349c7ad7537010b80476cf176793 url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel-publish.md -->

# Publish on a Message Channel

Before you can publish on a message channel, you must first [create the message channel](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-channel-intro.md).

Create a message channel if you want to:

- Communicate across the DOM within a Lightning page.
- Communicate between Visualforce pages embedded in the same Lightning page, Aura components, and Lightning web components, including components in a utility bar and pop-out utilities.
- Choose whether a component subscribes to messages from the entire application, or from only the active area.

To publish messages on a message channel from a Lightning web component, include the `@salesforce/messageChannel` scoped module in your component's JavaScript file and call the Lightning message service’s `publish()` function.

The Lightning message service publishes messages to any subscribed component until the destroy phase of the [component lifecycle](https://developer.salesforce.com/docs/platform/create/create-lifecycle-hooks.md). Sometimes when you navigate away from a Lightning page, components are cached and not destroyed. If the Lightning message service is scoped to the entire application, these components still publish to and receive messages from the Lightning message service.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an `lmsPublisherWebComponent` component that publishes a message to notify subscribers on a Lightning page. The Lightning message service communicates that message across Visualforce, Aura, and Lightning Web components on the page.

![Publisher components for LWC, Aura, and Visualforce](https://developer.salesforce.com/media/lms-publish-components.png)

Let's take a look at [the `lmsPublisherWebComponent` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/lmsPublisherWebComponent). The component's HTML template file displays a list of contacts. When a contact is selected, the `handleContactSelect` handler is invoked, which publishes a message to the message channel.

<!-- prettier-ignore -->
```html
<!-- lmsPublisherWebComponent.html -->
<template>
  <lightning-card title="LMSPublisherWebComponent" icon-name="custom:custom30">
    <div class="slds-m-around_medium" oncontactselect={handleContactSelect}>
      <template lwc:if={contacts.data}>
        <template for:each={contacts.data} for:item="contact">
          <c-contact-list-item-bubbling
            key={contact.Id}
            contact={contact}>
          </c-contact-list-item-bubbling>
        </template>
      </template>
    </div>
  </lightning-card>
</template>
```

In your component's JavaScript file, import the message channel and the Lightning message service functions necessary for working with a message channel.

```javascript
// lmsPublisherWebComponent.js
import { LightningElement, wire } from "lwc";
import getContactList from "@salesforce/apex/ContactController.getContactList";

// Import message service features required for publishing and the message channel
import { publish, MessageContext } from "lightning/messageService";
import recordSelected from "@salesforce/messageChannel/Record_Selected__c";

export default class LmsPublisherWebComponent extends LightningElement {
  @wire(getContactList)
  contacts;

  @wire(MessageContext)
  messageContext;

  // Respond to UI event by publishing message
  handleContactSelect(event) {
    const payload = { recordId: event.target.contact.Id };

    publish(this.messageContext, recordSelected, payload);
  }
}
```

Use `@wire(MessageContext)` to create a `MessageContext` object, which provides information about the Lightning web component that is using the Lightning message service. When using the `@wire(MessageContext)` adapter, you don’t have to interact with any of the component’s lifecycle events. The Lightning message service features automatically unregister when the component is destroyed.

The `handleContactSelect()` method creates the message content to publish. The Lightning message service's `publish()` function takes three parameters, the message context, the name of the message channel, and the message payload. Here, the message payload is a JSON object where the `recordId` key has the value `event.target.contact.Id`.

**note:** A component must be attached to the DOM before it can use the property decorated with `@wire(MessageContext)`. You can’t use `@wire(MessageContext)` in a `constructor()` function.

**See Also**

- [Component Reference: lightning/messageService](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-message-service)

<!-- document id=ded529f47696a8b186c9de10b2beb19072fa64b43744bd86fa6d619e85a2ac24 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-queryselector.md -->

# querySelector APIs Running With Lightning Locker

When Lightning Locker is enabled, components that use `element.querySelector` or `element.querySelectorAll` APIs to return elements can encounter memory leaks and performance problems with large DOM trees.

**note:** For Lightning web components, `element` refers to the `this.template` prefix. For Aura components, `element` refers to the `this` prefix.

When the component is removed from the DOM, the memory sometimes isn’t released. Garbage collection doesn’t clear the memory even if you manually invoke garbage collection in DevTools. The browser can use increasing amounts of memory, and potentially crash with an out-of-memory error.

The only workaround for this issue is to [enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-enable.md) in the org where the component runs. Garbage collection works correctly under LWS.

Alternatively, if you're developing Lightning web components, consider using [refs](/docs/platform/lwc/guide/create-components-dom-work.html#refs) instead of `querySelector`.

**See Also**

- [_Lightning Web Components Developer Guide_: Access Elements the Component Owns](/docs/platform/lwc/guide/create-components-dom-work.html)

<!-- document id=0c90899e610d108b3ef275adb7804dc63d7c8e7b9470d9e0931e9d86bc8091d6 url=/developer/current/en-us/lwc/lwc/guides/use/use-navigate-quick-action.md -->

# Quick Action Navigation

Use quick actions to invoke a custom Lightning web component on a record page. First, configure a component for quick action and then add it to a record page by adding it to your page layout. A headless quick action doesn't open a modal window, but a screen quick action does.

## Navigate With a Headless Quick Action

To create a component for a headless quick action, create an empty template for your component and use the `[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference, [replace])` function.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a [`navigateToRecordHeadlessAction` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/navigateToRecordHeadlessAction) example that uses a headless quick action to navigate to a contact create page.

In this example, clicking the quick action button on a record page opens a modal window that displays the contact create page.

```javascript
// navigateToRecordHeadlessAction.js
import { LightningElement, api } from "lwc";
import { NavigationMixin } from "lightning/navigation";

export default class NavigateToRecordHeadlessAction extends NavigationMixin(LightningElement) {
  @api invoke() {
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Contact",
        actionName: "new",
      },
    });
  }
}
```

By default, `replace` is false. When the modal window opens, the URL changes. So you can use the browser's Back button to return to the record page that you previously opened. Similarly, if you use the lookup field to open another modal window, such as to create a new record via the Account Name field, the URL changes again when the New Account modal is displayed.

If `replace` is true, the `pageReference` replaces the existing entry in the browser history. When you are on the modal window that's defined by `pageReference`, clicking the Back button on the browser returns you to the page you visited before the record page that contains the quick action button.

```javascript
this[NavigationMixin.Navigate](
  {
    type: "standard__objectPage",
    attributes: {
      objectApiName: "Contact",
      actionName: "new",
    },
  },
  true,
);
```

## Navigate With a Screen Quick Action

Let's say you have a screen quick action that displays a modal, and that modal uses the `[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lwc/guide/pageReference, [replace])` function to display another modal with the specific `pageReference`, such as a record create page.

By default, `replace` is false and the previous modal isn't closed automatically. In this case, the newer modal overlays and stacks on the previous modal.

For example, if your component navigates to a record create page, the modal that contains your component remains open but inactive while another modal overlays it with the record create page. When you dismiss the new modal with the record create page, the previous modal that contains your component becomes active again.

To automatically close the previous modal when navigating, set `replace` to `true`.

This `screenQuickAction` example shows a screen quick action that contains a button. The button navigates to a contact create page.

<!-- prettier-ignore -->
```html
<!-- screenQuickAction.html -->
<template>
  <lightning-quick-action-panel header="Quick action"> 
    <lightning-button onclick={navToRecord} label="Create Contact"></lightning-button>
      <!-- Standard footer with cancel/save buttons -->
      <div slot="footer">
        <lightning-button
            variant="neutral"
            label="Cancel"
            onclick={handleCancel}
        ></lightning-button>
        <lightning-button
            variant="brand"
            label="Save"
            onclick={handleSave}
        ></lightning-button>
    </div>
  </lightning-quick-action-panel>
</template>
```

By default, `replace` is false. So when you click the button to navigate to the contact create page, your `screenQuickAction` modal remains open and inactive while the contact create modal overlays and stacks on it.

```javascript
// screenQuickAction.js
import { LightningElement, api, wire } from "lwc";
import { NavigationMixin } from "lightning/navigation";
import { CloseActionScreenEvent } from "lightning/actions";

export default class ScreenQuickAction extends NavigationMixin(LightningElement) {
  navToRecord() {
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Contact",
        actionName: "new",
      },
    });
  }
}
```

When you successfully created a record from the page reference, such as the contact create modal in the previous example, you're redirected back to the record page that contains your quick action.

If `replace` is true, opening the page reference via the **Create Contact** button on the quick action removes the quick action modal. However, opening a new modal via the following methods preserve the previous modal.

- Creating a record via a lookup field, which opens a record create modal, such as via the Account Name field on a contact create modal
- Opening another modal by importing `LightningModal` from the `lightning/modal` module from the quick action modal

When you successfully create a record from the page reference, such as from a contact create modal, you're redirected to the newly created record.

**See Also**

- [Post-Save Navigation](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-quick-actions.md#post-save-navigation)

<!-- document id=fda40d183ed52642c65cea14eff738c47597f099ebb499f85de5f456e7a5ebac url=/developer/current/en-us/lwc/lwc/guides/use/use-quick-actions.md -->

# Quick Actions

Quick actions let users perform a predefined task with a single click. Create quick actions to streamline and simplify processes like creating a record, logging a call, updating a field, and more.

You can configure a Lightning web component to run a quick action. This lets you execute custom logic on a Lighting record page while maintaining your UI styles. For guidance on how to use a custom Lightning web component as a quick action, see [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-quick-actions.md).

**note:** LWC quick actions are available only on record pages in Lightning Experience. They’re not supported in Aura Experience Builder sites or on the Salesforce mobile app. The Field Service org supports Lightning web component actions on additional objects. These actions appear only in the Field Service mobile app and not in Lightning Experience on mobile or desktop.

There are two types of quick actions for Lightning web components:

**Screen Quick Actions**

A screen quick action displays a component in a modal window. For example, you can use a screen quick action to open a custom Lightning web component with a form that lets users create or update specific fields on a record.

See [Create Screen Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-quick-actions-screen.md) for more information.

**Headless Quick Actions**

A headless quick action executes custom code that you provide in an `@api invoke()` method. This type of quick action lets you execute Lightning web component code that navigates to another page or dispatches an event.

See [Create Headless Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-quick-actions-headless.md) for more information.

<!-- document id=94ecae4c1216ec5d7b9186bec75c978380d7fe3c833410a0fd2ab3535a139667 url=/developer/current/en-us/lwc/lwc/guides/reactivity/reactivity.md -->

# Reactivity

Reactivity is a system at the core of the Lightning Web Components framework. The framework observes changes to the values of fields and properties. When it observes a change, it reacts. It reevaluates all the expressions used in the template and rerenders the component, which displays the new values.

Public properties in a component template are reactive. In a component's JavaScript class, If a field’s value changes, and the field is used in a template or in a getter of a property that’s used in a template, the component rerenders and displays the new value. If a field is assigned an object or an array, the framework observes some changes to the internals of the object or array, such as when you assign a new value.

For more information, see:

- [Reactivity for public properties](https://developer.salesforce.com/docs/platform/lwc/guide/reactivity-public.md)
- [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/guide/reactivity-fields.md)

**See Also**

- [Run Code When a Component Renders](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-rendered.md)

<!-- document id=94f08a66585d19d3eb51a2764d07b6ff3e302a15f9ee07068d908bcae15703cc url=/developer/current/en-us/lwc/lwc/guides/reactivity/reactivity-fields.md -->

# Reactivity for Fields, Objects, and Arrays

If a field’s value changes, and the field is used in a template or in a getter of a property that’s used in a template, the component rerenders and displays the new value. If a field is assigned an object or an array, the framework observes some changes to the internals of the object or array, such as when you assign a new value.

When a component rerenders, the expressions used in the template are reevaluated and the [`renderedCallback()`](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-rendered.md) lifecycle hook executes.

## Reactivity for Primitives and Complex Types

Primitive fields—like booleans, numbers, and strings—are reactive. LWC tracks field value changes in a shallow fashion. Changes are detected when a new value is assigned to the field by comparing the value identity using `===`.

When manipulating complex types like objects and arrays, you must create a new object and assign it to the field for the change to be detected.

```javascript
import { LightningElement } from "lwc";

export default class ReactivityExample extends LightningElement {
  bool = true;
  number = 42;
  obj = { name: "John" };

  checkMutation() {
    this.bool = false; // Mutation detected

    this.number = 42; // No mutation detected: previous value is equal to the newly assigned value
    this.number = 43; // Mutation detected

    this.obj.name = "Bob"; // No mutation detect: `obj` field value is not reassigned
    this.obj = { name: "John" }; // Mutation detected - redefining the object with the same value creates a new object
    this.obj = { ...this.obj, title: "CEO" }; // Mutation detected
  }
}
```

To deeply track mutations made to the field value for a complex object, use the `@track` decorator.

## Track Changes Inside Objects and Arrays

To observe changes to the properties of an object or to the elements of an array, decorate the field with `@track`.

When a field is decorated with `@track`, Lightning Web Components tracks changes to the internal values of:

- Plain objects created with `{}`
- Arrays created with `[]`

The framework observes mutations made to plain objects and arrays in a recursive fashion, including nested objects, nested arrays, and a mix of objects and arrays. Cyclic references are also handled.

However, the framework doesn't observe mutations made to complex objects, such as objects inheriting from `Object`, class instances, `Date`, `Set`, or `Map`.

::video{src="https://youtube.com/embed/evIUIHcWbZI" title="@track Decorator" type="youtube" }

## Observe an Object’s Properties

To tell the framework to observe changes to the properties of an object, decorate the field with `@track`.

**note:** As discussed earlier, without using `@track`, the framework observes changes that assign a new value to the field. If the new value is not `===` to the previous value, the component rerenders.

For example, let's change the code a bit to declare the `fullName` field, which contains an object with two properties, `firstName` and `lastName`. The framework observes changes that assign a new value to `fullName`.

```javascript
fullName = { firstName: "", lastName: "" };
```

This code assigns a new value to the `fullName` field, so the component rerenders.

```javascript
// Component rerenders.
this.fullName = { firstName: "John", lastName: "Doe" };
```

However, if we assign a new value to one of the object’s properties, the component doesn't rerender, because the properties aren’t observed.

```javascript
// Component doesn't rerender.
this.fullName.firstName = "John";
```

The framework observes changes that assign a new value to the `fullName` field. This code doesn't do that, instead it assigns a new value to the `firstName` property of the `fullName` object.

To tell the framework to observe changes to the object's properties, decorate the `fullName` field with `@track`. Now if we change either property, the component rerenders.

```javascript
// Component rerenders.
@track fullName = { firstName : '', lastName : ''};
this.fullName.firstName = 'John';
```

If a property contains an object, to track changes on the object's properties, annotate the property with `@track`. To understand, let's modify our example. Our example initializes `firstName` and `lastName` to empty strings, which are primitive values, so the component rerenders when they change.

## Rerender an Object with New Properties

A component rerenders only if a property accessed during the previous rendering cycle is updated, even when the object is annotated with `@track`. This prevents the component from rerendering excessively,

Consider this tracked object and a getter that prints the object’s properties.

```javascript
@track obj = {value1: 'Hello'};

get words() {
    return Object.entries(this.obj)
              .map(([key, value]) => ({key, value}));
  }
```

During the first render cycle, the framework records that `obj.value1` is accessed. Any mutation to `obj` that doesn’t affect `value1` is ignored since it doesn’t impact the rendered content. Therefore, a change to `value1` triggers a rerendering, but adding a new property to `obj` or a change to `value2` doesn’t trigger a rerendering.

```javascript
// Component rerenders.
setValue1(e) {
  this.obj.value1 = 'Hello World';
}

// Component doesn’t rerender.
setValue2(e) {
  this.obj.value2 = 'Hello LWC';
}
```

To rerender your component when adding a new property, assign the object to a new object with both values.

```javascript
setValue2(e) {
  this.obj = {
    ...this.obj,
      value2: 'Hello LWC'
  };
}
```

## Observe an Array’s Elements

Another use case for `@track` is to tell the framework to observe changes to the elements of an array.

If you don’t use `@track`, the framework observes changes that assign a new value to the field.

```javascript
arr = ["a", "b"];
```

The component rerenders when you assign a new value to `arr`.

```javascript
// Component rerenders.
this.arr = ["x", "y", "z"];
```

However, if we update or add an element in the array, the component doesn’t rerender.

```javascript
// Component doesn’t rerender.
this.arr[0] = "x";
this.arr.push("c");
```

To tell the framework to observe changes to the array’s elements, decorate the `arr` field with `@track` Additionally, the framework doesn’t automatically convert the array to a string for updates to the array’s elements. To return the updated string, use a getter to convert the elements of the array to a string using `join()`.

```javascript
@track arr = ['a','b'];

get computedArray() { return this.arr.join(','); }

update() {
  this.arr[0] = 'x';
  this.arr.push('c');
}
```

## Observe Complex Objects

Let’s look at a component with a field, `x`, of type `Date`. The template has a few buttons that change the internal state of `x`. This example highlights that `new Date()` creates an object, as it is not a plain JavaScript object internal state mutation will not be observed by the LWC engine, even though the code uses `@track`.

```javascript
// trackDate.js
import { LightningElement, track } from "lwc";
export default class TrackDate extends LightningElement {
  @track x = new Date();

  initDate() {
    this.x = new Date();
  }

  updateDate() {
    this.x.setHours(7); // No mutation detected
  }
}
```

Similarly to our previous example, the template has a few buttons that change the internal state of `x`.

<!-- prettier-ignore -->
```html
<!-- trackDate.html -->
<template>
  <p>Date: {x}</p>

  <button onclick={initDate}>Init</button>
  <button onclick={updateDate}>Update</button>
</template>
```

When you click the **Init** button, the change is observed and the template is rerendered. Lightning Web Components observes that `x` is pointing to a new `Date` object. However, when you click **Update**, the template isn’t rerendered. Lightning Web Components doesn’t observe changes to the value of the `Date` object.

To ensure that the template is rerendered when the value changes, clone the existing date and update its value.

```javascript
updateDate() {
  const cloned = new Date(this.x.getTime());
  cloned.setHours(7);

  // Assign the new date instance to rerender the component.
  this.x = cloned;
}
```

**note:** When you set a property to a value that can’t be tracked, a warning is logged. If you’re trying to debug a scenario where the component isn’t rerendering on change, look in your browser console. For our example, the browser console logs this helpful warning:

`Property "x" of [object:vm TrackDate] is set to a non-trackable object, which means changes into that object cannot be observed.`

## Example: Reactive Strings for User Input

When you enter a value in the First Name or Last Name field, the component converts it to uppercase and displays it.

![Input fields for first and last names. The entered names are transformed to uppercase.](https://developer.salesforce.com/media/hello_expressions.png)

<!-- prettier-ignore -->
```html
<!-- helloExpressions.html -->

<template>
  <lightning-card title="HelloExpressions" icon-name="custom:custom14">
    <div class="slds-m-around_medium">
      <lightning-input
        name="firstName"
        label="First Name"
        onchange={handleChange}
      ></lightning-input>
      <lightning-input
        name="lastName"
        label="Last Name"
        onchange={handleChange}
      ></lightning-input>
      <p class="slds-m-top_medium">Uppercased Full Name: {uppercasedFullName}</p>
    </div>
  </lightning-card>
</template>
```

The component’s class defines the `firstName` and `lastName` fields. Because they’re used in the getter of a property that’s used in the template (`uppercasedFullName`), the component rerenders when their values change.

```javascript
// helloExpressions.js

import { LightningElement } from "lwc";

export default class TrackExample extends LightningElement {
  firstName = "";
  lastName = "";

  handleChange(event) {
    const field = event.target.name;
    if (field === "firstName") {
      this.firstName = event.target.value;
    } else if (field === "lastName") {
      this.lastName = event.target.value;
    }
  }

  get uppercasedFullName() {
    return `${this.firstName} ${this.lastName}`.trim().toUpperCase();
  }
}
```

**note:** Fields are reactive. Expando properties, which are properties added to an object at runtime, aren’t reactive.

**tip:** See the [helloExpressions](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/helloExpressions) component in the `lwc-recipes` repository.

**See Also**

- [Fields, Properties, and Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-intro.md)

<!-- document id=286fef2fe0e18d8ede0ecf684c934aad1baf7a0809c9f9f5bd76a3591f61ec49 url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-read.md -->

# `read(options)`

Reads an NFC tag and returns the data read from it.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
read(options?: NFCServiceOptions): Promise<Object>;
```

## Parameters

- `options`—(Required) An [`NFCServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md#nfcserviceoptions) object to configure the NFCService request.

## Returns

A Promise object that resolves to an array containing a single [NFCMessage](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md#nfcmessage) object.

A rejected promise returns a [`NFCServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md#nfcservicefailure).

## Usage

Use this function to read data from an NFC tag.

```javascript
myNFCService
  .read(options)
  .then((readText) => {
    this.results.records.parsed.payload = readText;
  })
  .catch((error) => {
    this.readText = [];
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- The design pattern of returning an array containing a single `NFCMessage` object instead of just the `NFCMessage` object is intentional. It’s to make extensibility updates easier, in case future enhancements to NFCService include the ability to read multiple NFC tags.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels the operation, the promise is rejected with a `NFCServiceFailure.code` value of USER_DISMISSED.

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)

<!-- document id=73d6bbfd7907bede9f7ba06db96651d7d01b762ce9c5206d228ffdfd31ac3cc5 url=/developer/current/en-us/lwc/lwc/guides/reference/reference.md -->

# Reference

The Lightning Web Components Developer Guide contains reference documentation for the Lightning Web Components development model.

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags.md)
- [HTML template directives](https://developer.salesforce.com/docs/platform/lwc/guide/reference-directives.md)
- [HTML Template Errors](https://developer.salesforce.com/docs/platform/lwc/guide/reference-template-errors.md)
- [Decorators](https://developer.salesforce.com/docs/platform/lwc/guide/reference-decorators.md)
- [Supported Objects for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/reference-objects-lwc.md)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.md)
- [LWC API Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-api-modules.md)
- [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-page-reference-type.md)

The reference section also covers documentation for wire service adapters and imperative JavaScript functions, as listed in the TOC menu.

**note:** For standard JavaScript documentation, see the [Mozilla Developer Network (MDN) JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference).

<!-- document id=aab92f05dd34a7cdcc554f397a2892f19e592de76a1854ad38e4eeabd81c7310 url=/developer/current/en-us/lwc/slds_linter/guides/reference/reference-intro.md -->

# Reference

Learn about the various [commands](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-commands.md) that you can use to work with SLDS Linter and the [rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.md) that it supports.

<!-- document id=361ca81498bcfcf8bfa8aac7fff3e91b3dd278e3029d62f96b5abc4118b71314 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-reference-by-editor-attribute.md -->

# Reference a Custom Property Editor by Editor Attribute

A component property can reference a custom property editor directly through the `editor` attribute. The `editor` attribute is a reference to a custom property editor by a `fullyQualifiedName` string. This option is best if you want only to override the default user experience, without needing the additional validations of a custom property type.

In the Custom Article component example in the [sample components](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples), you specify an `editor` reference to the custom `alignmentCPE` for the `textAlignment` property.

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="customArticle">
 <masterLabel>Custom Article</masterLabel>
 <apiVersion>66.0</apiVersion>
 <targets>
   <target>lightningCommunity__Page</target>
   <target>lightningCommunity__Default</target>
 </targets>
 <targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property  name="textAlignment" type="String" editor="c/alignmentCPE" label="Text Alignment"/>
  </targetConfig>
 </targetConfigs>
</LightningComponentBundle>
```

Don't use the `editor` attribute for a property if the property's `type` attribute references a custom `LightningTypeBundle`. Instead, specify the editor component as a component override in the `editor.json` file of the custom `LightningTypeBundle`. See [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.html) for details.

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)
- [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.html)

<!-- document id=ff30160cbc0ae6a35a474ba5549227ba64d807f7802d0f06967bf34e48f42bd9 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-reference-by-type-attribute.md -->

# Reference a Custom Property Type by Type Attribute

A component property can reference a custom property type via the existing `type` attribute. Previously, the `type` property was limited to a specific set of types, such as String, Integer, Boolean. Now the `type` property can be a `fullyQualifiedName` string that references a standard Lightning type or a custom `LightningTypeBundle`.

In the Custom Article component example, update the `js-meta.xml` file for `CustomArticle` and use the `type` attribute to reference a Lightning property type for the `articleDate` property.

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="customArticle">
 <masterLabel>Custom Article</masterLabel>
 <apiVersion>66.0</apiVersion>
 <targets>
   <target>lightningCommunity__Page</target>
   <target>lightningCommunity__Default</target>
 </targets>
 <targetConfigs>
   <targetConfig targets="lightningCommunity__Default">
     <property  name="articleDate" type="lightning__dateType" label="Date Updated" />
   </targetConfig>
 </targetConfigs>
</LightningComponentBundle>
```

In the same component example, you use the `type` attribute to reference the custom property type `layoutProperty`.

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="customArticle">
 <masterLabel>Custom Article</masterLabel>
 <apiVersion>66.0</apiVersion>
 <targets>
   <target>lightningCommunity__Page</target>
   <target>lightningCommunity__Default</target>
 </targets>
 <targetConfigs>
   <targetConfig targets="lightningCommunity__Default">
       <property name="layoutProperties" type="c__layoutProperty" label="Layout" />
   </targetConfig>
 </targetConfigs>
</LightningComponentBundle>
```

You can override the `label` and `description` attributes in the `<property>` definition of a custom property type. A change to the `label` attribute overrides the property's `title` attribute.

In the preceding example, the `layoutProperty` label "Layout" overrides the title "Layout Properties" specified in the `schema.json` file.

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)

<!-- document id=08e5996caab2215e9ea05ab051f0ebe7bb94b424cf6b25a9db8cf6856883598b url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-html-attributes.md -->

# Reflect JavaScript Properties to HTML Attributes

You can control whether public JavaScript properties appear as attributes in the rendered HTML of a Lightning web component. Allowing properties to appear as attributes is especially important when creating accessible components, because screen readers and other assistive technologies use HTML attributes.

All HTML attributes are reactive by default. When an attribute’s value changes in the component HTML, the component is rerendered.

To enable a screen reader to read a value aloud to the user, use `@api` to expose a public `title` attribute.

**note:** When you take control of an attribute by exposing it as a public property, the attribute doesn't appear in the HTML output by default.

To pass the value through to the rendered HTML as an attribute (to reflect the property), define a getter and setter for the property and call the `setAttribute()` method.

You can also perform operations in the setter. Use a field to hold the computed value.

This example exposes `title` as a public property. It converts the title to uppercase and uses the property `_privateTitle` to hold the computed value of the title. The setter calls `setAttribute()` to reflect the property’s value to the HTML attribute.

```javascript
// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  _privateTitle;

  @api
  get title() {
    return this._privateTitle;
  }

  set title(value) {
    this._privateTitle = value.toUpperCase();
    this.setAttribute("title", this._privateTitle);
  }
}
```

```html
/* parent.html */
<template>
  <c-my-component title="Hover Over the Component to See Me"></c-my-component>
</template>
```

```html
/* Generated HTML */
<c-my-component title="HOVER OVER THE COMPONENT TO SEE ME">
  <div>Reflecting Attributes Example</div>
</c-my-component>
```

To make sure that you understand how JavaScript properties reflect to HTML attributes, look at the same code without the call to `setAttribute()`. The generated HTML doesn’t include the `title` attribute.

```javascript
// myComponent.js
import { LightningElement, api } from "lwc";

export default class MyComponent extends LightningElement {
  _privateTitle;

  @api
  get title() {
    return this._privateTitle;
  }

  set title(value) {
    this._privateTitle = value.toUpperCase();
    // this.setAttribute('title', this._privateTitle);
  }
}
```

```html
/* parent.html */
<template>
  <c-my-component title="Hover Over the Component to See Me"></c-my-component>
</template>
```

```html
/* Generated HTML */
<c-my-component>
  <div>Reflecting Attributes Example</div>
</c-my-component>
```

Before you set a value, check if the value has already been set by the consumer.

```javascript
// myComponent.js
import { LightningElement } from "lwc";

export default class MyComponent extends LightningElement {
  connectedCallback() {
    const tabindex = this.getAttribute("tabindex");

    // Set the tabindex to 0 if it hasn’t been set by the consumer.
    if (!tabindex) {
      this.setAttribute("tabindex", "0");
    }
  }
}
```

Setting the `tabindex` using `this.setAttribute()` results in this markup.

```html
<c-my-component tabindex="0"></c-my-component>
```

To set and get these attributes, use `setAttribute()` and `getAttribute()`.

- `for`
- `aria-activedescendant`
- `aria-controls`
- `aria-describedby`
- `aria-details`
- `aria-errormessage`
- `aria-flowto`
- `aria-labelledby`
- `aria-owns`

To hide HTML attributes from the rendered HTML, call `removeAttribute()`.

**See Also**

- [Component Accessibility](https://developer.salesforce.com/docs/platform/lwc/create/create-components-accessibility.md)
- [_MDN Web Docs_: setAttribute() method](https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute)
- [_MDN Web Docs_: getAttribute() method](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAttribute)

<!-- document id=6e19faad2ce5a1ba846b3d9ca71d6013ae76eea8120df7ff08b01969f96308b9 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-graphql-refresh.md -->

# `refresh`

The [`lightning/graphql` module](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.md) caches your query results for faster loading. To update the cache and get fresh data, use the `refresh` method that's returned by the wire adapter.

**note:** `lightning/graphql` doesn’t currently support Mobile Offline use cases. For more information, see [GraphQL API Wire Adapter Comparison](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-intro.md).

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/graphql";

export default class MyGQLQuery extends LightningElement {
  records;
  errors;
  _refresh;

  @wire(graphql, {
    query: gql`
      // your query here
    `,
  })
  graphqlQueryResults({ data, errors, refresh }) {
    if (data) { //do something }
    this.errors = errors;
    this._refresh = refresh;
  }
  async handleRefresh() {
    return this._refresh();
  }
}
```

## GraphQL API Resource

```html
POST /graphql
```

The GraphQL wire adapter uses this [GraphQL API resource](https://developer.salesforce.com/docs/platform/graphql/references/graphql?meta=Graphql).

For information on parameters and returned data, see the [`lightning/graphql` module documentation](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.md).

## `refresh` Method

`refresh` reuses the current query, variables, and operation name. It returns a Promise object. The Promise resolves when fresh data is delivered through the wire.

Use the `refresh` method after a mutation or any external change when you want fresh data, or to bypass cached results.

For more information, see [Update Cached Query Results](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-refresh.html) in the _GraphQL API Developer Guide_.

## Usage Considerations

Don't use `refresh()` in a polling pattern with `setTimeout()` or `setInterval()`. Polling creates unnecessary server load and can degrade performance. Instead, refresh the data once after a mutating operation completes. If you can't determine when a mutation finishes, provide an explicit user-driven refresh action, such as a refresh button, rather than polling automatically.

<!-- document id=961d758fca7d11cec94f47bece44036e9913b17ecf362008e52702c1f181517a url=/developer/current/en-us/lwc/lwc/guides/data/refreshview/data-refreshview.md -->

# Refresh Component Data with RefreshView API

Whether user-driven or app-invoked, the ability to synchronize data without reloading an entire page is a key user experience requirement. The RefreshView API and `lightning/refresh` module provide a standard way to refresh component data in LWC and Aura.

## Synchronize Data Using the RefreshView API

RefreshView API’s detailed control of refresh scope lets you create refined user experiences while maintaining backward compatibility.

RefreshView API gives you the option to update a hierarchy of components, known as a view, without reloading an entire page. This refresh ensures complete synchronization with data externally sourced by components that subscribe to the refresh event in that view. RefreshView API supports refreshes that are triggered by end users or web components. RefreshView API provides a standard mechanism for data refresh experiences in LWC components, allowing flexible control of refresh scopes.

RefreshView API can refresh data for Salesforce platform containers and custom LWC and Aura components.

Lightning Data Service supports RefreshView API. However, a custom component must initiate the actual data refresh. For example, call [`refreshApex()`](https://developer.salesforce.com/docs/platform/apex/apex.md) to refresh Apex data provisioned via the wire service. Or call [`refreshGraphQL()`](https://developer.salesforce.com/docs/platform/reference/graphql/reference-refreshgraphql.md) to update the data provisioned by the GraphQL wire adapter. See [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/data-guidelines.md).

## Limitations for Using RefreshView API

RefreshView API can work in orgs that have enabled
[Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-intro.html) or [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html). The protocol for registering containers and handlers is different for each security architecture.

The [base components for Aura](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/lightning_overview.htm) currently don’t support RefreshView API.

**note:** If a component uses the wire service, record data is updated via the `@wire(getRecord)`. Lightning Data Service keeps the data provisioned by the wire service updated each time the record is changed via any Lightning Data Service calls. If the record is updated via a server action such as an Apex call, call `notifyRecordUpdateAvailable` to update the `@wire`. These calls are done outside the context of RefreshView API.

**See Also**

- [RefreshView API User Experience](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-intro.md)
- [Considerations for Using RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-considerations.md)
- [Refresh Action](https://developer.salesforce.com/docs/platform/reference/state-managers/reference-state-managers-use.md#refresh-action) on state managers

<!-- document id=f87b7093b8972521c55e5e87421e45ca1948dd85a39deedf8e22fbd02cd323d5 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshevent-data-type.md -->

# RefreshEvent Properties

An event that is sent when a module signals a refresh to a container. The `RefreshEvent` properties are as follows.

| Property Name | Type   | Value | Description                                                                                          |
| ------------- | ------ | ----- | ---------------------------------------------------------------------------------------------------- |
| `bubbles`     | String | true  | This event bubbles.                                                                                  |
| `composed`    | String | true  | This event propagates outside the template in which it was dispatched.                               |
| `cancelable`  | String | true  | This event has default behavior that can be canceled. You can call `preventDefault()` on this event. |

See [Signal a Refresh with RefreshEvent](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md#signal-a-refresh-with-refreshevent) for more details on using `RefreshEvent`.

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=361bb7b7656fbfbecd0521b494ee5f104814705643a7f67d086cc03b486ec867 url=/developer/current/en-us/lwc/lwc/guides/reference/graphql/reference-refreshgraphql.md -->

# `refreshGraphQL(result)` (Deprecated)

**note:** The `lightning/uiGraphQLApi` module is deprecated. Use the [`lightning/graphql` module](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-module.md) instead. The deprecated module continues to work. However, newer features, such as optional fields and dynamic query construction, require the `lightning/graphql` module.

Triggers a query to re-run. This function updates the data provisioned by the GraphQL wire adapter imperatively.

`refreshGraphql()` enables you to control when you want the query to re-run, such as in response to a button click or via JavaScript. Call this function to send a GraphQL query request again to the server and update the client-side stored result set.

## Syntax

```javascript
import { LightningElement, api, wire } from "lwc";
import { gql, graphql, refreshGraphQL } from "lightning/uiGraphQLApi";

export default class MyGQLQuery extends LightningElement {
  @wire(graphql, {
    query: gql`
            query [your_graphql_query]`,
  })
  graphqlQueryResult(result) {
    this.graphqlData = result; // Store the result so refreshGraphql() can refresh it later
  }

  // Trigger this function via a refresh button on the UI, or via javascript
  @api
  async refresh() {
    return refreshGraphQL(this.graphqlData);
  }
}
```

See the [GraphQL query syntax](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.md).

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has many GraphQL API examples. Look for components that start with `graphql`, such as [graphqlRefresh](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/graphqlRefresh).

## Returns

A Promise object. The Promise isn’t resolved until the wire has received the latest data. The wire function might not be invoked again if the data that’s returned from the server hasn’t changed. Instead, wait for the Promise to resolve if you need to know when the refresh has completed. The actual value to which the Promise resolves is meaningless.

## Usage Considerations

Don't use `refreshGraphQL()` in a polling pattern with `setTimeout()` or `setInterval()`. Polling creates unnecessary server load and can degrade performance. Instead, refresh the data once after a mutating operation completes. If you can't determine when a mutation finishes, provide an explicit user-driven refresh action, such as a refresh button, rather than polling automatically.

**See Also**

- [_GraphQL API Developer Guide_: Use GraphQL API with Lightning Web Components](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html)

<!-- document id=b25582a3429d21065ee39f0643d2582fcdd5f2324225f8670e0f60cac52392b1 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshstatus-constants.md -->

# RefreshStatus Constants

Status enum that represents the overall status of the refresh process. When a refresh process completes, this status is emitted to a registered refresh container via a `Promise` result.

- `RefreshError`
  - The refresh process couldn’t run on descendant refresh handler nodes.
- `RefreshComplete`
  - Default. The refresh process has completed on all descendant refresh handler nodes.
- `RefreshCompleteWithErrors`
  - The refresh process has completed on descendant refresh handler nodes, but some children have reported an error.

```javascript
@type {{RefreshCompleteWithErrors: number, RefreshError: number, RefreshComplete: number}}

export const REFRESH_ERROR = 0;
export const REFRESH_COMPLETE = 1;
export const REFRESH_COMPLETE_WITH_ERRORS = 2;

```

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=db71c3b18aed9e171069443b4a82d29e113aee61fc7b2422ddad23685ee1ecbe url=/developer/current/en-us/lwc/lwc/guides/data/refreshview/data-refreshview-example.md -->

# RefreshView API Example

Using RefreshView API typically involves a chain of actions.

First, there must be a component somewhere on the page that can send a `RefreshEvent` event when a refresh is desired. In this example, the `refreshButton` component can signal a refresh.

```javascript
// refreshButton.js
import { LightningElement } from "lwc";
import { RefreshEvent } from "lightning/refresh";

export default class RefreshButton extends LightningElement {
  // signal a refresh programmatically
  // or via a button click
  beginRefresh() {
    this.dispatchEvent(new RefreshEvent());
  }
}
```

<!-- prettier-ignore -->
```html
<!-- refreshButton.html -->
<template>
  <button label="Refresh Button" onclick={beginRefresh}>Refresh</button>
</template>
```

Next, to participate in a view refresh, a component registers a handler method to be invoked after a container has received `RefreshEvent`. In this example, the handler method is registered in `refreshHandler.js`.

```javascript
//refreshHandler.js
import { LightningElement } from "lwc";
import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
export default class RefreshHandler extends LightningElement {
  refreshHandlerID;
  connectedCallback() {
    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
    // if the component runs in an org with Lightning Locker instead of Lightning Web Security (LWS), use
    // this.refreshHandlerID = registerRefreshHandler(this.template.host, this.refreshHandler.bind(this));
  }
  disconnectedCallback() {
    unregisterRefreshHandler(this.refreshHandlerID);
  }
  refreshHandler() {
    // example usage case for refresh participant
    // fetch some data and report status once complete
    let endPoint = "https://api.<your company>.com";
    return new Promise((resolve) => {
      fetch(endPoint, {
        method: "GET",
      });
      resolve(true);
    });
  }
}
```

Finally, there must be a component somewhere on the page that registers to receive `RefreshEvent`. In this example, `refreshContainer` registers to receive refresh events. It starts a refresh process when an event is received.

```javascript
// refreshContainer.js
import { LightningElement } from "lwc";
import {
  registerRefreshContainer,
  unregisterRefreshContainer,
  REFRESH_COMPLETE,
  REFRESH_COMPLETE_WITH_ERRORS,
  REFRESH_ERROR,
} from "lightning/refresh";

export default class RefreshContainer extends LightningElement {
  refreshContainerID;
  connectedCallback() {
    this.refreshContainerID = registerRefreshContainer(this, this.refreshContainer);
    // if the component runs in an org with Lightning Locker instead of LWS, use
    // this.refreshContainerID = registerRefreshContainer(this.template.host, this.refreshContainer.bind(this));
  }
  disconnectedCallback() {
    unregisterRefreshContainer(this.refreshContainerID);
  }
  refreshContainer(refreshPromise) {
    console.log("refreshing");
    return refreshPromise.then((status) => {
      if (status === REFRESH_COMPLETE) {
        console.log("Done!");
      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
        console.warn("Done, with issues refreshing some components");
      } else if (status === REFRESH_ERROR) {
        console.error("Major error with refresh.");
      }
    });
  }
}
```

Put the `refreshHandler` and `refreshButton` components in the `refreshContainer` template, including your namespace in the tags.
`c` is the default namespace in this example.

```html
<!-- refreshContainer.html -->
<template>
  <!-- Ensure handler exists within structure of container -->
  <div>
    <c-refresh-handler></c-refresh-handler>
  </div>
  <div>
    <c-refresh-button></c-refresh-button>
  </div>
</template>
```

**See Also**

- [RefreshStatus Constants](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshstatus-constants.md)
- [`lightning/refresh` module](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refresh.md)

<!-- document id=5b3c7788c25999a494211f187c100ea465b4967e0a8991720706a81538c304fe url=/developer/current/en-us/lwc/lwc/guides/data/refreshview/data-refreshview-intro.md -->

# RefreshView API User Experience

Reliable content refresh is a fundamental web UX requirement and can be either user-driven or app-invoked.

A typical flow for a user-triggered refresh is:

1.  A Lightning web component displays a button (or other user interface control) to start a process that synchronizes the data being displayed in the component with its source.
2.  When the button is tapped, the button component dispatches a [`RefreshEvent`](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshevent-data-type.md) event.
3.  The nearest level container component, which is registered with the RefreshView API, receives the `RefreshEvent`, stopping its propagation.
4.  The components’ refresh handlers initiate the refresh process on the appropriate components. They can display spinners, perform instrumentation, and do other things to prepare the UI to be refreshed.
5.  Descendant components of the handler participate in the refresh process through exposed API hooks. They can fetch data from a Salesforce org or perform other tasks to synchronize displayed data with the external data source.
6.  The refresh for the component hierarchy completes when all data is synchronized and updated onscreen.

For an app-triggered refresh:

1.  An application determines that a refresh is needed for a view to ensure the data is synchronized. For example, a refresh is needed after a reauthentication from an expired session, or after a pull-to-refresh action on a mobile UI.
2.  From this point, the refresh flow is similar to that described above for user-triggered refreshes.

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=0862efbd5eea2ebda3db2d1bfdad82f75c7b4e8de00f893dbc0233aa97378685 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-register-guest-buyer/reference-lightning-commerce-register-guest-buyer.md -->

# `registerGuestBuyer(guestBuyerInput)`

Registers a guest buyer account against a webstore.

## Syntax

```javascript
import { registerGuestBuyer } from 'lightning/commerceRegisterGuestBuyerApi';
registerGuestBuyer(guestBuyerInput: object): Promise<RegisterGuestBuyerOutput>
```

## Commerce API Resource

```
POST /commerce/webstores/{webstoreId}/accounts/{accountId}/actions/register-guest-buyer
```

`registerGuestBuyer` uses this [Commerce API resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_register_guest_buyer.htm).

## Parameters

- `webstoreId`—(Required) The ID of the webstore. The ID prefix is `0ZE`.
- `accountId`—(Required) The ID of the account to register as a guest buyer. The ID prefix is `001`.
- `version`—(Required) The API version for the adapter, for example, `v62.0`. Without this parameter, the call doesn't fire.
- `registerGuestBuyerInput`—(Optional) The request body. Pass an empty object `{}` when no fields are required.

## Returns

A `Promise` that resolves with a `RegisterGuestBuyerOutput` object with these fields:

- `success`—Indicates whether the registration was successful. Check this field even when the `Promise` resolves, because it can be `false` without the call throwing an error.
- `errors`—A list of errors if the registration failed. Each error has these fields:
  - `errorCode`—A machine-readable error code.
  - `message`—A human-readable error message.
  - `errorEntityId`—The ID of the entity the error relates to, when applicable.

## Usage

`registerGuestBuyer` is an imperative function, not a `@wire` adapter. It performs a mutation and must be called in response to a user action.

```javascript
import { LightningElement, api } from 'lwc';
import { registerGuestBuyer } from 'lightning/commerceRegisterGuestBuyerApi';

export default class RegisterGuestBuyerExample extends LightningElement {
  @api webstoreId;
  @api accountId;

  async handleRegister() {
    try {
      const result = await registerGuestBuyer({
        webstoreId: this.webstoreId,
        accountId: this.accountId,
        version: 'v62.0',
        registerGuestBuyerInput: {},
      });

      if (result.success) {
        console.log('Guest buyer registered successfully');
      } else {
        console.error('Registration failed:', result.errors);
      }
    } catch (error) {
      console.error('Error registering guest buyer:', error);
    }
  }
}
```

## Error Handling

Always check the `success` field on the resolved value. A resolved `Promise` doesn't guarantee a successful registration. If the call itself fails, the `Promise` rejects with an error.

<!-- document id=58478b21b9118b06d2988bb00aaf61b0321c169eda0de349c138cf7abdfe9973 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshview-registerrefreshcontainer.md -->

# `registerRefreshContainer()`

Registers a container to receive the dispatched refresh event and begin the refresh process when the event is received. To use the RefreshView API, there must be a component somewhere on the page that registers to receive `RefreshEvent`.

## Syntax

```typescript
import { LightningElement, wire } from "lwc";
import { registerRefreshContainer } from "lightning/refresh";

export function registerRefreshContainer(contextElement, providerMethod);
```

## Parameters

- `contextElement`—(Required) An `HTMLElement` representing the container to receive a refresh event.
- `providerMethod`—(Required) A `Function` identifying the callback method to be invoked when the refresh process begins. This callback receives a `Promise` as a parameter that represents the status of the overall refresh process.

## Returns

Returns a numeric `refreshNode.handle` value that uniquely identifies the container that is to receive refresh events. You can pass this value to `unregisterRefreshContainer()` to stop the component from receiving refresh events.

## Usage

To register to receive a [`RefreshEvent`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshevent-data-type.md) signal, use the `registerRefreshContainer()` method in a container’s `connectedCallback()`.

**tip:** If the component must run in an org that has Lightning Locker enabled, use the modified format of the `registerRefreshContainer()` parameters shown in the code comments inside `connectedCallback()`.

```javascript
import { LightningElement } from "lwc";
import {
  registerRefreshContainer,
  unregisterRefreshContainer,
  REFRESH_ERROR,
  REFRESH_COMPLETE,
  REFRESH_COMPLETE_WITH_ERRORS,
} from "lightning/refresh";

export default class RefreshContainer extends LightningElement {
  refreshContainerID;
  connectedCallback() {
    this.refreshContainerID = registerRefreshContainer(this, this.refreshContainer);
    // if the component runs in an org with Lightning Locker instead of Lightning Web Security (LWS), use
    // this.refreshContainerID = registerRefreshContainer(this.template.host, this.refreshContainer.bind(this));
  }
  disconnectedCallback() {
    unregisterRefreshContainer(this.refreshContainerID);
  }
  refreshContainer(refreshPromise) {
    console.log("refreshing");
    return refreshPromise.then((status) => {
      if (status === REFRESH_COMPLETE) {
        console.log("Done!");
      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
        console.warn("Done, with issues refreshing some components");
      } else if (status === REFRESH_ERROR) {
        console.error("Major error with refresh.");
      }
    });
  }
}
```

When you pass `this` to `registerRefreshContainer()`, event listeners are bound to the element for `RefreshEvent`.

When a registered refresh container receives `RefreshEvent`, the refresh process begins on the container's refresh tree.

**note:** `RefreshEvent` follows DOM event bubbling rules, so the refresh container that begins this process is the nearest registered ancestor to the signaling component. To refresh the entire page, you must either register a container at the proper level or allow the page host to act as the container.

The registered container callback — in this example `refreshContainer()` — is invoked when the container receives `RefreshEvent`. The callback receives a `Promise` as a parameter when the refresh process begins. This `Promise` is resolved with a [`RefreshStatus`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshstatus-constants.md) value when the refresh process finishes.

The registered container callback method can be used to manage processes surrounding the refresh, such as:

- Instrumenting begin/end
- Showing spinners
- Error handling
- Toasts

You must unregister the view controller as a refresh container in `disconnectedCallback()` using the [`unregisterRefreshContainer()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-unregisterrefreshcontainer.md) method.

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=cfa896c6a2660a7200d09cf3b668445f86ed3aa70f926a2f7f9147ab0128e8e7 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshview-registerrefreshhandler.md -->

# `registerRefreshHandler()`

Registers a component’s refresh handler method to be included in a refresh process.

## Syntax

```typescript
import { LightningElement, wire } from "lwc";
import { registerRefreshHandler } from "lightning/refresh";

export function registerRefreshHandler(contextElement, providerMethod);
```

## Parameters

- `contextElement`—(Required) An `HTMLElement` representing the container that is participating in the refresh process.
- `providerMethod`—(Required) A `Function` identifying the callback method to be invoked when the refresh process begins. The handler callback is required to return a `Promise` that represents the refresh status of its particular element.

## Returns

Returns a numeric `refreshNode.handle` value that uniquely identifies the node of this component on the refresh tree. You can pass this value to [`unregisterRefreshHandler()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-unregisterrefreshhandler.md) to remove this component’s refresh handler method from the refresh process.

## Usage

Use the `registerRefreshHandler()` method to register components belonging to refresh-enabled views to be included in the refresh process.

To participate in a view refresh, a component registers a handler method. Use the `registerRefreshHandler()` method in the container’s `connectedCallback()` to register a handler method.

**tip:** If the component must run in an org that has Lightning Locker enabled, use the modified format of the `registerRefreshHandler()` parameters shown in the code comments inside `connectedCallback()`.

A handler method is invoked after a container has received `RefreshEvent`. Registered containers compose a "refresh tree" of registered refresh handlers, the order of which emulates the DOM.

```javascript
import { LightningElement } from "lwc";
import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
export default class RefreshHandler extends LightningElement {
  refreshHandlerID;
  connectedCallback() {
    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
    // if the component runs in an org with Lightning Locker instead of Lightning Web Security (LWS), use
    // this.refreshHandlerID = registerRefreshHandler(this.template.host, this.refreshHandler.bind(this));
  }
  disconnectedCallback() {
    unregisterRefreshHandler(this.refreshHandlerID);
  }
  refreshHandler() {
    // example usage case for refresh participant
    // fetch some data and report status once complete
    let endPoint = "https://api.<your company>.com";
    return new Promise((resolve) => {
      fetch(endPoint, {
        method: "GET",
      });
      resolve(true);
    });
  }
}
```

Registered refresh methods in the refresh tree are invoked in a breadth-first order from the registered container’s node. This ensures that higher level (parent) handlers resolve before lower level (child) handlers are invoked.

The registered container callback method must:

- Return a `Promise` that resolves to a `Boolean`:
  - `true` if the component has completed operations for a refresh and the refresh process should continue down the refresh tree from this node
  - `false` to prevent the refresh process from continuing to child elements of this node
- Perform necessary view update operations in accordance with current state.
- Ensure data and state are resynchronized, if necessary.
- Show appropriate UI during the process, such as spinners or toasts.

You must unregister your component’s handler methods by calling [`unregisterRefreshHandler()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-unregisterrefreshhandler.md) in `disconnectedCallback()`.

**See Also**

- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)
- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)

<!-- document id=d4de077417b82ba840de3e2646eb8a3f97aacdccabe65e1d36dfa67bb90e74a5 url=/developer/current/en-us/lwc/lightning-components-security/guides/get-started/get-started-release-notes.md -->

# Release Notes

Use the Salesforce Release Notes to learn about the most recent updates and changes to security for Lightning Components.

For updates and changes that impact security for Lightning web components and Aura components, see [Lightning Components](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc.htm) in the Salesforce Release Notes.

For updates and changes that impact your org's overall security, see [Security, Identity, and Privacy](https://help.salesforce.com/s/articleView?id=release-notes.rn_security.htm) in the Salesforce Release Notes.

<!-- document id=ff5c9dd10b319cebb9dce0e0763aa2c3a429e69e5c0848f74586be72c85ba4b8 url=/developer/current/en-us/lwc/slds-validator/guides/release-notes.md -->

# Release Notes

Here are the new and changed features of SLDS Validator. We publish new versions of SLDS Validator frequently. Check back here often to read the latest information.

## 2.0.12 (March 2025)

- NEW: We separated these rule sets into their own categories in both VS Code and in Sarif Viewer reports: BEM, DEPRECATED, and DENSITY.
- ADD: To smooth the transition from SLDS 1 to SLDS 2, we reintroduced several classes from SLDS 1 in SLDS 2 rules.

## 2.0.11 (February 2025)

- FIX: We fixed user-reported issues with SARIF reports.
- FIX: We re-enabled the mobile validation rule.

<!-- document id=d02c606732c452dcecfa9a3b69f0d6799543eb4f26a253aac568122620460403 url=/developer/current/en-us/lwc/slds_linter/guides/get-started/get-started-release-notes.md -->

# Release Notes for SLDS Linter

Here are the new and changed features in recent updates of SLDS Linter.

## 1.2.0 (February 26, 2026)

NEW: The `no-deprecated-classes-slds2` rule now validates both CSS and HTML files. Previously, it validated only HTML files.

## 1.1.0 (January 12, 2026)

- **CHANGE:** Review linter validation results easily in the ESLint `stylish` output format. This human-readable output provides a clear and organized view of validation issues in your terminal, helping you identify and resolve issues efficiently.

  This example shows the SLDS Linter validation results before the change.

  ![Screenshot showing Linter validation results in terminal before the ESLint `stylish` format is applied.](https://developer.salesforce.com/media/slds_linter/linter_validation_results_before_ESLint.png)

  This example shows the SLDS Linter validation results in the ESLint `stylish` format.

  ![Screenshot showing Linter validation results in terminal in the ESLint `stylish` format.](https://developer.salesforce.com/media/slds_linter/linter_validation_results_after_ESLint.png)

- **FIX:** We fixed some under-the-hood issues.

## 1.0.7 (November 26, 2025)

**NEW:** Easily configure additional plug-ins along with ESLint to lint your code. The `.eslint.config.mjs` configuration file includes a new `sldsCssPlugin()` helper function. This function facilitates the integration of ESLint with other plug-ins, such as the CSS plug-in (`@eslint/css`), while maintaining all the required dependencies. For more information, see [Use SLDS Linter with Custom Configuration Files](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-custom-config-files.html).

## 1.0.6 (November 20, 2025)

**FIX:** We fixed some under-the-hood bugs.

## 1.0.5 (November 6, 2025)

**FIX:** SLDS Linter now identifies all valid SLDS 2 styling hooks correctly. Previously, some valid styling hooks were incorrectly reported as violations.

## 1.0.4 (November 4, 2025)

**FIX:** You can now configure the ESLint plug-in to lint CSS files by providing the ESLint recommended rules and SLDS 2 rules in the same configuration. Previously, configuring both sets of rules together resulted in an error.

## 1.0.3 (October 24, 2025)

**FIX:** We fixed some under-the-hood bugs.

## 1.0.2 (September 25, 2025)

- **NEW:** We’re excited to announce that SLDS Linter is now integrated into Salesforce Code Analyzer.  
  That means you can use Code Analyzer via the CLI or the VS Code extension to scan your code against SLDS Linter rules. This integration provides these benefits.

  - Run all SLDS Linter rules within Salesforce Code Analyzer alongside its suite of other powerful engines and rules rather than running separate tools.
  - Integrate SLDS Linter analysis into your CI/CD pipelines to detect code violations during check-ins and builds.
  - Use the [Code Analyzer VS Code extension](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html) to see violations indicated by squiggly line highlights.
    For more information, see [Use SLDS Linter Rules with Salesforce Code Analyzer](https://developer.salesforce.com/docs/platform/slds-linter/use/use-work-with-code-analyzer.md).

- **NEW**: The `lwc-token-to-slds-hook` rule reports instances where deprecated `--lwc` tokens are used in the code. For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html).

## 1.0.1 (September 23, 2025)

**CHANGE:** To provide a unified linting experience, we migrated these Stylelint-based rules to ESLint.

- `enforce-component-hook-naming-convention`
- `enforce-sds-to-slds-hooks`
- `no-hardcoded-values-slds2`
- `no-slds-class-overrides`
- `no-slds-private-var`
- `no-unsupported-hooks-slds2`
- `reduce-annotations`
- `no-slds-namespace-for-custom-hooks`
- `no-sldshook-fallback-for-lwctoken`
- `no-important-tag`

This migration was possible because ESLint version 9.0.0 and later supports Cascading Style Sheet (CSS) files, along with HTML and Component (CMP) files. The rules continue to work the same as before.
For information about the rules, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html)

## 0.5.3 (September 4, 2025)

- **NEW:** The `no-hardcoded-values-slds2` rule now validates the `line-height` CSS property.  
  For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-hardcoded-values-slds2).

* **CHANGE:** You can now get faster results when you execute the `lint` and `report` commands. We’ve improved file scanning performance by optimizing glob pattern resolution and directory traversal.

## 0.5.2 (August 26, 2025)

**FIX:** When you run SLDS Linter, the Stylelint extension now correctly processes CSS files. This includes files that contain the `font-weight` CSS property with a nonnumerical value assigned to it.

In this example, the `font-weight` CSS property is set to the nonnumerical value `bold`. After this fix, the Stylelint extension processes these instances correctly.

```
.myRule
{
    font-weight: bold;
    display: inline-block;
}
```

## 0.5.1 (August 14, 2025)

- **NEW:** The `no-hardcoded-values-slds2` rule validates several additional shorthand CSS properties.

  - `outline`, `outline-width`, `outline-color`
  - `border-width`
  - `margin`
  - `padding`
  - `max-height`, `min-height`
  - `max-width`, `min-width`

- **FIX:** When you run the `lint` command with the `--fix` option, it correctly fixes issues identified when multiple hard-coded values are assigned to the `padding` or `margin` CSS properties.

  In this example, four values of `16px` are assigned to the `padding` property.

  ```
  padding: 16px 16px 16px 16px;
  ```

  Previously, while replacing the hard-coded values with styling hooks, SLDS Linter recursively nested the styling hooks.

  ```
  // Before

  padding: var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, var(--slds-g-spacing-4, 16px))))))))))))) 16px 16px 16px;
  ```

  After the fix, SLDS Linter correctly replaces each hard-coded value with a styling hook, and retains the hard-coded value as fallback.

  ```
  // After

  padding: var(--slds-g-spacing-4, 16px) var(--slds-g-spacing-4, 16px) var(--slds-g-spacing-4, 16px) var(--slds-g-spacing-4, 16px);
  ```

## 0.5.0 (August 1, 2025)

- **NEW**: We’re excited to announce that SLDS Linter now supports ESLint version 9.0.0 and later. This upgrade provides these improvements.

  - Flat Config Support: Full support for ESLint’s new flat config system. Enables ‌integration with modern JavaScript projects using ESLint version 9.0.0 and later.
  - Continued Legacy Config Support: For projects using ESLint version 8.x, the plug-in maintains backward compatibility with the legacy configuration, allowing a phased migration.
  - Simplified Import: The ESLint plug-in offers a simple import mechanism from the root (`@salesforce-ux/eslint-plugin-slds`), and it automatically adapts to your ESLint configuration type (legacy or flat).

  After this upgrade, if you emit the custom configuration file for the ESLint plug-in, it creates an `.eslint.config.mjs` file. Use this file the same way as before.  
  For more information, see [Use SLDS Linter with Custom Configuration Files](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-custom-config-files.html).

- **CHANGE**: If you emit the custom configuration file for the Stylelint plug-in, it now creates a `.stylelint.config.mjs` file. Use this file the same way as before.  
  Previously, the `emit` command generated a `.stylelintrc.yml` file.  
  For more information, see [Use SLDS Linter with Custom Configuration Files](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-custom-config-files.html).

- **FIX**: Only the `no-deprecated-classes-slds2` rule reports deprecated SLDS 2 classes as issues. The `no-slds-class-overrides` rule no longer reports these classes as overrides. Previously, the `no-deprecated-classes-slds2` and `no-slds-class-overrides` rules reported deprecated SLDS 2 classes as issues.

  In this example, `slds-is-focused` is a deprecated SLDS 2 class. The `no-deprecated-classes-slds2` rule reports it as an error.

  ```
  .THIS .slds-is-focused
  {
   border-color: 1px solid var(--slds-g-color-border-success-2)
  }
  ```

- **FIX**: When you run the `lint` command with the `--fix` option, the `reduce-annotations` rule no longer removes these SLDS Validator annotations.

  - `@sldsValidatorIgnoreNextLine`
  - `@sldsValidatorAllow`
  - `@sldsValidatorIgnore`

- **FIX**: The ESLint and Stylelint plug-ins now show validation issues in plain text format. Previously, ‌issues were displayed as composite values.

  This example shows a validation issue displayed as composite values before the fix.

  ```
  {"message":"slds-button--brand has been retired. Update it to the new name slds-button_brand.","suggestions":["slds-button_brand"]}
  ```

  This example ‌shows a validation issue displayed as plain text after the fix.

  ```
  "slds-button--brand has been retired. Update it to the new name slds-button_brand."
  ```

## 0.3.0 (July 7, 2025)

NEW: Use the `no-slds-namespace-for-custom-hooks` rule to identify custom styling hooks that use the `--slds` or `--sds` namespace. To differentiate between custom styling hooks and SLDS styling hooks, create the identified custom styling hooks in your namespace.  
For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html).

NEW: The `no-sldshook-fallback-for-lwctoken` rule  
reports instances where `--slds` styling hooks are provided as fallback values for `--lwc` tokens. To fix these instances, replace the `--lwc` token with a suitable `--slds` styling hook. Retain the `--lwc` token as the fallback value.
For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html).

NEW: The `enforce-component-hook-naming-convention` rule reports `--slds-c` component-level styling hooks that use a deprecated naming convention. Keep in mind that component-level styling hooks are only available in SLDS 1.  
For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html) in the _SLDS Linter Developer Guide_ and [Styling Hooks](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks) on the SLDS 2 website.

NEW: The `no-hardcoded-values-slds2` rule reports instances of hard-coded values that specify font weight. The rule recommends suitable styling hooks as replacements for the hard-coded values.  
For more information, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html).

**Example**

Existing code:

Here, ‌`700` is a hard-coded value that specifies the font weight.

```
.THIS .example-1
{
  font-weight:700
}
```

Recommended code:

Use the `--slds-g-font-weight-7` styling hook to specify the font weight. Retain `700` as the fallback value.

```
.THIS .example-1
{
  font-weight: var(--slds-g-font-weight-7, 700);
}
```

NEW: For each Stylelint rule, you can now define the CSS properties that you want ‌the rule to validate. In the `.stylelintrc.yml` configuration file, use the `propertyTargets` option to define the required CSS properties for each rule. This is an optional configuration to list specific CSS properties. By default, all ‌CSS properties are validated.

**Example**

For the `no-hardcoded-values-slds2` rule, the `propertyTargets` option is set to validate two CSS properties: `color` and `background-color`.

```
//.stylelintrc.yml
slds/no-hardcoded-values-slds2:
        - true
        - severity: warning
        - propertyTargets:
            - color
            - background-color
```

FIX: We updated multiple Stylelint rules to stop reporting valid fallback values as issues. Each rule no longer reports these fallback values.

- `enforce-sds-to-slds-hooks`: `--sds` styling hooks
- `lwc-token-to-slds-hook`: `--lwc` tokens
- `no-deprecated-token-slds1`: `t()` or `token()` functions
- `no-slds-var-without-fallback`: SLDS styling hooks
- `no-unsupported-hooks-slds2`: deprecated SLDS styling hooks

**Example**

These examples show fallback values that were previously reported as issues. With this fix, these values are valid and no longer reported by SLDS Linter.

```
// Previously, using --sds-g-color-border-1 as fallback value was reported

.THIS .container
{
  border-color: var(--slds-g-color-border-1, var(--sds-g-color-border-1))
}

// Previously, using --lwc-colorBackgroundAlt as fallback value was reported

.THIS .container
{
  background-color:var(--slds-g-color-surface-container-1,var(--lwc-colorBackgroundAlt));
}

// Previously, using t(fontSize3) as fallback value was reported

.THIS .container
{
   font-size: var(--slds-g-font-size-base, t(fontSize3))
}
```

FIX: The `no-hardcoded-value-slds2` rule correctly identifies the complete hard-coded value specified for the `box-shadow` property as one value instead of multiple, separate values. If the hard-coded value has a matching styling hook, use the recommendation to update your code.

**Example**

Existing code:

In this example, `0 0 1.5px 0 #00000017, 0 1.4px 1.5px 0 #00000017, 0 -1px 1px 0 #00000009` is the hard-coded value ‌specified for the `box-shadow` property. Before this fix, the rule reported individual parts of the value, such as `#00000017, 1.4px,` as an issue.

```
.shadow-multi-down-1
{
  box-shadow: 0 0 1.5px 0 #00000017, 0 1.4px 1.5px 0 #00000017, 0 -1px 1px 0 #00000009;
}
```

After this fix, the rule identifies the entire hard-coded value as a single value and reports it.

Recommended Code:

Replace the hard-coded value with the suggested `--slds-g-shadow-1` styling hook.

```
.shadow-multi-down-1
{
  box-shadow: var(--slds-g-shadow-1)
}
```

FIX: Previously, the `no-slds-class-overrides` rule reported instances of SLDS classes in any location within a selector. The rule now correctly reports only instances where SLDS classes are specified at the end of the selector.

**Example**

This example uses the .`slds-box_small` SLDS class in the middle of the selector. Before this fix, we identified this location of a class in the middle as an issue.

```
// Before .slds-box_small is reported as slds class override (FALSE positive)

.THIS .slds-box_small .box-title
{
  color: var(--slds-g-color-palette-blue-10)
}
```

This example uses the `.slds-box_border` SLDS class at the end of the selector. After this fix, only the location of a class at the end of a selector is correctly identified as an issue.

```
// Now .slds-box_border will be reported as slds class override

.THIS .slds-box_small .slds-box_border:hover
{
  .border-color: var(--slds-g-color-palette-hot-orange-40)
}
```

## 0.2.2 (June 25, 2025)

NEW: SLDS Linter is now compatible with Stylelint version 16.21.0 and later. The `rules` property is added to the `.stylelintrc.yml` configuration file for compatibility.

## 0.2.0 (June 5, 2025)

FIX: The `no-unsupported-hooks-slds2` rule now reports all types of deprecated styling hooks. The rule identifies global, shared, and kinetics styling hooks.

This example uses a deprecated component styling hook. Before this fix, we identified only these instances.

```
 .div-modal-cls
 {
 --slds-c-breadcrumbs-spacing-inline-start: 1rem;
 }
```

This example uses deprecated global styling hooks. After this fix, we also identify these instances.

```
/* Global hooks */

.global-example
{
  --slds-g-color-border-base-2: #dddbda;
  --slds-g-color-border-base-3: #c9c7c5;
  border: 1px solid var(--slds-g-color-border-base-2);
}

```

## 0.1.9 (May 7, 2025)

- NEW: SLDS Linter now identifies styling hooks that don’t have a fallback value provided.  
  The new rule `slds/no-slds-var-without-fallback` captures the variables that contain these styling hooks and recommends the fallback value to be used.  
  Adding a fallback is important for your code to work properly in multiple environments, like SLDS 2 and SLDS 1.
  For more information, see the [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-rules.md) topic.

- FIX: The `no-hardcoded-values-slds2` rule now identifies only instances in which a hard-coded value is used in the code. If the hard-coded value is used as a fallback value along with an SLDS 2 styling hook, it isn’t captured as an issue in the SLDS Linter report.

  In this example, a hard-coded value is used as a standalone value in the code. This instance is captured as an issue.

  ```
  .THIS .site-tos-container
  {
    height: 32px;
  }
  ```

  In this example, a hard-coded value is used as a fallback value along with the `--slds-g-sizing-9` styling hook. This instance isn’t captured as an issue.

  ```
  .THIS .site-tos-container
  {
    height: var(--slds-g-sizing-9, 32px);
  }
  ```

## 0.1.7 (April 24, 2025)

- NEW: SLDS Linter now validates components and styling hooks based on the new `@salesforce-ux/sds-metadata` package. This package consolidates design system metadata in a single location so you can easily access and integrate the latest metadata and improve consistency and performance.

- CHANGE: The `no-hardcoded-values-slds2` rule is enhanced to support the conversion between `px` and `rem` units of measurement. For each `px` or `rem` value present in your code, SLDS Linter now converts the value from one unit to the other and suggests SLDS 2 styling hooks that work for both values.

<!-- document id=f2577853331ea4b15614566cd6f9b60b408cc8f4dc04346a2fc8420dbce19610 url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-removeevent.md -->

# `removeEvent(event, options)`

Removes an event from a device’s calendar.

**note:** Using `removeEvent()` is an inherently dangerous action, as it allows event data to be irreversibly deleted. Use caution when using this functionality in your component. At an absolute minimum, consider adding a confirmation window for your users that clearly states the outcome of the action, with an option for them to cancel if they wish.

## Syntax

```
import { getCalendarService } from 'lightning/mobileCapabilities';
removeEvent(event: Event,
  options: CalendarServiceOptions
  ): Promise<Object>
```

## Parameters

- `event`—(Required) The `Event` object to be removed from the device’s calendar.
- `options`—(Required) A [`CalendarServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-data-types.md) object to configure the CalendarService request.

## Returns

If successful, nothing is returned. If unsuccessful, an error message is returned.

## Usage

Use this function to remove an event from a device’s calendar.

```javascript
myCalendarService
  .removeEvent(event, options)
  .then((results) => {
    console.log("Event successfully removed!");
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

<!-- document id=55a7fd52a06dfa09e99b7ad3c4147bbb65a0e4c0eddb0c3bc5c9e868cb97b54c url=/developer/current/en-us/lwc/lwc/guides/create/create-conditional.md -->

# Render DOM Elements Conditionally

**note:** The legacy `if:true` and `if:false` directives are no longer recommended. To future-proof your code, replace them with the `lwc:if|elseif|else` conditional directives.

[Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) are special HTML attributes that let you manipulate the DOM using markup. To render different HTML depending on a `{property}`, add conditional directives to a tag that encloses your conditional content.

Lightning Web Components supports the conditional directives `lwc:if={property}`, `lwc:elseif={property}`, and `lwc:else`. The `lwc:if|elseif` directives bind `{property}` to the template, removing and inserting DOM elements based on whether the data is a [truthy or falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) value.

## Usage and Considerations

You can use conditional directives on nested `<template>` tags and HTML standard tags such as `<div>`. You can also use conditional directives with your custom component tags like `<c-custom-cmp>` or base component tags like `<lightning-spinner>`.

For a full list of guidelines for conditional directive usage, see [HTML Template Directives: lwc:if|elseif={expression} and lwc:else](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md).

## Example: Static Conditions

The following example has two properties: `property1` and `property2`.

<!-- prettier-ignore -->
```html
<template>
  <template lwc:if={property1}> Statement1 </template>
  <template lwc:elseif={property2}> Statement2 </template>
  <template lwc:else> Statement3 </template>
</template>
```

Only one of the three statements renders based on this logic:

- `Statement1` renders if `property1` is true.
- `Statement2` renders if `property1` is false and `property2` is true.
- `Statement3` renders if `property1` and `property2` are false.

Although the example uses all three directives, `lwc:elseif` and `lwc:else` are optional.

**important:** The outer `<template>` tag is the root template element and must not have a directive. Only nested `<template>` tags use conditional directives. If you see error `LWC1077: Invalid template tag`, verify you're not adding extra wrapper `<template>` tags around the conditional group.

## Example: Interactive Conditions

Let’s look at another example. This template contains a checkbox labeled **Show details**. When a user selects or deselects the checkbox, the `handleChange` function sets the value of the `areDetailsVisible` property. If the `areDetailsVisible` property is `true`, the `lwc:if` directive renders the nested template, which displays **These are the details!**.

<!-- prettier-ignore -->
```html
<!-- helloConditionalRendering.html -->
<template>
  <lightning-card title="HelloConditionalRendering" icon-name="custom:custom14">
    <div class="slds-m-around_medium">
      <lightning-input
        type="checkbox"
        label="Show details"
        onchange={handleChange}
      ></lightning-input>
      <template lwc:if={areDetailsVisible}>
        <div class="slds-m-vertical_medium">These are the details!</div>
      </template>
    </div>
  </lightning-card>
</template>
```

Notice that the JavaScript doesn’t manipulate the DOM, it simply changes the value of a property.

```javascript
// helloConditionalRendering.js
import { LightningElement } from "lwc";

export default class HelloConditionalRendering extends LightningElement {
  areDetailsVisible = false;

  handleChange(event) {
    this.areDetailsVisible = event.target.checked;
  }
}
```

![Checkbox labeled Show details.](https://developer.salesforce.com/media/render_conditional.png)

![Checkbox with Show Details checked and detail text displaying beneath.](https://developer.salesforce.com/media/render_conditional_2.png)

**note:** To toggle the value of a boolean property in markup, default the value to `false`. See [Boolean Properties](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-boolean.md).

**tip:** This sample code is the `helloConditionalRendering` component from the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. For an example that uses a conditional directive on an HTML element, such as a `div` element, see the [`helloIterator` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/helloIterator).

## Example: Nested Conditional Directives

You can nest conditional statements within one another to create complex custom logic. For example, the following code checks if a user is logged in, and if they are, it subsequently checks if they have new notifications.

```
<template>
    <template lwc:if={isLoggedIn}>
        <p>Welcome back, User!</p>
        <template lwc:if={hasNewNotifications}>
            <strong>You have new notifications!</strong>
        </template>
        <template lwc:else>
            No new notifications at this time.
        </template>
    </template>
    <template lwc:else>
        <p>Welcome, Guest!</p>
    </template>
</template>
```

## Example: Nested Conditional Directives in Components

You can nest conditional directives inside components. In this example, if `property1` is true, `<c-child-1>` is rendered inside `<c-parent`>. If `property1` is false and `property2` is true, `<c-child>` renders `<c-child-2`> instead.

```
<!-- VALID CODE -->
<c-parent>
  <template lwc:if={property1}>
    <c-child-1></c-child-1>
  </template>
  <template lwc:elseif={property2}>
    <c-child-2></c-child-2>
  </template>
</c-parent>
```

However, preceding `lwc:elseif` or `lwc:else` with text or another element isn't allowed. The following sample code throws an error because the `lwc:elseif` directive must be used immediately after an element with `lwc:if` or `lwc:elseif`.

```
<!-- INVALID CODE -->
<template lwc:if={property1}>
  <c-child-1></c-child-1>
</template>
<div>This preceding div element before lwc:elseif makes the code invalid.</div>
<template lwc:elseif={property2}>
<c-child-2></c-child-2>
</template>
```

**See Also**

- [HTML Template Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md)
- [Boolean Properties](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-boolean.md)

<!-- document id=d7d4c7e42725d8a461b29c417649c6054e628e4de7eea3f43e81f5a43dc08569 url=/developer/current/en-us/lwc/lwc/guides/create/create-lists.md -->

# Render Lists

To render a list of items, use `for:each` directive or the `iterator` directive to iterate over an array. Add the directive to a nested `<template>` tag that encloses the HTML elements you want to repeat.

The `iterator` directive has `first` and `last` properties that let you apply special behaviors to the first and last items in an array.

Regardless of which directive you use, you must use a `key` directive to assign a unique ID to each item. When a list changes, the framework uses the `key` to rerender only the item that changed. The `key` in the template is used for performance optimization and isn’t reflected in the DOM at run time.

**tip:** To follow along in a code editor, open the `helloForEach` and `helloIterator` components from the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. You can also copy the code to the [component IDE](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-lwc.md).

## `for:each`

When using the `for:each` directive, use `for:item="currentItem"` to access the current item.

To assign a key to the first element in the nested template, use the `key={uniqueId}` directive.

This example iterates over an array called `contacts`, which is defined in the component’s JavaScript class.

<!-- prettier-ignore -->
```html
<!-- helloForEach.html -->
<template>
  <lightning-card title="HelloForEach" icon-name="custom:custom14">
    <ul class="slds-m-around_medium">
      <template for:each={contacts} for:item="contact">
        <li key={contact.Id}>{contact.Name}, {contact.Title}</li>
      </template>
    </ul>
  </lightning-card>
</template>
```

```
import { LightningElement } from 'lwc';

export default class HelloForEach extends LightningElement {
    contacts = [
        {
            Id: '003171931112854375',
            Name: 'Amy Taylor',
            Title: 'VP of Engineering'
        },
        {
            Id: '003192301009134555',
            Name: 'Michael Jones',
            Title: 'VP of Sales'
        },
        {
            Id: '003848991274589432',
            Name: 'Jennifer Wu',
            Title: 'CEO'
        }
    ];
}

```

![List of names and titles.](https://developer.salesforce.com/media/list.png)

**important:** Every item in a list must have a `key`. When a list changes, the framework uses the `key` to identify each item so that it can rerender only the item that changed. The `key` must be a string or a number, it can't be an object. You can’t use `index` as a value for `key`. Assign unique keys to an incoming data set. To add new items to a data set, use a private property to track and generate keys.

## `iterator`

To apply a special behavior to the first or last item in a list, use the `iterator` directive, `iterator:iteratorname={array}`. Use the `iterator` directive on a `template` tag. `iteratorname` must be lowercase.

Use _`iteratorname`_ to access these properties:

- `value`—The value of the item in the list. Use this property to access the properties of the array. For example, `{iteratorname}.value.{propertyName}`.
- `index`—The index of the item in the list.
- `first`—A boolean value indicating whether this item is the first item in the list.
- `last`—A boolean value indicating whether this item is the last item in the list.

This sample code uses the same array as the previous example. To apply special rendering to the first and last items in the list, the code uses the `first` and `last` properties with the `lwc:if` directive.

If the item is first in the list, the `<div>` tag renders with the styling defined in the CSS `list-first` class. If the item is last in the list, the `<div>` tag renders with the styling defined in the CSS `list-last` class.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="HelloIterator" icon-name="custom:custom14">
    <ul class="slds-m-around_medium">
      <template iterator:it={contacts}>
        <li key={it.value.Id}>
          <div lwc:if={it.first} class="list-first"></div>
          {it.value.Name}, {it.value.Title}
          <div lwc:if={it.last} class="list-last"></div>
        </li>
      </template>
    </ul>
  </lightning-card>
</template>
```

```css
.list-first {
  border-top: 1px solid black;
  padding-top: 5px;
}

.list-last {
  border-bottom: 1px solid black;
  padding-bottom: 5px;
}
```

![List of names and titles with the first name and title rendered in bold.](https://developer.salesforce.com/media/list_iterator.png)

## Example

The `wireGetPicklistValues` component in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo uses the `lightning-input` base component to display a list of picklist values.

**See Also**

- [HTML Template Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md)

<!-- document id=76f0c620ad7932f8674b9cf5272b763492665791c823ff942376257141bd9a4d url=/developer/current/en-us/lwc/lwc/guides/create/create-render.md -->

# Render Multiple Templates

You may want to render a component with more than one look and feel, but not want to mix the HTML in one file. For example, one version of the component is plain, and another version displays an image and extra text. In this case, you can import multiple HTML templates and write business logic that renders them conditionally. This pattern is similar to the code splitting used in some JavaScript frameworks.

**note:** Although it’s possible for a component to render multiple templates, we recommend using the `lwc:if|elseif|else` directives to [render nested templates conditionally](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.md) instead.

Create multiple HTML files in the component bundle. Import them all and add a condition in the `render()` method to return the correct template depending on the component’s state. The returned value from the `render()` method must be a template reference, which is the imported default export from an HTML file.

In this example, the template references are `templateOne` and `templateTwo`.

```javascript
// miscMultipleTemplates.js

import { LightningElement } from "lwc";
import templateOne from "./templateOne.html";
import templateTwo from "./templateTwo.html";

export default class MiscMultipleTemplates extends LightningElement {
  showTemplateOne = true;

  render() {
    return this.showTemplateOne ? templateOne : templateTwo;
  }

  switchTemplate() {
    this.showTemplateOne = !this.showTemplateOne;
  }
}
```

<!-- prettier-ignore -->
```html
<!-- templateOne.html -->
<template>
  <lightning-card title="Template One">
    <div>This is template one.</div>
    <p class="margin-vertical-small">
      <lightning-button label="Switch Templates" onclick={switchTemplate}> </lightning-button>
    </p>
  </lightning-card>
</template>
```

<!-- prettier-ignore -->
```html
<!-- templateTwo.html -->
<template>
  <lightning-card title="Template Two">
    <div>This is template two.</div>
    <p class="margin-vertical-small">
      <lightning-button label="Switch Templates" onclick={switchTemplate}> </lightning-button>
    </p>
  </lightning-card>
</template>
```

To reference CSS from an extra template, the CSS filename must match the filename of the extra template. For example, `templateTwo.html` can reference CSS only from `templateTwo.css`. It can’t reference CSS from `miscMultipleTemplates.css` or `templateOne.css`.

```ascii
MiscMultipleTemplates
   ├──miscMultipleTemplates.js
   ├──miscMultipleTemplates.js-meta.xml
   ├──templateOne.html
   ├──templateOne.css
   ├──templateTwo.html
   └──templateTwo.css
```

If you include a template with a matching name, `miscMultipleTemplates.html`, the default `render()` method returns that template unless you include an override discussed in the previous example.

**tip:** Check out the `miscMultipleTemplates` component in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/miscMultipleTemplates).

**See Also**

- [Render DOM Elements Conditionally](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.md)
- [Lifecycle Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)

<!-- document id=aaeca11b5f6028efce7d1979865802996ce6e14c19be712f5972177b3c51d317 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-replace-block.md -->

# `replaceBlock`

Replaces the selected component on the canvas of a marketing content item. Updates persist when the user saves their changes in the content builder. Use this function when building a CMS extension for Marketing Cloud Next that interacts with components on the canvas.

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { replaceBlock } from "experience/blockBuilderApi";

class Example extends LightningElement {
  blockText;
  block;

  @wire(getCurrentSelectedBlock, {})
  onCurrentSelectedBlock({ data }) {
    if (data) {
      // extract the text attribute
      this.blockText = data.attributes.text;

      // convert the block JSON to a JS object
      this.block = JSON.parse(JSON.stringify(data));
    }
  }

  // manipulate the text, or other block attributes

  updateBlock() {
    const id = this.block.id;
    this.block.attributes.text = this.blockText;

    // replaceBlock requires the block and the nodeId in an object
    replaceBlock(this.block, {
      nodeId: id,
    }).then((response) => {
      // while the call returns a promise with a payload,
      // it is not an indication of the success of the
      // replace operation, since it is asynchronous
    });
  }
}
```

## Parameters

| Parameter Name  | Type   | Description                                                                                                                  | Required?                                  |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `selectedBlock` | Object | The new component that replaces the selected component on the canvas.                                                        | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `nodeId`        | String | The ID of the selected component (or node) to be replaced. This field must be included in an object as the second parameter. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves when the `replaceBlock` action has been initiated. The replacement operation is asynchronous in the content builder.
- `error`—A validation error indicating that the `nodeId` was invalid or not provided, or that the block is invalid.

<!-- document id=e4f01bcc3f34aa1e5b6d3ba482af5628215e93ad96d39325508c941ffa174b51 url=/developer/current/en-us/lwc/lwc/guides/reference/appreviewservice/reference-lightning-appreviewservice-requestappreview.md -->

# `requestAppReview()`

Requests an app review.

## Syntax

```javascript
import { getAppReviewService } from 'lightning/mobileCapabilities';
requestAppReview(options: AppReviewServiceOptions|null): Promise<Object>
```

## Parameters

- `options`— An [`AppReviewServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-appreviewservice-data-types.md) object to configure the AppReviewService request.

## Returns

A resolved promise returns no object.

A rejected promise returns a `AppReviewServiceFailure` object containing details about the error.

## Usage

This function requests an app review.

```javascript
myAppReviewService
  .requestAppReview(null)
  .then(() => {
    console.log("App review request complete successfully");
  })
  .catch((error) => {
    console.error(error);
  });
```

**See Also**

- [AppReviewService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_appreviewservice_example.htm)
- [AppReviewService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-appreviewservice-data-types.md)

<!-- document id=670d38f7d740d173b831800791f8f129e5cb893ebb99b0577ab52e248bcedcc6 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-restricted-globals.md -->

# Restricted Access to Salesforce Global Variables

Lightning Locker blocks access to some global JavaScript objects that are available to other Salesforce features.

[Lightning web components (LWC)](/docs/platform/lwc/guide/get-started-introduction.html) **don't have access** to:

- `$A`
- `Aura`
- `Sfdc`
- `sforce`

Locker restricts access to these objects for Lightning web components because they are either deprecated or can lead to cross-framework dependencies.

<!-- document id=932961df00a29992a083bce9bafec9539559cdeebee46c8e52643d0d3e675d15 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-resume-example.md -->

# Resume a Flow Interview

You can customize how and where users can resume their interviews by embedding the `lightning-flow` component in a custom LWC component.

To use this component, build a flow with the Salesforce Flow Builder first. The component includes the navigation buttons Back, Next, Pause, and Finish.

**note:** If your flow has custom Lightning web components or Aura components, then you can’t use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

## Handle Paused Interviews

By default, users can resume interviews that they paused from the Paused Interviews component on their home page. To customize how and where users can resume their interviews, embed the `lightning-flow` component in a custom LWC component and pass the interview ID into the `flow-interview-id` attribute.

This example shows how you can resume an interview, or start a new one. When users click Survey Customer from a contact record, the `lightning-flow` component does one of these actions.

- If the user has any paused interviews for the Survey Customers flow, the `lightning-flow` component resumes the first one.
- If the user doesn’t have any paused interviews for the Survey Customers flow, the `lightning-flow` component starts a new one.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-flow flow-api-name={flowName} flow-interview-id={pausedInterviewId}>
  </lightning-flow>
</template>
```

## Example: Use Apex to Resume or Start a New Interview

This Apex controller gets a list of paused interviews by performing a SOQL query. The query returns a null value if there are no paused interviews, and then the component starts a new interview. If the query returns at least one interview, the component resumes the first interview in that list.

```apex
// InterviewsController.apex
public class InterviewsController {
    @AuraEnabled(cacheable=true)
    public static String getPausedId() {
        // Get the ID of the running user.
        String currentUser = UserInfo.getUserId();
        // Find all of that user’s paused interviews for the Survey customers flow.
        List<FlowInterview> interviews =
             [ SELECT Id FROM FlowInterview WHERE CreatedById = :currentUser AND
                 InterviewLabel LIKE '%Survey customers%'];
        if (interviews == null || interviews.isEmpty()) {
            return null; // early out
        }
        // Return the ID for the first interview in the list.
        return interviews.get(0).Id;
    }
}
```

If the Apex controller returns an interview ID, the `pausedInterviewId` passes to the `flow-interview-id` attribute. If the Apex controller returns a null interview ID, the component starts a new interview by passing the flow name to the `flow-api-name` attribute.

```javascript
// myComponent.js
import { LightningElement, wire } from "lwc";
import getPausedId from "@salesforce/apex/InterviewsController.getPausedId";

export default class MyComponent extends LightningElement {
  flowName;
  pausedInterviewId;

  @wire(getPausedId)
  getPausedInterviewId({ error, data }) {
    if (error) {
      // start a new interview since no interview id was returned.
      this.flowName = "Survey_customers";
    } else if (data) {
      // resume the flow with the returned interview id.
      this.pausedInterviewId = data;
    }
  }
}
```

<!-- document id=42bb95b30fd3e372b921a3d4c2d2023674b73e898bfa7a690c0be4b20b386d3c url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-resumecapture.md -->

# `resumeCapture()` (Legacy)

Use this function to continue a scanning session.

**note:** We recommend using the modern [`scan()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-scan.md) and [`dismiss()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-dismiss.md) APIs in your LWC’s scanning code to streamline your development experience. The legacy APIs `beginCapture()`, `resumeCapture()`, and `endCapture()` are still available, but will be retired in a future release.

## Syntax

```javascript
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
resumeCapture(): Promise<Object>
```

## Parameters

None.

## Returns

A Promise object that resolves as a [`Barcode`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) with the scanned barcode details.

A rejected promise returns a [`BarcodeScannerFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md).

## Usage

This function reuses an existing scanning session created by `beginCapture()`.

`resumeCapture()` behaves like `beginCapture()` in all other respects.

**See Also**

- [BarcodeScanner Example—Continuous Scanning (Legacy)](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_example_continuous.htm)
- [Scan Multiple Barcodes (Legacy)](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_scan_multiple_barcodes.htm)

<!-- document id=46705c3fccb030cb74e401c1d7127bf716361b4b783beadf78cc1d55a1013679 url=/developer/current/en-us/lwc/slds_linter/guides/reference/reference-rules.md -->

# Rules

SLDS Linter rules validate your code against a series of SLDS 2 best practices and, where possible, provide suggestions for you to improve your code. By default, all rules validate all CSS properties unless otherwise specified.
Each rule has a different severity level. The options are listed here.

- **Error** \- The code won’t work and causes issues. Fix the errors.
- **Warning** \- The code works, but it can be deprecated. We recommend addressing it.

## Overview

This table lists all supported rules, their severity levels, and whether they are enabled by default.

| Rule                                     | Severity Level                            | Enabled by Default | Supported File Types |
| :--------------------------------------- | :---------------------------------------- | :----------------- | :------------------- |
| enforce-bem-usage                        | Error                                     | Yes                | HTML                 |
| modal-close-button-issue                 | Error                                     | Yes                | HTML                 |
| no-deprecated-classes-slds2              | Error in HTML files, Warning in CSS files | Yes                | HTML, CSS            |
| enforce-component-hook-naming-convention | Error                                     | Yes                | CSS                  |
| lwc-token-to-slds-hook                   | Error                                     | Yes                | CSS                  |
| enforce-sds-to-slds-hooks                | Warning                                   | Yes                | CSS                  |
| no-hardcoded-values-slds2                | Warning                                   | Yes                | CSS                  |
| no-slds-class-overrides                  | Warning                                   | Yes                | CSS                  |
| no-slds-private-var                      | Warning                                   | Yes                | CSS                  |
| no-unsupported-hooks-slds2               | Warning                                   | Yes                | CSS                  |
| no-slds-var-without-fallback             | Warning                                   | Yes                | CSS                  |
| reduce-annotations                       | Warning                                   | Yes                | CSS                  |
| no-slds-namespace-for-custom-hooks       | Warning                                   | Yes                | CSS                  |
| no-sldshook-fallback-for-lwctoken        | Warning                                   | Yes                | CSS                  |
| no-important-tag                         | Warning                                   | No                 | CSS                  |

## enforce-bem-usage

Identifies instances that use the double-dash (`--`) syntax for block-element-modifier (BEM) in classes. Replace these instances with the single underscore (`_`) syntax.

### Severity Level

Error

### Example

Existing code:

```
slds-avatar--medium
```

Recommended code:

```
slds-avatar_medium
```

The `--` syntax is replaced with the `_` syntax.

## modal-close-button-issue

Identifies instances where the CSS classes or component attributes for the modal close button must be changed to follow the modal component blueprint.

- Remove classes that contain the `slds-button_icon-inverse` attribute within the close button.
- Change the variant value for the `lightning-button-icon` attribute from bare-inverse to bare.
- Change the variant value for the `lightning-icon` attribute from bare-inverse to bare.

For more information, see the [Modal close button is not visible with the new white background](https://issues.salesforce.com/issue/a028c00000zh1iqAAA/modal-close-button-is-not-visible-with-the-new-white-background-after-winter-25-release) topic.

### Severity Level

Error

### Example

Existing code:

```
<lightning-button-icon
        title={labels.closeButton} icon-name="utility:close"
        onclick={closeAction}
        class="slds-button slds-button_icon slds-modal__close slds-button--icon-inverse" variant="bare-inverse" size="large">
</lightning-button-icon>
```

Recommended code:

```
<lightning-button-icon
        title={labels.closeButton} icon-name="utility:close"
        onclick={closeAction}
        class="slds-button slds-button_icon slds-modal__close" variant="bare" size="large">
</lightning-button-icon>
```

To fix the issues, these changes are made.

- The variant attribute value for the `lightning-button-icon` attribute is changed from bare-inverse to bare.
- The `slds-button–icon-inverse` class is removed.

## no-deprecated-classes-slds2

Identifies classes that aren’t available in SLDS 2. Update these classes to a class that’s supported in SLDS 2.

### Severity Level

Error

### Example

Existing code:

```
<span class="slds-icon_left">
</span>
```

The `slds-icon_left` class is deprecated in SLDS 2 and must be updated to a class that is supported in SLDS 2.

## enforce-component-hook-naming-convention

Identifies `--slds-c` component-level styling hooks that use a deprecated naming convention. To align with the prescribed styling hooks naming convention, replace with styling hooks that SLDS Linter recommends.

### Severity Level

Error

### Examples

Existing code:

```
// Before
:root
{
   --slds-c-breadcrumbs-spacing-inlineend: 16px
}
```

Recommended code:

```
// After
:root
{
   --slds-c-breadcrumbs-spacing-inline-end: 16px
}
```

The `--slds-c-breadcrumbs-spacing-inlineend` styling hook is replaced with the `--slds-c-breadcrumbs-spacing-inline-end` styling hook.

Existing code:

```
// Before
:root{
   --slds-c-accordion-heading-color:#03234d;
   --slds-c-accordion-heading-font-lineheight: 1.25;
}
```

Recommended code:

```
// After
:root{
   --slds-c-accordion-heading-text-color:#03234d;
   --slds-c-accordion-heading-font-line-height: 1.25;
}
```

The `--slds-c-accordion-heading-color` and `--slds-c-accordion-heading-font-lineheight` styling hooks are replaced with the `--slds-c-accordion-heading-text-color` and `--slds-c-accordion-heading-font-line-height` styling hooks.

## lwc-token-to-slds-hook

Identifies deprecated `--lwc` tokens in your code and recommends suitable `--slds` styling hooks. Replace the `--lwc` token with the recommended `--slds` styling hook and retain the `--lwc` token as the fallback value.

If the rule identifies a deprecated `--lwc` token but no replacement is recommended for it, refer to the [Global Styling Hooks Index](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks/b/768d36) and find the most suitable styling hook replacement.

### Severity Level

Error

### Example

Existing Code:

```
.example
{
 padding: var(--lwc-cardBodyPadding);
}
```

Recommended Code:

```
.example
{
 padding: var(--slds-g-spacing-4, var(--lwc-cardBodyPadding));
}
```

The `--lwc-cardBodyPadding` token is replaced with the `--slds-g-spacing-4` styling hook. The `--lwc` token is mentioned as the fallback value.

## enforce-sds-to-slds-hooks

Identifies Salesforce Design System (SDS) styling hooks that must be replaced with the suggested SLDS 2 styling hooks.

### Security Level

Warning

### Example

Existing code:

```
.slds-expandable-section .sldc-section__content
{
 background-color: var(--sds-g-color-brand-base-100, rgb(255, 255, 255));
}
```

Recommended code:

```
.slds-expandable-section .sldc-section__content
{
 background-color: var(--slds-g-color-brand-base-100, rgb(255, 255, 255));
}
```

The `--sds-g-color-brand-base-100` styling hook is replaced with the `--slds-g-color-brand-base-100` SLDS 2 styling hook.

<!-- ## lwc-token-to-slds-hook

Identifies deprecated `--lwc` design tokens that must be replaced with the latest SLDS 2 styling hooks. Include the SLDS 2 styling hook and retain the `--lwc` design token as a fallback value.

### Severity Level

Warning

### Example

Existing code:

```
.my-component {
background-color: var(--lwc-colorBackgroundAlt);
}
```

Recommended code:

```
.my-component {
background-color: var(--slds-g-color-surface-1,--lwc-colorBackgroundAlt);
}
```

The `--slds-g-color-surface-1` styling hook is included. -->

## no-hardcoded-values-slds2

Identifies static or hard-coded values that must be replaced with SLDS 2 styling hooks. Include the SLDS 2 styling hook and retain the hard-coded value as the fallback value.
This rule validates only these CSS properties.

- color
- fill
- background
- background-color
- stroke
- border\*-color
- outline\*
- border\*
- margin\*
- padding\*
- width
- height
- max-height
- min-height
- line-height
- max-width
- min-width
- top
- right
- left
- bottom
- box-shadow
- font
- font-weight

### Severity Level

Warning

### Example

Existing code:

```
.THIS .site-tos-container
{
    height: 32px;
}
```

Recommended code:

```
.THIS .site-tos-container
{
    height: var(--slds-g-sizing-9, 32px);
}
```

The `--slds-g-sizing-9` styling hook is included.

## no-slds-class-overrides

Identifies existing class names that must be replaced with new custom CSS classes, instead of overriding SLDS selectors. This rule only reports classes located at the end of an SLDS selector.

### Severity Level

Warning

### Example

Here, the `.slds-box_border` SLDS class is located at the end of the selector. Only such instances are identified as an issue.

```
// Now .slds-box_border will be reported as SLDS class override
.THIS .slds-box_small .slds-box_border:hover
{
   .border-color: var(--slds-g-color-palette-hot-orange-40)
}
```

Here, overriding the `.slds-box_border` class isn’t supported. So a new `my-app-box_border` CSS class is created to replace it.

Existing code:

```
.slds-box_border
{
    visibility: hidden;
}
```

Recommended code:

```
.my-app-box_border{
    visibility: hidden;
}
```

## no-slds-private-var

Identifies SLDS styling hooks that are reserved only for internal Salesforce use. You must remove these styling hooks.

### Severity Level

Warning

### Example

Existing code:

```
.example {
    --_slds-deprecated-var: #fff;
    border: var(--slds-g-sizing-border-1, 1px) solid;
}
```

Recommended code:

```
.example {
    border: var(--slds-g-sizing-border-1, 1px) solid;
}
```

The `--_slds-deprecated-var` styling hook is meant for internal Salesforce use and is removed.

## no-unsupported-hooks-slds2

Identifies styling hooks that aren’t present in SLDS 2. They must be replaced with ‌styling hooks that have a similar effect, or they must be removed.

### Severity Level

Warning

### Example

Existing code:

```
.playground-editor-prompt-container {
    height: calc(100% - 60px); /* minus the height of the header */
    --slds-c-card-body-spacing-block-end: 0;
}
```

Recommended code:

```
.playground-editor-prompt-container {
    height: calc(100% - 60px); /* minus the height of the header */
}
```

The `–-slds-c-card-body-spacing-block-end` styling hook is removed because it doesn’t have a suitable SLDS 2 replacement.

## no-slds-var-without-fallback

Identifies SLDS styling hooks that are specified without fallback values and recommends suitable fallback values based on the SLDS metadata.  
Each `var()` function’s arguments must contain a styling hook and a hard-coded value or branded design token as a fallback value. The fallback value is used in environments in which styling hooks aren’t supported.

### Severity Level

Error

### Example

Existing code:

```
.example {
  color: var(--slds-g-link-color-focus);
  background-color: var(--slds-g-color-brand-base-20);
  margin: var(--slds-c-card-spacing-block);
}
```

Recommended code:

```
.example {
  color: var(--slds-g-link-color-focus, #014486);
  background-color: var(--slds-g-color-brand-base-20, #0176d3);
  margin: var(--slds-c-card-spacing-block, 1rem);
}
```

The `--slds-g-link-color-focus, --slds-g-color-brand-base-20,` and `--slds-c-card-spacing-block` styling hooks are used with hard-coded values as fallback values.

## reduce-annotations

Identifies annotations that must be removed from the code.

### Severity Level

Warning

### Example

Existing code:

```
/* @sldsValidatorAllow */
.THIS--mailapp.forceDockingPanel .slds-docked-composer__body {
    flex-shrink: 1;
}
```

The `@sldsValidatorAllow` annotation must be removed.

## no-slds-namespace-for-custom-hooks

Identifies custom styling hooks that use the `--slds` or `--sds` namespaces, which are reserved for SLDS styling hooks. To differentiate them from SLDS styling hooks, create the identified custom styling hooks within your own namespace.

### Severity Level

Warning

### Example

Existing code:

```
/*  Custom token --slds-color-999 using reserved namespace --slds will be flagged as violation */
.THIS .container
{
--slds-color-999: #999
}
```

Recommended code:

```
.THIS .container
{
--myapp-color-999: #999
}
```

The `--slds-color-999` custom styling hook is replaced with `--myapp-color-999`.

## no-sldshook-fallback-for-lwctoken

Identifies instances where `--slds` styling hooks are provided as fallback values for `--lwc` tokens. Replace the `--lwc` token with a suitable `--slds` styling hook and retain the `--lwc` token as the fallback value.

### Severity Level

Warning

### Example

Existing code:

```
/* Using --slds-g-color-border-1 as fallback value for --lwc-color-background-1 is not supported. */

.example
{
color: var(--lwc-color-background-1, var(--slds-g-color-border-1));
}
```

Recommended code:

```
.example
{
color: var(--slds-g-color-border-1, var(--lwc-color-background-1));
}
```

The `--lwc-color-background-1` token is replaced with the `--slds-g-color-border-1` styling hook. The `--lwc` token is mentioned as the fallback value.

<!--
## length-zero-no-unit

Identifies instances that specify length units for zero lengths.
This is a Stylelint rule that SLDS Linter supports.

For more information, see [Stylelint](https://stylelint.io/user-guide/rules/length-zero-no-unit/).

### Severity Level

Warning

### Example

Existing code:

```
// Before
.THIS. container
{
padding: 0px
}
```

Recommended code:

```
// After
.THIS. container
{
padding: 0
}
```

The `0px` value is replaced with `0` without the length unit `px`.
-->

## no-important-tag

Indicates that the `!important` tag must be used only if it’s necessary. The tag functions by overriding all other attributes.

### Severity Level

Warning

### Example

Existing code:

```
.test-cls2 {
color: red !important;
}
```

Recommended code:

```
.test-cls2 {
color: red;
}
```

The `!important` tag is removed.

<!-- document id=ac2fe6b299a3eecc260fb42efe5a5b13c3904673366010f8e3c7637128ed554e url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-test-components.md -->

# Run a Live Component Preview

**note:** Live Preview VS Code Extension for React components is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/?_ga=2.247987783.1372150065.1709219475-629000709.1639001992). Use of this pilot or beta service is at the Customer's sole discretion.

| USER PERMISSIONS NEEDED            |                                              |
| ---------------------------------- | -------------------------------------------- |
| To enable Live Preview for an org: | **View Setup** and **Customize Application** |

Use Live Preview to develop Lightning web components in a real-time browser preview. You can load your component in isolation, or preview it within a Lightning app or an Experience Cloud Lightning Web Runtime (LWR) site. Alternatively, you can run the Live Preview Visual Studio Code (VS Code) extension to test a single Lightning web component or React component inside your integrated development environment (IDE).

When you save changes to your source code, Live Preview automatically updates your component in the browser or IDE. This lets you iterate quickly on your components without deploying code or manually refreshing the preview.

**note:** Live Preview was previously called Local Dev. In Spring '26, we rebranded this feature to reflect the real-time nature of the preview tools.

## Where is Live Preview Supported?

Live Preview is available for Lightning apps, Experience sites, Lightning web components, and React components.

You can use Live Preview in production, sandbox, and scratch orgs. However, we recommend running it only in sandbox and scratch orgs.

## Set Up Live Preview

**tip:** First time using Live Preview? For a step-by-step walkthrough of how to configure and run this feature for a Lightning app, check out the project **[Set Up Your Lightning Web Components Developer Tools](https://trailhead.salesforce.com/content/learn/projects/set-up-your-lightning-web-components-developer-tools)** on Trailhead.

Before you can run Live Preview, follow these setup steps.

### 1. Install the Salesforce Command Line Interface (CLI)

Follow the instructions outlined in [Install the Salesforce CLI](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-cli.md). The Salesforce CLI automatically installs the Live Preview plugin for you.

### 2. Enable Live Preview

When you run a Live Preview command for the first time, the CLI prompts you to enable the feature. In response, press **Enter** or type `y` to enable it.

## Run a Real-Time Preview

Choose from the following Live Preview tools.

| Tool                                                                  | Use Case                                                                    | CLI Command                  |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
| **[Lightning App Live Preview](#lightning-app-live-preview)**         | Preview a Lightning app (desktop or Salesforce mobile app) in your browser. | `sf lightning dev app`       |
| **[Experience Sites Live Preview](#experience-sites-live-preview)**   | Preview an Experience LWR site in your browser.                             | `sf lightning dev site`      |
| **[Single Component Live Preview](#single-component-live-preview)**   | Preview a single Lightning web component in your browser.                   | `sf lightning dev component` |
| **[Live Preview VS Code Extension](#live-preview-vs-code-extension)** | Preview a single Lightning web component or React component in VS Code.     |                              |

**Considerations for CLI Commands**

- To use the latest version of the CLI commands, run `sf update` before you start a Live Preview instance.
- To successfully run Live Preview CLI commands, you must have an `lwc` directory in your project that contains your components. This directory is typically nested in the `force-app/main/default` directory.

### Lightning App Live Preview

To preview a Lightning app in a desktop environment or on the Salesforce mobile app (iOS or Android), run `sf lightning dev app` on the CLI with the following flags as needed.

If you forget to set a required flag, don't worry: the CLI prompts you to select a value from a list of valid options.

| Flag                  | Required/Optional | Description                                                                                                                                                                                                                         |
| --------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-o`, `--target-org`  | Required          | The username or alias of the target org for the preview. Not required if you already set the `target-org` configuration variable. _Example:_ `--target-org myOrg`                                                                   |
| `-n`, `--name`        | Optional          | The name of the Lightning Experience app you want to preview. If your app name has spaces in it, wrap the name in quotes. _Example:_ To start Live Preview for an app named **SDO – Consumer**, run `--name "SDO - Consumer"`       |
| `-t`, `--device-type` | Optional          | The type of device to display the app preview. This flag accepts only one of these options: - `desktop` - `ios` - `android` _Example:_ `--device-type desktop`                                                                      |
| `-i`, `--device-id`   | Optional          | If you set `--device-type` to `ios` or `android`, you can choose the ID of the mobile device to display the preview. The default value is the ID of the first available mobile device. _Example:_ `--device-id "iPhone 15 Pro Max"` |
| `--flags-dir`         | Optional          | Import flag values from a directory.                                                                                                                                                                                                |

#### Lightning Apps in a Mobile Environment

Live Preview supports previewing only Lightning apps in a mobile environment. Specifically, you can run your preview in an iOS simulator or an Android emulator.

**Prerequisites**

Before you can use this feature, you have to install and configure Salesforce mobile development tools. You only have to complete this setup process once on your machine.

For a hands-on walkthrough of this setup, complete the Trailhead project **[Set Up Your Salesforce Mobile Developer Tools for Lightning Web Components](https://trailhead.salesforce.com/content/learn/projects/set-up-your-salesforce-mobile-developer-tools-for-lightning-web-components)**.

**iOS Simulators**

Mac users can run an iOS simulator for Live Preview using Xcode. If you don’t already have Xcode, install it from the Mac App Store and complete the initial setup process. In Xcode, make sure that you download the iOS mobile device simulators that you want to use with Live Preview.

If you're having trouble with your Xcode installation, refer to [Mobile and Offline Developer Guide: Set Up Xcode](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/mobile_extensions_setup_ios_xcode.htm).

To run your app in an iOS simulator using Live Preview, set `--device-type` to `ios` in your CLI command: `sf lightning dev app --device-type ios`.

**Android Emulators**

You can run your app in an Android emulator using Android Studio. If you don't already have this tool, install it from [developer.android.com/studio](https://developer.android.com/studio). For a walkthrough of how to install Android Studio for Salesforce projects, see [Mobile and Offline Developer Guide: Set Up Android Studio](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/mobile_extensions_setup_android_studio.htm).

To run your app in an Android emulator using Live Preview, set `--device-type` to `android` in your CLI command: `sf lightning dev app --device-type android`.

**Salesforce Mobile App**

Don't worry about manually installing the Salesforce mobile app on your simulator or emulator virtual device. When you run the Live Preview CLI command, the CLI prompts you to install the Salesforce mobile app if needed, like this:

![Terminal output for the Live Preview iOS simulator command that automatically prompts you to install the Salesforce mobile app, if needed.](https://developer.salesforce.com/media/livepreview_mobile_output.png)

### Experience Sites Live Preview

When you run `sf lightning dev site` on the CLI, Live Preview automatically generates and downloads a static bundle based on the current state of your site. You can preview an Experience Cloud LWR site only in a desktop environment with Live Preview.

**important:** For now, you have to publish your Experience LWR site before you can run an Experience Sites Live Preview instance.

| Flag                 | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-o`, `--target-org` | Required          | The username or alias of the target org for the preview. Not required if you already set the `target-org` configuration variable. _Example:_ `--target-org myOrg`                                                                                                                                                                                                                   |
| `-n`, `--name`       | Optional          | The name of the Experience Cloud LWR site you want to preview. If your site name has spaces in it, wrap the name in quotes. If you don't set this flag, Live Preview prompts you in the terminal to select a value for the name from a list of valid options. _Example:_ To run Live Preview for a site named **SDO - Consumer**, run `--name "SDO - Consumer"`                     |
| `--flags-dir`        | Optional          | Import flag values from a directory.                                                                                                                                                                                                                                                                                                                                                |
| `--get-latest`       | Optional          | The `sf lightning dev site` command caches a version of your Experience LWR site on your machine. This cached version is used whenever you subsequently run the Live Preview `site` command again. To update the local cache with the latest version of your site from your org, such as to preview recent Experience Builder changes, add the `--get-latest` flag to your command. |
| `--ssr`              | Optional          | Starting in Spring '26, Live Preview doesn't support this flag. Don't use it.                                                                                                                                                                                                                                                                                                       |

### Single Component Live Preview

To test a single LWC in your browser with Live Preview, run the `sf lightning dev component` command on the CLI with the following flags as needed. If you forget to set a required flag, don't worry: the CLI prompts you to select a value for it from a list of valid options.

In a Single Component Live Preview, components can access platform modules such as public Lightning Data Service wire adapters, `@salesforce` scoped modules, and Apex controllers.

| Flag                 | Required/Optional | Description                                                                                                                                                                                                                                                                |
| -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-o`, `--target-org` | Required          | The username or alias of the target org for the preview. Starting in Winter '26, you have to specify a target org to run a single component preview. This flag is not required if you already set the `target-org` configuration variable. _Example:_ `--target-org myOrg` |
| `-n`, `--name`       | Optional          | The name of the component you want to preview. If your component name has spaces in it, wrap the name in quotes. _Example:_ To run Live Preview for a component named **myComponent**, run `--name "myComponent"`                                                          |
| `--flags-dir`        | Optional          | Import flag values from a directory.                                                                                                                                                                                                                                       |
| `--json`             | Optional          | Format output as JSON.                                                                                                                                                                                                                                                     |

#### Single Component Developer Tools

If your command runs successfully, Live Preview automatically opens a new browser tab for the single component preview. Here's what the single component interface looks like in the browser:

![Screenshot of a browser preview of a single LWC.](https://developer.salesforce.com/media/livepreview_single.png)

The toolbar at the top of the single component preview page offers the following tools.

- **Change Component Dimensions:** Click a device icon to resize your component to preset dimensions, or drag the resizing bars on three sides of your component to set custom dimensions.
- **Performance:** Toggle Performance Mode to preview your component without page UI elements. To exit Performance Mode, click your browser's back button.
- **Project Components:** Click the menu icon in the top right to open the Project Components sidebar, which lists components in your project that are available for preview.

### Live Preview VS Code Extension

Live Preview lets you run a real-time preview of a Lightning web component or a React component inside a dedicated panel in your VS Code or Code Builder environment. The preview updates automatically when you save local changes, which makes it easy to test component design and behavior without leaving your IDE.

Previewing a Lightning web component with this extension is generally available, while previewing a React component is in beta. You can find more details about this extension in [Visual Studio Code Marketplace: Salesforce Live Preview](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode-ui-preview).

**tip:** Consider using Live Preview in tandem with [Agentforce Vibes](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/einstein-overview.html), an AI assistant that can help you write, refactor, and test your code. For fast and easy iteration on your components, Agentforce Vibes can directly open components in the Lightning Preview panel when your local changes are complete.

#### Preview a Single Lightning Web Component with the VS Code Extension

Here's what the LWC Live Preview extension looks like in action. The **UI Preview** tab displays a preview of the `Sales Overview Dashboard` component, which was built using an Agentforce Vibes prompt.

![Screenshot of the LWC Live Preview VS Code Extension panel in a sample project.](https://developer.salesforce.com/media/livepreview_lwc_vscode.png)

To run a Lightning web component in the Lightning Preview panel, use one of these three methods.

**IDE Context Menu**

1. In the VS Code Explorer, right-click a Lightning web component's directory or any file inside it.
2. Select **SFDX: Open in Lightning Preview**.

**IDE Command Palette**

Open the Command Palette in VS Code, search for `SFDX: Open in Lightning Preview`, and then select **SFDX: Open in Lightning Preview**. When prompted, enter or select the name of the component you want to preview.

**Agent Integration**

If you're using Agentforce Vibes, you can instruct the agent to preview a component after it's finished updating your code. The agent automatically opens the component in the Lightning Preview panel.

#### Preview a Single React Component with the VS Code Extension (Beta)

For more information, see [Agentforce Vibes Developer Guide: Preview Your App](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-vibe-code.html#preview-your-app).

## Considerations and Limitations

Be aware of these guidelines for working with Live Preview.

### For Real-Time Preview Updates

When you edit local files with Live Preview enabled, your components automatically reflect only the following changes in your app or site preview:

| Automatically Loaded Change                                                          | Example                                                                                                                                                               |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basic HTML revisions                                                                 | Changing component attributes, like `title="Hello"` to `title="Goodbye"`                                                                                              |
| New reference to a component                                                         | Adding `<lightning-button></lightning-button>` to your markup                                                                                                         |
| Basic CSS revisions                                                                  | Changing `--slds-c-card-heading-font-weight: 100px;` to `--slds-c-card-heading-font-weight: 500px;`                                                                   |
| Importing a new CSS-only component                                                   | Adding a `cssLibrary` component that contains only a CSS file and a configuration file, like in [Share CSS Style Rules](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-share.md) |
| JavaScript changes in component methods that don't affect the component's public API | Using a new event handler in a template or changing existing event handler logic.                                                                                     |

**To apply any other local changes** to your preview, follow these steps.

For a Lightning app or Experience Cloud LWR site:

1. Deploy the changes to your org using the `project deploy start` command.
2. Restart the Live Preview server to see the updated app or site preview in your browser.

For a component in isolation:

1. Refresh your browser page.

For example, the following changes do **not** automatically load in your component preview. To see these changes in your preview, you have to follow the steps for manually loading local changes.

- Adding a new `@api` property or method to a component class
- Making changes related to wire adapters, such as configuration updates, importing a new wire adapter, adding `@wire` to a property, and changing a GraphQL query
- Importing new `@salesforce` scoped modules
- Updating your `.js-meta.xml` file
- Revising a service component library

### For Adding Component Files

Starting in Spring '25, Live Preview detects new or deleted files in your components and automatically updates your preview. For example, if you move shared functions into a component's `Util.js` file, your app preview automatically updates to reflect the code you added.

Previously, if you added or deleted a file in an existing component, you had to redeploy the component and restart the Live Preview server to see that change in your preview.

### For Modifying Certain File Types

Live Preview automatically updates your preview with [most local changes](#for-real-time-preview-updates) to files ending in `.js`, `.html`, and `.css`. If you edit a component file of any other type — like `.js-meta.xml` — you have to deploy the component to see those changes in your local preview.

### Supported Components

Live Preview only lets you preview Lightning web components. You can't use it to test Aura components in your app or site preview.

### Static Resources

Starting in Spring '25, Live Preview no longer saves a copy of your built app or site in your [static resources](https://help.salesforce.com/s/articleView?id=platform.pages_static_resources.htm&type=5) directory. Previously, automatically saved builds counted toward the 250 MB org static resource limit.

### Landing Pages

You can't preview [Landing Pages](https://help.salesforce.com/s/articleView?id=mktg.mktg_content_lp_create.htm&type=5) with Live Preview.

**See Also**

- [Salesforce Developers Blog: Develop LWC at Lightning Speed with the New Local Dev Experience](https://developer.salesforce.com/blogs/2024/10/develop-lwc-at-lightning-speed-with-the-new-local-dev-experience)

<!-- document id=fb4ffc35c136e4f34dfd617acc0bcf82235436f8e9e17fe36f01f669417751a6 url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks-created.md -->

# Run Code When a Component Is Created

The `constructor()` method fires when a component instance is created. Don’t add attributes to the host element during construction. You can add attributes to the host element in any other lifecycle hook.

The constructor flows from parent to child, which means that it fires in the parent first. You can't access child elements because they don't exist yet. Properties aren’t passed yet, either. Properties are assigned to the component after construction and before the [`connectedCallback()` hook](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom.md).

## Constructor Considerations

These requirements from the [HTML: Custom elements spec](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance) apply to the `constructor()`.

- The first statement must be `super()` with no parameters. This call establishes the correct prototype chain and value for `this`. Always call `super()` before touching `this`.
- Don’t use a `return` statement inside the constructor body, unless it is a simple early-return (`return` or `return this`).
- Don’t use the `document.write()` or `document.open()` methods.
- Don’t inspect the element's attributes and children, because they don’t exist yet.
- Don’t inspect the element’s public properties, because they’re set after the component is created.

## Don’t Add Attributes to Host Element During Construction

You can add attributes to the host element during any stage of the component lifecycle other than construction.

This pattern isn't recommended, because it adds an attribute to the host element in the `constructor()`.

```javascript
// don't do this
import { LightningElement } from "lwc";
export default class Deprecated extends LightningElement {
  constructor() {
    super();
    this.classList.add("new-class");
  }
}
```

To add an attribute to the host element, use the `connectedCallback()` method instead.

```javascript
import { LightningElement } from "lwc";

export default class New extends LightningElement {
  connectedCallback() {
    this.classList.add("new-class");
  }
}
```

**See Also**

- [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)

<!-- document id=12de5d3d1f79d1aec1dd05024221143665b53e4d47df15586cc50dc2a26414ac url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks-dom.md -->

# Run Code When a Component Is Inserted or Removed from the DOM

The `connectedCallback()` lifecycle hook fires when a component is inserted into the DOM. The `disconnectedCallback()` lifecycle hook fires when a component is removed or hidden from the DOM. Both hooks flow from parent to child. To access the host element, use `this`. To access elements in a component’s template, use `this.template`.

`connectedCallback()` and `disconnectedCallback()` are standard lifecycle callbacks that follow [web components standards](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).

**tip:** To check whether a component is connected to the DOM, you can use [`this.isConnected`](https://developer.salesforce.com/docs/platform/lwc/js/js-web-apis.md).

## `connectedCallback()`

Use `connectedCallback()` to interact with a component's environment. For example, use it to:

- Establish communication with the current document or container and coordinate behavior with the environment.
- Perform initialization tasks, such as fetch data, set up caches, or listen for events
- [Subscribe and Unsubscribe from a Message Channel](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-subscribe.md).
- Navigate to different page types, like records and list views using [the `lightning/navigation` module](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-basic.md).
- Work with [third-party web components](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-custom-elements.md).

The `connectedCallback()` hook is invoked with the initial properties passed to the component. If a component derives its internal state from the properties, it's better to write the logic in a setter than in `connectedCallback()`. For sample code, see this [StackExchange post](https://salesforce.stackexchange.com/questions/334634/lwc-setting-properties-in-connectedcallback) by Salesforce engineer Pierre-Marie Dartus.

`connectedCallback()` can fire more than one time. For example, if you remove an element and then insert it into another position, such as when you reorder a list, the hook fires several times. If you want code to run one time, write code to prevent it from running twice.

You can’t access child elements from the callbacks because they don’t exist yet.

```html
<template>
  <div>Some content</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ConnectedCallbackExample extends LightningElement {
  connectedCallback() {
    // This doesn't work
    const div = this.template.querySelector("div");
  }
}
```

## `disconnectedCallback()`

Use `disconnectedCallback()` to clean up work done in the `connectedCallback()`, like purging caches or removing event listeners.

You can also use this hook to [unsubscribe from a message channel](https://developer.salesforce.com/docs/platform/lwc/use/message-channel/use-message-channel-subscribe.md).

## Don't mark lifecycle hooks as `async`

`connectedCallback()` and `disconnectedCallback()` are synchronous. The framework doesn't await a promise that's returned from a lifecycle hook. If you mark a hook as `async`, code after an `await` runs after the framework moves on, which causes unpredictable order of execution relative to rendering, parent and child callbacks, and event handlers.

To run async work from a lifecycle hook, call a separate `async` method from the synchronous hook.

```javascript
import { LightningElement } from "lwc";

export default class extends LightningElement {
  connectedCallback() {
    this.loadData();
  }

  async loadData() {
    const result = await fetchSomething();
    // Update reactive properties here.
  }
}
```

**See Also**

- [Use Getters and Setters to Modify Data](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getters-setters.md)
- [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)
- [Communicate Across the DOM](https://developer.salesforce.com/docs/platform/lwc/events/events-pubsub.md)

<!-- document id=9f0695eb086b4373a1b3e3bede887c046fdc8c0b3bdf64381f16b4b99e2a1fac url=/developer/current/en-us/lwc/lwc/guides/create/create-lifecycle-hooks-rendered.md -->

# Run Code When a Component Renders

The `renderedCallback()` lifecycle hook is unique to Lightning Web Components. Use it to perform logic after a component has finished the rendering phase. This [hook flows](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md) from child to parent.

When a component renders, the expressions used in the template are reevaluated.

## Rerendering Components

After a component is connected and rendered, any changes or mutations to its state trigger the rerendering process:

1. The component gets marked as "dirty."
2. A microtask rerender the component gets enqueued.

For example, components get rerendered when a property's value changes and that property is used either directly in a component template or indirectly in the getter of a property that is used in a template. To learn more about which changes are tracked, see [Reactivity](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md).

When a template is rerendered, the LWC engine attempts to reuse the existing elements. In the following cases, the engine uses a diffing algorithm to decide whether to discard an element.

- Elements created using the [`for:each`](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.md) directive. The decision to reuse these iteration elements depends on the `key` attribute. If `key` changes, the element may be rerendered. If `key` doesn’t change, the element isn’t rerendered, because the engine assumes that the iteration element didn’t change.
- Elements received as [slot](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md) content. The engine attempts to reuse an element in a `<slot>`, but the diffing algorithm determines whether to evict an element and recreate it.

## `hasRendered`

A component is usually rendered many times during the lifespan of an application. To use this hook to perform a one-time operation, use a boolean field like `hasRendered` to track whether `renderedCallback()` has been executed. The first time `renderedCallback()` executes, perform the one-time operation and set `hasRendered = true`. If `hasRendered = true`, don’t perform the operation.

## Event Listeners

It’s best to [add event listeners declaratively in an HTML template](https://developer.salesforce.com/docs/platform/lwc/events/events-handling.md). However, if you do need to add an event listener to a template element programmatically, do it in `renderedCallback()`. You don’t need to remove the listener. If a listener is added to the same element repeatedly, the browser ignores the duplicates.

## Considerations

Updating the state of your component in `renderedCallback()` can cause an infinite loop. For example:

- Don’t update a wire adapter configuration object property in `renderedCallback()`. See [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md).
- Don’t update a public property or field in `renderedCallback()`. See [Reactivity](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md).

**tip:** The `libsChartjs` module in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) samples repo uses the `renderedCallback()` lifecycle hook.

**See Also**

- [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)

<!-- document id=aef40e4191d232a5d3477c2e6d50517d46657003594bf8b5f520b815239759e6 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-run-tests.md -->

# Run Jest Tests for Lightning Web Components

Run your unit tests frequently or continuously during component development.

## Run Tests from VS Code

If you install Salesforce Extensions for Visual Studio Code, you can run tests, debug them, and watch Jest files from within VS Code. For more information, see [Salesforce Extensions for Visual Studio Code](https://developer.salesforce.com/tools/vscode/en/lwc/testing).

## Run Tests on the Command Line

To run all tests for your project, use the Salesforce CLI command [`sf force lightning lwc test run`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_lightning.htm#cli_reference_force_lightning) from the root folder of your project. Otherwise, run the command that you added to the `scripts` block of your project’s `package.json` file when [installing Jest and dependencies](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-installation.md) .

```bash
npm run test:unit
```

## Run Tests Continuously During Development

To run all tests for a single component every time you save changes, go to the component directory and run the `sfdx-lwc-jest` command with the `--watch` parameter. Use the entry that you added to the `scripts` block of your project’s `package.json` file when [installing Jest and dependencies](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-installation.md).

```bash
npm run test:unit:watch
```

Jest watches all component files for updates, and runs all relevant tests each time it detects a change.

## Run Jests Tests in Debug Mode

Running Jest tests in debug mode is useful if you want to step through your tests and app code to find out why your tests or code aren't behaving as expected. You can debug Jest tests using the following tools.

- VS Code Salesforce Extension Pack
- Chrome Developer Tools
- VS Code debugger advanced configuration

The VS Code Salesforce Extension Pack provides the simplest and most straightforward option, while Chrome DevTools caters to seasoned web developers. Additionally, the advanced configuration for the VS Code debugger enables you to work with different debuggers and debugging scenarios. The advanced configuration offers the most flexible option for debugging your Jest tests.

For more information, see [Debug Jest Tests for Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-debug-tests.md).

## Advanced Jest Configurations

`sfdx-lwc-jest` is configured to run Jest tests without any additional changes. However, if you’re an advanced Jest user, check out some of Jest's other configuration options. See [`github.com/salesforce/sfdx-lwc-jest#overriding-jest-config`](https://github.com/salesforce/sfdx-lwc-jest#overriding-jest-config).

**important:** If your Jest tests are executing slowly and they have dependencies from different folders, provide mappings to speed up the resolution. See the `moduleNameMapper` in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/blob/master/jest.config.js).

**See Also**

- [Debug Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/debug/debug-intro.md)

<!-- document id=b06d5378cc278ed02df4b8a6b904c7a1df5f97314812e6b9daec5faa0092da39 url=/developer/current/en-us/lwc/slds_linter/guides/get-started/get-started-linter-AI-skills.md -->

# Run SLDS Linter with SLDS AI Development Skills

SLDS Linter powers three SLDS AI development skills that guide coding agents through building, validating, and migrating SLDS-compliant components. If you're using Claude Code, Cursor, Agentforce Vibes, or another AI tool that supports the [Agent Skills](https://agentskills.io) specification, these skills run SLDS Linter as part of their workflow.

**note:** SLDS Linter currently parses only HTML and CSS files. If you're working in React or a similar framework, SLDS Linter coverage is currently limited.

Learn how each skill uses SLDS Linter plus where SLDS Linter's automated checks end and the skill's guidance begins.

## How SLDS AI Development Skills Work

SLDS Linter autofixes most violations with high confidence when you run the `lint` command with the `--fix` option. But some violations require judgment that SLDS Linter can't apply on its own. For example, when a hardcoded color value maps to more than one valid styling hook, the correct choice depends on the component's context.

SLDS AI development skills close that gap. These three skills read SLDS Linter's output, apply the decision logic, and choose the right fix. SLDS Linter plays a different role in each skill.

- `design-systems-slds-validate`
- `design-systems-slds-apply`
- `design-systems-slds2-migrate`

For new projects, use the [SLDS 2 AI Starter Kit](https://github.com/salesforce-ux/design-system-2-starter-kit), which includes the SLDS AI development skills already set up. For existing projects, install and run the SLDS AI development skills via the Agentforce Vibes plugin or install and run them directly in your AI tool with the `npx skills add forcedotcom/sf-skills` command. Browse full information about these skills — and all Salesforce agent skills — in the [Salesforce Skills Library](https://github.com/forcedotcom/sf-skills).

**note:** Each skill instructs the agent to run SLDS Linter and not skip it. Agents can still skip an SLDS Linter step even when it’s indicated as mandatory in the skill.

### design-systems-slds-validate

Audits code for SLDS compliance and produces a scored quality report.

SLDS Linter analyzes your design code against SLDS 2 rules and reports specific rule violations. The skill also checks for missing styling hook fallbacks, invented styling hook names, missing foreground and background styling hook pairing, strict `!important` tag usage, hardcoded pixel values, and accessibility attributes.

SLDS Linter results make up 30% of the overall quality score, alongside theming, accessibility, code quality, and component usage. The SLDS Linter score formula is: `100 − (10 × total errors) − (5 × total warnings)`.

**Example prompts:**

- Give this component a compliance score.
- Which SLDS rules is this component failing, and how severe are they?

### design-systems-slds-apply

Creates SLDS-compliant UI using the correct component blueprints, styling hooks, utility classes, and icons.

SLDS Linter runs as a mandatory validation step. The skill selects the right component and applies styling hooks first. It then runs SLDS Linter and works through the reported violations, before the component is considered fully compliant with SLDS 2 guidelines.

**important:** Combining the `design-systems-slds-apply` skill with custom instructions can cause an agent to skip the SLDS Linter validation step. So, use the skill on its own to create new LWC components with reliable SLDS compliance.

**Command:**

```
npx @salesforce-ux/slds-linter@latest lint <component-path>
```

**Example prompts:**

- I need a data table with sortable columns. Pick the correct SLDS component blueprint.
- Add utility classes and an icon to this card so it matches SLDS spacing conventions.

### design-systems-slds2-migrate

Migrates Lightning Web Components from SLDS 1 to SLDS 2.

The skill runs SLDS Linter as a mandatory first step with the `--fix` option to autofix simple violations. Then the skill works through the remaining violations one rule at a time. For example, `no-hardcoded-values-slds2`, `lwc-token-to-slds-hook`, `no-slds-class-overrides`, and so on. Then the skill reruns SLDS Linter until no errors or warnings remain.

**Command:**

```
npx @salesforce-ux/slds-linter@latest lint --fix
```

**Example prompts:**

- Uplift this component from SLDS 1 to SLDS 2 and resolve all violations.
- Replace all deprecated tokens in this component with SLDS 2 styling hooks.

## Run SLDS Linter Manually

You can run SLDS Linter through an AI development skill, or you can [run SLDS Linter](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-scan-code.html) directly. Directly run SLDS Linter to check auto-fixable violations before invoking a skill, or to confirm a skill's changes independently.

## See Also

- [Salesforce Lightning Design System 2: AI Development Skills](https://www.lightningdesignsystem.com/2e1ef8501/p/8225d4-ai-development-skills)
- [Salesforce Lightning Design System 2: SLDS 2 AI Starter Kit](https://www.lightningdesignsystem.com/2e1ef8501/p/057d3b-slds-2-ai-starter-kit)
- [Salesforce Skills Library](https://github.com/forcedotcom/sf-skills)

<!-- document id=59830b96a3845d2aa8dd736b399263c995bd6ecd30de40c88cda938b202e3fb6 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-runtime-considerations.md -->

# Runtime Considerations for Flow Screen Components

When you’re configuring components for flows, review these considerations for defining attributes and flow runtime behavior.

- **Handle `null` default input values.**

  If a flow admin doesn't set a default input value for a custom screen component, Flow Builder passes a `null` value at component run time. To set a default value at run time, add a `null` handler.

- **Handle hidden component output values.**

  If a screen component is hidden, all output attributes are set to `null` when the user navigates away from the screen.

- **Notify runtime of attribute changes.**

  Lightning web components use events to report changes from components to flows. To notify the flow runtime of attribute changes, a component fires the `FlowAttributeChangeEvent` event. For example, use this event when using conditional visibility to render a screen component when conditions are met or when mapping the value of output attributes to flow variables. For code samples, see `lightning-flow-support`.

- **Consider the default attribute behavior.**

  All flow screen component input attributes are also output attributes by default.

**See Also**

- [_Salesforce Help_: Flow Builder](https://help.salesforce.com/articleView?id=flow_builder.htm&type=5)
- [Component Reference: lightning-flow-support](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-flow-support)

<!-- document id=d5930295059db02a852b3372af8fe9dc9a9ed09702876b85954a037c2014c058 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-restricted-globals.md -->

# Salesforce Global Variables Blocked by Lightning Web Security

Lightning Web Security (LWS) blocks access to some global JavaScript objects that are available to other Salesforce features.

Lightning web components (LWC) **don’t have access** to:

- `$A`
- `Aura`
- `Sfdc`
- `sforce`

LWS restricts access to these objects for Lightning web components because they are either deprecated or not supported for LWC.

**See Also**

- [Lightning Web Security Limitations](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-limitations.md)

<!-- document id=8bd71473870bc89f4b808a36a923a529279e26038261f40c9e921b380117d574 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-objects-lwc.md -->

# Salesforce Objects Support in LWC

Lightning web components can access Salesforce data and metadata from all custom objects and from all the [standard objects](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) that User Interface API (UI API) supports.

However, not all Salesforce standard objects support **all** features of LWC or the Salesforce Platform. Some objects that are supported by UI API nevertheless have some limitations you'll need to work around. And some standard objects appear simple when you work with them in Salesforce, but have complex, multi-object implementations. You'll need to understand those objects and their relationships before working with them in LWC.

If you're having difficulty working with a standard object, check the following references to verify whether or not it's fully supported from LWC.

**See Also**

- [`ui*API` Supported Objects](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)
- [Standard Objects Support for Record Home Pages](https://developer.salesforce.com/docs/platform/lwc/guide/reference-objects-lwc-record-home.md)
- [Standard Objects That Support List View Multiple-Column Sort](https://developer.salesforce.com/docs/platform/lwc/guide/reference-objects-lwc-multi-column-sort.md)
- [Standard Objects That Don't Support Related List Multiple-Column Sort](https://developer.salesforce.com/docs/platform/lwc/guide/reference-objects-lwc-related-lists-sort.md)
- [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/)

<!-- document id=b0265731f1076ae4cfe4e33fe3ac300c849a0446e758e63f2b463e3ed8676d80 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-supported-objects.md -->

# Salesforce Objects Supported by `lightning/ui*Api` Modules

The wire adapters and JavaScript functions in `lightning/ui*Api` modules are built on User Interface API. User Interface API supports all custom objects and many standard objects.

Lightning web components can access Salesforce data and metadata from all custom objects and from all the [standard objects](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_get_started_supported_objects.htm) that User Interface API supports.

**See Also**

- [Salesforce Objects Support in LWC](https://developer.salesforce.com/docs/platform/lwc/guide/reference-objects-lwc.md)

<!-- document id=b7947efbf2fcfcd31550a370b0ff9988f46ec9256ac1f6964853187cb147e04f url=/developer/current/en-us/lwc/lwc/guides/create/create-version-alignment.md -->

# Salesforce Releases and LWC API Versions

Here's how Salesforce releases map to LWC API versions and LWC open source (LWC OSS) versions.

| Salesforce Release | LWC API Version  | LWC OSS             |
| ------------------ | ---------------- | ------------------- |
| Spring ’25         | 63.0             | v8.0.0              |
| Winter ’25         | 62.0             | v7.0.0              |
| Summer ’24         | 61.0             | v6.0.0              |
| Spring ’24         | 60.0\*           | v5.0.0              |
| Winter ’24         | 59.0             | v3.0.0              |
| Summer ’23         | 58.0 and earlier | v2.50.0 and earlier |

\* LWC API version 60.0 also includes changes from LWC OSS [v4.0.0](https://github.com/salesforce/lwc/releases/tag/v4.0.0).

**note:** LWC open source follows [semantic versioning](https://semver.org/) (semver) characteristics. See [_LWC Open Source_: LWC Versioning](https://lwc.dev/guide/versioning). While LWC on the Salesforce platform uses the same code base as [LWC open source](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md), the version of LWC on the Salesforce platform is 3-6 months behind the open source version. For example, LWC OSS released v3.0.0 in June 2023 and the same was available to Salesforce platform developers as part of the Winter ’24 release.

**See Also**

- [Find Salesforce Edition and API version](https://help.salesforce.com/s/articleView?id=000386929&type=1)

<!-- document id=28728b9fcfeb6baec890d568dedfed94b9352718a93c5c93d5bb7eae3981f510 url=/developer/current/en-us/lwc/slds_linter/guides/use/use-scan-code.md -->

# Scan Your Code

Run SLDS Linter against your project to check for any issues and generate a SARIF report. This report helps you identify the components to be updated.

In VS Code, in your project root directory, follow these steps.

1. Open a Terminal.
2. Run SLDS Linter.
   The linting output displays in the console and includes the row and column numbers.

   ```
   npx @salesforce-ux/slds-linter lint
   ```

3. Select the displayed numbers to go to specific lines in the source code (Command+Click on macOS).
4. Produce a SARIF report in your project’s root directory.

   ```
   npx @salesforce-ux/slds-linter report
   ```

   Optionally, you can specify an output directory by using `-o [output directory]`.

   ```
   npx @salesforce-ux/slds-linter report -o [output directory]
   ```

   The output file is named as `slds-linter-report.sarif`.

5. Open the generated SARIF report file.
6. Make a note of how many components SLDS Linter has identified for fixing.

<!-- document id=ab31e5d7b5cf09bec6dbad0addd00eebb0661e4d4c17f760d27134bbf7d30076 url=/developer/current/en-us/lwc/slds-validator/guides/scan-your-code.md -->

# Scan Your Code with SLDS Validator

With a single file or an entire project open in VS Code, SLDS Validator recommendations are highlighted in your CSS file.

## Scan Your Completed Code

1. Open your CSS file or project that contains CSS files in VS Code.

   ![An example CSS file open in VS Code with a highlight on line 4 -–sds-g-sizing-border, 1px.](https://developer.salesforce.com/docs/media/slds-validator/ValidatorHighlightSquiggles.png)

2. Hover over the SLDS Validator recommendation.

   ![An example SLDS Validator recommendation.](https://developer.salesforce.com/docs/media/slds-validator/ValidatorHighlightRecommendation.png)

3. Review the recommendation info available in the window.
   The recommendation contains:

- A description of the issue. In this example, a styling hook is deprecated.
- A View Problem link with more info
- A Quick Fix link

  ![An example Quick Fix.](https://developer.salesforce.com/docs/media/slds-validator/ValidatorHighlightQuickFix.png)

4. Hover over **Quick Fix** to see and select a replacement value.

## Get Live Recommendations with Autocomplete

As you write code in VS Code, use SLDS Validator to autocomplete code. Just type `--slds`,`.slds`, or `slds-` to receive a full list of available options.

![An example SLDS Validator autocomplete recommendation.](https://developer.salesforce.com/docs/media/slds-validator/ValidatorAutocomplete.png)

<!-- document id=096c1c2a1c0e5ad41bd1ad10b757515a901e0bfec10627e8922d30a9832835e1 url=/developer/current/en-us/lwc/lwc/guides/reference/barcodescanner/reference-lightning-barcodescanner-scan.md -->

# `scan(options)`

Use this function to start scanning barcodes.

## Syntax

```
import { getBarcodeScanner } from 'lightning/mobileCapabilities';
scan(options: BarcodeScannerOptions): Promise<Object>
```

## Parameters

- `options`—(Required) A [`BarcodeScannerOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) object to configure the scanning session.

## Returns

A Promise object that resolves as an array of [`Barcode`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) objects with the scanned barcode details.

A rejected promise returns a [`BarcodeScannerFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md).

## Usage

This function allocates scanner resources. To release the resources when scanning is complete, pair it with `dismiss()`.

```javascript
myScanner
  .scan(scanningOptions)
  .then((resultsArray) => {
    // Do something with the result of the scan
    for (let singleResult in resultsArray) {
      console.log(singleResult);
      this.scannedBarcodes.push(singleResult.value);
    }
  })
  .catch((error) => {
    // Handle cancellation and scanning errors here
    console.error(error);
  })
  .finally(() => {
    myScanner.dismiss();
  });
```

When this function is called, a mobile OS scanning user interface is displayed on the mobile device. The user can point their camera at a barcode and wait for the barcode to be recognized.

- When a barcode is successfully scanned, the result is returned via a fulfilled promise. Handle successful results in a `then` clause.
- When a barcode scan fails, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user clicks the **Cancel** button during a scan, the promise is rejected with a [`BarcodeScannerFailure.code`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types.md) value of `userDismissedScanner`.
- The mobile OS scanner interface remains displayed after a successful scan or an error. To close the scanner interface and return to your component’s interface, call `dismiss()`.
- Handle any final cleanup, such as calling `dismiss()`, in a `finally` clause.

**See Also**

- [BarcodeScanner Example–Modern Scanning API](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_barcodescanner_example_modern.htm)

<!-- document id=dfe89ce3025e63dec013ef26c9eaa7fcf6157b00d1ef04d2798b1526f03ba179 url=/developer/current/en-us/lwc/lwc/guides/reference/documentscanner/reference-lightning-documentscanner-scan.md -->

# `scan(options)`

Use this function to start scanning a document.

## Syntax

```javascript
import { getDocumentScanner } from 'lightning/mobileCapabilities';
getEvents(options: DocumentScannerOptions): Promise<Object>;
```

## Parameters

- `options`—(Required) A [`DocumentScannerOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-data-types.md#documentscanneroptions) object to configure the scanning session.

## Returns

A Promise object that resolves to an array containing one or more [Document](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-data-types.md#document) objects.

A rejected promise returns a [`DocumentScannerFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-data-types.md#documentscannerfailure).

## Usage

Use this function to scan a document and handle the results of the scan. 

```javascript
myDocumentScanner
.scan(options)
.then((results) => {
    // Do something with the result of the scan
    this.scannedText = results.value;
})
.catch((error) => {
    // Handle cancellation and scanning errors here
    this.results = [];
    console.error('Error code: ' + error.code); + 
    console.error('Error message: ' + error.message);
});
```

- The design pattern of returning an array containing a single `Document` object instead of just the Document object is intentional. This flexibility makes it easier to add future enhancements without causing existing code to break.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels a scan, the promise is rejected with a `DocumentScannerFailure.code` value of USER_DISMISSED.

**See Also**

- [DocumentScanner Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-documentscanner-data-types.md)

<!-- document id=8fbd0c0a769d4ff6926d20b4eef8d10ffd759be7df0c9a7ba9cfce61c5f2e69c url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-script-tags.md -->

# Script Tags Transformed to Fetch Calls

Lightning Web Security (LWS) transforms `<script>` tags into `fetch` calls. LWS downloads the script to evaluate it in the sandbox.

To enable the `fetch` calls to succeed:

- Configure the `connected-src` CSP directive on the Salesforce site where the component runs to allow access to the script resource server. See [Manage Trusted URLs](https://help.salesforce.com/s/articleView?id=sf.security_trusted_urls_manage.htm).

- Configure the resource server with cross-origin resource sharing [(CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to add the origin of the Salesforce site to its allowed origins list. The component can then access server resources.

<!-- document id=fc743e123fd788433d1a12fe9c788b9ed8463271028c1e26c4d5ef3088242268 url=/developer/current/en-us/lwc/lwc/guides/reference/commerce-repricing/reference-lightning-commerce-repricing-search-products.md -->

# `searchProducts`

Searches for products in a webstore. Use this wire adapter in Order Management repricing scenarios.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { searchProducts } from 'lightning/commerceRepricingApi';

@wire(searchProducts, { webstoreId: string, version: string })
propertyOrFunction
```

## Commerce API Resource

```
GET /commerce/order-management/webstores/{webstoreId}/products
```

`searchProducts` uses this [Commerce API resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search.htm).

## Parameters

- `webstoreId`—(Required) The ID of the webstore. The ID prefix is `0ZE`.
- `version`—(Required) The API version for the adapter, for example, `v62.0`. Without this parameter, the wire doesn't fire.
- `searchTerm`—(Optional) A keyword to search products by.
- `page`—(Optional) The page number of results to return.
- `pageSize`—(Optional) The number of results per page.
- `effectiveAccountId`—(Optional) The effective account ID for buyer-specific results.
- `facets`—(Optional) Facets to apply to the search.

## Returns

- `data`—A `ProductSearchOutputRepresentation` object with these fields:
  - `pageSize`—The number of results per page.
  - `totalRecordsFound`—The total number of products matching the search.
  - `pageNumber`—The current page number.
  - `products`—A list of matching products.
  - `facets`—A list of facets for the result set.
  - `success`—Indicates whether the request was successful.
  - `errors`—A list of errors, if any. Each error has `errorCode`, `message`, and `errorEntityId` fields.
- `error`—[`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

```javascript
import { LightningElement, wire } from 'lwc';
import { searchProducts } from 'lightning/commerceRepricingApi';

export default class SearchProductsExample extends LightningElement {
  webstoreId = '0ZExx0000000001';
  searchTerm = 'widget';

  @wire(searchProducts, {
    webstoreId: '$webstoreId',
    version: 'v62.0',
    searchTerm: '$searchTerm',
    page: 1,
    pageSize: 25,
  })
  searchResults;

  get products() {
    return this.searchResults?.data?.products;
  }

  get totalCount() {
    return this.searchResults?.data?.totalRecordsFound;
  }
}
```

## Error Handling

If the wire adapter encounters an error, `data` is `undefined` and `error` contains the error details.

**See Also**

- [`productDetails`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-repricing-product-details.md)

<!-- document id=7221b65b56f2dd9d46729e6baaa106fb8f3ba6c5a8ecf38cf989831e6604a66e url=/developer/current/en-us/lwc/lwc/guides/apex/apex-security.md -->

# Secure Apex Classes

In API version 67.0 and later, Apex runs in user mode by default, meaning that the current user’s permissions and field-level security (FLS) are enforced during code execution. To ignore the FLS and object permissions of the current user, you must explicitly set a database operation or query to run in system mode. Additionally, Apex classes enforce record sharing rules by default. If you don’t want to enforce sharing rules, then you must declare a class with the `without sharing` keyword.

**important:** In API version 66.0 and earlier, Apex runs in system mode by default, which means that it runs with substantially elevated permissions, acting as if the user had most permissions and all field- and object-level access granted. Because these security layers aren’t enforced like they are in the Salesforce UI, you must write code to enforce them. Otherwise, your components may inadvertently expose sensitive data that would normally be hidden from users in the Salesforce UI.

**tip:** To work with Salesforce records, we recommend using Lightning Data Service, which handles sharing rules, CRUD, and field-level security for you. See [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/data/data-guidelines.md).

## Grant User Access for Apex Classes

An authenticated or guest user can access an `@AuraEnabled` Apex method only when the user’s profile or an assigned permission set allows access to the Apex class.

For details on configuring user profile or permission set access to an Apex class, see [Class Security](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_security.htm) in the _Apex Developer Guide_.

## Set Sharing Rules

An `@AuraEnabled` Apex class that doesn’t explicitly set `with sharing` or `without sharing`, or is defined with `inherited sharing`, uses a default or implicit value of `with sharing`. However, Salesforce recommends that you use keyword declarations on all your classes to make your code easier to maintain across API versions.

```apex
public with sharing class SharingClass {
    // Code here
}
```

To bypass sharing rules, you must explicitly declare the class as `without sharing`.

```apex
public without sharing class WithoutSharingClass {
    // Code here
}
```

The `with sharing` and `without sharing` keywords set record-level security. They don’t enforce object-level and field-level security.

## Set Object and Field Permissions (CRUD and FLS)

Apex database operations run in user mode by default. Database operations only ignore FLS and object permissions if you explicitly set them to run in system mode. However, Salesforce recommends setting an access mode on all database operations so that your code is easier to maintain across API versions.

### Set an Access Mode for SOQL and SOSL Queries

Use the `WITH USER_MODE` or `WITH SYSTEM_MODE` clauses for `SOQL SELECT` queries in Apex code, including subqueries and cross-object relationships.

For example, `getExpenses()` uses the `WITH USER_MODE` clause to enforce object-level and field-level permissions.

```apex
public with sharing class ExpenseController {
    // This method is recommended because it enforces FLS.
    @AuraEnabled
    public static List<ns__Expense__c> getExpenses() {
    // Query the object safely
    return [SELECT Id, Name, ns__Amount__c, 
            ns__Client__c, ns__Date__c,
            ns__Reimbursed__c, CreatedDate
            FROM ns__Expense__c 
            WITH USER_MODE];
    }
}
```

To bypass the current user’s FLS and object permissions, you must explicitly add the `WITH SYSTEM_MODE` clause to the SOQL query.

```apex 
List<Account> acc = [SELECT Id FROM Account WITH SYSTEM_MODE];
```

For more details, see [Set an Access Mode for Database Operations](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_enforce_usermode.htm) in the _Apex Developer Guide_.

### Graceful Degradation with `stripInaccessible()`

For more graceful degradation on permissions errors, use the `stripInaccessible()` method to enforce field- and object-level data protection. This method strips the fields and relationship fields from query and subquery results that the user can’t access. You can find out if any fields were stripped and throw an `AuraHandledException` with a custom error message, if desired.

You can also use the method to remove inaccessible sObject fields before DML operations to avoid exceptions and to sanitize sObjects that have been deserialized from an untrusted source.

This example updates `ExpenseController` to use `stripInaccessible()` instead of the `WITH USER_MODE` SOQL clause. The results are the same but `stripInaccessible()` gives you the opportunity to gracefully degrade instead of failing on an access violation when using `WITH USER_MODE`.

```apex
public with sharing class ExpenseControllerStripped {

    @AuraEnabled
    public static List<ns__Expense__c> getExpenses() {
        // Query the object but don't use WITH USER_MODE
        List<ns__Expense__c> expenses =
            [SELECT Id, Name, ns__Amount__c, ns__Client__c, ns__Date__c,
                ns__Reimbursed__c, CreatedDate
                    FROM ns__Expense__c];

            // Strip fields that are not readable
            SObjectAccessDecision decision = Security.stripInaccessible(
                AccessType.READABLE,
                expenses);

            // Throw an exception if any data was stripped
            if (!decision.getModifiedIndexes().isEmpty()) {
                throw new AuraHandledException('Data was stripped');
            }

            return expenses;
    }
}
```

For more details and examples, see [Enforce Security with the stripInaccessible Method](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_with_security_stripInaccessible.htm) in the _Apex Developer Guide_.

### Update Legacy Code Using `DescribeSObjectResult` and `DescribeFieldResult` Methods

Before the `WITH USER_MODE` clause and `stripInaccessible()` method were available, the only way to enforce object and field permissions was to check the current user’s access permission levels by calling the `Schema.DescribeSObjectResult` and `Schema.DescribeFieldResult` methods. Then, if a user has the necessary permissions, perform a specific DML operation or a query.

For example, you can call the `isAccessible`, `isCreateable`, or `isUpdateable` methods of `Schema.DescribeSObjectResult` to verify whether the current user has read, create, or update access to an `sObject`, respectively. Similarly, `Schema.DescribeFieldResult` exposes access control methods that you can call to check the current user’s read, create, or update access for a field.

This example uses the describe result methods. This approach requires many more lines of boilerplate code so we recommend using the `WITH USER_MODE` clause or `stripInaccessible()` method instead.

```apex
public with sharing class ExpenseControllerLegacy {
    @AuraEnabled
    public static List<ns__Expense__c> getExpenses() {
        String [] expenseAccessFields = new String [] {'Id',
                                                        'Name',
                                                        'ns__Amount__c',
                                                        'ns__Client__c',
                                                        'ns__Date__c',
                                                        'ns__Reimbursed__c',
                                                        'CreatedDate'
                                                        };


    // Obtain the field name/token map for the Expense object
    Map<String,Schema.SObjectField> m = Schema.SObjectType.ns__Expense__c.fields.getMap();

    for (String fieldToCheck : expenseAccessFields) {

        // Call getDescribe to check if the user has access to view field
        if (!m.get(fieldToCheck).getDescribe().isAccessible()) {

            // Pass error to client
            throw new System.NoAccessException();
        }
    }

    // Query the object safely
    return [SELECT Id, Name, ns__Amount__c, ns__Client__c, ns__Date__c,
            ns__Reimbursed__c, CreatedDate FROM ns__Expense__c];
    }
}
```
For more details and examples, see [Enforce Security with Field and SObject Describe Methods](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_field_object_describe.htm) in the _Apex Developer Guide_.

**See Also**

- [_Apex Developer Guide_: Enforcing Sharing Rules](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_security_sharing_rules.htm)
- [_Apex Developer Guide_: Enforcing Object and Field Permissions](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_perms_enforcing.htm)
- [_Apex Developer Guide_: Using the with sharing, without sharing, and inherited sharing Keywords](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_keywords_sharing.htm)
- [_Secure Coding Guide_: Lightning Security](https://developer.salesforce.com/docs/atlas.en-us.secure_coding_guide.meta/secure_coding_guide/secure_coding_lightning_security.htm)

<!-- document id=ad3f1de189fe2011db0b8989a1b01a3ccbbb524f01799602f49a8b449ddc02d8 url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-global-access.md -->

# Secure Wrappers

For security, Lightning Locker restricts the use of global objects by hiding an object or by wrapping it in a secure version of the object. For example, the secure version of `window` is `SecureWindow`. Locker intercepts calls to `window` and uses `SecureWindow` instead.

To see which APIs are supported by the `SecureWindow`, `SecureDocument`, and `SecureElement` wrappers, use the [Locker API Viewer](https://developer.salesforce.com/tools/locker-service-viewer) tool.


**important:** Under Legacy Locker (Aura), `Secure` wrappers wrap DOM elements with a curated allowlist of [supported APIs](https://developer.salesforce.com/tools/locker-service-viewer) per element type. Reading any property outside that list across a namespace boundary returns `undefined`. Use `data-*` attributes for custom values.

## Types of Secure Wrappers

- `SecureWindow`

  - : Available: Lightning Web Components and Aura Components

    Secure wrapper for the `window` object, which represents a window containing a DOM document.

    If a Lightning web component and an Aura component belong to the same namespace, they share the same `SecureWindow` instance.

- `SecureDocument`

  - : Available: Lightning Web Components and Aura Components

    Secure wrapper for the `document` object, which represents the root node of the HTML document or page. The `document` object is the entry point into the page’s content, which is the DOM tree.

    If a Lightning web component and an Aura component belong to the same namespace, they share the same `SecureDocument` instance.

- `SecureObject`

  - : Available: Lightning Web Components and Aura Components

    Secure wrapper for an object that is wrapped by Lightning Locker. When you see a `SecureObject`, it typically means that you don’t have access to the underlying object and its properties aren’t available.

- `SecureElement`

  - : Available: Lightning Web Components and Aura Components

    Secure wrapper for the `element` object, which represents various HTML elements.

    If a Lightning web component and an Aura component belong to the same namespace, they share the same `SecureElement` instance.

    Lightning web components additionally use the `SecureLightningElement` wrapper.

- `SecureLightningElement`

  - : Available: Lightning Web Components

    Secure wrapper for the `LightningElement` base class. Lightning web components extend the `LightningElement` base class, and at runtime Locker switches the class with `SecureLightningElement`. When you create a Lightning web component, do not extend `SecureLightningElement` directly.

    These APIs are not supported.

    - [`Element.attachShadow()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow)
    - [`Element.shadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot)—use `this.template` instead
    - [`Element.slot`](https://developer.mozilla.org/en-US/docs/Web/API/Element/slot)

- `SecureTemplate`

  - : Available: Lightning Web Components

    Secure wrapper for the `template` object, which represents a `shadowRoot` node.

    These APIs are not supported.

    - [`Node.localName`](https://developer.mozilla.org/en-US/docs/Web/API/Node/localName)
    - [`Node.namespaceURI`](https://developer.mozilla.org/en-US/docs/Web/API/Node/namespaceURI)
    - [`Node.nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue)
    - [`Node.nextSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)
    - [`Node.previousSibling`](https://developer.mozilla.org/en-US/docs/Web/API/Node/previousSibling)
    - [`Node.parentElement`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement)
    - [`Node.parentNode`](https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode)
    - [`Node.prefix`](https://developer.mozilla.org/en-US/docs/Web/API/Node/prefix)
    - [`NonDocumentTypeChildNode.nextElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/NonDocumentTypeChildNode/nextElementSibling)
    - [`NonDocumentTypeChildNode.previousElementSibling`](https://developer.mozilla.org/en-US/docs/Web/API/NonDocumentTypeChildNode/previousElementSibling)
    - [`DocumentOrShadowRoot.getSelection()`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection)
    - [`DocumentOrShadowRoot.pictureInPictureElement`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/pictureInPictureElement)
    - [`DocumentOrShadowRoot.styleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/styleSheets)
    - [`DocumentOrShadowRoot.pointerLockElement`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/pointerLockElement)
    - [`DocumentFragment.getElementById()`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment/getElementById)
    - [`ParentNode.append`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/append)
    - [`ParentNode.prepend`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/prepend)
    - [`constructor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/constructor)
    - [`EventTarget.dispatchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent)

**note:** [Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md) doesn't use wrappers. It uses API distortions in JavaScript sandboxes to selectively modify APIs that enable non-secure behaviors.

## Aura Component Example

Let’s look at a sample Aura component that demonstrates some of the secure wrappers.

```
<!--c:secureWrappers-->
<aura:component >
    <div id="myDiv" aura:id="div1">
        <p>See how Lightning Locker uses secure wrappers</p>
    </div>
    <lightning:button name="myButton" label="Peek in DOM"
        aura:id="button1" onclick="{!c.peekInDom}"/>
</aura:component>
```

The `c:secureWrappers` component creates a `<div>` HTML element and a `lightning:button` component.

Here’s the client-side controller that peeks around in the DOM.

```javascript
/* secureWrappersController.js */
({
  peekInDom: function (cmp, event, helper) {
    console.log("div1: ", cmp.find("div1").getElement());
    console.log("button1: ", cmp.find("button1"));
    console.log("button name: ", event.getSource().get("v.name"));
    // add debugger statement for inspection
    // always remove this from production code
    debugger;
  },
});
```

We use `console.log()` to look at the `<div>` element and the button. The `<div>` SecureElement is wrapped in a Proxy object as a performance optimization so that its data can be lazily filtered when it’s accessed.

We put a debugger statement in the code so that we could inspect the elements in the browser console.

Type these expressions into the browser console and look at the results.

```javascript
/* Browser console */
cmp;
cmp + "";
cmp.find("button1");
cmp.find("button1") + "";
window;
window + "";
$A;
$A + "";
```

Here’s the output.

![The console output of an Aura component that demonstrates how Lightning Locker uses secure wrappers](https://developer.salesforce.com/media/locker_wrapper_example.png '{"class": "image-full"}')

Let’s examine some of the output.

- `cmp+""` returns a `SecureComponent` object for `cmp`, which represents the `c:secureWrappers` component.
- `cmp.find("button1")+""` returns a `SecureComponentRef`, which represents the external API for a component in a different namespace. In this example, the component is `lightning:button`.
- `window+""` returns a`SecureWindow` object.
- `$A+""` returns a `SecureAura` object.

**See Also**

- [Lightning Locker API Viewer Overview](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-api-viewer.md)
- [How Lightning Locker Uses the Proxy Object](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-proxy.md)

<!-- document id=49375476b615fa555257322f23ec58706bd0421111482b77cdaf0472fab2647f url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-api-setting.md -->

# Select the Locker API Version for an Org

Select the API version used by Lightning Locker across your org. The default is the current API version, which includes the latest Locker security enhancements. Select an earlier API version when custom components only comply with Locker in an older version. When components become compliant with the current security enhancements, you can change the setting to the current API version.

After your sandbox org updates to a new Salesforce release, it’s possible that custom components conflict with Lightning Locker security enhancements. Check the web console for messages.

We recommend updating your custom components to comply with the latest Locker API version, but we know that updates can take some time. Your org could also depend on managed packages containing custom components that third-party developers must update. Set your org to use an older Locker API version to give developers time to update custom Lightning components and comply with Locker’s latest security enhancements.

Verify in a sandbox org that custom components perform correctly with the Locker API version set to the latest. Then you can change the Locker API version to the latest in your production org to take advantage of the latest security enhancements.

**note:** The Locker API version setting is first available in the Winter ’20 release. The earliest Locker API version you can select is 46.0, which enables the Locker features of the Summer ’19 release.

## Where the Locker API Version Is Used

The Locker API version for the org affects all Lightning components used in the areas listed in [What Does Lightning Locker Affect?](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-where.md).

The Locker API version for the org has no effect on Lightning web components when [Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/lws/lws-intro.md) is enabled in the org.

**note:** Every Lightning web component has a configuration file with an `apiVersion`. The component `apiVersion` and the Locker API version use the same version number strategy to align with Salesforce releases. However, the org setting for Locker API version has no relation to the component’s `apiVersion`. The Locker API version set in the org applies to all Lightning components, regardless of their `apiVersion` setting.

If an Aura component's `apiVersion` is set to 39.0, which [disables Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-disable.md), the component isn't affected by the Locker API version setting for the org. Locker is still disabled in the component.

## Locker API Version Changes

View the security changes in the API versions to help determine compatibility of your custom components.

| **Locker API Version** | **Security Changes**                                                          | **Description**                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 53.0 and later         | None                                                                          | Lightning Locker changes in this release don’t impact custom components.                                                                                                                                                                                                                                                            |
| 52.0                   | Prevent several potential mutation-based cross-site scripting (mXSS) vectors. | Lightning Locker tightened the sanitizing of markup to improve security. This change applies to all the API versions. You can’t roll back this change by selecting an earlier API version.                                                                                                                                          |
| 51.0                   | None                                                                          | Lightning Locker changes in this release don’t impact custom components.                                                                                                                                                                                                                                                            |
| 50.0                   | None                                                                          | Lightning Locker changes in this release don’t impact custom components.                                                                                                                                                                                                                                                            |
| 49.0                   | Restrict APIs used in `$A.getCallback()`                                      | Lightning Locker wraps the `$A.getCallback()` function. JavaScript that is wrapped by `$A.getCallback()` must adhere to Locker’s security restrictions. See the [Locker API Viewer](https://developer.salesforce.com/docs/component-library/tools/locker-service-viewer) for support status of JavaScript APIs in Lightning Locker. |
| 48.0                   | Sanitize HTML inserted with `execCommand`                                     | Lightning Locker sanitizes HTML that’s inserted using `document.execCommand(insertHTML)` to remove potentially malicious executable script content.                                                                                                                                                                                 |
| 47.0                   | Reject `import()` expressions                                                 | Lightning Locker doesn't allow the `import()` expression because importing third-party code is a potential security risk.                                                                                                                                                                                                           |
|                        | Restrict the `name` and `id` properties of an HTML element                    | Lightning Locker doesn't allow the `name` or `id` attribute to be set to property names that are reserved for the DOM.                                                                                                                                                                                                              |
| 46.0                   | All Locker security features                                                  | Supports all Lightning Locker features since its introduction, when it was called LockerService. This includes all features in version 37.0 (Spring '16) through version 46.0 (Summer '19) releases.                                                                                                                                |

## Change the Locker API Version for Your Org

1.  From Setup, enter `Session` in the Quick Find box, and then select **Session Settings**.
2.  In the Locker API Version section, for the **Use security enhancements in API version** field, select the API version.
3.  Click **Save**.

**See Also**

- [_Lightning Web Components Developer Guide_: Component Configuration File](/docs/platform/lwc/guide/create-components-meta-file.html)

<!-- document id=eae4c881f644343cc57fcee12b637a17614e7cbe1a124558037f7a083d8be23f url=/developer/current/en-us/lwc/lwc/guides/events/events-sending-to-aura-components.md -->

# Send Events to an Enclosing Aura Component

To communicate from child to parent, dispatch an event. Lightning web components fire DOM events. An enclosing Aura component can listen for these events, just like an enclosing Lightning web component can. The enclosing Aura component can capture the event and handle it. Optionally, the Aura component can fire an Aura event to communicate with other Aura components or with the app container.

**tip:** The [`auraEmbeddedLWC` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/aura/auraEmbeddedLWC) in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo shows how to embed a Lightning web component in a parent Aura component and communicate with events.

The following example illustrates this technique. This Lightning web component fires a custom `filterchange` event in its JavaScript file.

```javascript
// categoryFilter.js
import { LightningElement } from "lwc";

export default class CategoryFilter extends LightningElement {
  handleCheckboxChange() {
    // Get the labels of selected checkboxes
    const filters = Array.from(this.template.querySelectorAll("lightning-input"))
      .filter((element) => element.checked)
      .map((element) => element.label);
    const filterChangeEvent = new CustomEvent("filterchange", {
      detail: { filters },
    });
    // Fire the custom event
    this.dispatchEvent(filterChangeEvent);
  }
}
```

<!-- prettier-ignore -->
```html
<!-- categoryFilter.html -->
<template>
  <lightning-input
    label="Category 1"
    type="checkbox"
    onchange={handleCheckboxChange}
  ></lightning-input>
  <lightning-input
    label="Category 2"
    type="checkbox"
    onchange={handleCheckboxChange}
  ></lightning-input>
</template>
```

The enclosing Aura component wrapper adds a handler for the custom event. Notice that the event handler, `onfilterchange`, matches the event name with “on” prefixed to it. That is, use `onfilterchange` to handle the event named `filterchange`.

```xml
<!-- auraDomEventListener.cmp -->
<aura:component implements="flexipage:availableForAllPageTypes">
    <aura:attribute name="message" type="String" default="No selection"/>

    <lightning:card title="AuraDomEventListener" iconName="custom:custom30">
        <aura:set attribute="actions">
            <span class="aura">Aura Component</span>
        </aura:set>
        <div class="slds-m-around_medium">
            <lightning:layout>
                <lightning:layoutItem size="4">
                    <!-- This is an LWC component -->
                    <c:categoryFilter onfilterchange="{!c.handleFilterChange}"/>
                </lightning:layoutItem>
                <lightning:layoutItem size="8" class="slds-p-left_medium">
                    {!v.message}
                </lightning:layoutItem>
            </lightning:layout>
        </div>
    </lightning:card>
</aura:component>
```

**note:** You can only specify an `onfilterchange` handler in the first Aura component that the DOM event bubbles to.

The Aura component’s controller receives the event. You can handle the event however you’d like. This component operates on the `filters` array passed in the `details` property of the Lightning web component event. You can optionally fire a new Aura event to communicate with other Aura components.

```javascript
// auraDomEventListenerController.js
({
  handleFilterChange: function (component, event) {
    var filters = event.getParam("filters");
    component.set(
      "v.message",
      filters.length > 0 ? "Your selection: " + filters.join() : "No selection",
    );
  },
});
```

**See Also**

- [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md)

<!-- document id=bba25ada06962635d129dc57d3b41eaa16556c8619fbec0ce30007f25c5f967b url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-component-properties.md -->

# Set Component Styles and Properties in a Lightning Out 2.0 App

Tailor your Lightning Out 2.0 app to the specific branding requirements of an external app. Set Cascading Style Sheets (CSS) custom properties, including Salesforce Lightning Design System (SLDS) styling hooks, as style attributes directly in the context of the external app. You can also set or override values on other properties defined for your custom LWC component. This way, your embedded components can match the branding of any external app without changing individual component code.

## Overview

Recall that a Lightning Out 2.0 app includes Lightning Out 2.0 web components that mirror your embedded LWC components but run in the context of the host page. If you need a refresher, review [Understand Lightning Out 2.0 Architecture](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-architecture.md). This mirroring extends to most standard and custom attributes set on the Lightning Out 2.0 web component.

The `style` attribute has additional requirements. To set component styles in a Lightning Out 2.0 app, you must declare styles as [SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md) or other [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) using the `--` prefix syntax. For example, `--slds-g-sizing-border-1` and `--custom-color` are both valid styles, but `background-color` and `font-size` aren’t.

Lightning Out 2.0 supports the same syntax for style values as Lightning Web Components, including values defined in imported CSS modules, SLDS styling hooks with fallback values, and hard-coded values.

Lightning Out 2.0 supports both [SLDS 1](https://v1.lightningdesignsystem.com/platforms/lightning/styling-hooks/#site-main-content) and [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks) styling hooks. However, the styling hooks must be compatible with your org themes and the custom LWC components that you embed. Always manually verify that your embedded LWC components have the desired look and feel.

Other supported standard attributes include:

- `autocapitalize`
- `autocorrect`
- `dir`
- `enterkeyhint`
- `inputmode`
- `lang`
- `spellcheck`
- `title`
- `translate`

Additionally, these standard aria attributes are supported.

- `aria-disabled`
- `aria-hidden`
- `aria-label`
- `aria-live`
- `aria-modal`
- `aria-pressed`
- `aria-valuemax`
- `aria-valuemin`
- `aria-valuenow`

All custom attributes are supported unless the attribute name starts with an underscore (`_`).

Passing an unsupported attribute doesn’t trigger compilation or run-time errors, but that attribute’s value isn’t set on the LWC component.

## Define Component Styles and Properties

To set component styles in a Lightning Out 2.0 app, make sure that a CSS stylesheet is defined for each of the embedded components. See [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css.md). Always declare styles as [SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-custom-properties.md) or other [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) using the `--` syntax.

**tip:** To share CSS rules among the components, you can use a [common CSS module](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-share.md).

For example, here’s a CSS module file that declares style rules as CSS custom properties. Notice that it references an [SLDS 2 global styling hook](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks/b/768d36) with a hard-coded fallback value.

```css
/* cssLibrary.css */
:host {
  --primary-color: rgb(242, 228, 242);
  --secondary-color: var(--slds-g-color-brand-base-30, #022ac0);
  --text-color: black;
}
```

The CSS file of the Lightning web component `c-my-embedded-component` imports the CSS module. The [SLDS 1 card component styling hooks](https://v1.lightningdesignsystem.com/components/cards/#Styling-Hooks-Overview) reference the properties defined in the CSS module.

```css
/* myEmbeddedComponent.css */
@import "c/cssStyles";

:host {
  /* Card styling hooks */
  --slds-c-card-color-background: var(--primary-color);
  --slds-c-card-text-color: var(--text-color);
  --slds-c-card-color-border: var(--secondary-color);
}
```

Here’s the HTML file for `c-my-embedded-component`, which is a custom wrapper for the standard `lightning-card` component.

```html
<!--myEmbeddedComponent.html -->
<template>
  <lightning-card>
    <h1>This is the body</h1>
  </lightning-card>
</template>
```

Here’s the JavaScript for `c-my-embedded-component`. The `@api` decorator is imported from `lwc`, so that the `cardBody` field is exposed as a public property. This custom property allows you to set the body text of the card from a parent component or the external host page.

```js
// myEmbeddedComponent.js
import { LightningElement, api } from "lwc";

export default class MyEmbeddedComponent extends LightningElement {
  @api cardBody = "Default card body.";
}
```

Here’s how `c-my-embedded-component` renders in an org that uses the Cosmos theme.

![c-my-embedded-component in Salesforce](https://developer.salesforce.com/media/lightning_out_style_salesforce.png '{"class": "image-sm"}')

After you set up the LWC components and their properties, if you haven’t already, [create your Lightning Out 2.0 app](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5). To the app, add the components that you want to embed into an external host page and save your changes.

## Set Component Properties in the Lightning Out 2.0 App Manager

You can set component styles and other properties in the [Lightning Out 2.0 App Manager](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5).

1. From the Lightning Out 2.0 App Manager in Setup, select **Edit App** from the actions dropdown next to the Lightning Out 2.0 app name. The Edit Lightning Out 2.0 App page opens.
2. Open the App Components tab.
3. Click ![Edit icon](https://developer.salesforce.com/media/edit_60.png '{"class": "image-icon-sm"}') in the Custom Properties cell for the custom component that you want to add properties to. Enter the properties and their values in JSON format. For example, to override values for `c-my-embedded-component`, enter `{"style": "--slds-c-card-color-background: var(--secondary-color); --slds-c-card-text-color: var(--slds-g-color-palette-cloud-blue-90, #CFE9FE) ; --slds-c-card-color-border:#8E030F;", "card-body": "Not the default card body."}`.
4. Save your changes.

Here’s how `c-my-embedded-component` renders on a host page with the custom property overrides specified.

![c-my-embedded-component on a host page with custom property overrides](https://developer.salesforce.com/media/lightning_out_style_host.png '{"class": "image-md"}')

## Set Component Properties Declaratively

Alternatively, directly edit the Lightning Out 2.0 app markup for that component on the host page. In the Lightning Out 2.0 web component for the embedded component, set a supported attribute with the override value.

For example, here’s the edited code for a Lightning Out 2.0 app that was generated with the Lightning Out 2.0 App Manager. `c-my-embedded-component` is referenced in the markup as `<c-my-embedded-component>`. All three properties declared in the CSS file of `c-my-embedded-component` are overwritten with new values. The `card-body` custom attribute is also set to `Not the default card body.`

```html
<script
  type="text/javascript"
  async=""
  src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
></script>
<lightning-out-application
  frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
  app-id="18_DIGIT_SALESFORCE_ID"
  components="c-my-embedded-component"
></lightning-out-application>
<c-my-embedded-component
  style="--slds-c-card-color-background: var(--secondary-color);
        --slds-c-card-text-color: var(--slds-g-color-palette-cloud-blue-90, #CFE9FE);
        --slds-c-card-color-border:#8E030F;"
  card-body="Not the default card body."
></c-my-embedded-component>
```

**note:** In true implementations, the `frontdoor-url` attribute value on the `lightning-out-application` isn’t set until run time. See [Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_auth.htm&type=5) in _Salesforce Help_.

## Set Component Properties Programmatically

Alternatively, programmatically generate the Lightning Out 2.0 app markup by using [Document Object Model (DOM) interface methods](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model).

For example, here’s the JavaScript that generates the equivalent markup as the example in the [Set Component Properties Declaratively](#set-component-properties-declaratively) section.

```js
const loScript = document.createElement("script");
loScript.src =
  "https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js";
loScript.async = true;
loScript.type = "text/javascript";
document.body.appendChild(loScript);

const loApp = document.createElement("lightning-out-application");
loApp.setAttribute(
  "frontdoor-url",
  "https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?...",
);
loApp.setAttribute("app-id", "18_DIGIT_SALESFORCE_ID");
loApp.setAttribute("components", "c-my-embedded-component");
document.body.appendChild(loApp);

const loComp = document.createElement("c-my-embedded-component");
loComp.setAttribute(
  "style",
  "--slds-c-card-color-background: var(--secondary-color); --slds-c-card-text-color: var(--slds-g-color-palette-cloud-blue-90, #CFE9FE); --slds-c-card-color-border: #8E030F;",
);
loComp.setAttribute("card-body", "Not the default card body.");
document.body.appendChild(loComp);
```

## Current Style Limitations

Lightning Out 2.0 currently supports only CSS custom properties and SLDS styling hooks as style overrides. Other CSS properties aren’t passed from the host page into the iframe of the component, even if the component’s CSS file declares those properties.

For example, here’s the CSS file of a component.

```css
/* exampleComponent.css */

:host {
  --custom-magenta-color: #b50be3;
}

h1 {
  color: var(--custom-magenta-color);
  font-family: courier;
  font-size: 120%;
}
```

Here’s an attempt to override the embedded component’s styles on a host page.

```html
<script
  type="text/javascript"
  async=""
  src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
></script>
<lightning-out-application
  frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
  app-id="18_DIGIT_SALESFORCE_ID"
  components="c-example-component"
></lightning-out-application>
<c-example-component
  style="--custom-magenta-color: #8c23a8; font-family: cursive; font-size: var(--slds-g-font-scale-3);"
></c-example-component>
```

The CSS custom property `--custom-magenta-color` is successfully passed to the component inside the iframe. The `color` property of the component’s `h1` element references `--custom-magenta-color`. Therefore, when the component renders on the host page, the component’s `h1` text is colored`#8c23a8` instead of`#b50be3`.

However, the `font-family` and the `font-size` properties aren’t overridden because they aren’t CSS custom properties. When the component renders on the host page, the `font-family` of the`h1` element is still `courier`, and its `font-size` is still `120%`.

## Limitations on Other Component Properties

Here are other attributes and properties that you can’t pass from the host page to an embedded LWC component.

Blocked standard attributes:

- `accesskey`
- `autofocus`
- `draggable`
- `exportparts`
- `hidden`
- `inert`
- `nonce`
- `part`
- `slot`
- `tabindex`

Blocked aria attributes:

- `aria-activedescendant`
- `aria-controls`
- `aria-describedby`
- `aria-details`
- `aria-errormessage`
- `aria-flowto`
- `aria-labelledby`
- `aria-owns`

**See Also**

- [Style a Component](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-intro.md)
- [_Salesforce Help_: Build a Lightning Out 2.0 App](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5)

<!-- document id=ae7907e7cdf0f1ea5997f82665bc6e28403e46c0f2423728a4d7c620869d96bd url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-embed-input-variables-example.md -->

# Set Flow Input Variables

When you embed a flow in a custom `lightning-flow` component, give the flow more context by initializing its variables. To create a flow in your component, set the `lightning-flow` component’s `flow-api-name` attribute to the API name of the flow that you want to use.

To use this component, build a flow with the Salesforce Flow Builder first. The component includes the navigation buttons Back, Next, Pause, and Finish.

**note:** If your flow has custom Lightning web components or Aura components, then you can’t use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

## Create Input Variables for the Flow

In the component's Javascript file, create a list of maps and pass that list to the `flow-input-variables` attribute.

**note:** You can only set variables at the beginning of an interview, and the variables you set must allow input access. If you reference a variable that doesn’t allow input access, attempts to set the variable are ignored.

For each variable that you set, provide the variable's name, type, and value. For type, use the API name for the flow data type. For example, for a record variable use **SObject**, for a text variable use String.

```javascript
{
  name : "varName",
  type : "flowDataType",
  value : valueToSet
},
{
  name : "varName",
  type : "flowDataType",
  value : [ value1, value2 ]
}, ...
```

This method in the JavaScript file returns an array of values for a number variable, a date collection variable, and a couple of record variables. The Record data type in Flow Builder corresponds to **SObject** here.

```javascript
// myComponent.js
get inputVariables() {
  return [
    { name: 'numVar', type: 'Number', value: 30 },
    { name: 'dateColl', type: 'String', value: [ '2016-10-27', '2017-08-01' ] },
    // Sets values for fields in the account record (sObject) variable.
    // Id uses the value of the accountId property. Rating uses a string.
    { name: 'account', type: 'SObject', value: {
      'Id': this.accountId,
      'Rating': 'Warm'
    }},
    // Set the contact record (sObject) variable to the value of the contact property.
    // We're assuming the property contains the entire sObject for a contact record.
    { name: 'contact', type: 'SObject', value: this.contact }
  ]
}
```

## Example: Pass Account Data to the Flow

This example component gets an account via an Apex controller. The Apex controller passes the data to the flow's record variable through a wire in the JavaScript file.

<!-- prettier-ignore -->
```html
<!-- myComponent.html -->
<template>
  <lightning-flow flow-api-name="myFlow" flow-input-variables={inputVariables}> </lightning-flow>
</template>
```

```apex
// AccountController.apex
public with sharing class AccountController {
    @AuraEnabled(cacheable=true)
    public static Account getAccount() {
        return [SELECT Id, Name, LastModifiedDate, FROM Account LIMIT 1];
    }
}
```

```javascript
// myComponent.js
import { LightningElement, track, wire } from "lwc";
import getAccount from "@salesforce/apex/AccountController.getAccount";

export default class MyComponent extends LightningElement {
  @track
  inputVariables = [];

  @wire(getAccount)
  getAccountFromApex({ error, data }) {
    if (error) {
      console.log("Failed to get account data.");
    } else if (data) {
      this.inputVariables = [
        {
          name: "account",
          type: "SObject",
          value: data,
        },
      ];
    }
  }
}
```

<!-- document id=e5b63b16e89f9273f449d9cb88656350da915cd562b8d37411795a2a02266c96 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-data-binding.md -->

# Set Properties on Child Components

To communicate down the containment hierarchy, an owner can set a property on a child component. An attribute in HTML turns into a property assignment in JavaScript.

A parent component can set a primitive value like a string or number on a child component. However, non-primitive value like an object or array passed to a component is read-only and you must make a shallow copy to modify any of the nested values.

## Set a Primitive Value on a Child Component

Let’s look at how the owner, `c-todo-app`, sets public properties on the two instances of `c-todo-item`.

Look at `todoItem.js`. The `@api` decorator exposes the `itemName` field as a public property.

```javascript
// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  @api itemName;
}
```

To set the public `itemName` property, `todoApp.html` sets the `item-name` attribute on each `c-todo-item` component.

```html
<!-- todoApp.html -->
<template>
  <c-todo-item item-name="Milk"></c-todo-item>
  <c-todo-item item-name="Bread"></c-todo-item>
</template>
```

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`.

**tip:** This example uses static values of `Milk` and `Bread`, but a real-world component would typically use a `for:each` iteration over a collection computed in the owner’s JavaScript file, `todoApp.js`.

For a more advanced example, see the composition basics recipe in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/compositionBasics).

You can also play with similar code in a playground at [lwc.dev](https://lwc.dev/guide/composition#set-a-property-on-a-child-component), which is the Lightning Web Components: Open Source developer site.

## Set a Non-Primitive Value on a Child Component

A non-primitive value like an object or array that's passed to a component is read-only. To mutate the data, make a [shallow copy](https://developer.mozilla.org/en-US/docs/Glossary/Shallow_copy) of the objects you want to mutate.

Let's take a look at a parent component that passes an object to a child component and then let the child component update its value.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <div>Parent: {serializedObj}</div>
  <c-child obj={obj}></c-child>
</template>
```

Set the value in the JavaScript.

```javascript
// parent.js
import { LightningElement } from "lwc";

export default class Parent extends LightningElement {
  obj = {
    msg: "hello",
  };

  get serializedObj() {
    return JSON.stringify(this.obj);
  }
}
```

The reactive object `obj` is passed from the parent component to the child component. The child component displays the serialized object string with two buttons that update the object value either by updating the original object or a shallow copy of it.

<!-- prettier-ignore -->
```html
<!-- child.html -->
<template>
  <div>Child: {serializedObj}</div>

  <lightning-button label="Update original" onclick={updateOriginal}></lightning-button>
  <lightning-button label="Update shallow" onclick={updateShallow}></lightning-button>
</template>
```

The component cannot change the content of the object or array. When you try to update the original object value, an error `Uncaught Error: Invalid mutation: Cannot set "msg" on "[object Object]". "[object Object]" is read-only.` is thrown since the child component is attempting to mutate a property on the object.

**note:** This mutation error requires Lightning Web Security (LWS) and development mode. If you don't see the error, verify that LWS is enabled and debug mode is active. The Update Shallow button creates a new object reference. This triggers reactivity in the child component but doesn't propagate to the parent.

```javascript
// child.js
import { LightningElement, api } from "lwc";

export default class Child extends LightningElement {
  @api obj;

  get serializedObj() {
    return JSON.stringify(this.obj);
  }

  updateOriginal() {
    this.obj.msg += "!!!"; // throws an invalid mutation error
  }

  updateShallow() {
    this.obj = { ...this.obj, msg: this.obj.msg + "!" };
  }
}
```

Non-primitive values with references from a parent component, as shown by `this.obj`, are wrapped in a proxy and can't be modified. However, you can modify its content by creating a shallow copy of the non-primitive.

While `this.obj.msg` throws an invalid mutation error, the `this.obj` value assignment in `updateShallow()` updates the `{serializedObj}` value on the child component only. The `{serializedObj}` value on the parent component isn't updated.

**See Also**

- [_Security for Lightning Components_: Avoid Mutating Objects](/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.html)
- [Compose Components Using Slots Vs Data](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-best-composition.md)
- [Data Binding Behavior Differences With Aura](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-data-binding.md)
- [Reactivity for Fields, Objects, and Arrays](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity-fields.md)

<!-- document id=1ab75cb5510ec9dfeef3e00736ff796a6c7e605f2e7e22a0ab4ab9556fe1a417 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-editor-linter-org.md -->

# Set Up an Editor, Linter, and Org

Whatever your development workflow, you have to set up your code editor, set up linting, and configure an org to see your component in action.

## Install a Code Editor

To develop Lightning web components, use your favorite code editor.

We recommend using Visual Studio Code because its Salesforce Extension Pack provides powerful features for working with the Salesforce CLI, the Lightning Component framework, Apex, and Visualforce.

If you choose to work with Visual Studio Code, install it with the Salesforce Extension Pack.

- [Visual Studio Code](https://code.visualstudio.com/) (VS Code)
- [Salesforce Extension Pack](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode) for Visual Studio Code

The Salesforce Extension Pack installs helpful extensions for LWC development, including those for Apex code completion and SLDS validation. We also recommend using Prettier for code formatting. VS Code can install Prettier as an extension. For other editors, see the [Prettier documentation](https://prettier.io/).

**note:** You can’t develop Lightning web components in the Salesforce Developer Console.

## Set Up Linting

Linting finds errors in your code while you’re editing, before you compile. Linting is more than spell-checking, it steers you away from anti-patterns and towards good patterns. Salesforce has created ESLint rules to minimize Lightning Web Components programming mistakes.

**important:** We recommend migrating your projects to ESLint v9 as soon as possible. Starting in Spring '26, all new ESLint rules and bug fixes will only support ESLint v9.

To make your projects compatible with ESLint v9, follow the instructions in [Salesforce Developers: Lightning Web Components Now Supports ESLint v9](https://developer.salesforce.com/blogs/2025/05/lightning-web-components-now-supports-eslint-v9). For information about breaking changes for ESLint v9, see [ESLint: Migrate to v9.x](https://eslint.org/docs/latest/use/migrate-to-9.0.0).

If you’re using a Salesforce DX project, you don’t have to set up linting manually. See [Develop in Scratch Orgs](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx-scratch-org.md) and [Develop in Non-Scratch Orgs](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx-deploy.md).

If you aren’t using a Salesforce DX project, install the ESLint rules from the command line. See the [github/salesforce/eslint-plugin-lwc](https://github.com/salesforce/eslint-plugin-lwc) and [github/salesforce/eslint-config-lwc](https://github.com/salesforce/eslint-config-lwc) repositories for instructions.

**tip:** There are three configuration levels for linting rules. Check out the [eslint-config-lwc](https://github.com/salesforce/eslint-config-lwc) README and choose the configuration that matches your coding needs.

If you are developing components to run in Lightning Web Security, see [Install ESLint Rules for Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-tools-lint.html).

## Set Up a Development Org

Sign up for a Developer Edition org.

- [Developer Edition Sign-Up Form](https://developer.salesforce.com/signup)

You can develop Lightning web components in scratch orgs and non-scratch orgs. To create scratch orgs, configure an org as a Dev Hub. Local development requires a scratch org.

The Salesforce CLI works a bit differently with scratch orgs than it does with non-scratch orgs. We create a project and go over the workflows in [Develop with Salesforce DX Tools](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx.md).

**note:** Beginning in Winter ’23, Lightning Web Security (LWS) is enabled by default in scratch orgs. For more information, see [Enable and Disable LWS in Scratch Orgs](/docs/platform/lightning-components-security/guide/lws-enable-scratch-orgs.html).

## Enable Debug Mode in Your Development Org

To make it easier to debug JavaScript code, enable debug mode in your org. When you enable debug mode, framework JavaScript code isn’t minified, so it’s easier to read and debug. Debug mode also adds more detailed output for some warnings and errors.

Only enable debug mode for users who are actively developing or debugging JavaScript. Salesforce is slower for users who have it enabled.

1.  In Salesforce, from Setup, enter `Debug Mode` in the Quick Find box, then select **Debug Mode**.
2.  In the user list, locate any users who need debug mode enabled. If necessary, use the standard list view controls to filter your org’s users.
3.  Enable the selection checkbox next to users for whom you want to enable debug mode.
4.  Click **Enable**.

**See Also**

- [HTML Template Errors](https://developer.salesforce.com/docs/platform/lwc/reference/reference-template-errors.md)
- [Debug Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/debug/debug-intro.md)

<!-- document id=188ad8cfecbda6f8699f09edde4200db8a1b238b5c34e28878948052c34029ce url=/developer/current/en-us/lwc/slds_linter/guides/get-started/get-started-setup-linter.md -->

# Set Up SLDS Linter

To get started with SLDS Linter, follow these steps.

## Complete these prerequisites:

- Install [Visual Studio (VS) Code](https://code.visualstudio.com/).
- Install the [SARIF Viewer](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) VS Code extension.  
  With this extension you can view reports containing the issues identified by SLDS Linter.
- Install [Node.js](https://nodejs.org/).  
  The minimum supported version is v18.4.0. We recommend using the latest [Active Long Term Support](https://nodejs.org/en/about/previous-releases) (LTS) version of Node.js.

## Install SLDS Linter

1. Open your project in VS Code.
2. Open Terminal in VS Code.
3. Run any SLDS Linter command.

   ```
   npx @salesforce-ux/slds-linter@latest lint
   ```

4. If SLDS Linter isn’t installed, you’re asked to install the SLDS Linter package. Type `y`.

   The SLDS Linter package installs in a temporary location on your system.

   For more information about SLDS Linter commands, run this command.

   ```
   npx @salesforce-ux/slds-linter@latest --help
   ```

## See Also

[SLDS Linter Commands](https://developer.salesforce.com/docs/platform/slds-linter/reference/reference-commands.md)

<!-- document id=1abd7de0ee5984fd977b884c21e7e7b70be593dd65a3c99333bd467ebdc449c6 url=/developer/current/en-us/lwc/slds-validator/guides/set-up.md -->

# Set Up SLDS Validator

To get started with SLDS Validator, follow these steps.

## Complete These Prerequisites

- Install [Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm).
- Create a [Salesforce DX project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_workspace_setup.htm).  
  To turn on all SLDS Validator features, open your Salesforce DX project in a directory that contains an `sfdx-project.json` file. If you don’t have a Salesforce DX project for development, create one in a scratch org with the **SFDX: Create Project** command. For development in a sandbox or DE org, use the **SFDX: Create Project with Manifest** command.
- Install the Java Standard Edition Development Kit (JDK).

  Some features in Salesforce Extensions for VS Code depend upon the JDK. You must have either version 11, 17, 21, or the latest version of the JDK installed. To install the latest version, visit [Java Downloads](https://www.oracle.com/ae/java/technologies/downloads/).

**note:** If you also use other versions of the Java JDK, set your VS Code user setting for `salesforcedx-vscode-apex.java.home` to point to the location where you installed the appropriate Java version for SLDS Validator.

- Install [VS Code](https://code.visualstudio.com/download) v1.90.0 and later.
- To view SLDS Validator reports, install a Static Analysis Results Interchange Format (SARIF) Viewer VS Code extension, like [this one](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer).

## Install SLDS Validator

To install SLDS Validator, install the [Salesforce Extension Pack](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode).

<!-- document id=4e3659859a85e380ee065f2c01b11830c166928e51e9d851e2bb472251797f65 url=/developer/current/en-us/lwc/lwc/guides/install/install-setup-develop.md -->

# Set Up Your Development Environment

Develop Lightning web components with a workflow that fits your needs. We recommend Salesforce DX tools, but you might be in a situation where those tools are not supported. You can still use your favorite code editor and deploy to an org using your own tools. However, you can’t develop Lightning web components in the Developer Console.

**See Also**

- [Project: Set Up Your Lightning Web Components Developer Tools](https://trailhead.salesforce.com/content/learn/projects/set-up-your-lightning-web-components-developer-tools)
- [Quick Start: Lightning Web Components](https://trailhead.salesforce.com/content/learn/projects/quick-start-lightning-web-components/)

<!-- document id=f03928d3323217aad132d78149d5a70a9e49faa5b5945769e1cd3d53a4619c96 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-screen-reactivity.md -->

# Set Up Your Screen Flow Components for Reactivity

Screen flow reactivity means making your screen flow component changes affect another same-screen component.

Before adding and configuring a custom Lightning web component in the Flow builder, create your custom LWCs.

If you plan on building reactive screen components or using supported components, you'll need to understand the considerations for each. Reactivity involves:

- Identifying which screen component is the source and which component is reactive.
- Understanding the different interactions for each set of components.

<!-- document id=6f988db6374480e1e94767fd1058ddc582f366a26cc354079a3f20ad89bd1970 url=/developer/current/en-us/lwc/lwc/guides/create/create-dom.md -->

# Shadow DOM

Shadow DOM is a standard that encapsulates the internal document object model (DOM) structure of a web component. Encapsulating the DOM gives developers the ability to share a component and protect the component from being manipulated by arbitrary HTML, CSS, and JavaScript. The internal DOM structure is called the shadow tree. The shadow tree affects how you work with CSS, events, and the DOM.

Since not all browsers support Shadow DOM, LWC uses a [synthetic shadow](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom-synthetic.md) polyfill for Lightning Experience and Experience Cloud. A polyfill is code that allows a feature to work in a web browser.

::video{src="https://youtube.com/embed/K5i9zMzVlzM" title="Explaining the Shadow DOM" type="youtube" }

**note:** If you use LWC outside of Lightning Experience or Experience Cloud, such as in Lightning Out (beta), LWC renders in native shadow. See [Compile-time Differences on the Salesforce Platform](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md).

## Shadow Tree

To understand the [shadow tree](https://dom.spec.whatwg.org/#shadow-trees), let’s look at some markup. This markup contains two Lightning web components: `c-todo-app` and `c-todo-item`. The `#shadow-root` [document fragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) defines the boundary between the DOM and the shadow tree. Elements below the shadow root are in the shadow tree.

```html
<c-todo-app>
  #shadow-root
  <div>
    <p>Your To Do List</p>
  </div>
  <c-todo-item>
    #shadow-root
    <div>
      <p>Go to the store</p>
    </div>
  </c-todo-item>
</c-todo-app>
```

Let’s look at how to work with the shadow tree in each of these areas.

- CSS

  - : CSS styles defined in a parent component don’t leak into a child. In our example, a `p` style defined in the `todoApp.css` stylesheet doesn’t style the `p` element in the `c-todo-item` component, because the styles don’t reach into the shadow tree. See [CSS](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-intro.md).

- Events

  - : To prevent exposing a component’s internal details, if an event bubbles up and crosses the shadow boundary, some property values change to match the scope of the listener. See [Event Retargeting](https://developer.salesforce.com/docs/platform/lwc/events/events-handling.md#event-retargeting).

- Access Elements

  - : Elements in a shadow tree aren’t accessible via traditional DOM querying methods. Code can’t use `document` or `document.body` to access the shadow tree of a Lightning web component. For example, code can’t call `document.querySelector()` to select nodes in a Lightning web component’s shadow tree. To access its own shadow tree, a Lightning web component calls `this.template.querySelector()`. See [Access Elements the Component Owns](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md).

- Access Slots

  - : A slot is a placeholder for markup that a parent component passes into a component’s body. DOM elements that are passed to a component via slots aren’t owned by the component and aren’t in the component’s shadow tree. To access DOM elements passed via slots, call `this.querySelector()`. The component doesn't own these elements, so you don’t use `template`. See [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots.md).

- Test Components

  - : See [DOM Inspection Tests Are Subject to Change](https://developer.salesforce.com/docs/platform/lwc/testing/testing-dom-api.md).

**tip:** Watch Salesforce Developer Evangelist Alba Rivas [explain the Shadow DOM](https://www.youtube.com/watch?v=K5i9zMzVlzM&list=PLgIMQe2PKPSJdFGHjGpjd1FbCsOqq5H8t&index=5).

## DOM APIs

Don’t use these DOM APIs to reach into a component’s shadow tree in orgs that use Lightning Locker. If you’re using a third-party JavaScript library that uses these DOM APIs to reach into a component’s shadow tree, work with the library author to file and fix issues.

- `Document.prototype.getElementById`
- `Document.prototype.querySelector`
- `Document.prototype.querySelectorAll`
- `Document.prototype.getElementsByClassName`
- `Document.prototype.getElementsByTagName`
- `Document.prototype.getElementsByTagNameNS`
- `Document.prototype.getElementsByName`
- `document.body.querySelector`
- `document.body.querySelectorAll`
- `document.body.getElementsByClassName`
- `document.body.getElementsByTagName`
- `document.body.getElementsByTagNameNS`

Lightning Locker prevents you from breaking shadow DOM encapsulation between Lightning web components by blocking these APIs. However, in Aura components version 39.0 and earlier, Lightning Locker is disabled at the component level, so an Aura component could have code that fails.

These APIs aren’t restricted by [Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html). LWS prevents you from breaking shadow DOM encapsulation by enforcing a value of `closed` on the ShadowRoot's `mode` property for all components.

**important:** The Shadow DOM polyfill includes a patch to the `MutationObserver` interface. If you use `MutationObserver` to watch changes in a DOM tree, disconnect it or you will create a memory leak. Note that a component can observe mutations only in its own template. It can't observe mutations within the shadow tree of other custom elements.

## Convert Components from Synthetic to Native Shadow DOM

To easily convert components from synthetic DOM to native shadow DOM, use the lwc-codemod tool. The tool adds the `static shadowSupportMode` property to a synthetic DOM component.

For more information, see the [lwc-codemod documentation](https://github.com/salesforce/lwc-codemod).

<!-- document id=8e043a77b236e0a66d63d2adfe756616d2f671c8914cb2421d89a6663909fd16 url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-example-fromcontext.md -->

# Share a State Manager Across Components

To share a state manager instance across components, all _consumer_ components must be children of a parent _provider_ component that creates or acquires a reference to the shared state manager. In consumer components, use the `fromContext` function to retrieve a reference to the shared state manager.

## State Manager Context

A state manager instance is available to the component that creates it, and to all descendant components. Only the outer, enclosing component needs to create the state manager instance. Descendant consumer components must import the state manager definition, but instead of creating a state manager, they retrieve a reference to an existing state manager instance from their component context.

Consumers retrieve the closest state manager instance of the requested type, starting with themselves, and working upwards in their component hierarchy.

## Shared State Manager Considerations

State manager instances are resolved when a component, whether provider or consumer, is connected to the DOM.

That is, the provider component:

- Must have a reference to the state manager instance in one of its properties when it's connected to the DOM.
- Must not change that reference after it's connected (the behavior is undefined if it does).

And the consumer component:

- Does not receive a reference to the state manager instance until it's connected to the DOM.
- Must not try to reference the state manager instance's value before the component is connected to the DOM. For example, in its constructor or any code that might be called from its constructor.

**tip:** Diving a little deeper, all of the state manager context "magic" happens when the component is connected to the DOM. In the diagram in [Lifecycle Hooks](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md), for the provider component, resolving the state manager context happens in the "Parent inserted into DOM" box. For the consumer component, resolution happens in the "Child inserted into DOM" box.

This constraint means that the provider must set the state manager property during construction or initial property processing, and the consumer won't have its reference to the state manager until its `connectedCallback` runs.

## Shared State Manager Example

This example is visually identical to the all-in-one example component from [Implement a State Manager](https://developer.salesforce.com/docs/platform/lwc/guide/state-management-define-implementation.md), but each UI element is defined in a separate component. The state of the counter is maintained in the `smCounter` state manager, and shared across all components.

### smCounter State Manager API Module

**tip:** It's a best practice to define your state manager in a separate [API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md). That makes it easy to import the state manager into any component that uses it.

The state manager component has no user interface, and no `.html` template file.

```javascript
import { defineState } from '@lwc/state';

const counterManager = defineState(
    ({ atom, computed, setAtom }, initialValue = 0) => {

        // Create reactive value
        const count = atom(initialValue);

        // Create computed (and reactive) value
        const doubleCount = computed([count], (countValue) => countValue * 2);

        // Create a function that increments the count value
        const increment = () => {
            setAtom(count, count.value + 1);
        };

        // Create a function that directly sets the count atom
        const setCount = (newValue) => {
            setAtom(count, Number(newValue));
        };

        // This defines the API shape of counterManager
        return {
            count,
            doubleCount,
            increment,
            setCount,
        };
    }
);
export default counterManager;
```

### multiCounter Parent Component

The `multiCounter` component creates an instance of a shared state manager in the JavaScript file, and composes together the child components that make up the user interface in its `.html` template file.

```javascript
import { LightningElement } from 'lwc';
import counterManager from 'c/smCounter';

export default class MultiCounter extends LightningElement {
    counter = counterManager(100);
}
```

```html
<template>
    <lightning-card title="Example: Multi-Counter">
        <c-counter-display></c-counter-display>
        <c-counter-increment></c-counter-increment>
        <c-counter-set></c-counter-set>
        <c-counter-debug-state></c-counter-debug-state>
    </lightning-card>
</template>
```

### Descendant Components

The user interface for viewing and interacting with the counter state manager is made up of four components, each of which retrieves the shared `smCounter` state manager using the `fromContext` function.

The `c-counter-display` component retrieves the shared counter and displays the `count` and `doubleCount` values.

```javascript
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import counterManager from 'c/smCounter';

export default class CounterDisplay extends LightningElement {
    counter = fromContext(counterManager);
}
```

```html
<template>
    <section class="slds-p-around_small">
        <p>Count: {counter.value.count}</p>
        <p>Doubled: {counter.value.doubleCount}</p>
    </section>
</template>
```

The `c-counter-increment` component retrieves the shared counter and provides a button that calls the `increment()` action.

```javascript
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import counterManager from 'c/smCounter';

export default class CounterIncrement extends LightningElement {
    counter = fromContext(counterManager);

    increment() {
        this.counter.value.increment();
    }

}
```

```html
<template>
    <section class="slds-p-around_small">
        <lightning-button label="Increment" onclick={increment}></lightning-button>
    </section>
</template>
```

The `c-counter-set` component retrieves the shared counter, takes a numeric input, and calls `setCount()` to set the value.

```javascript
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import counterManager from 'c/smCounter';

export default class CounterSet extends LightningElement {
    counter = fromContext(counterManager);

    setCount() {
        this.counter.value.setCount(Number(this.refs.newValue.value));
    }

}
```

```html
<template>
    <section class="slds-p-around_small">
        <lightning-input type="text" label="Counter"
            value={counter.value.count} lwc:ref="newValue"></lightning-input>
        <lightning-button label="Set Counter" onclick={setCount}></lightning-button>
    </section>
</template>
```

The `c-counter-debug-state` component retrieves the shared counter and renders the entire state as formatted JSON for debugging.

```javascript
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import counterManager from 'c/smCounter';

export default class CounterDebugState extends LightningElement {
    counter = fromContext(counterManager);
    get stateDump() {
        return JSON.stringify(this.counter.value, null, 2);
    }

}
```

```html
<template>
    <hr/>
    <section class="slds-p-around_small">
        <textarea rows="10" cols="40">{stateDump}</textarea>
    </section>
    <hr/>
</template>
```

<!-- document id=3720390eb8636721ac4aedf279d5bd12a3e7ad735d5b9ba3cb41df423b0360f1 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-share.md -->

# Share CSS Style Rules

Create a consistent look and feel for Lightning web components using a common CSS module. Define styles in the CSS module, and import the module into the components that you want to share styles.

You can import one or more CSS modules. The imported style rules apply to the template just like non-imported style rules. Lightning Web Components (LWC) supports the [CSS cascade algorithm](https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade).

```css
/* myComponent.css */

/* Syntax */
@import "namespace/moduleName";

/* Example */
@import "c/cssLibrary";

/* Note: Lightning web components can access modules only from the c and lightning namespaces
under Lightning Locker. If Lightning Web Security is enabled, Lightning web components 
can access modules from other namespaces. */
```

For more information about `@import`, see [MDN web docs: `@import`](https://developer.mozilla.org/en-US/docs/Web/CSS/@import). MDN lists two syntax statements:`@import {url}` and `@import {url list-of-media-queries}`. LWC doesn’t honor the `{list-of-media-queries}`.

1.  Create a Lightning web component that contains a CSS file and a configuration file. The folder and filenames must be identical. This component is your CSS module.

    ```
    cssLibrary
       ├──cssLibrary.css
       └──cssLibrary.js-meta.xml
    ```

2.  Define the style rules in the CSS file.

    ```css
    /* cssLibrary.css */
    h1 {
      font-size: xx-large;
    }
    ```

3.  The configuration file requires only these tags.

    ```xml
    <!-- cssLibrary.js-meta.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
        <apiVersion>49.0</apiVersion>
        <isExposed>false</isExposed>
    </LightningComponentBundle>
    ```

4.  In the CSS file of a Lightning web component, import the CSS module.

    ```
    myComponent
       ├──myComponent.html
       ├──myComponent.js
       ├──myComponent.js-meta.xml
       └──myComponent.css
    ```

    ```css
    /* myComponent.css */
    @import "c/cssLibrary";

    /* Define other style rules for myComponent here */
    ```

5.  Imported style rules are applied to the template just like non-imported style rules. All style rules cascade. In the `myComponent.html` template, the text in the `<h1>` tag uses the `xx-large` style defined in `cssLibrary.css`.

    ```html
    <!-- myComponent.html -->

    <template>
      <h1>Words to the Wise</h1>
      <p>An apple a day keeps the doctor away.</p>
    </template>
    ```

**tip:** You can play with the code in a playground at [lwc.dev/guide/css](https://lwc.dev/guide/css#share-css-style-rules).

**See Also**

- [MDN: @import](https://developer.mozilla.org/en-US/docs/Web/CSS/@import)

<!-- document id=4f4245f1745cca3e0a608e6495e6d1ea09987e01a0e7f426e088cf8f656cf3ae url=/developer/current/en-us/lwc/lwc/guides/js/js-share-code.md -->

# Share JavaScript Code

To share code between components, create an ES6 module in an API module component and export the variables or functions that you want to share using standard JavaScript syntax. Each JavaScript file is subject to the [file size limit](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md).

An [ES6 module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) is a JavaScript file that explicitly exports variables or functions that other modules can use. Modules make it easier to structure your code.

LWC has two patterns for sharing code:

- Create JavaScript files that export code in the same folder as the component importing the code. Import the code using a relative path. Other components can’t import this file directly. This approach supports structuring code within a component rather than sharing code with other components.
- Create an API module component (library), which is a component folder that contains one or more JavaScript files that export code. To import the code, other components use `c/componentName` syntax. Components can import code only from the main JavaScript file, which has the same name as the folder name. To share code from supplemental JavaScript files in the library, export the code from those files, then re-export it from the main JavaScript file. See the **How to Access Exports in Supplemental JavaScript Files** section.

This example uses the first pattern. Only `myComponent.js` can import code from `utils.js` and `myFunction.js`.

```
lwc
  └───myComponent
    ├──myComponent.html
    ├──myComponent.js
    ├──myComponent.js-meta.xml
    ├──myFunction.js
    └──utils.js
```

To import the code, use relative paths.

```javascript
// myComponent.js
import { getAmount, calculateCost } from "./utils";
import myFunction from "./myFunction";
```

To import from the `lwc` module, see [LWC Import Declarations](https://developer.salesforce.com/docs/platform/lwc/guide/js-share-code.md).

**tip:** A JavaScript file can export named exports or a default export. To import a named export, the code uses the specific names in `{}`. To import a default export, the code can use any name. In the previous example, `utils.js` uses named exports and `myFunction.js` uses a default export.

This example is an API module component. The folder and one JavaScript file must have the same name. In this example, the name is `mortgageUtils`.

```ascii
lwc
  ├──mortgageUtils
    ├──mortgageUtils.js
    └──mortgageUtils.js-meta.xml
  └───myComponent
    ├──myComponent.html
    ├──myComponent.js
    └──myComponent.js-meta.xml

```

To import the code into other components, use `c/componentName` syntax.

```javascript
// myComponent.js
import { getTermOptions, calculateMonthlyPayment } from "c/mortgageUtils";
```

**important:** In the `import` statement, specify the folder to import from, not the file—don’t specify a file extension. Other components can import code only from the library’s main JavaScript file, which has the same name as the folder. Components can’t import from a supplemental JavaScript file with another name or from a file in a nested folder. To share code from such files, export their functions or variables, then export them again from the main JavaScript file.

## Export Default Functions and Variables

An ES6 module can export a single default function or variable.

```
lwc
  └──myComponent
    ├──myComponent.html
    ├──myComponent.js
    ├──myComponent.js-meta.xml
    └──myFunction.js
```

```javascript
// myFunction.js
export default function () { ··· }
```

This `export` syntax also works.

```javascript
// myFunction.js
export { myFunction as default, … };
```

To refer to the default export, the component that imports the function must choose a name in the `import` statement. It doesn't have to be the name of the exported function or JavaScript file, that’s just a convention.

```javascript
// myComponent.js
import myFunction from "./myFunction";
```

## Export Named Functions and Variables

An ES6 module can export multiple named functions or variables.

```javascript
// mortgage.js
const getTermOptions = () => {
  return [
    { label: "20 years", value: 20 },
    { label: "25 years", value: 25 },
  ];
};

const calculateMonthlyPayment = (principal, years, rate) => {
  // Your calculation logic here
};

export { getTermOptions, calculateMonthlyPayment };
```

The component that imports the functions uses the exported names.

```javascript
// myComponent.js
import { getTermOptions, calculateMonthlyPayment } from "c/mortgage";
```

```
lwc
  ├──mortgage
    ├──mortgage.js
    └──mortgage.js-meta.xml
  └──myComponent
    ├──myComponent.html
    ├──myComponent.js
    └──myComponent.js-meta.xml
```

**tip:** See `mortgage` and `miscSharedJavaScript` in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) sample repo.

## How the LWC Compiler Resolves Component Entry Points

An LWC module `c/moduleName` exposes only one of its `moduleName` files as the entry point. The entry point can be its [JavaScript file](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md) or its [CSS file](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-share.md). The LWC compiler resolves the module’s entry point in the following order.

1.  If `moduleName.js` exists, it’s the entry point.
2.  Otherwise, `moduleName.css` is the entry point.

If neither file is found, the compilation fails.

In this example, `utils.js` is the entry point of the `c/utils` module:

```
utils
   ├──utils.js
   └──other.js
```

Importing a function from `c/utils` resolves to `utils.js`.

```javascript
// someComponent.js
// This import is valid
import { getSomething } from "c/utils";
```

All of these imports fail:

```javascript
// someComponent.js
// These imports are invalid
import { getSomething } from "c/utils/utils.js";
import { getSomething } from "c/utils/other.js";
import { getSomething } from "c/utils/utils";
```

## How to Access Exports in Supplemental JavaScript Files

Supplemental JavaScript files use a different file name than the component or module name. To access an export from a supplemental JavaScript file, use `export from` syntax to import it and re-export it in the main JavaScript file. This syntax is a combination of `import` and `export`.

For example, let’s say you want to export code from a supplemental `moreUtils.js` file.

```
lwc
  └───utils
    ├──utils.js
    └──moreUtils.js
```

In `moreUtils.js`, export the code.

```javascript
// moreUtils.js
const someFunction = () => {
    // logic
};

const someOtherFunction = (arg1 arg2) => {
    // logic
};

export{ someFunction, someOtherFunction };
```

In `utils.js`, this statement exports the functions and makes them available to other Lightning web components. The functions aren’t available in `utils.js` unless you also import them like in the first example on this page.

```javascript
// utils.js
export { someFunction, someOtherFunction } from "./moreUtils";
```

You can also use a wildcard to export all resources from a supplemental module.

```javascript
// utils.js
export * from "./moreUtils";
```

In the component, import the functions as if they are in `utils.js`.

```javascript
// someComponent.js
import { someFunction, someOtherFunction } from "c/utils";
```

## Avoid Circular Imports

LWC doesn't support circular imports between modules. A circular import happens when module A imports from module B, and module B imports from module A. This can happen directly or through a chain of other modules. Avoid these dependency cycles in your components and shared libraries.

When a cycle exists, one of the modules loads before its dependency finishes evaluating. Imported names from that module resolve to `undefined`. Symptoms vary, but common signs include:

- `TypeError: X is not a function` when calling an imported function.
- `Cannot read properties of undefined` when accessing an imported value.
- Components that render in isolation but fail when composed with others.
- Errors that appear only after a platform upgrade changes module evaluation order.

### Identify a Circular Import

To find a cycle, trace the `import` statements between the failing module and its dependencies. Follow each imported module's own imports until you either return to the starting module or exhaust the chain. A return to the starting module confirms a cycle.

For example, this pair of modules forms a direct cycle.

```javascript
// c/alpha/alpha.js
import { useBeta } from "c/beta";
export function useAlpha() { ··· }

// c/beta/beta.js
import { useAlpha } from "c/alpha";
export function useBeta() { ··· }
```

A cycle can also span more than two modules: `c/alpha` imports from `c/beta`, `c/beta` imports from `c/gamma`, and `c/gamma` imports from `c/alpha`.

### Resolve a Circular Import

Pick one of these patterns to break the cycle.

- **Extract shared code into a third module.** Move the values that both modules need into a new library, then import them from that library in both places.
- **Merge the modules.** If two modules are tightly coupled, combine them into one.
- **Invert the dependency.** Pass the dependency as a function argument or component property instead of importing it.
- **Remove the unnecessary import.** Cycles often appear after a refactor leaves a stale import behind.

After you remove the circular import, redeploy the affected components and confirm that the original error no longer occurs.

**See Also**

- [Component JavaScript File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-javascript.md)
- [Blog: ES6 In Depth: Modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)
- [Trailhead: Modern JavaScript Development: Learn about JavaScript ES6 features and what you can do with them](https://trailhead.salesforce.com/en/content/learn/modules/modern-javascript-development?trail_id=learn-to-work-with-javascript)
- [MDN: export statement](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export)

<!-- document id=e5fa90350ee931128c9b9256a9b8607a51987e333a704112a94a7122f8c52c03 url=/developer/current/en-us/lwc/lwc/guides/interop/interop-share-javascript.md -->

# Share JavaScript Code Between LWC and Aura

To share JavaScript code between Lightning web components and Aura components, put the code in an ES6 module.

To share an ES6 module:

1.  [Create an API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md) using the Lightning Web Components programming model.
2.  To use the code in a Lightning web component, [import and reference it](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md) in the component’s JavaScript file.
3.  To use the code in an Aura component, use the same syntax that you use to import an Aura component and call its methods. For example code, see the Aura [`lightning:navigationItemAPI`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-navigation.html) component docs. Note that `lightning:navigationItemAPI` is an Aura component, not an ES6 module, but to import an ES6 module, you use the same Aura syntax.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an `lmsPublisherWebComponent` module that enables communication between Lightning web components and Aura components.

**See Also**

- [Salesforce Developers Blog: Inter-Component Communication Patterns for Lightning Web Components](https://developer.salesforce.com/blogs/2021/05/inter-component-communication-patterns-for-lightning-web-components.html)

<!-- document id=f1959bd6f20e26c6852eaeec8818b72d8243a19d1d0ab388cb4b86ffed3c11f0 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-public-apps.md -->

# Share Lightning Out (Beta) Apps with Unauthenticated Users

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

To make your Lightning Out (beta) app available to users without requiring them to authenticate with Salesforce, add the `ltng:allowGuestAccess` interface. With this interface, you can build your app with Lightning web components, and deploy it anywhere and to anyone.

**note:** If a user is authenticated with the Lightning Out (beta) endpoint, you must set the session in `$Lightning.use()`.

## Usage

You can add a Lightning Out (beta) app with the `ltng:allowGuestAccess` interface to a Visualforce page and to a page hosted outside Salesforce.

- Using Lightning Web Components for Visualforce, you can add your Lightning Out (beta) app to a Visualforce page, and then use that page in Salesforce Tabs + Visualforce sites. Then you can allow public access to that page.
- Using Lightning Out (beta), you can deploy your app anywhere Lightning Out (beta) is supported—which is almost anywhere!

The `ltng:allowGuestAccess` interface is only usable in orgs that have Digital Experiences enabled, and your Lightning Out (beta) app is associated with all site endpoints that you’ve defined in your org.

**important:** When you make a Lightning Out (beta) app accessible to guest users by adding the `ltng:allowGuestAccess` interface, it’s available through **every** Experience Cloud site in your org, whether that site is enabled for public access or not. You can’t prevent it from being accessible via site URLs, and you can’t make it available for some sites but not others.

**note:** Be careful about apps you open for guest access. Apps enabled for guest access bypass the object- and field-level security (FLS) you set for your site’s guest user profile. Components don’t automatically enforce CRUD and FLS in an Apex method when you reference or retrieve objects. The framework continues to display records and fields for which users don’t have CRUD access and FLS visibility. A mistake in code used in an app enabled for guest access can open your org’s data to the world.

## Example: Allow Guest Access to a Lightning Out (Beta) App

Add the `ltng:allowGuestAccess` interface to your Lightning Out (beta) app.

```xml
<aura:application access="GLOBAL" extends="ltng:outApp"
    implements="ltng:allowGuestAccess">

    <aura:dependency resource="c:storeLocatorMain"/>

</aura:application>
```

**note:** You can only add the `ltng:allowGuestAccess` interface to the Lightning Out (beta) app, not to individual components.

Next, add the Lightning Out (beta) JavaScript library to your page.

- With Lightning Web Components for Visualforce, simply add the `<apex:includeLightning />` tag anywhere on your page.
- With Lightning Out (beta), add a `<script>` tag that references the library directly, using a site endpoint URL.

  ```html
  <script src="https://SITE_DOMAIN/SITE_URL/lightning/lightning.out.js"></script>
  ```

  For example: `https://universalcontainers.force.com/ourstores/lightning/lightning.out.js`

Finally, add the JavaScript code to load and activate your Lightning Out (beta) app. This code is standard Lightning Out (beta), with the important addition that you must use one of your org’s site URLs for the endpoint. The endpoint URL takes the form `https://YOURSITEDOMAIN/SITEURL`, as shown by `https://universalcontainers.force.com/ourstores/` in this example.

```html
<script>
  $Lightning.use(
    "c:locatorApp", // name of the Lightning Out (beta) app
    function () {
      // Callback once framework and app loaded
      $Lightning.createComponent(
        "c:storeLocatorMain", // top-level component of your app
        {}, // attributes to set on the component when created
        "lightningLocator", // the DOM location to insert the component
        function (cmp) {
          // callback when component is created and active on the page
        },
      );
    },
    "https://universalcontainers.force.com/ourstores", // Site endpoint
  );
</script>
```

**See Also**

- [_Salesforce Help_: Create Communities](https://help.salesforce.com/articleView?id=networks_creating.htm)
- [Use Components in Visualforce Pages](https://developer.salesforce.com/docs/platform/lwc/use/use-visualforce.md)

<!-- document id=4426bcd6a80104d0b4332eaf72f5cfd565fd25884a9f6cb076f6cc828e712d51 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-mime.md -->

# Specify a MIME Type for Blob Objects in Lightning Web Security

Lightning Web Security (LWS) requires you to set the MIME type when you create Blob objects. LWS permits some MIME types, sanitizes some MIME types, and blocks the rest.

Set the MIME type explicitly when you create a Blob object.

```javascript
const blob = new Blob([result], { type: "text/plain" });
```

If you don’t set the type, the object isn’t created with the expected content.

LWS allows these MIME types, the same as Lightning Locker.

- `application/octet-stream` — Default value for binary files
- `application/json` — JSON format
- `application/pdf` — Portable Document Format (.pdf)
- `video/` — All `video/*` mime types
- `audio/` — All `audio/*` mime types
- `image/` — All `image/*` mime types
- `font/` — All `font/*` mime types
- `text/plain` — Text (.txt)
- `text/markdown` — Markdown (.md)
- `application/zip` — Zip archive (.zip)
- `application/x-bzip` — Bzip archive (.bz)
- `application/x-rar-compressed` — RAR archive (.rar)
- `application/x-tar` — Tape archive (.tar)

LWS sanitizes `text/html`, `image/svg+xml`, and `text/xml` MIME types. These types are permitted but LWS removes potentially malicious code.

Any other types are blocked with the error message `Unsupported MIME type`.

To send binary files that aren’t explicitly permitted, specify the MIME type as `application/octet-stream`.

LWS doesn’t support the specification of MIME type parameters.

<!-- document id=9f2ac6f947a4e2fc2e38304590ab8906716f050aacfa2c11a1f78a8f9b3bd0ea url=/developer/current/en-us/lwc/lwc/guides/create/create-components-spread-properties.md -->

# Spread Properties on Child Components

Pass a set of properties in an object to a child component using the `lwc:spread` directive. `lwc:spread` also enables elements to accept an object that's bound as properties at runtime.

You don't have to manually define each attribute or property in your template like this.

<!-- prettier-ignore -->
```html
<!-- Replace this with lwc:spread -->
<c-mycomponent name={config.name} country={config.country}></c-mycomponent>
```

`lwc:spread` makes it easier to work with large config or objects. You can dynamically pass multiple attributes or properties. However, it only spreads top-level properties. Nested objects won't be automatically spread.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an `apiSpread` component that demonstrates the `lwc:spread` directive.

The `lwc:spread` directive accepts one object.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <c-child lwc:spread={childProps}></c-child>
</template>
```

Use an object with key-value pairs, where the keys are property names.

```javascript
// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  childProps = { name: "James Smith", country: "USA" };
}
```

In your child component, use the properties in your template.

```html
<!-- child.html -->
<template>
  <p>Name: {name}</p>
  <p>Country : {country}</p>
</template>
```

Use the `@api` decorator to expose your properties to the parent component.

```javascript
// child.js
import { LightningElement, api } from "lwc";

export default class Child extends LightningElement {
  @api name;
  @api country;
}
```

`lwc:spread` is always applied last, so it overrides any properties that are directly declared in the template. Only one `lwc:spread` instance can be used on a directive.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <c-child name="lwc" lwc:spread={childProps}></c-child>
</template>
```

In this example, `c-child` passes `name` as `Lightning Web Components` even though the parent component is passing in `name="lwc"`. Ultimately, the child component takes the `"Lightning Web Components"` name.

```javascript
// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  childProps = { name: "Lightning Web Components" };
}
```

## Use `lwc:spread` With an Event Handler

`lwc:spread` doesn't bind the component to the event handlers defined in the template. For example, you can pass in an `onclick` handler in the object as the property name.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <c-child lwc:spread={simpleProps}></c-child>
</template>
```

Here, `c-child` passes `name` as `LWC`. When the c-child element is clicked, `spreadClick()` replaces `name` with `Lightning Web Components`.

```javascript
// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  simpleProps = { name: "LWC", onclick: this.spreadClick.bind(this) };
  spreadClick() {
    this.simpleProps = { name: "Lightning Web Components" };
  }
}
```

Although we don't include `onclick` in `spreadClick()`, the element contains `onclick` as previously assigned to it via the `simpleProps` object.

## Reflect HTML Attributes on a Child Component

Most of the HTML attributes are [reflected as properties](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-html-attributes.md). For example, `class` attribute is reflected as `className` property.

Let's say you pass properties to a child component.

<!-- prettier-ignore -->
```html
<!-- app.html -->
<template>
  <c-child lwc:spread={spanProps}></c-child>
</template>
```

As a result, the `spanProps` property causes the element to be rendered as `<c-child class="spanclass" id="mySpan"></c-child>`.

```javascript
// app.js
import { LightningElement } from "lwc";

export default class extends LightningElement {
  spanProps = { className: "spanclass", id: "myspan" };
}
```

**See Also**

- [HTML Template Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md)
- [Add Event Listeners Dynamically on Children](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-spread-dynamic.md)

<!-- document id=c8f5a4bc37d26a450e7c9d97b2b7a152fbc36106b320264be141fefc9c5ed391 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-standard-layouts.md -->

# Standard Definitions for Layouts

Specify the layout of a complex property type by using standard layout definitions. A layout is made up of one or more layout definitions.

These are the standard layout definitions.

- `lightning/verticalLayout`
- `lightning/tabSetLayout`
- `lightning/accordionLayout`

Each layout definition can contain a `lightning/propertyLayout` definition to specify where in the property sheet the property editor is expected to appear. The layout definition takes a required attribute called "property," whose value is a reference to a sub-property in the schema. The property editor that's rendered is based on the `lightning:type` that the sub-property references and whether the sub-property is overridden by the `componentOverrides`.

## lightning/verticalLayout

To arrange your property sheet in a flat list, use the `lightning/verticalLayout` definition. In this case, the properties appear in the order in which you define them in the schema. This layout can take only `lightning/propertyLayout` definitions as children.

Here's a code snippet of a layout with properties for `borderStyle`, `borderWeight`, `borderRadius`, `layoutHeight`, and `layoutWidth` arranged in vertical order.

```json
{
  "editor": {
    "layout": {
      "definition": "lightning/verticalLayout",
      "children": [
        {
          "definition": "lightning/propertyLayout",
          "attributes": {
            "property": "borderStyle"
          }
        },
        {
          "definition": "lightning/propertyLayout",
          "attributes": {
            "property": "borderWeight"
          }
        },
        {
          "definition": "lightning/propertyLayout",
          "attributes": {
            "property": "borderRadius"
          }
        },
        {
          "definition": "lightning/propertyLayout",
          "attributes": {
            "property": "layoutHeight"
          }
        },
        {
          "definition": "lightning/propertyLayout",
          "attributes": {
            "property": "layoutWidth"
          }
        }
      ]
    }
  }
}
```

Here's how the layout looks in the component property panel in Experience Builder.

![Vertical layout in component property panel](https://developer.salesforce.com/media/use-experience-cloud-vertical-layout.png)

## lightning/accordionLayout

To arrange your property sheet in accordion sections, use the `lightning/accordionLayout` definition. This layout definition can take only `lightning/accordionSectionLayout` definitions as children. The `lightning/accordionSectionLayout` definition, in turn, can use only `lightning/propertyLayout` definitions as children.

Here's an example of the properties for `borderStyle`, `borderWeight`, `borderRadius`, `layoutHeight`, and `layoutWidth` laid out in accordion sections for Borders and Size.

```json
{
  "editor": {
    "layout": {
      "definition": "lightning/accordionLayout",
      "children": [
        {
          "definition": "lightning/accordionSectionLayout",
          "attributes": {
            "label": "Borders"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderStyle"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderWeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderRadius"
              }
            }
          ]
        },
        {
          "definition": "lightning/accordionSectionLayout",
          "attributes": {
            "label": "Size"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutHeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutWidth"
              }
            }
          ]
        }
      ]
    }
  }
}
```

Here's how the accordion layout looks in the component property panel in Experience Builder.

![Accordion layout for Borders and Size in component property panel](https://developer.salesforce.com/media/use-experience-cloud-accordion-layout.png)

## lightning/tabSetLayout

To arrange your property sheet in tabs, use the `lightning/tabSetLayout` definition. This layout definition can take only `lightning/tabLayout` definitions as children. The `lightning/tabLayout` definition, in turn, can take only `lightning/propertyLayout` definitions as children.

Here's an example of the properties `borderStyle`, `borderWeight`, `borderRadius`, `layoutHeight`, and `layoutWidth` laid out on tabs for Borders and Size.

```json
{
  "editor": {
    "layout": {
      "definition": "lightning/tabSetLayout",
      "children": [
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Borders"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderStyle"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderWeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "borderRadius"
              }
            }
          ]
        },
        {
          "definition": "lightning/tabLayout",
          "attributes": {
            "label": "Size"
          },
          "children": [
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutHeight"
              }
            },
            {
              "definition": "lightning/propertyLayout",
              "attributes": {
                "property": "layoutWidth"
              }
            }
          ]
        }
      ]
    }
  }
}
```

Here's how the tabset layout looks in the component property panel in Experience Builder.

![Tabset layout for Borders and Size in component property panel](https://developer.salesforce.com/media/use-experience-cloud-tabset-layout.png)

**See Also**

- _Code samples_: [custom-property-editor-code-samples](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples)
- _Lightning Types Developer Guide_: [Object-Based Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-object.html)
- _Lightning Types Developer Guide_: [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.html)

<!-- document id=a5fb6692092cf51a830e190af5041e93bdeac63b2ca384a9e82d63d59b53c541 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-objects-lwc-record-home.md -->

# Standard Objects Support for Record Home Pages

Salesforce uses Lightning Web Components (LWC) to build record pages for most standard objects. Some standard objects still use Aura components. Record pages that use Aura components don't support some features that are available to record pages that use LWC. For example, a record page that uses Aura components doesn't currently support [LWC actions](https://help.salesforce.com/s/articleView?id=platform.lightning_web_component_actions_create.htm).

## Standard Objects With Aura Record Home Pages

The record home pages for these standard objects continue to use Aura components.

- Campaign
- OrderSummary
- Task

## Standard Objects With LWC Record Home Pages

The record home pages for these standard objects use LWC.

**note:** As of Summer ’23, all new standard objects render with LWC. It’s possible that this list doesn’t include the newest supported objects.

- AcademicCredential
- AcademicSession
- AcademicTerm
- AcademicTermEnrollment
- AcademicYear
- Account
- AccountAccountRelation
- AccountBillingAccount
- AccountContactRelation
- AccountForecast
- AccountForecastAdjustment
- AccountForecastPeriodMetric
- AccountPartner
- AccountProductForecast
- AccountProductPeriodForecast
- AccountRelationship
- AccountServicePreference
- Accreditation
- AcctMgrPeriodicTargetDstr
- AcctMgrTargetDstr
- ActionableEventOrchestration
- ActionableEventSubtype
- ActionableEventType
- ActionableList
- ActionableListAsgntDetail
- ActionableListAssignment
- ActionableListColumn
- ActionableListDefFltrCond
- ActionableListDefFltrCrit
- ActionableListDtastClmnUsr
- ActionableListFilterCondition
- ActionableListFilterCriteria
- ActionableListMbrInvitation
- ActionPlanBaseTemplateAsgn
- ActionPlanItem
- ActionPlanItemDependency
- ActionPlanTemplate
- ActionPlanTemplateAssignment
- ActionPlanTemplateItem
- ActionPlanTemplateItemValue
- ActionPlanTemplateVersion
- ActionPlanTmplItmAssessmentInd
- ActionPlnTmplItmDependency
- ActionVisibility
- ActivationTargetSecureFTP
- ActiveScratchOrg
- ActivityTiming
- AdAvailabilityDimensions
- AdAvailabilityJob
- AdAvailabilityViewConfig
- AdBuyServerAccount
- AdCreativeSizeType
- AdDemographicCode
- AdDigitalAvailability
- AddOnDefinition
- Address
- AdLinearAvailability
- AdOpportunity
- AdOrderItem
- AdOrderItemCreativeSizeType
- AdOrderItemPrintIssue
- AdOrderItemUnitsSplit
- AdOrderLineAdTarget
- AdOrderLineHiatus
- AdPageLayoutType
- AdProductDefaultTargetCategory
- AdProductTargetCategory
- AdQuote
- AdQuoteLine
- AdQuoteLineAdTarget
- AdQuoteLinearMetrics
- AdQuoteLineCreativeSizeType
- AdQuoteLineHiatus
- AdQuoteLinePrintIssue
- AdQuoteLineUnitsSplit
- AdServer
- AdServerAccount
- AdServerUser
- AdSpaceCreativeSizeType
- AdSpaceSpecification
- AdSpecMediaPrintIssue
- AdTargetCategory
- AdTargetCategorySegment
- AdUsage
- AdUsageSummary
- AdvAccountForecastFact
- AdvancedFieldMapping
- AdvancedObjectMapping
- AdverseEventAction
- AdverseEventCause
- AdverseEventContribFactor
- AdverseEventEntry
- AdverseEventOutcome
- AdverseEventParty
- AdverseEventSupportInfo
- AdverseEvntResultingEffect
- AdvTherapyFieldOptOverride
- AffinityScore
- AiDataset
- AiImageDetectedObject
- AiImageTrainingObject
- AINaturalLangProcessRslt
- AINtrlLangProcChunkRslt
- AINtrlLangProcStsEvent
- AIPredictionScore
- AirTravelEmssnFctr
- AirTravelEnrgyUse
- AiVisionModel
- AiVisionModelMetric
- AiVisionModelObjectMetric
- AiVisitSummary
- AiVisitTaskRcmd
- AllergyIntolerance
- AnnualEmssnInventory
- AnnualEmssnRdctnTarget
- AntiCorruptionInitSum
- ApiAnomalyEventStore
- AppAnalyticsQueryRequest
- AppFormProductParticipant
- Applicant
- ApplicationActionItem
- ApplicationCase
- ApplicationDecision
- ApplicationForm
- ApplicationFormEvaluation
- ApplicationFormParticipant
- ApplicationFormProduct
- ApplicationFormProductDev
- ApplicationFormProductFee
- ApplicationFormProductProposal
- ApplicationFormTemplate
- ApplicationFormVendorProduct
- ApplicationRecommendation
- ApplicationRecommender
- ApplicationRenderMethod
- ApplicationReview
- ApplicationSectionDefinition
- ApplicationStageDefinition
- ApplicationTimeline
- ApplnRenderMethodAssignment
- ApplnStageSectionDefinition
- AppointmentCategory
- AppointmentInvitation
- AppointmentInvitee
- AppointmentReason
- AppointmentTopicTimeSlot
- ApptBundleAggrDurDnscale
- ApptBundleConfig
- ApptBundlePolicy
- ApptBundlePolicySvcTerr
- ApptBundleRestrictPolicy
- ApptBundleSortPolicy
- ApptReasonEngmtChannelType
- AppUsageAssignment
- ASEOrgSyncFailure
- ASEOrgSyncHealthStats
- ASEOrgSyncHealthTxns
- ASEOrgTxnTimingCount
- AsmtQstnRespRecommendation
- Assessment
- AssessmentEnvelope
- AssessmentEnvelopeItem
- AssessmentIndDefinedValue
- AssessmentIndicatorDefinition
- AssessmentIndValue
- AssessmentQuestion
- AssessmentQuestionAssignment
- AssessmentQuestionResponse
- AssessmentQuestionSet
- AssessmentQuestionSourceDoc
- AssessmentQuestionVersion
- AssessmentSignature
- AssessmentTask
- AssessmentTaskContentDocument
- AssessmentTaskDefinition
- AssessmentTaskIndDefinition
- AssessmentTaskOrder
- Asset
- AssetAccountParticipant
- AssetAction
- AssetActionSource
- AssetAttribute
- AssetContactParticipant
- AssetContractRelationship
- AssetDowntimePeriod
- AssetFulfillmentDecomp
- AssetMilestone
- AssetRelationship
- AssetStatePeriod
- AssetStatePeriodAttribute
- AssetTitle
- AssetTitleParty
- AssignedResource
- AssistantText
- AssociatedLocation
- Assortment
- AssortmentProduct
- AsyncOperationLog
- AsyncOperationTracker
- AttributeAdjustmentCondition
- AttributeBasedAdjRule
- AttributeBasedAdjustment
- AttributeCategory
- AttributeCategoryAttribute
- AttributePicklist
- AttributePicklistValue
- AuditTrailFileExport
- AuthApplicationAsset
- AuthApplicationPlace
- AuthFormRequestRecord
- AuthLocationAccessSchedule
- AuthorizationForm
- AuthorizationFormConsent
- AuthorizationFormDataUse
- AuthorizationFormText
- AuthorizedInsuranceLine
- AuthorNote
- AutomatedActionOverride
- AutomatedActionReminder
- Award
- BackgroundOperation
- BackgroundOpOutcomeEvent
- BackgroundOpStatusEvent
- BalanceAdjustmentRequest
- Banker
- BatchJobPartFailedRecord
- BCEntityPermission
- BCEntityPermissionSet
- BCFieldPermission
- BCParticipant
- BCParticipantAccess
- BCPermissionSet
- BCRecordAccess
- BCRecordAccessApproval
- BCRelatedParticipant
- Benefit
- BenefitAsgntProviderLoc
- BenefitAssignment
- BenefitAssignmentAdjustment
- BenefitDisbursement
- BenefitDisbursementAdj
- BenefitItemCode
- BenefitParameterValue
- BenefitPrvdSearchableFld
- BenefitSchedule
- BenefitScheduleAssignment
- BenefitSession
- BenefitSpecialty
- BillingAccount
- BillingAccountContact
- BillingBatchScheduler
- BillingPaymentMethod
- BillingPeriodItem
- BillingPolicy
- BillingSchedule
- BillingScheduleCreationStatus
- BillingScheduleGroup
- BillingScheduleRelationship
- BillingTreatment
- BillingTreatmentItem
- BldgEnrgyIntensity
- BldgEnrgyIntensityVal
- BldgSizeCategory
- BlockchainApplication
- BlockchainAppMember
- BlockchainEntity
- BlockchainField
- BlockchainMember
- BoardCertification
- BranchUnit
- BranchUnitBusinessMember
- BranchUnitCustomer
- BranchUnitRelatedRecord
- BroadcastCommAudience
- BroadcastCommunication
- BroadcastTopic
- Budget
- BudgetAllocation
- BudgetCategory
- BudgetCategoryValue
- BudgetParticipant
- BudgetPeriod
- BulkApi2JobEvent
- BundleBasedAdjustment
- BundledCareFeeAgreement
- BusinessAlert
- BusinessAlertStatus
- BusinessBrand
- BusinessLicense
- BusinessMilestone
- BusinessProfile
- BusinessType
- BusRegAuthorizationType
- BusRegAuthTypeDependency
- BuyerAccount
- BuyerCriteria
- BuyerGroup
- BuyerGroupBuyerCriteria
- BuyerGroupPricebook
- BuyerGroupRelatedObject
- CalcMatrixColumnRange
- CalcProcStepRelationship
- CalculatedInsightRangeBound
- CalculationMatrixColumn
- CalculationMatrixRow
- CalculationMatrixVersion
- CalculationProcedure
- CalculationProcedureStep
- CalculationProcedureVariable
- CalculationProcedureVersion
- CampaignInsight
- CampaignMemberStatus
- CampaignTemplate
- CapitationCareFeeAgreement
- CareBarrier
- CareBarrierDeterminant
- CareBarrierType
- CareBenefitVerifyRequest
- CareDeterminant
- CareDeterminantType
- CareDiagnosis
- CareEpisode
- CareEpisodeDetail
- CareFacilityBed
- CareFeeScheduleItem
- CareGap
- CareGapCriteriaResult
- CareInterventionType
- CareLimitType
- CareMetricTarget
- CareObservation
- CareObservationComponent
- CarePerformer
- CarePgmEnrleeStatusPeriod
- CarePgmEnrolleeWkOrdStep
- CarePgmEnrolleeWorkOrder
- CarePgmProvHealthcareProvider
- CarePgmTeamMbrRolePeriod
- CarePlan
- CarePlanActivity
- CarePlanActivityDetail
- CarePlanDetail
- CarePlanTemplate
- CarePlanTemplateBenefit
- CarePlanTemplateGoal
- CarePlanTemplateProblem
- CarePractnFacilityAppt
- CarePreauth
- CarePreauthItem
- CareProcessingError
- CareProgram
- CareProgramCampaign
- CareProgramDetail
- CareProgramEligibilityRule
- CareProgramEnrollee
- CareProgramEnrolleeProduct
- CareProgramEnrollmentCard
- CareProgramGoal
- CareProgramProduct
- CareProgramProvider
- CareProgramSite
- CareProgramStatusPeriod
- CareProgramTeamMember
- CareProviderAdverseAction
- CareProviderFacilitySpecialty
- CareProviderSearchableField
- CareRegisteredDevice
- CareRequest
- CareRequestDrug
- CareRequestExtension
- CareRequestItem
- CareRequestReviewer
- CareService
- CareServiceVisit
- CareServiceVisitPlan
- CareSpecialty
- CareSpecialtyTaxonomy
- CareTaxonomy
- CartDeliveryGroup
- CartDeliveryGroupMethodAdj
- CartItem
- CartTax
- Case
- CaseContactRole
- CaseEpisode
- CaseMilestone
- CaseParticipant
- CaseProceeding
- CaseProceedingComplaint
- CaseProceedingInfraction
- CaseProceedingParticipant
- CaseProceedingResult
- CaseProgram
- CaseRelatedIssue
- CaseServiceProcess
- CaseTeamMemberProgram
- CategorizedCareFeeAgreement
- ChangeRequest
- ChangeRequestRelatedIssue
- ChangeRequestRelatedItem
- ChannelProgram
- ChannelProgramLevel
- ChannelProgramMember
- Claim
- ClaimCase
- ClaimCoverage
- ClaimCoveragePaymentDetail
- ClaimCoverageReserveDetail
- ClaimCovPaymentAdjustment
- ClaimCovReserveAdjustment
- ClaimItem
- ClaimParticipant
- ClaimPaymentSummary
- ClaimPayoutPlan
- ClaimRecovery
- ClaimTeamMember
- CleanEnergyProject
- ClinicalAlert
- ClinicalDetectedIssue
- ClinicalDetectedIssueDetail
- ClinicalEncounter
- ClinicalEncounterDiagnosis
- ClinicalEncounterFacility
- ClinicalEncounterIdentifier
- ClinicalEncounterProvider
- ClinicalEncounterReason
- ClinicalEncounterSvcRequest
- ClinicalMeasure
- ClinicalMeasureCriteria
- ClinicalMeasureCriteriaGrp
- ClinicalServiceRequest
- ClinicalServiceRequestDetail
- CloudServiceProvider
- CodeSet
- CodeSetBundle
- CodeSetRelationship
- CollaborationRoom
- CommerceConfigRelatedRecord
- CommissionSchedule
- CommissionScheduleAssignment
- CommSubscription
- CommSubscriptionChannelType
- CommSubscriptionConsent
- CommSubscriptionTiming
- ComplaintCase
- ComplaintParticipant
- ComplianceControl
- ComplianceProcCtrlParamMap
- ComplianceProcedure
- ComplianceProcedureControl
- ComplianceProcedureParam
- ComplianceProcedureVersion
- ConsentMetric
- ConsentUsageMetric
- ConstituentRole
- ConsumptionRate
- ConsumptionSchedule
- Contact
- ContactContactRelation
- ContactEncounter
- ContactEncounterParticipant
- ContactPointAddress
- ContactPointConsent
- ContactPointTypeConsent
- ContactProfile
- ContentDocumentListViewMapping
- ContentTaxonomy
- ContentTaxonomyRelatedTerm
- ContentTaxonomyTerm
- ContentTaxonomyTermRelatedObject
- ContentTaxonomyTermRelatedTerm
- ContentTaxonomyTermRelationshipType
- Contract
- ContractContactRole
- ContractDocumentReview
- ContractDocumentVersion
- ContractDocVerContentDoc
- ContractDocVersionSection
- ContractExtractionResult
- ContractGroupPlan
- ContractGroupPlanGroupClass
- ContractLineItem
- ContractLineOutcome
- ContractLineOutcomeData
- ContractPaymentAgreement
- ConversationBroadcastEntry
- Coupon
- CourseOffering
- CourseOfferingParticipant
- CourseOfferingPtcpResult
- CourseOfferingSchedule
- CourseOfferingScheduleTmpl
- CourtAction
- CourtActionOutcome
- CoverageBenefit
- CoverageBenefitItem
- CoverageBenefitItemLimit
- CoverageLimit
- CoverageType
- CrbnCreditAlloc
- CrbnCreditAllocItem
- CrbnCreditDistribution
- CrbnCreditProject
- CrbnEmssnScopeAlloc
- CrbnEmssnScopeAllocVal
- CredentialStuffingEventStore
- CreditMemo
- CreditMemoAddressGroup
- CreditMemoInvApplication
- CreditMemoLine
- Crisis
- CryptoProdCatgWalletGroup
- CryptoProdtCatgWalletRole
- CryptoProduct
- CryptoTransaction
- CryptoTransactionEnvelope
- CryptoTransEnvelopeChgLog
- CryptoWallet
- CryptoWalletGroup
- CryptoWalletGroupItem
- CustodyChainEntry
- CustodyEntryVerification
- CustodyItem
- CustodyItemRelation
- CustodyItemRgltyCodeVio
- CustodyVerfcTypeOverride
- Customer
- CustomerProperty
- DandBCompany
- DataAction
- DataActionJobSummary
- DataActionTarget
- DataCloudCurrencyConfig
- DataCloudFiscalCalendar
- DataUseLegalBasis
- DataUsePurpose
- DeleteEvent
- DeliveryTask
- Deviation
- DiagnosticSummary
- DiagnosticSummaryDetail
- DigitalSignature
- DigitalVerfSetupDetail
- DigitalVerification
- DigitalVerificationSetup
- DisclsReportingPeriod
- Dispute
- DisputeItem
- DisputeItemMerchantAlert
- DistributorAuthorization
- DivrsEquityInclSum
- DocChkItemValidatedTarget
- DocGenerationBatchProcess
- DocTemplateSectionCondition
- DocumentAuthoredContent
- DocumentClause
- DocumentClauseSet
- DocumentDecisionRequirement
- DocumentEnvelope
- DocumentGenerationProcess
- DocumentRecipient
- DocumentTemplate
- DocumentTemplateContentDoc
- DocumentTemplateSection
- DocumentTemplateToken
- DonorGiftSummary
- DrugDisplayTerm
- EconomicPerformanceSum
- EditionDefinition
- EducationalInfoRequest
- ElectricityEmssnFctrSet
- ElectronicMediaGroup
- EmissionsActivity
- EmissionsAllocation
- EmissionsForecastFact
- EmpBenefitSummary
- Employee
- EmployeeCrisisAssessment
- EmployeeDemographicSum
- EmployeeDevelopmentSum
- EmploymentCompensationSummary
- EmpUserProvisioningProcess
- EmpUserProvisionProcessErr
- EmssnRdctnCommitment
- EmssnReductionTarget
- EnergyAttrCertCredit
- EnergyAttrCertPurchase
- EnergyAttrCreditDstr
- EnergyServiceAgreement
- EnergyServiceAgreementItem
- EngagementAttendee
- EngagementChannel
- EngagementChannelType
- EngagementChannelWorkType
- EngagementInteraction
- EngagementProgramVersion
- EngagementTopic
- EnrollmentEligibilityCriteria
- Entitlement
- EntitlementContact
- EntitlementProvisioningRequest
- EntityArchivingException
- EntityArchivingJob
- EnvironmentalRisk
- Examination
- Expense
- ExpenseReport
- ExpenseReportEntry
- ExpressionSet
- ExpressionSetVersion
- ExternalAccountHierarchy
- ExternalAssessmentDefinition
- ExternalSourceStatusEvent
- ExtKnowledgeConnector
- FeeScheduleDefinition
- FileBasedDataImport
- FinanceBalanceSnapshot
- FinanceBook
- FinancePeriod
- FinanceTransaction
- FinanceTransactionErrorLog
- FinancialAccount
- FinancialAccountAddress
- FinancialAccountBalance
- FinancialAccountFee
- FinancialAccountMilestone
- FinancialAccountParty
- FinancialAccountStatement
- FinancialAccountTransaction
- FinancialDeal
- FinancialDealAsset
- FinancialDealBid
- FinancialDealInteraction
- FinancialDealParty
- FinancialDealProduct
- FinancialGoal
- FinancialGoalFunding
- FinancialGoalParty
- FinancialPlan
- FinancialSecurity
- FinclAcctPtyFinclAsset
- FinclDealInteractionSummary
- Fleet
- FleetAsset
- FleetParticipant
- FlowOrchestrationInstance
- FlowOrchestrationInstRelaObj
- FlowOrchestrationStageInstance
- FlowOrchestrationStepInstance
- FlowOrchestrationWorkItem
- FlowRecord
- FlowRecordElement
- FlowRecordVersion
- FlowRecordVersionOccurrence
- ForecastingCustomData
- ForecastingSrcRecJudgment
- FrgtHaulingEmssnFctr
- FrgtHaulingEnrgyUse
- FTestDataspaceScopedFacade
- FulfillmentAsset
- FulfillmentAssetAttribute
- FulfillmentAssetRelationship
- FulfillmentLineAttribute
- FulfillmentLineRel
- FulfillmentLineSourceRel
- FulfillmentOrder
- FulfillmentOrderLineItem
- FulfillmentPlan
- FulfillmentStep
- FulfillmentStepDefinition
- FulfillmentStepDefinitionGroup
- FulfillmentStepDependency
- FulfillmentStepDependencyDef
- FulfillmentStepSource
- FulfillmentWorkspace
- FulfillmentWorkspaceItem
- FundingAward
- FundingAwardAmendment
- FundingAwardParticipant
- FundingAwardRequirement
- FundingDisbursement
- FundingOpportunity
- FundingOppParticipant
- FundraisingConfig
- GameDefinition
- GameParticipant
- GameParticipantReward
- GameReward
- GenAIConversationSummary
- GeneratedDocument
- GeneratedDocumentSection
- GeneratedWaste
- GenericVisitTask
- GenericVisitTaskContext
- GeoCountry
- GeoState
- GiftBatch
- GiftCmtChangeAttrLog
- GiftCommitment
- GiftCommitmentSchedule
- GiftDefaultDesignation
- GiftDesignation
- GiftEntry
- GiftRefund
- GiftSoftCredit
- GiftTransaction
- GiftTransactionDesignation
- GiftTribute
- GnrcVstKeyPerformanceInd
- GnrcVstTaskContextRelation
- GoalAssignment
- GoalAssignmentDetail
- GoalAssignmentRecommendation
- GoalDefinition
- GovtFinancialAsstSum
- GroundTravelEmssnFctr
- GroundTravelEnrgyUse
- GroupCensus
- GroupCensusMember
- GroupCensusMemberPlan
- GroupClass
- GroupClassContribution
- GuestBuyerProfile
- GuestUserAnomalyEventStore
- HealthCareDiagnosis
- HealthcareFacility
- HealthcareFacilityNetwork
- HealthcarePayerNetwork
- HealthcarePractitionerFacility
- HealthCareProcedure
- HealthcareProvider
- HealthcareProviderNpi
- HealthcareProviderService
- HealthcareProviderSpecialty
- HealthcareProviderTaxonomy
- HealthcareServiceDetail
- HealthCondition
- HealthConditionDetail
- HealthScore
- HealthScoreActionLog
- HlthCareProvTreatedCondition
- HotelStayEmssnFctr
- HotelStayEnrgyUse
- Identifier
- IdentityDocument
- Image
- ImpactStrategy
- ImpactStrategyAssignment
- Incident
- IncidentRelatedItem
- IncludedLicenseDefinition
- IndexRate
- IndicatorAssignment
- IndicatorDefinition
- IndicatorPerformancePeriod
- IndicatorResult
- IndividualApplicationItem
- IndividualApplicationTask
- IndividualApplnParticipant
- IndvApplnItemProdtAttr
- InflationRate
- InfoAuthorizationRequest
- InfoAuthRequestForm
- InformationVerification
- InspectionAssessmentInd
- InspectionType
- InsPolicyAssetAttribute
- InsPolicyCoverageAttribute
- InsPolicyParticipantAttr
- InsPolicyTransactionDetail
- InStoreLocation
- InsuranceAsyncBulkRequest
- InsuranceAsyncBulkRequestDetail
- InsuranceAsyncBulkRequestItem
- InsuranceClaimAsset
- InsuranceContract
- InsurancePolicy
- InsurancePolicyAsset
- InsurancePolicyAttribute
- InsurancePolicyCoverage
- InsurancePolicyMemberAsset
- InsurancePolicyOwner
- InsurancePolicyParticipant
- InsurancePolicySurcharge
- InsurancePolicyTransaction
- InsuranceProfile
- InsuranceRatingRequest
- IntegrationProviderDcsnRqmt
- IntegrationProviderExecution
- Interaction
- InteractionAttendee
- InteractionRelatedAccount
- InteractionSumDiscussedAccount
- InteractionSummary
- InterestTag
- InternalOrganizationUnit
- InvBatchDraftToPostedRun
- InventoryItemReservation
- InventoryReservation
- Invoice
- InvoiceAddressGroup
- InvoiceBatchRun
- InvoiceBatchRunRecovery
- InvoiceLine
- InvoiceLineRelationship
- IssuedCard
- JobProfile
- JournalSubType
- JournalType
- KnowledgeArticleVersion
- Lead
- LeadLineItem
- LeadPreferredSeller
- LearnerProgram
- LearnerProgramRequirement
- LearnerProgramRqmtProgress
- Learning
- LearningAchievement
- LearningAchievementConfig
- LearningCourse
- LearningFoundationItem
- LearningItemSubmission
- LearningOutcomeItem
- LearningPractice
- LearningProgram
- LearningProgramPlan
- LearningProgramPlanRqmt
- LegalEntity
- LicensingError
- LicensingRequest
- LicensingRequestOrderItem
- LicensingSnapshotRequest
- LiveAgentSession
- LiveChatVisitor
- LoanApplicant
- LoanApplicantAddress
- LoanApplicantAsset
- LoanApplicantDeclaration
- LoanApplicantEmployment
- LoanApplicantIncome
- LoanApplicantLiability
- LoanApplicationAsset
- LoanApplicationFinancial
- LoanApplicationLiability
- LoanApplicationProperty
- LoanApplicationTitleHolder
- LocationGroup
- LocationGroupAssignment
- LocationTrustMeasure
- LocationWaitlist
- LocationWaitlistedParty
- LoyaltyLedger
- LoyaltyMemberCurrency
- LoyaltyMembershipLifecycle
- LoyaltyMemberTier
- LoyaltyPartnerProduct
- LoyaltyPgmEngmtAttribute
- LoyaltyPgmEngmtAttrProm
- LoyaltyPgmGroupMbrRlnsp
- LoyaltyPgmMbrAttributeVal
- LoyaltyPgmPartnerCurrency
- LoyaltyPgmPartnerPromotion
- LoyaltyPgmPtnrLdgrSummary
- LoyaltyPgmPtnrPrepaidPack
- LoyaltyProgram
- LoyaltyProgramCurrency
- LoyaltyProgramMemberBadge
- LoyaltyProgramMemberCase
- LoyaltyProgramMemberMerge
- LoyaltyProgramPartner
- LoyaltyProgramProcess
- LoyaltyProgramWidget
- LoyaltyTier
- LoyaltyTierBenefit
- LoyaltyTierGroup
- MaintenanceAsset
- MaintenancePlan
- ManagedCareProgramPrfm
- ManagedContent
- MarketingForm
- MarketingLink
- Marketplace
- MarketplaceSeller
- MaterialityAssessment
- MaterialityMatrixScore
- MaterialityStakeholder
- MaterialityStkhldrCatg
- MaterialityTopic
- MaterialityTopicQstn
- MaterialLine
- MaterialLineGroup
- MediaChannel
- MediaContentTitle
- MediaPrintIssue
- MediaTitleAvailability
- MediaTitleAvailAttribute
- MediaTitleReleaseDate
- MediaTitleRevenue
- Medication
- MedicationDispense
- MedicationReconciliation
- MedicationRequest
- MedicationStatement
- MedicationStatementDetail
- MedicationTherapyReview
- MedicationTherapyStmtReview
- MedicinalIngredient
- MedReconRecommendation
- MedReconStmtRecommendation
- MedTherapyStmtReviewIssue
- MemberBenefit
- MemberPlan
- MerchAccPaymentMethodSet
- MerchAccPaymentMethodType
- MerchantAccount
- MessagingEndUser
- MgmtEntitlementDefinition
- MgmtEntitlementTransaction
- MgmtEntitlementTransaction
- MgmtUsageSubTypeDefinition
- MgmtUsageTypeDefinition
- MgmtUsageTypeMultiplier
- MktAiPredictiveInsight
- MktDataApplicationObject
- MktSgmtActvDataSource
- MngContentPublishedUrl
- MultipartyInfoAuthRequest
- NamespaceRegistry
- NetworkDataCategory
- Note
- ObjectMetadataTag
- ObjectRelatedUrl
- ObjectStateActionDefinition
- ObjectStateDefinition
- ObjectStateTransition
- ObjectStateTransitionAction
- ObjectStateTransitionCondition
- ObjectStateTransitionCriteria
- ObjectStateTransitionEntry
- ObjectStateValue
- Obligation
- OmniAssessmentTask
- OmniDataPack
- OmniDataTransform
- OmniDataTransformItem
- OmniESignatureTemplate
- OmniProcess
- OmniProcessAsmtQuestionVer
- OmniProcessCompilation
- OmniProcessElement
- OmniProcessTransientData
- OmniScriptSavedSession
- OmniUiCard
- OperatingHours
- OperatingHoursHoliday
- Opportunity
- OpportunityPreferredSeller
- OpportunityRelatedDeleteLog
- Order
- OrderAction
- OrderAdjustmentGroup
- OrderAdjustmentGroupSummary
- OrderChangeLog
- OrderDeliveryGroup
- OrderDeliveryMethod
- OrderItemAdjustmentLineItem
- OrderItemAdjustmentLineSummary
- OrderItemAttribute
- OrderItemConsumptionRate
- OrderItemConsumptionSchedule
- OrderItemDetail
- OrderItemDetail
- OrderItemMaterialLineGroup
- OrderItemPriceSheet
- OrderItemRelationship
- OrderItemSummaryChange
- OrderItemTaxLineItem
- OrderItemTaxLineItemSummary
- OrderPaymentSummary
- OrderPaymentSummaryReference
- OrderSummaryAdditionalInfo
- OrderSummaryRelationship
- OrderSummaryRoutingSchedule
- OrderTotal
- OrgIncidentSummary
- OrgMetric
- OrgMetricScanResult
- OrgMetricScanSummary
- OtherComponentTask
- OtherEmssnFctrSet
- OtherEmssnFctrSetItem
- Outcome
- OutcomeActivity
- OutreachSourceCode
- OutreachSummary
- PartnerFundAllocation
- PartnerFundClaim
- PartnerFundRequest
- PartnerMarketingBudget
- PartyCertifiedCapacity
- PartyConsent
- PartyCreditProfile
- PartyExpense
- PartyFinancialAsset
- PartyFinancialLiability
- PartyFinclAssetAddlOwner
- PartyFinclLiabAddlBrwr
- PartyIdentityVerification
- PartyIdentityVerificationStep
- PartyIncome
- PartyProfile
- PartyProfileAddress
- PartyProfileParticipant
- PartyProfileRisk
- PartyRoleRelation
- PartyScreeningStep
- PartyScreeningSummary
- PatientHealthReaction
- PatientImmunization
- PatientImmunizationProtocol
- PatientMedicalProcedure
- PatientMedicalProcedureDetail
- PatientMedicationDosage
- PaymentApplicationMethod
- PaymentAuthAdjustment
- PaymentBatchRun
- PaymentBatchRunCriteria
- PaymentGateway
- PaymentGatewayLog
- PaymentInstrument
- PaymentIntent
- PaymentLineInvoice
- PaymentLink
- PaymentMandate
- PaymentPolicy
- PaymentRequest
- PaymentRequestLine
- PaymentSchedule
- PaymentScheduleItem
- PaymentSchedulePolicy
- PaymentScheduleTreatment
- PaymentScheduleTreatmentDtl
- PaymentTerm
- PaymentTermItem
- PaymentTreatment
- PcmtEmssnFctrSet
- PcmtEmssnFctrSetItem
- PercentileBsdCareFeeAgreement
- PersonAcademicCredential
- PersonalizationAttribute
- PersonalizationAttributeValue
- PersonalizationPoint
- PersonalizationPointBinding
- PersonalizationRecommender
- PersonalizationSchema
- PersonDisability
- PersonEducation
- PersonEmployment
- PersonExamination
- PersonLanguage
- PersonLifeEvent
- PersonList
- PersonName
- PersonPublicProfile
- PersonPublicProfilePrefSet
- PickTicket
- PickTicketAssignment
- PickTicketProduct
- PlanBenefit
- PlanBenefitItem
- PlatformLicenseDefinition
- Polygon
- PrcShtAttrDefinition
- PreliminaryApplicationRef
- PreventiveCareAgreement
- PriceAdjustment
- PriceAdjustmentSchedule
- PriceBookEntryDerivedPrice
- PriceListEntry
- PriceSheetAttributeRange
- PriceSheetDefinition
- PriceSheetEntry
- PricingActionParameters
- PricingAttributeCondition
- PricingFieldMapping
- PricingProcedureResolution
- PricingRecipe
- PricingRecipeTableMapping
- PrivacyHold
- PrivacyHoldReason
- PrivacyPolicy
- PrivacyProcessorOrchestrator
- PrivacyRequest
- PrivacyRTBFRequest
- PrivacyRtntStoreDelStatus
- PrivacySessionRecordFailure
- Problem
- ProblemDefinition
- ProblemGoalDefinition
- ProblemRelatedItem
- ProdtProvisioningTgtRoleTrust
- Producer
- ProducerCommission
- ProducerPolicyAssignment
- ProductAttribute
- ProductAttributeDefinition
- ProductAttributeSetProduct
- ProductAvailabilityProjection
- ProductAvlSvcCatalogItem
- ProductCatalog
- ProductCategoryAttribute
- ProductCategoryDisqual
- ProductCategoryMedia
- ProductCategoryProduct
- ProductCategoryQualification
- ProductCategoryServiceProcess
- ProductClassification
- ProductClassificationAttr
- ProductClsfnFlowDefinition
- ProductComponentGroup
- ProductComponentGrpOverride
- ProductConfigFlowAssignment
- ProductConfigurationRule
- ProductConfigurationRule
- ProductConsumedState
- ProductConsumptionSchedule
- ProductCoverage
- ProductCoverageLimit
- ProductDecompEnrichmentRule
- ProductDisqualification
- ProductEmissionsFactor
- ProductFaultCode
- ProductFee
- ProductFulfillmentDecompRule
- ProductFulfillmentLocation
- ProductFulfillmentScenario
- ProductItem
- ProductItemTransaction
- ProductLaborCode
- ProductLicenseMap
- ProductListRate
- ProductMedia
- ProductOverridePathItem
- ProductPriceSheet
- ProductPricingModel
- ProductQualification
- ProductQuantityRule
- ProductRelatedServiceProcess
- ProductRelationshipType
- ProductRelComponentOverride
- ProductRequest
- ProductRequestLineItem
- ProductRequired
- ProductSellingModel
- ProductSellingModelOption
- ProductServiceCampaign
- ProductServiceCampaignItem
- ProductTaxPolicy
- ProductTransferState
- ProductWarrantyTerm
- Program
- ProgramEnrollment
- ProgramInitiative
- ProgramInitiativeEnrl
- ProgramProduct
- ProgramRebateTypeBenefit
- ProgramRebateTypeFilter
- ProgramRebateTypePayout
- ProgramRebateTypeProduct
- ProgramRebateTypeReference
- ProgramRebateTypPayoutSrc
- ProgramTermApplnTimeline
- PromotionChannel
- PromotionLimit
- PromotionLimitUsage
- PromotionLineItemRule
- PromotionLoyaltyPtnrProdt
- PromotionMarketSegment
- PromotionPartyUsage
- PromotionPartyUsageDetail
- PromotionProduct
- PromotionProductCategory
- PromotionQualifier
- PromotionRuleTemplate
- PromotionSegment
- PromotionSegmentBuyerGroup
- PromotionSegmentSalesStore
- PromotionStage
- PromotionStageEmailTemplate
- PromotionTarget
- PromotionTier
- PromotionUsage
- ProrationPolicy
- ProviderNetworkContract
- ProviderNetworkTier
- ProviderOffering
- ProviderSearchSyncLog
- ProvisionedUsageTypeMultiplier
- ProvisioningRun
- ProvisioningRunEvent
- ProvisioningTargetGroup
- ProvisioningTargetItem
- ProvisioningTargetRole
- PublicApplicationParticipant
- PublicComplaint
- PublicProgram
- PurchaseQuantityRule
- PurchaserPlan
- PurchaserPlanAssn
- PymtSchdDistributionMethod
- QuoteAction
- QuoteItemTaxItem
- QuoteLineDetail
- QuoteLineDetail
- QuoteLineItemAttribute
- QuoteLineItemGroupClass
- QuoteLineItemPriceSheet
- QuoteLineMaterialLineGroup
- QuoteLinePriceAdjustment
- QuoteLineRelationship
- RebateClaim
- RebateClaimAdjustment
- RebateMemberAggregateItem
- RebateMemberClaimAggregate
- RebateMemberProductAggregate
- RebatePartnerSpecialPrcTrm
- RebatePayment
- RebatePayoutAdjustment
- RebateProgram
- RebateProgramMember
- RebateProgramMemberPayout
- RebateProgramPayoutPeriod
- RebatePtnrSpclPrcTrmBnft
- ReceivedDocument
- ReceivedDocumentType
- RecordAction
- RecordAggregationResult
- RecordAlert
- RecordsetFilterCriteria
- RecordsetFltrCritMonitor
- RecordType
- RecruitmentContentSection
- RecruitmentPosting
- RecruitmentPostingCntntSect
- RecruitmentRequisition
- RecurrenceSchedule
- ReferenceDataLoadLog
- Referral
- RefrigerantEmssnFctr
- RefundLinePayment
- RegAuthorizationTypeProduct
- RegulatoryAuthority
- RegulatoryAuthorizationType
- RegulatoryCode
- RegulatoryCodeAssessmentInd
- RegulatoryCodeUse
- RegulatoryCodeViolation
- RegulatoryTrxnFeeItem
- ReinsAgreementLineItem
- ReinsPolicyBordereauFact
- ReinsProtocolProdtComponent
- ReinsuranceAgreement
- ReinsuranceProtocol
- ReinsuranceProtocolAgreement
- RelationshipGraphView
- ReminderDefinition
- ReminderDefinition
- ReminderDefinitionChannel
- RentalCarEmssnFctr
- RentalCarEnrgyUse
- ReplyText
- ReportAnomalyEventStore
- ReportedConsumption
- ResearchStdyCndtStatusPrd
- ResearchStudy
- ResearchStudyCandidate
- ResearchStudyRelation
- ResidentialLoanApplication
- ResourceAbsence
- ResourcePreference
- RetailLocationGroup
- RetailStore
- RetailStoreGroupAssignment
- RetailStoreKpi
- RetailVisitKpi
- ReturnOrder
- ReturnOrderItemAdjustment
- ReturnOrderItemTax
- ReturnOrderLineItem
- RevenueAsyncOperation
- RevenueDistributionMethod
- RevenueElement
- RevenueElementDistribution
- RevenueRecognitionPolicy
- RevenueRecognitionTreatment
- RevenueRecogTreatmentItem
- RevenueTransactionErrorLog
- RevRecogTreatmentItemGroup
- RightsQuote
- RightsQuoteLineItem
- RightsQuoteLineMediaTitle
- SalesAgreementProduct
- SalesAgreementProductSchedule
- SalesAgreeProductAttribute
- SalesChannel
- SalesContractLine
- SalesforceContract
- SalesforceInvoice
- SalesforceQuote
- SavedPaymentMethod
- ScheduleBrdcstApptResource
- ScheduleBroadcast
- ScheduleBroadcastAppointment
- ScheduleBroadcastTerritory
- SchedulingConstraint
- SchedulingWorkspace
- SchedulingWorkspaceTerritory
- Scope3CrbnFtprnt
- Scope3EmssnSrc
- Scope3PcmtItem
- Scope3PcmtSummary
- Scorecard
- ScorecardAssociation
- ScorecardMetric
- ScratchOrgInfo
- SearchPromotionRule
- SecuritiesHolding
- Seller
- SerializedProduct
- SerializedProductTransaction
- ServiceAppointment
- ServiceAppointmentAttendee
- ServiceAppointmentCapacityUsage
- ServiceAppointmentGroup
- ServiceContract
- ServiceCrew
- ServiceCrewMember
- ServicePoint
- ServiceResource
- ServiceResourceCapacity
- ServiceResourcePreference
- ServiceTerritory
- ServiceTerritoryLocation
- ServiceTerritoryRelationship
- ServiceTerritoryWorkType
- SessionHijackingEventStore
- SettingUsageDefinition
- SettingUsageMap
- SetupAssistantStep
- SharedSavingPaymentAgreement
- SharingRecordCollection
- ShiftEngagementChannel
- ShiftPattern
- ShiftPatternEntry
- ShiftSegment
- ShiftWorkTopic
- Shipment
- ShipmentItem
- ShippingConfigurationSet
- ShippingRateArea
- ShippingRateGroup
- SignatureTask
- SignatureTaskLineItem
- SkillLevelDefinition
- SkillType
- SocialContributionSum
- SocialPersona
- StandardCareFeeAgreement
- StandardPermissionSet
- StandardShippingRate
- StnryAssetAnnualFact
- StnryAssetCrbnFtprnt
- StnryAssetCrbnFtprntItm
- StnryAssetEnrgyUse
- StnryAssetEnvrSrc
- StnryAssetWaterActvty
- StnryAssetWaterFtprnt
- StnryAssetWtrFtprntItm
- StoreActionPlanTemplate
- StoreAssortment
- StoreProduct
- StreamingChannel
- SuccessTeam
- SuggestedAssessmentDef
- SuggestedAssessmentReason
- Supplier
- SupplierProduct
- Survey
- SurveyQuestionChoice
- SurveyQuestionResponse
- SurveyResponse
- SustainabilityCredit
- SustainabilityPurchase
- SustainabilityScorecard
- SvcCatalogReqExtdAttrVal
- SvcCatalogRequest
- Swarm
- SwarmMember
- TableauHostMapping
- TagCategoryAssignment
- TaxDisclosureSummary
- TaxEngine
- TaxEngineInteractionLog
- TaxEngineProvider
- TaxGeoConfig
- TaxPolicy
- TaxRate
- TaxTreatment
- Team
- TeamMember
- Tenant
- TenantEntitlementTransaction
- TenantParameterMap
- TenantSecurityCustomMetricSetup
- TenantSecurityCustomMetricStat
- TenantSecurityEncryptionPolicy
- TenantSecurityGuestUserAnomaly
- TenantSecurityLicense
- TenantSecurityLoginIpRangeTrend
- TenantSecurityUiFilter
- TenantUsageTypeMultiplier
- ThreatDetectionFeedback
- TimePeriod
- TimeSheet
- TimeSheetEntry
- TimeSlot
- TrackedCommunication
- TrackedCommunicationDetail
- TrainingCourseParticipant
- TransactionJournal
- TravelMode
- TrialEnvironmentSignup
- TrnCourse
- UnitOfMeasure
- UnitOfMeasureConversion
- UsageEntitlement
- UsageEntitlementPeriod
- UsageEntitlementUsage
- UsageFactor
- UsageImpactFactor
- UsageImpactGroup
- UsageImpactGroupFactor
- UsageImpactGroupPgmMeasure
- UsageImpactGroupVersion
- UserEsignVendorIdentifier
- UserFinancialAuthority
- UserLicenseDefinition
- UserLocationAssignment
- Vehicle
- VehicleAssetCrbnFtprnt
- VehicleAssetEmssnSrc
- VehicleAssetEnrgyUse
- VehicleDefinition
- VehicleSearchableField
- VehicleUserAssignment
- VendorProject
- ViolationEnforcementAction
- ViolationType
- ViolationTypeAssessmentInd
- ViolationTypeUse
- Visit
- VisitedParty
- Visitor
- VoiceChnlInteractionEvent
- VoiceChnlIntrctnDtlEvent
- VolumeBasedAdjustment
- VolunteerProject
- Voucher
- VoucherDefinition
- Waitlist
- WaitlistParticipant
- WaitlistServiceResource
- WaitlistWorkType
- WarrantyTerm
- WarrantyTermCoverage
- WasteFootprint
- WasteFootprintItem
- WaveAutoInstallRequest
- WebStoreBuyerGroup
- WebStoreCatalog
- WebStoreInventorySource
- WebStorePricebook
- WebStoreSearchProdSettings
- WorkCapacityAvailability
- WorkCapacityLimit
- WorkCapacityUsage
- WorkerCompCoverageClass
- WorkOrder
- WorkOrderLineItem
- WorkPlan
- WorkPlanSelectionRule
- WorkPlanTemplate
- WorkPlanTemplateEntry
- WorkProcedure
- WorkProcedureStep
- WorkReport
- WorkReportError
- WorkReportLineItem
- WorkTypeCareSpecialty
- WorkTypeCodeSetBundle
- WorkTypeExtension
- WorkTypeGroup
- WorkTypeGroupMember
- WorkTypeGroupRole
- WorkTypeStep
- WorkTypeStepLdTimeOvride
- WorkTypeSvcTerrSchdPrio
- WstDispoEmssnFctrSet
- WstDispoEmssnFctrSetItm

<!-- document id=bd4368738fb740e0176366c5606cafca346b19eac00c8e456121d7c4ce3d58a0 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-objects-lwc-related-lists-sort.md -->

# Standard Objects That Don't Support Related List Multiple-Column Sort

You can sort related lists by multiple columns for many standard objects and for some custom objects.

- For standard objects, you can sort related lists by multiple columns only if the object is supported by [UI API](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md) and doesn't appear in [Exceptions to Standard Object Support](#exceptions-to-standard-object-support).
- For custom objects, you can sort related lists by multiple columns only if the parent object supports multiple-column sorting.

## Limitations

The following limitations apply when you sort related lists by multiple columns.

- You can’t sort an Account related list on a Campaign record by multiple columns.
- You can’t sort an OpportunityContactRole related list by multiple columns on an Account record. However, you can sort an OpportunityContactRole related list by multiple columns on a PersonAccount record.
- In some cases, a related list that’s supported on LWC renders with Aura instead. Rendering with Aura prevents sorting by multiple columns on that related list. If you click **View all** on a related list and don’t see ![Sort by multiple columns](https://developer.salesforce.com/media/multisort_120.png '{"class": "image-icon-sm"}'), then sorting by multiple columns isn’t supported for that related list.

## Exceptions to Standard Object Support

The following standard objects do **not** suppport [sorting related lists](https://help.salesforce.com/s/articleView?id=xcloud.basics_understanding_related_lists_lex.htm&type=5) by multiple columns.

**note:** As of Summer ’23, all new standard objects render with LWC. It’s possible that this list doesn’t include the newest object support details.

- AccountBrand
- AccountInsight
- AccountTeamMember
- AccountUserTerritory2View
- AcctMgrTarget
- ActionableListMemberStatus
- ActionCadence
- ActionPlan
- ActivationTarget
- ActivityHistory
- ActnblListKeyPrfmIndAsgnt
- AdSpaceGroupMember
- AdvAcctForecastFactAdj
- AdvAcctForecastSetPartner
- AdvAcctForecastSetUse
- AlternativePaymentMethod
- AppAnalyticsDeliveryConfig
- AppExtension
- AppMenuItem
- ApptBundleAggrPolicy
- ApptBundlePropagatePolicy
- AssetWarranty
- AttachedContentNote
- BatchJob
- BatchJobPart
- BillingPeriodTaxItem
- BusinessHours
- BusinessUnitMember
- BuyerGroupMember
- CallTemplate
- Campaign
- CampaignInfluence
- CampaignMember
- CardPaymentMethod
- CartItemPriceAdjustment
- CartValidationOutput
- CaseComment
- CaseFileProcessDependency
- CaseFileProcessExecution
- ChannelObjectLinkingRule
- CleanRule
- CollaborationGroup
- CommerceEntitlementBuyerGroup
- CommerceEntitlementPolicy
- CommerceEntitlementProduct
- CompiledProduct
- ContactPointEmail
- ContactPointPhone
- ContactRequest
- ContactSuggestionInsight
- ContentDocument
- ContentNote
- ContentVersion
- ContentWorkspace
- ConversationBroadcast
- CryptoTransEnvelopeChgSnp
- CspTrustedSite
- Dashboard
- DataConnectorS3
- DataLakeObjectInstance
- DataSpace
- DataStream
- DefinedSkill
- DelegatedAccount
- DigitalWallet
- Disclosure
- DisclosureDefinition
- DisclosureDefinitionVersion
- DisclosureType
- DocumentChecklistItem
- DsarPolicyLog
- DuplicateRecordItem
- DuplicateRecordSet
- ECart
- EmailContent
- EmailMessage
- EmailTemplate
- EmbeddedServiceConfig
- EmbeddedServiceLiveAgent
- EmbeddedServiceMenuSettings
- EnablementMeasureDefinition
- EnablementProgram
- EngagementProgram
- EnhancedEmailTemplate
- EnhancedLetterhead
- EnqueueOrderSummary
- EnvironmentHubMember
- Event
- ExplainabilityMsgTemplate
- ExpressionSetView
- ExtDataShare
- ExtDataShareTarget
- FavoriteConfiguration
- FeedItem
- FieldServiceMobileExtension
- FieldServiceMobileSettings
- FlowDefinitionView
- FlowInterview
- FlowOrchestrationLog
- Folder
- FtestAllContactPoint
- FtestApplication2CInterface
- FtestContactPointEmail
- FtestContactPointPhone
- GenericAsmtTaskContext
- GenericAssessmentTask
- GnrcAsmtTaskContextRela
- Holiday
- IdentityResolution
- Individual
- IPAddressRange
- LandingPage
- LearnerSkill
- LearningItem
- ListEmail
- ListEmailSentResult
- LiveChatSensitiveDataRule
- LiveChatTranscript
- Location
- LocWaitlistMsgTemplate
- LoyaltyProgramBadge
- LoyaltyProgramPartnerLedger
- LoyaltyProgramProcessParameter
- LoyaltyProgramProcessRule
- Macro
- ManagedContentVariant
- ManufacturingProgram
- MarketingAppExtAction
- MarketingAppExtActivity
- MarketingAppExtAssignment
- MarketingAppExtension
- MarketSegment
- MarketSegmentActivation
- MessagingChannel
- MessagingDeliveryError
- MessagingSession
- MessagingTemplate
- MfgProgramCpntFrcstFact
- MfgProgramForecastFact
- MfgProgramVariantFrcstFact
- MktAiPredictiveInsight
- MktCalculatedInsight
- MktDataTransform
- MktMLModel
- MobileSettingsAssignment
- MsgChannelLanguageKeyword
- NetworkReferencedObject
- ObjectTerritory2Association
- ObjectUserTerritory2View
- OpenActivity
- OpportunityContactRole
- OpportunityContactRoleSuggestionInsight
- OpportunityHistory
- OpportunityInsight
- OpportunityLineItem
- OpportunityLineItemSchedule
- OpportunityPartner
- OpportunitySplit
- OpportunityTeamMember
- OrderAdjustmentAggregateSummary
- OrderItem
- OrderItemSummary
- OrderSummary
- Payment
- PaymentActivity
- PaymentAuthorization
- PaymentGatewayProvider
- PendingOrderSummary
- PersonListMember
- PgmRebateTypBnftMapping
- PriceAdjustmentTier
- PriceBookPriceGuidance
- PriceRule
- PrivacyJobSession
- ProcessException
- ProcessInstanceHistory
- ProcessInstanceStep
- ProcessInstanceWorkitem
- ProductAttributeSet
- ProductAttributeSetItem
- ProductCategory
- ProductRelatedMaterial
- ProductTransfer
- ProfileSkill
- ProfileSkillUser
- Promotion
- PublicKeyCertificate
- PublicKeyCertificateSet
- QuickText
- QuoteAdjustmentGroup
- QuoteDocument
- QuoteLineItem
- RebatePayoutSnapshot
- Recommendation
- RecordAlertTemplate
- RecordMergeHistory
- RecordsetFilterCriteriaRule
- Refund
- RegulatoryTrxnFee
- RelationshipGraphView
- Report
- SalesAgreement
- SalesAgreementStatus
- SalesforceContract
- SalesforceInvoice
- SalesforcePayment
- SalesforceQuote
- SharingRecordCollectionItem
- ShiftTemplate
- SiqExchangeConnection
- Skill
- Snippet
- SnippetAssignment
- SocialPost
- SurveyEmailBranding
- SurveyInvitation
- SurveyQuestion
- SurveyVersion
- SvcCatalogItemDef
- TagCategory
- Task
- TaxCertificate
- TimelineObjectDefinition
- TimeSheetTemplate
- Topic
- TopicAssignment
- UhsCategorySyncState
- UnifiedActivity
- UnitOfMeasureUnit
- User
- UserAppMenuItem
- UserDefinedLabel
- UserRole
- UserTerritory2AssocLog
- WebCart
- WebCartAdjustmentBasis
- WebCartAdjustmentGroup
- WebCartDocument
- WebStore
- WorkPlan
- WorkSkillRouting
- WorkStep
- WorkStepTemplate

<!-- document id=bc6de3d1eb7c57c8135dfdc3948ab60cc6577b7f87c4f3c6bb1599cdbcbc73e4 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-objects-lwc-multi-column-sort.md -->

# Standard Objects That Support List View Multiple-Column Sort

Most standard objects now render using LWC, but only a limited set supports multiple-column sort in list views. You can sort list views by multiple columns for all custom objects. The following standard objects support sorting list views by multiple columns.

**note:** As of Summer ’23, all new standard objects render with LWC. It’s possible that this list doesn’t include the newest supported objects.

- AISentimentResult
- Account
- AccountBrand
- AccountForecast
- AccountForecastAdjustment
- AccountForecastPeriodMetric
- AccountProductForecast
- AccountProductPeriodForecast
- Accreditation
- AcctMgrPeriodicTargetDstr
- AcctMgrTargetDstr
- ActionPlanTemplate
- ActionVisibility
- ActivityTiming
- AddOnDefinition
- AdCreativeSizeType
- AdOrderLineAdTarget
- AdPageLayoutType
- AdProductTargetCategory
- AdQuote
- AdServer
- AdServerUser
- AdSpaceSpecification
- AdTargetCategory
- AdTargetCategorySegment
- AdUsage
- AdUsageSummary
- AdvAccountForecastFact
- AiDataset
- AiImageDetectedObject
- AiImageTrainingObject
- AiVisionModel
- AiVisionModelMetric
- AiVisionModelObjectMetric
- AiVisitRecommendRequest
- AiVisitRecommendation
- AiVisitSummary
- AiVisitTaskRcmd
- AiVisitTaskRcmdRequest
- AirTravelEmssnFctr
- AirTravelEnrgyUse
- AlternativePaymentMethod
- ApiAnomalyEventStore
- ApplicationCase
- ApplicationFormTemplate
- AppointmentInvitation
- AppointmentReason
- ApptBundleConfig
- ApptBundlePolicy
- Assessment
- AssessmentIndDefinedValue
- AssessmentIndValue
- AssessmentIndicatorDefinition
- AssessmentQuestion
- AssessmentQuestionResponse
- AssessmentQuestionSet
- AssessmentTask
- AssessmentTaskContentDocument
- AssessmentTaskDefinition
- AssessmentTaskOrder
- Asset
- AssetStatePeriod
- AssistantText
- AssortmentProduct
- AsyncOperationLog
- AttributeCategory
- AttributePicklist
- AttributePicklistValue
- AuthApplicationAsset
- AuthApplicationPlace
- AuthLocationAccessSchedule
- AuthorNote
- AuthorizationFormConsent
- AuthorizationFormDataUse
- AuthorizedInsuranceLine
- Award
- BackgroundOperation
- BenefitSchedule
- BenefitSession
- BenefitType
- BillingBatchFilterCriteria
- BillingBatchScheduler
- BillingTreatment
- BillingTreatmentItem
- BldgEnrgyIntensity
- BldgEnrgyIntensityVal
- BldgSizeCategory
- BoardCertification
- BranchUnitCustomer
- BroadcastCommunication
- Budget
- BudgetAllocation
- BusRegAuthTypeDependency
- BusRegAuthorizationType
- BusinessBrand
- BusinessLicense
- BusinessLicenseApplication
- BusinessMilestone
- BusinessProfile
- BusinessType
- BuyerGroupPricebook
- Campaign
- CardPaymentMethod
- CareBarrier
- CareBarrierType
- CareBenefitVerifyRequest
- CareDeterminant
- CareDeterminantType
- CareDiagnosis
- CareInterventionType
- CareMetricTarget
- CarePlanDetail
- CarePgmProvHealthcareProvider
- CarePractnFacilityAppt
- CarePreauth
- CarePreauthItem
- CareProgram
- CareProgramCampaign
- CareProgramEligibilityRule
- CareProgramEnrollee
- CareProgramEnrolleeProduct
- CareProgramEnrollmentCard
- CareProgramGoal
- CareProgramProduct
- CareProgramProvider
- CareProgramTeamMember
- CareProviderAdverseAction
- CareProviderFacilitySpecialty
- CareProviderSearchableField
- CareRegisteredDevice
- CareRequest
- CareRequestDrug
- CareRequestExtension
- CareRequestItem
- CareRequestReviewer
- CareSpecialty
- CareSpecialtyTaxonomy
- CareTaxonomy
- Case
- CaseParticipant
- CaseRelatedFile
- ChangeRequest
- ChannelProgram
- ChannelProgramLevel
- Claim
- ClaimCoverage
- ClaimRecovery
- ClinicalEncounter
- ClinicalEncounterDiagnosis
- ClinicalEncounterFacility
- ClinicalEncounterProvider
- ClinicalEncounterReason
- CloudServiceProvider
- CodeSet
- CodeSetBundle
- CommSubscription
- CommSubscriptionTiming
- CommissionSchedule
- CommissionScheduleAssignment
- ComplaintCase
- ComplaintParticipant
- ConsentMetric
- ConsentUsageMetric
- ConsumptionSchedule
- Contact
- ContactEncounter
- ContactPointConsent
- ContactPointTypeConsent
- ContactRequest
- ContentDocumentListViewMapping
- Contract
- ContractGroupPlan
- ContractGroupPlanGroupClass
- ContractPaymentAgreement
- Coupon
- CourseOffering
- CoverageBenefit
- CoverageBenefitItem
- CoverageBenefitItemLimit
- CoverageType
- CrbnEmssnScopeAlloc
- CrbnEmssnScopeAllocVal
- CredentialStuffingEventStore
- CryptoTransEnvelopeChgLog
- Customer
- CustomerProperty
- DataUseLegalBasis
- DataUsePurpose
- DelegatedAccount
- DeliveryTask
- DiagnosticSummaryDetail
- DigitalWallet
- DistributorAuthorization
- DocumentChecklistItem
- DocumentEnvelope
- DocumentTemplate
- DuplicateRecordSet
- EditionDefinition
- ElectricityEmssnFctrSet
- EmailTemplate
- Employee
- EmpUserProvisioningProcess
- Entitlement
- EntityArchivingException
- EntityArchivingJob
- Examination
- Expense
- ExpenseReport
- ExternalAccountHierarchy
- FeeScheduleDefinition
- FinanceBalanceSnapshot
- FinanceBook
- FinancePeriod
- FinanceTransaction
- FinanceTransactionErrorLog
- FinancialDeal
- FinancialDealParty
- FinancialDealProduct
- FlowOrchestrationInstance
- FrgtHaulingEmssnFctr
- FrgtHaulingEnrgyUse
- FtestBigObjectLookup
- FtestConcrete
- FulfillmentOrder
- GeneratedDocument
- GeneratedWaste
- GenericVisitTask
- GenericVisitTaskContext
- GeoCountry
- GeoState
- GnrcVstKeyPerformanceInd
- GnrcVstTaskContextRelation
- GoalDefinition
- GroundTravelEmssnFctr
- GroundTravelEnrgyUse
- GroupCensus
- GroupCensusMember
- GroupClass
- GroupClassContribution
- HealthCareDiagnosis
- HealthCareProcedure
- HealthCondition
- HealthConditionDetail
- HealthcareFacilityNetwork
- HealthcarePayerNetwork
- HealthcarePractitionerFacility
- HealthcareProvider
- HealthcareProviderNpi
- HealthcareProviderSpecialty
- HealthcareProviderTaxonomy
- HotelStayEmssnFctr
- HotelStayEnrgyUse
- IdentityDocument
- Image
- Incident
- Individual
- IndividualApplication
- InflationRate
- InfoAuthorizationRequest
- InspectionAssessmentInd
- InspectionType
- InStoreLocation
- InsuranceContract
- InsurancePolicy
- InsuranceProfile
- Interaction
- InteractionSummary
- InterestTag
- InventoryItemReservation
- InventoryReservation
- Invoice
- InvoiceAddressGroup
- InvoiceLine
- JobPosition
- JobProfile
- JournalSubType
- JournalType
- Lead
- LegalEntity
- LicensingRequestOrderItem
- LicensingSnapshotRequest
- ListEmail
- Location
- LocationWaitlist
- LocationWaitlistedParty
- LoyaltyLedger
- LoyaltyMemberCurrency
- LoyaltyMemberTier
- LoyaltyPartnerProduct
- LoyaltyPgmGroupMbrRlnsp
- LoyaltyPgmPartnerCurrency
- LoyaltyPgmPartnerPromotion
- LoyaltyPgmPtnrLdgrSummary
- LoyaltyPgmPtnrPrepaidPack
- LoyaltyProgram
- LoyaltyProgramCurrency
- LoyaltyProgramMbrPromotion
- LoyaltyProgramMember
- LoyaltyProgramMemberCase
- LoyaltyProgramPartner
- LoyaltyProgramPartnerLedger
- LoyaltyProgramProcess
- LoyaltyTier
- LoyaltyTierBenefit
- LoyaltyTierGroup
- ManufacturingProgram
- MaintenancePlan
- MaintenanceWorkRule
- MarketingForm
- MarketingLink
- MarketingLinkContent
- MediaChannel
- MediaContentTitle
- MedicationDispense
- MedicationReconciliation
- MedicationStatementDetail
- MedicinalIngredient
- MedReconRecommendation
- MedReconStmtRecommendation
- MemberBenefit
- MemberPlan
- MessagingSession
- MultipartyInfoAuthRequest
- NetworkReferencedObject
- OmniDataTransform
- OmniDataTransformItem
- OmniESignatureTemplate
- OmniProcess
- OmniProcessAsmtQuestionVer
- OmniProcessCompilation
- OmniProcessElement
- OmniProcessTransientData
- OmniScriptSavedSession
- OmniUiCard
- OperatingHours
- Opportunity
- Order
- OrderSummary
- OrderSummaryRoutingSchedule
- OrgMetric
- OtherComponentTask
- OtherEmssnFctrSet
- OtherEmssnFctrSetItem
- PartnerFundAllocation
- PartnerFundClaim
- PartnerFundRequest
- PartnerMarketingBudget
- PartyConsent
- PartyIncome
- PatientImmunization
- PaymentAuthorization
- PaymentAuthAdjustment
- PaymentBatchRun
- PaymentLineInvoice
- PaymentRequest
- PaymentSchedule
- PaymentScheduleItem
- PcmtEmssnFctrSet
- PcmtEmssnFctrSetItem
- PersonEducation
- PersonEmployment
- PersonExamination
- PersonLanguage
- PersonLifeEvent
- PersonName
- PlanBenefit
- PlanBenefitItem
- PlatformLicenseDefinition
- Polygon
- PreliminaryApplicationRef
- PriceAdjustmentSchedule
- Pricebook2
- PricebookEntry
- PrivacyJobSession
- PrivacyPolicy
- PrivacyRequest
- Problem
- ProcessException
- Producer
- ProducerCommission
- Product2
- ProductAvailabilityProjection
- ProductCatalog
- ProductCategory
- ProductCategoryAttribute
- ProductComponentGroup
- ProductCoverage
- ProductEmissionsFactor
- ProductFulfillmentLocation
- ProductItem
- ProductRelationshipType
- ProductRequest
- ProductRequestLineItem
- ProductRequired
- ProductServiceCampaign
- ProductTransfer
- ProgramRebateTypPayoutSrc
- ProgramRebateTypeBenefit
- ProgramRebateTypeFilter
- ProgramRebateTypePayout
- ProgramRebateTypeProduct
- ProgramRebateTypeReference
- Promotion
- PromotionChannel
- PromotionLoyaltyPtnrProdt
- PromotionMarketSegment
- PromotionProduct
- PromotionProductCategory
- PromotionSegment
- ProrationPolicy
- ProviderNetworkTier
- ProviderSearchSyncLog
- ProvisioningTargetGroup
- ProvisioningTargetItem
- ProvisioningTargetRole
- PublicApplicationParticipant
- PublicProgram
- PurchaseQuantityRule
- PurchaserPlan
- PurchaserPlanAssn
- Quote
- RebateMemberAggregateItem
- RebateMemberProductAggregate
- RebatePayment
- RebatePayoutAdjustment
- RebateProgram
- RebateProgramMember
- RebateProgramMemberPayout
- RebateProgramPayoutPeriod
- Recommendation
- RecordsetFilterCriteria
- RefrigerantEmssnFctr
- RefundLinePayment
- RegAuthorizationTypeProduct
- RegulatoryAuthority
- RegulatoryAuthorizationType
- RegulatoryCode
- RegulatoryCodeAssessmentInd
- RegulatoryCodeViolation
- RegulatoryTrxnFee
- RegulatoryTrxnFeeItem
- RentalCarEmssnFctr
- RentalCarEnrgyUse
- ReplyText
- ReportAnomalyEventStore
- ResourceAbsence
- RetailLocationGroup
- RetailStore
- RetailVisitKpi
- ReturnOrder
- RevRecogTreatmentItemGroup
- RevenueDistributionMethod
- RevenueElement
- RevenueElementDistribution
- RevenueRecogTreatmentItem
- RevenueRecognitionPolicy
- RevenueRecognitionTreatment
- RevenueTransactionErrorLog
- SalesAgreementProductSchedule
- SalesContractLine
- SalesforceContract
- SalesforceInvoice
- SalesforceQuote
- SchedulingConstraint
- Scope3CrbnFtprnt
- Scope3EmssnSrc
- Scope3PcmtItem
- Scope3PcmtSummary
- Scorecard
- SecuritiesHolding
- Seller
- SerializedProductTransaction
- ServiceAppointment
- ServiceContract
- ServiceCrew
- ServiceCrewMember
- ServiceResource
- ServiceResourcePreference
- ServiceTerritory
- SessionHijackingEventStore
- SharingRecordCollection
- Shift
- ShiftPattern
- ShiftTemplate
- Shipment
- SignatureTask
- SignatureTaskLineItem
- Snippet
- SocialPersona
- StnryAssetCrbnFtprnt
- StnryAssetCrbnFtprntItm
- StnryAssetEnrgyUse
- StnryAssetEnvrSrc
- StnryAssetWaterActvty
- StnryAssetWaterFtprnt
- StoreActionPlanTemplate
- StoreAssortment
- StoreProduct
- StreamingChannel
- Survey
- SvcCatalogReqRelatedItem
- Swarm
- SwarmMember
- TagCategoryAssignment
- TaxEngine
- TaxEngineInteractionLog
- TaxEngineProvider
- TaxRate
- ThreatDetectionFeedback
- TimeSheet
- TimeSheetEntry
- TrainingCourseParticipant
- TransactionJournal
- TravelMode
- TrnCourse
- UnitOfMeasure
- UnitOfMeasureConversion
- UsageFactor
- UserDefinedLabel
- UserEsignVendorIdentifier
- UserLicenseDefinition
- VehicleAssetCrbnFtprnt
- VehicleAssetEmssnSrc
- VehicleAssetEnrgyUse
- VehicleUserAssignment
- VideoCall
- ViolationEnforcementAction
- ViolationType
- ViolationTypeAssessmentInd
- Visit
- VisitedParty
- Visitor
- VolunteerProject
- Voucher
- VoucherDefinition
- WarrantyTerm
- WasteFootprint
- WasteFootprintItem
- WebCart
- WebStorePricebook
- WorkCapacityLimit
- WorkCapacityUsage
- WorkOrder
- WorkPlan
- WorkPlanSelectionRule
- WorkPlanTemplate
- WorkStepTemplate
- WorkTypeCareSpecialty
- WorkTypeCodeSetBundle
- WorkTypeGroup
- WorkerCompCoverageClass
- WstDispoEmssnFctrSet
- WstDispoEmssnFctrSetItm

<!-- document id=8dc97c5e0a1befd4146aa0fc97b6aaa801cda2d4440e2b872c4c1447103372c4 url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-start-monitoring.md -->

# startMonitoringGeofence()

Start monitoring a geofence region.

## Syntax

```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
startMonitoringGeofence(
    geofence: Geofence
): Promise<string>;
```


## Parameters

- `geofence`—(Required) A `Geofence` object to monitor.

## Returns

A Promise object that resolves as a string value. The value is a unique ID that’s assigned to the monitored geofence. If there’s an error, a rejected promise returns the error type of `GeofenceServiceFailure`.

## Usage

Use this function to start monitoring of a geofence. 

```js
myGeofenceService.startMonitoringGeofence(geofence)
   .then((id) => {
       const msg = `ID for geofence created: ${id}`;
       console.log(msg);
   })
   .catch((error) => {
       const msg = `Failed to start monitoring:${JSON.stringify(error)}`; 
       console.log(msg);
   });
```
Your callback function is called to return the ID of the geofence that’s been created. To stop monitoring the geofence in the future, retain the geofence ID.

<!-- document id=2907103cd7ea81bdba34f2da0180d9fb30c31081f762a3f60b70ff47e8e01ce2 url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-startwatchingposition.md -->

# `startWatchingPosition(options, callback)`

Subscribes to asynchronous location updates for the mobile device.

**note:** This function will be retired in a future release. From feedback, we’ve determined that the limitations of the API render it unsuitable for many customer use cases. Additional Android and iOS platform constraints require us to fully reevaluate our approach. We’re exploring the possibility of replacing this API in a future release.

## Syntax

```javascript
import { getLocationService } from 'lightning/mobileCapabilities';
startWatchingPosition(
  options: LocationServiceOptions,
  callback: (location: Location, error: LocationServiceFailure) => void
): number;
```

## Parameters

- `options`—(Required) A [`LocationServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) object to configure the location request.
- `callback`—(Required) A function to handle location update responses.

## Returns

An integer identifier for the location subscription, which you can use to end the subscription when you want to stop receiving location updates.

## Usage

This function creates a subscription to significant location updates, where “significant” is determined by the operating system. See usage notes below.

**important:** Receiving location updates with `startWatchingPosition()` is suitable for components that remain on the screen while receiving updates. If the user puts the mobile app into the background, location tracking can, and likely will, stop shortly afterward. If the user navigates away from the page, but remains in the mobile app, your component can continue to receive location updates, but can also be deallocated by the framework.

In other words, while the user remains on the same page, position tracking works as expected. If the user leaves the page or the app, the behavior is undefined.

```javascript
myLocationWatchId = 0;
async startTracking() {
  let locationService = getLocationService();
  this.myLocationWatchId = await locationService.
    startWatchingPosition({ enableHighAccuracy:false }, (result, error) => {

      // Check for error first
      if(error) {
        console.error(error);
        this.stopTracking();
      }
      else {
        this.myLocation = result.coords;

        // Do something with the updated location
        // Refresh a map, upsert a record, or whatever
        // needs to happen when a location change occurs
      }
    });
}
```

Your callback function will be called initially to provide the current location, similar to [`getCurrentPosition()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-getcurrentposition.md). After that, it’s called whenever there’s a significant location change.

- Retain the `watchId` for use in a [`stopWatchingPosition()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-stopwatchingposition.md) call when you’re ready to stop receiving updates.
- Your callback function receives a [`Location`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) object, or a [`LocationServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md) if there’s an error.
- There’s no specific timing for receiving position updates via your callback function. They happen when the underlying operating system location feature detects a significant change, where “significant” is influenced by a number of external factors, such as the accuracy you requested, reliability of the underlying location hardware, velocity or rate of change, and so on.
- Creating a location subscription with `startWatchingPosition()` allocates resources that aren’t released automatically. Call `stopWatchingPosition()` to release those resources when appropriate. Failing to release resources can (eventually) result in errors, such as your app being terminated by the operating system.

**See Also**

- [stopWatchingPosition(watchId)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-stopwatchingposition.md)
- [LocationService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-data-types.md)

<!-- document id=886b9409e4882c125a9645b00a3d14b42b808a1780f06f0bbb1d3ce1d695ef6f url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-alternatives.md -->

# State Management Compared with Alternatives

There are a few ways to share common data across components in an LWC app. For example, you can set properties on child components to pass data into them from the parent. Events let you send data in the opposite direction. These simple solutions can be optimal for many apps, or a small set of related components that work together.

State management can work well in those situations too. However, it's specifically designed to optimize data sharing for an app or collection of components that's grown large and complex. For example, you don't want to pass property values down chains of a dozen or more child components, or send events back up the same long hierarchy. A state manager is a "black box" that holds a set of related data values that are managed in a consistent way. Components in a shared subtree can access a state manager instance through the component hierarchy. You can also export a singleton state manager from a shared module, which gives all components that import it access to the same instance. Then, a component can use the state manager to read values managed elsewhere, or to perform safe, managed changes to the contents.

Developers can use LWC state management to address various challenges that arise from size and complexity.

- Reduce Prop Drilling: In complex apps, passing data down through multiple layers of nested components (prop drilling) can become cumbersome and hard to maintain. State managers offer a way to access state in deeply nested children without explicitly passing props through every intermediate component.
- Separate Data from Presentation: Separating the concerns of data retrieval, transformation, and business logic from the presentation logic of UI components that show that data leads to more maintainable and testable code.
- Centralize State Logic: A state manager allows for the co-location of state definitions and the logic for updating that state. This makes it easier to understand and manage how data changes over time.
- Improve Performance and Data Orchestration: By decoupling data loading from component rendering, state managers can enable scenarios like pre-fetching data before components render, potentially improving perceived performance. They also lay the groundwork for more advanced data coordination and optimization strategies.
- Manage Complex State Interactions: For apps with intricate state dependencies and frequent updates, state managers provide a more robust and idiomatic way to handle these complexities compared to manual state handling or relying solely on `@wire` in many places.
- Reusability: State logic encapsulated within a state manager can be reused across different parts of an app, or even in different apps.

LWC state management aims to provide an idiomatic way to manage state for larger collections of components (apps), making it more obvious how to retrieve, transform, distribute, and present data.

<!-- document id=b506c8640dacbd67ea52db56acc50063c55e25c4fe54875c3f92e7e69309fb36 url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-examples.md -->

# State Management Examples

Often the best documentation for code-based features is examples of those features in use. State management has a dedicated repository on GitHub with several example implementations. You can find the repo under the `forcedotcom` org:

[https://github.com/forcedotcom/state-management](https://github.com/forcedotcom/state-management)

The repo currently contains two examples.

## Example: `platform-state-managers`

This simple example provides a minimal implementation of a state manager. It demonstrates how to define a state manager, how to use it to retrieve Salesforce metadata and data, and how to show state manager data in your LWC user interface.

This example also demonstrates how to compose nested state managers, by using the `lightning/stateManagerRecord` and `lightning/stateManagerLayout` state managers. These built-in state managers wrap related UI API calls, providing an alternative to calling them directly, or via `@wire`.

## Example: `simple-store`

This example is more complex. It provides a set of related components that demonstrate using a state manager to maintain the state of a shopping cart in a simple online store.

Rather than retrieving data from Salesforce, it shows how to build and manipulate local data that isn't ready to be sent to a server yet, but still needs coherent logic to ensure that correct, always current information is used or shown.

## Example: `opportunitiesStateManager` in LWC Recipes

An additional example is available in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

- [`opportunitiesStateManager`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/opportunitiesStateManager) module
- [`opportunitiesList`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/opportunitiesList) component
- [`opportunitiesSummary`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/opportunitiesSummary) component

<!-- document id=18ddc737f3b4abb2c6c7bad113ad3de2d99727a6311a97c5b7bec11526bfa195 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-async.md -->

# Static Resources with async Functions Behave Inconsistently

When you use `lightning/platformResourceLoader` in Lightning web components (LWC) to access static resources and Lightning Web Security (LWS) is enabled, it’s possible that some APIs in those static resources exhibit inconsistent behavior among various browsers.

When LWS is enabled, JavaScript `async` functions that are used from a static resource work in Chromium-based browsers, but don’t work in Firefox currently. The issue is a [bug in Firefox](https://bugzilla.mozilla.org/show_bug.cgi?id=1663090).

You can get around this issue in Firefox by pre-compiling the code that’s in the static resource so the `async` function is replaced by equivalent code.

This Babel plugin is recommended if you’re having issues with `async` functions in static resources: [https://babeljs.io/docs/en/babel-plugin-transform-async-to-generator](https://babeljs.io/docs/en/babel-plugin-transform-async-to-generator)

Alternatively, you can refactor to use another approach, such as JavaScript promises.

**See Also**

- [YouTube Video: Understanding Asynchronous JavaScript](https://www.youtube.com/watch?v=ytL4NXW_CGY)

<!-- document id=4f9710013b99b44ad829e8fc6eba32da07d5ab62ca28ca46f59fac6fe80db242 url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-stop-monitoring-all.md -->

# stopMonitoringAllGeofences()

Stop monitoring all geofences.

## Syntax

```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
stopMonitoringAllGeofences(): Promise<void>;
```

## Parameters
None.

## Returns

A Promise object that resolves as void. If there’s an error, a rejected promise returns the error type of `GeofenceServiceFailure`.

## Usage
This function stops the monitoring of all geofences. 

```js
myGeofenceService.stopMonitoringAllGeofences()
    .then(() => {
        const msg = `Successfully stopped monitoring all geofences.`;
        console.log(msg);
    })
    .catch((error) => {
        const msg = `Failed to stop monitoring:${JSON.stringify(error)}`;
        console.log(msg);
    });

```

<!-- document id=25b7028360ab992259d3a382d8b1873063a10b60d5c99408fab1770ce0132eed url=/developer/current/en-us/lwc/lwc/guides/reference/geofencingservice/reference-lightning-geofencingservice-stop-monitoring.md -->

# stopMonitoringGeofence()

Stop monitoring a specific geofence.

## Syntax


```js
import { getGeofencingService } from 'lightning/mobileCapabilities';
stopMonitoringGeofence(
    id: string
): Promise<void>;

```

## Parameters

- `id`—(Required) Unique ID assigned to a specific geofence.

## Returns

A Promise object that resolves as void. If there’s an error, a rejected promise returns the error type of `GeofenceServiceFailure`.

## Usage

Use this function to stop monitoring of a specific geofence.

```js
myGeofenceService.stopMonitoringGeofence(geofenceId)
    .then(() => {
        const msg = `Successfully stopped monitoring geofence for ID:${geofenceId}`;
        console.log(msg);
    })
    .catch((error) => {
        const msg = `Failed to stop monitoring:${JSON.stringify(error)}`;
        console.log(msg);
    });

```

<!-- document id=032741405d04f97a8bd5ab97e1336cc20b88903c0dacbc0cc3cfe01d7ad8d6f2 url=/developer/current/en-us/lwc/lwc/guides/reference/locationservice/reference-lightning-locationservice-stopwatchingposition.md -->

# `stopWatchingPosition(watchId)`

Unsubscribes from location updates for the mobile device.

**note:** This function will be retired in a future release. From feedback, we’ve determined that the limitations of the API render it unsuitable for many customer use cases. Additional Android and iOS platform constraints require us to fully reevaluate our approach. We’re exploring the possibility of replacing this API in a future release.

## Syntax

```javascript
import { getLocationService } from 'lightning/mobileCapabilities';
stopWatchingPosition(watchId: number): void;
```

## Parameters

- `watchId`—(Required) An integer identifier for an active location subscription, returned by a call to [`startWatchingPosition()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-startwatchingposition.md).

## Returns

None.

## Usage

This function ends an existing subscription to location updates.

```javascript
stopTracking() {
  let locationService = getLocationService();
  locationService.stopWatchingPosition(this.myLocationWatchId);
}
```

Calling `stopWatchingPosition()` releases resources used to track the current location. You can’t reactivate a watch that’s been stopped. Create a new location subscription with `startWatchingPosition()` instead.

**See Also**

- [startWatchingPosition(options, callback)](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-locationservice-startwatchingposition.md)

<!-- document id=6069806ea8e778bf31d1d863b0380def8f07381b047b9024195f9b75c48a9672 url=/developer/current/en-us/lwc/lightning-components-security/guides/content-security-policy/content-security-policy-stricter.md -->

# Stricter CSP Restrictions

The Lightning Component framework uses Content Security Policy (CSP), which is a W3C standard, to control the source of content that can be loaded on a page. The CSP rules work at the page level, and apply to all components and libraries, regardless of whether Lightning Locker or Lightning Web Security are enabled. The Enable Stricter Content Security Policy org setting further mitigates the risk of cross-site scripting attacks. This setting is enabled by default.

## What Does Stricter CSP Do?

The Enable Stricter Content Security Policy setting disallows the `unsafe-inline` source for the `script-src` directive. When the setting is enabled, `script` tags can’t be used to load JavaScript, and event handlers can’t use inline JavaScript.

You must ensure that all your code, including third-party libraries, respects all CSP restrictions.

**important:** Lightning Web Security (LWS) relies on Stricter CSP. Disabling the Enable Stricter Content Security Policy setting reduces the level of security that LWS provides. We strongly advise that you keep Enable Stricter Content Security Policy switched on when LWS is enabled.

## Which Experiences Does Stricter CSP Affect?

Stricter CSP affects:

- Lightning Experience
- Salesforce app
- Standalone apps that you create (for example, `myApp.app`)

Stricter CSP doesn’t affect:

- Salesforce Classic
- Any apps for Salesforce Classic, such as Salesforce Console in Salesforce Classic
- Experience Builder sites, which have their own CSP settings
- Lightning Out, which allows you to run Lightning components in a container outside of Lightning apps, such as Lightning components in Visualforce and Salesforce Tabs + Visualforce sites. The container defines the CSP rules.

**note:** CSP in Experience Builder sites is controlled separately through each site’s settings.

<!-- document id=1c89ad6890dab2e82e782d84c3b39fd869683a66ef6efe951a81684c2bc147cd url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-intro.md -->

# Style a Component

To give your component the Lightning Experience look and feel, use [Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds.md) (SLDS) and Lightning base components. To go your own way, [write your own CSS](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css.md).

**tip:** Interactive base component examples are available in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

When you use base components in the `lightning` namespace, you get SLDS styling automatically. Using these base components, you can [customize the styling using SLDS styling hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md). Additionally, you can:

- [Create a component from an SLDS blueprint](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds-blueprint.md)
- [Import CSS modules in a component](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-share.md)
- [Create your own styling hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-styling-hooks.md)

We recommend that you avoid these [common mistakes when styling components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-antipatterns.md).

<!-- document id=ba7f1ed004f190792a5d2a2cd92eccbd274cce4d98296766ae4437698b9c2ade url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-custom-properties.md -->

# Style Components Using Lightning Design System Styling Hooks

Salesforce Lightning Design System (SLDS) styling hooks make it easy to customize component styling and express your brand. Use styling hooks to access CSS custom properties that are used in SLDS component blueprints and design variations. To customize an SLDS style, declare a corresponding custom property in a component’s stylesheet. You can use the custom properties to style base components and custom components.

**tip:** To change the styling of a Lightning base component, first check to see whether the component has [design variations](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-variants.md). To change the spacing of a component, such as the alignment, padding, margin, or even its typography, check [Lightning Design System utility classes](https://v1.lightningdesignsystem.com/utilities/alignment/). If these techniques don’t work for your use case, try SLDS styling hooks.

A styling hook is a placeholder in the SLDS stylesheet. For example, you can use `var(--slds-c-badge--color-background, #ecebea)`, to change the color value of the corresponding `--slds-c-badge-color-background` CSS custom property.

A CSS custom property is used in an SLDS component blueprint and its design variations. For example, the `--slds-c-button-brand-*` custom properties are used in the [button blueprint with the brand variation](https://v1.lightningdesignsystem.com/components/buttons/#Brand).

**note:** Currently, SLDS 2 doesn’t support component-level styling hooks, which have the prefix `--slds-c`. If your custom components use component-level styling hooks, we recommend that you use only SLDS 1 themes in your org for now. If you enable the Salesforce Cosmos theme in the org, your custom component styling can be incorrect. We’re working on component-level styling hook support for SLDS 2.

## Component Styling Hooks Versus Global Color Styling Hooks

Component styling hooks (`--slds-c-*`) enable you to update properties in a specific component. For example, to apply a thicker border to a single button, supply a value to the component hook for that button border. The change won't affect buttons in other components. See [Lightning Design System: Styling Hooks](https://v1.lightningdesignsystem.com/platforms/lightning/styling-hooks/).

**note:** Component styling hooks are available only in SLDS 1 as of Summer ’25. See [Styling Hooks](https://v1.lightningdesignsystem.com/platforms/lightning/styling-hooks/) in the SLDS 1 site.

Global color styling hooks (`--slds-g-*`) are predefined values used globally in an app. Use global hooks to make a change across all the components you are using. See [Lightning Design System: Global Color Styling Hooks](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks/).

We recommend that any color customizations that you make align with the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) 2.1 text and non-text color contrast standards. See [Lightning Design System: Migration Guide](https://www.lightningdesignsystem.com/accessibility/color-contrast/migration-guide/).

## Component Styling Hook Example

Let’s look at a Lightning web component that implements the SLDS button blueprint with the brand variation, which turns the background color a standard Salesforce blue.

```html
<!-- myButton.html -->
<template>
  <button class="slds-button slds-button_brand">Submit</button></div>
</template>
```

**important:** Don’t override SLDS classes directly, as shown in this example.

```css
/* myButton.css */
/* Anti-pattern - Don't do this */
.slds-button_brand {
  background-color: purple;
}
```

CSS overrides are not supported because SLDS classes and base component internals can change in future releases. The overrides can become outdated and no longer work as you intended.

Instead, use component styling hooks, as in the next example.

To apply a different background color to the brand variation, specify the styling hooks for the corresponding CSS custom property, which is `--slds-c-button-brand-color-background`. To target all elements in a component with your custom styles, use the [`:host`](https://developer.mozilla.org/en-US/docs/Web/CSS/:host) selector.

```css
/* myButton.css */
:host {
  --slds-c-button-brand-color-background: var(--slds-g-purple-30);
  --slds-c-button-brand-color-border: var(--slds-g-purple-30);
  /* Other CSS custom properties here */
}
```

Alternatively, you can scope your customizations using other selectors, such as elements or custom classes.

Base components implement SLDS component blueprints and use SLDS styles. You can use component styling hooks to customize some elements of base components. For example, to customize an SLDS style on the base component `lightning-button`, use a `--slds-c-button-*` component styling hook. Set the component styling hook's value to a global styling hook for the color you want.

<!-- prettier-ignore -->
```html
<!-- myBaseButton.html -->
<template>
  <lightning-button variant="brand" label="Submit" onclick={handleClick}></lightning-button>
</template>
```

```css
/* myBaseButton.css */
:host {
  --slds-c-button-brand-color-background: var(--slds-g-orange-70);
  --slds-c-button-brand-color-border: var(--slds-g-orange-70);
  /* Other CSS custom properties here */
}
```

**note:** For a complete list of component styling hooks, see each component’s blueprint in the SLDS 1 site. For example, the button styling hooks are listed at [v1.lightningdesignsystem.com/components/buttons/#Styling-Hooks-Overview](https://v1.lightningdesignsystem.com/components/buttons/#Styling-Hooks-Overview). To learn more about styling hooks, see [v1.lightningdesignsystem.com/platforms/lightning/styling-hooks/](https://v1.lightningdesignsystem.com/platforms/lightning/styling-hooks/).

## Support Limitations

- SLDS 2

  - : Component styling hooks are not yet supported in SLDS 2. If your custom components use component styling hooks, which have the prefix `--slds-c-*`, we recommend that you keep your org on SLDS 1 themes for now. We're working to enable component styling hooks in SLDS 2.

- Component Blueprints

  - : These Lightning Design System component blueprints and their CSS custom properties aren’t supported on base components.

    - Toast—The `lightning/platformShowToastEvent` module doesn’t support the `--slds-c-toast-*` custom properties. The `lightning/toast` and `lightning/toastContainer` modules do support these properties.

    - Tooltip—The `lightning-helptext` component doesn’t support `--slds-c-tooltip-*` custom properties.

- Links

  - : Styling links using custom properties isn’t supported. Links are used in base components such as `lightning-breadcrumb` and `lightning-formatted-*`, and in the `lightning/navigation` module.

- Form Elements

  - : Styling form elements using custom properties isn’t supported. Form elements are used in the `lightning-input-*`, `lightning-checkbox-group`, `lightning-radio-group`, and `lightning-textarea` components.

**See Also**

- [Create Styling Hooks for Your Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-styling-hooks.md)

<!-- document id=721cc0a4c3c947c98d687f4894d60bd87d1a240ad96681c4e46c2c6ef709b2e8 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css.md -->

# Style Components with CSS Stylesheets

To bundle a set of styles with a component, create a stylesheet with the same name as the component in the component’s folder. The stylesheet is automatically applied to the component. If you want to style a component with one or more stylesheets, configure the `stylesheets` static property.

You can only have one stylesheet in a component’s folder. Stylesheets use standard CSS syntax and you can use most selectors. A stylesheet can [import style rules](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-share.md) from multiple CSS modules.

In shadow DOM, styles defined in a component’s stylesheet are scoped to the component. This rule allows you to reuse a component in different contexts without losing its style. It also prevents a component’s styles from overriding styles in other parts of a page.

::video{src="https://youtube.com/embed/T7OGDMRnjT4" title="Deep Dive: Shadow DOM & CSS in Lightning Web Components" type="youtube" }

**note:** The video discusses CSS styling in synthetic shadow using the format `<div c-child_child>`, which is how the CSS scope tokens were generated before Winter '24.
The previous format and the current format `<div lwc-12abcdefg-host>` look different, but their purpose as CSS scope tokens is the same.

## CSS Encapsulation in Shadow DOM

This example demonstrates how the CSS styles defined in a parent component don’t reach into a child.

**note:** The examples use static values for font sizes and colors to make it easier to see CSS and shadow DOM concepts. In your component code, use global styling hooks to set CSS values instead. For example:

```css
h1 {
  font-size: var(--slds-g-font-scale-7);
}
```

There are two components, `c-parent` and `c-child`. Each component contains an `<h1>` tag. The `parent.css` stylesheet defines the `h1` style as `xx-large`. When you run the code, the style applies only to the `<h1>` tag in the parent, not to the `<h1>` tag in the nested child.

```html
<!-- parent.html -->
<template>
  <h1>To Do List (h1)</h1>
  <c-child></c-child>
</template>
```

```css
/* parent.css */
h1 {
  font-size: xx-large;
}
```

```html
<!-- child.html -->
<template>
  <h1>To Do Item (h1)</h1>
</template>
```

![Parent text is extra large. Child text is normal size.](https://developer.salesforce.com/media/css_1.png)

A parent component can style a child component, but it styles it as a single element. A parent can’t reach into a child. Let’s add a `c-child` selector to `parent.css` that defines a border around the child component.

```css
/* parent.css */
h1 {
  font-size: xx-large;
}

c-child {
  display: block;
  border: 2px solid red;
}
```

![The child component has a red box around it.](https://developer.salesforce.com/media/css_2.png)

Now let’s style the `c-child` component from its own style sheet, `child.css`.

Before we add a selector to `child.css`, let’s remove the `c-child` selector from `parent.css` to remove the red box. It’s not a good practice to style components from both the component and its parent, because it can be confusing and yield unexpected results. Here is `parent.css` with the `c-child` removed.

```css
/* parent.css */
h1 {
  font-size: xx-large;
}
```

A component’s stylesheet can reach up and style its own element, which in this example is `c-child`.

Instead of using a `c-child` selector, use the [`:host`](https://developer.mozilla.org/en-US/docs/Web/CSS/:host) selector.

```css
/* child.css */
:host {
  display: block;
  background: yellow;
}
```

![Child component's background is yellow.](https://developer.salesforce.com/media/css_3.png)

By targeting the host element with `:host`, we’ve applied styling to `<c-child>`, from `child.css`.

The `:host` selector accepts an optional list of selectors. To match, the host element must have a class that matches the passed selector. To see how the `:host` selector works, let’s rewrite our sample code to look slightly more like a real app. We add a `<slot>` to `c-child` so we can pass the name of the item on the To Do List.

```html
<!-- child.html -->
<template>
  <h1>To Do Item</h1>
  <slot></slot>
</template>
```

Let’s style the `h1` in the child component, but make it `large`, which is a bit smaller than the `xx-large` `h1` we defined in the parent component. Let’s also make all list items light gray except the active item, which is light green.

```css
/* child.css */
h1 {
  font-size: large;
}
:host {
  display: block;
  background: lightgray;
}

:host(.active) {
  background-color: lightgreen;
}
```

In the parent, let’s add three `c-child` components and make one active. In a real app, the active component would be the selected item.

```html
<!-- parent.html -->
<template>
  <h1>To Do List</h1>
  <c-child>Buy potatoes</c-child>
  <c-child>Donate to a good cause</c-child>
  <c-child class="active">Plan a party</c-child>
</template>
```

```css
/* parent.css */

h1 {
  font-size: xx-large;
}
```

![To do list with active to do item in light green.](https://developer.salesforce.com/media/css_4.png)

## CSS Cascading and Specificity

The CSS rules on [cascading, specificity, and inheritance](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance) apply to shadow DOM.

Cascading refers to the combining of CSS rules in different stylesheets that are applied to an element. For specificity, if you have a `<div>` in a component with multiple selectors with the same property, the browser uses the property that's defined the latest, or `background: red` in this example.

```css
div {
  background: green;
}

div {
  background: red;
}
```

To increase the specificity of a selector, use a CSS class or include the element that the selector appears under. ID selectors aren't supported as they are transformed into globally unique values at runtime. In this example, adding the `lightning-card` element targets the `<div>` tags and increases the specificity.

```css
lightning-card div {
  background: green;
}

div {
  background: red;
}
```

Using a CSS class selector is more specific. A `<div>` tag that uses the `.somecolor` class selector gets `background: blue;` instead of the latest definition `background:red`.

```css
.somecolor {
  background: blue;
}

lightning-card div {
  background: green;
}

div {
  background: red;
}
```

## CSS Property Inheritance

CSS inheritance applies if no cascaded value is found. Some CSS property values like `color` and `font` are inherited from parent elements. Consider this HTML markup in a component.

```html
<div>Some <span>text</span></div>
```

Given this CSS class selector, "Some text" is rendered in red because the `color` property is inherited from the `<div>` parent element.

```css
div {
  color: red;
}
```

Not all properties can inherit colors from a parent element. To check if the CSS property is inherited, review the [W3C](https://www.w3.org/TR/CSS21/propidx.html) or MDN documentation. If the property is inherited, the styles of the parent apply to the children. If it's not an inherited property, such as the `border` property, the property is set to the initial value.

## Cascaded Styles vs Inherited Styles

Shadow DOM prevents cascaded styles from affecting your component, but the same isn't true with inherited styles. Cascaded styles don't traverse the shadow boundary, while inherited values do traverse the shadow boundary.

In this example, the text in the `c-child` component is red although `c-child` renders in shadow DOM. Since `color` is an inherited property, it's inherited through the shadow DOM as well.

```html
<div>
  <c-child></c-child>
</div>
```

```css
div {
  color: red;
}
```

Additionally, [CSS custom properties](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md) also traverse shadow boundaries.

## CSS Support and Performance Impact

The CSS scoping matches the [CSS Scoping Module Level 1 standard](https://drafts.csswg.org/css-scoping/), with a few exceptions.

- No support for the [`:host-context()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:host-context) pseudo-class function.
- No support for the [`::part`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) pseudo-element.
- No support for ID selectors in CSS. Make sure that `id` values are unique within your HTML template. When the template renders, `id` values can transform into globally unique values. If you use an ID selector in CSS, it won’t match the transformed ID.
- LWC doesn’t reflect a component’s custom public properties into their corresponding HTML attributes. To give identity to a child element for styling, use a `class` attribute or a `data-*` attribute.

Scoped CSS affects performance, so use it with care. Each selector chain is scoped, and each compound expression that's passed to `:host()` is spread into multiple selectors. This transformation increases the size and complexity of the generated CSS. These increases mean more bits on the wire, longer parsing time, and longer style recalculation time.

To ensure CSS encapsulation, each element has an extra attribute, which also increases rendering time. For example, the `<c-parent>` element has a `c-parent_parent-host` attribute.

```html
<c-parent c-parent_parent-host>
  <h1 c-parent_parent>To Do List</h1>
  <c-child c-parent_parent c-child_child-host>
    <h1 c-child_child>To Do Item</h1>
  </c-child>
  <c-child class="active" c-parent_parent c-child_child-host>
    <h1 c-child_child>To Do Item</h1>
  </c-child>
</c-parent>
```

## Assign CSS Stylesheets to a Component

To customize a component with one or more stylesheets, add the `stylesheets` static property to the `LightningElement` constructor. This property accepts an array of stylesheets, and its default value is an empty array. You can set the `stylesheets` property for light DOM and shadow DOM components.

For example, to inject the `header-styles.css` and `button-styles.css` stylesheets into `myComponent`, configure the `stylesheets` static property in `myComponent.js`.

```ascii
myComponent/
    ├── myComponent.js
    ├── myComponent.html
    ├── myComponent.css
    ├── header-styles.css
    └── button-styles.css

```

```javascript
// myComponent.js
import { LightningElement } from "lwc";
import headerStyles from "./header-styles.css";
import buttonStyles from "./button-styles.css";

export default class Example extends LightningElement {
  static stylesheets = [headerStyles, buttonStyles];
}
```

The first stylesheet that the LWC engine injects is `myComponent.css`, as it's implicitly associated with the component’s template. Then the engine loads all the stylesheets associated with the `stylesheets` property in the order that they’re listed inside the array. Based on this configuration of `stylesheets`, `myComponent` loads its stylesheets in this order: `myComponent.css`, `header-styles.css`, and `button-styles.css`.

The LWC engine caches the `stylesheets` array for the lifetime of the application during the component class definition. If you modify `stylesheets` after the component’s code is evaluated, it won’t affect the injected stylesheets.

A subclass component doesn’t automatically inherit `stylesheets` from a superclass component. If you want to extend `stylesheets` from a superclass component to a subclass component, use `super.stylesheets` to manually merge the superclass `stylesheets` with the stylesheets for the subclass component.

```javascript
import { LightningElement } from "lwc";
import superclassStylesheet from "./superclass.css";
import subclassStylesheet from "./subclass.css";

class Superclass extends LightningElement {
  static stylesheets = [superclassStylesheet];
}

class Subclass extends Superclass {
  static stylesheets = [...super.stylesheets, subclassStylesheet];
}
```

**See Also**

- [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create-components-slots.md)
- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create-dom.md)
- [Anti-Patterns for Styling Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-antipatterns.md)

<!-- document id=edb326b4147a1ba2b9247a158240aaac080bea5b58435a723524c03b6912845b url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-slds.md -->

# Style Components with Lightning Design System

Salesforce Lightning Design System (SLDS) is a CSS framework that provides the look and feel of Lightning Experience. SLDS includes styles, themes, branding, and customizations for Lightning Experience. Use SLDS styles to give your custom Lightning web components a UI that is consistent with Salesforce. And best of all, SLDS just works with Lightning components running in Lightning Experience.

In Spring ’25, we introduced [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2). This new SLDS architecture prioritizes CSS custom properties. We offer new tools that make it easier to validate your components against SLDS rules and migrate components to SLDS 2. The new SLDS 2 site has a [Transition to SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2) guidebook to get your org up and running with SLDS 2.

**tip:** The [lightningdesignsystem.com](http://lightningdesignsystem.com) site now presents SLDS 2 content. The SLDS 1 content is available at [v1.lightningdesignsystem.com](http://v1.lightningdesignsystem.com).

## Analyze Component Code with SLDS Linter

SLDS Linter is the latest code analysis tool that helps smooth your org’s transition to SLDS 2 and future-proofs your code. SLDS Linter provides many advantages over our previous tool, SLDS Validator. SLDS Linter is easier to set up, offers increased automation, and contains a more robust library of rules reflecting the new SLDS 2 styling guidelines.

Use SLDS Linter to help prepare your components for use in SLDS 2. SLDS Linter analyzes your code against SLDS 2 rules. It offers suggestions on how to improve your code and make it more future-proof. SLDS Linter can also automatically make suggested fixes to your code and apply those suggestions in bulk across your repository.

For more information, see [SLDS Linter](https://www.lightningdesignsystem.com/2e1ef8501/p/012d73-slds-linter) on the SLDS 2 site.

## Analyze Component Code with SLDS Validator

SLDS Validator for VS Code scans your component markup and CSS, validates it against a set of SLDS guidelines, and provides recommendations to improve your code. The SLDS Validator extension simplifies working with [Salesforce Lightning Design System (SLDS) 1](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://lightningdesignsystem.com).

Use SLDS Validator to help get your components ready for SLDS 2 and its default theme, Salesforce Cosmos. With SLDS Validator, you get:

- SLDS 1 and SLDS 2 support
- Validation with recommended styling hooks and utility classes
- Syntax highlighting
- Code completion
- Context awareness
- Bulk report generation

SLDS Validator helps you transition your component styling from legacy SLDS 1 design tokens to global styling hooks, correct the BEM syntax used in SLDS classes, and more. If you’re going to stick with SLDS 1 for now, SLDS Validator can help with that too.

SLDS Validator also simplifies working with Lightning base components. You can enable [SLDS validation for mobile](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/ux_extensions_base_component_validation.htm), color contrast detection, and more. To install SLDS Validator, go to the extension page on [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforce-vscode-slds). To learn more, read the [SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/overview) developer guide.

**note:** When you install the [Salesforce Extension Pack](https://developer.salesforce.com/docs/platform/get-started/get-started-editor-linter-org.md), SLDS Validator is automatically installed, so you might already have it. For more information, see [SLDS Validator for VS Code](https://www.lightningdesignsystem.com/tools/validator/).

## Use Lightning Base Components

Base components in the `lightning` namespace use Salesforce Lightning Design System styling. Salesforce used the SLDS component blueprints to build the base components that create visible UI elements. A blueprint is framework-agnostic, accessible HTML and CSS that defines how a component looks and its user interaction, but doesn’t provide logic. The base components do include JavaScript logic and provide attributes, events, and methods to enable you to interact with your org’s data. A few examples of base components include the `lightning-accordion`, `lightning-button`, `lightning-card`, and `lightning-tree` components.

Base components provide a `class` attribute so that you can add an SLDS utility class or custom class to the outer elements of the components. For example, to apply a margin utility class to the `lightning-button` base component, use `class="slds-m-left_medium"`. Here it’s used to increase the margin between buttons.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button 
    label="Submit" 
    title="submit" 
    onclick={handleSubmit}
></lightning-button>
  <lightning-button
    variant="brand"
    label="Cancel"
    title="cancel"
    onclick={handleCancel}
    class="slds-m-left_medium"
  ></lightning-button>
</template>
```

Some components provide a `variant` attribute so that you can apply a design variation easily. For example, `lightning-button` has a `variant` attribute that you can set to base, neutral, brand, brand-outline, destructive, destructive-text, inverse, and success. These values implement the [button blueprint’s variations](https://v1.lightningdesignsystem.com/components/buttons/#Variations).

**important:** When styling your components, don’t depend on the internal markup or CSS classes of Lightning base components, as they can change in future releases. To display correctly in Salesforce Lightning Design System (SLDS) 2, components whose styling depends on internal markup must migrate to global styling hooks. For more information, see [Transition to SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2).

Overriding base component styling isn't supported except when using documented styling hooks. See [Anti-Patterns for Styling Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-antipatterns.md).

## Use Lightning Base Component Design Variations and Utility Classes

To change the styling of a Lightning base component, first check that component's documentation in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) to see if it has [design variations](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-variants.md). These can be specified with component attributes such as `variant` or `type`, for example. To change the spacing of a component, such as the alignment, padding, margin, or even its typography, use [Lightning Design System utility classes](https://v1.lightningdesignsystem.com/utilities/alignment/).

## Use Styling Hooks to Customize Default Styles

If design variations and utility classes don’t meet your requirements, use styling hooks. For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md).

## Apply Custom CSS Classes

To further customize your code, create your own custom CSS classes instead of overriding SLDS classes. For example, don’t target `.slds-input` because it’s part of the base component internal markup. Instead, create a custom class and pass it into the `class` attribute.

Custom components that run in Lightning Experience or in the Salesforce mobile application can use Lightning Design System without any `import` statements or static resources. Simply assign a Lightning Design System CSS class to an HTML element. For example, you can apply SLDS styling to a standard button element in your component.

```html
<button class="slds-button">Click here</button>
```

What if you want different padding in your button? You can’t override the `slds-button` class because Salesforce doesn’t support that.

This example shows the correct way to get the styling you want by creating your own custom style with its value set using an SLDS global styling hook. In the default SLDS themes, the `--slds-g-spacing-4` styling hook is equivalent to 16px or 1rem in most browsers. The example follows our recommendation of providing a fallback value when setting CSS variables to accommodate all environments where a component can run. The `--lwc-spacingMedium` property is a fallback value for SLDS 1 themes. The static value `1rem` is a fallback value for an environment without SLDS.

```css
/* DON’T DO THIS */
.slds-button {
  padding: 16px;
}

/* Do this */
.my-button-padding {
  padding: var(--slds-g-spacing-4, var(--lwc-spacingMedium, 1rem));
```

**tip:** While working with SLDS 2 global styling hooks, always assign an SLDS 1 fallback value. To find the correct fallback value, refer to our documentation on our [SLDS 1](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2) websites. Search for the component type or the styling hook to determine appropriate values.

Apply your styling incrementally. In this example, apply the `slds-button` class and your `my-button-padding` class in the `class` attribute.

```html
<button class="slds-button my-button-padding"></button>
```

Practice good CSS habits and don’t overload a selector. Here's an example of overloaded selectors.

```css
/* DON’T DO THIS */
button.button {
  ...;
}
.card > * {
  ...;
}
.button {
  margin-bottom: 18px !important;
}
body.container > div.sidebar > article.card {
  ...;
}
```

## Create Custom Components from Base Components

To build a Lightning web component, compose it by combining simpler `lightning` base components into a more complex, custom component. Try to construct your design from components like buttons and media objects. For more information, see [Work with Lightning Base Components](https://developer.salesforce.com/docs/platform/base-components/base-components-overview.md/).

Use utilities such as grid and spacing classes for layout. When you add new functionality to the component, search our [SLDS 1](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2) websites for patterns that work and apply the classes to the template.

For example, use the [utility classes](https://www.lightningdesignsystem.com/2e1ef8501/p/05098e-utility-classes) to change your header size or add padding to your `div` containers.

```html
<template>
  <h1 class="slds-text-heading_large">SLDS Example</h1>
  <div class="slds-p-top_medium">
    <p>Hello!</p>
  </div>
</template>
```

## Create Custom Components from Lightning Design System Blueprints

If you can’t find a base component for your use case, find the closest SLDS blueprint to help you build your component. See [Create a Component from an SLDS Blueprint](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds-blueprint.md).

**See Also**

- [Lightning Design System: Global Color Styling Hooks](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks/)

<!-- document id=135cf21d4b5c3fd6d985b71514a8bbe6d914e73ff1fa84041f8d83d084f04044 url=/developer/current/en-us/lwc/lwc/guides/use/message-channel/use-message-channel-subscribe.md -->

# Subscribe and Unsubscribe from a Message Channel

To subscribe and unsubscribe from messages on a message channel, import the message channel from the `@salesforce/messageChannel` scoped module into your Lightning web component. Call the Lightning message service’s `subscribe()` and `unsubscribe()` functions.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has an `lmsSubscriberWebComponent` component that shows how to subscribe and unsubscribe from a message channel. This example works with the publisher component from [Publish on a Message Channel](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-channel-publish.md).

Let's take a look at the [`lmsSubscriberWebComponent` component](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/lmsSubscriberWebComponent). Selecting a contact from the publisher component publishes the selected record ID to the `Record_Selected__c` message channel.

The subscriber component's HTML reacts to the published message and displays the data for the contact whose record ID was supplied through the message payload.

<!-- prettier-ignore -->
```html
<!-- lmsSubscriberWebComponent.html -->
<template>
  <lightning-card title="LMSSubscriberWebComponent" icon-name="custom:custom30">
    <div class="slds-m-around_medium">
      <template lwc:if={Picture__c}>
        <img src={Picture__c} alt="Profile photo" />
      </template>
      <p>{Name}</p>
      <p>{Title}</p>
      <p>
        <lightning-formatted-phone value={Phone}></lightning-formatted-phone>
      </p>
      <p>
        <lightning-formatted-email value={Email}></lightning-formatted-email>
      </p>
    </div>
  </lightning-card>
</template>
```

In the component’s JavaScript, import the message service features required for subscribing from `lightning/messageService`. Import the `Record_Selected__c` message channel from `@salesforce/messageChannel`.

Use `@wire(MessageContext)` to create a Context object, which provides information about the Lightning web components that are using the Lightning message service. A component must be attached to the DOM before it can use the property decorated with `@wire(MessageContext)`.

The `subscribeToMessageChannel()` function checks whether `subscription` is null. If the subscription is null, it calls the Lightning message service's `subscribe()` method and assigns it to `subscription`. The `subscribe()` method takes three required parameters, the message context, the name of the message channel, and a listener method that handles the published message. When the listener method is invoked, it passes the message to `handleMessage()`. `handleMessage()` extracts the `recordId` property from the JSON message payload that it received. The HTML template is then updated with the information related to the contact that matches the record Id.

To receive messages on a message channel from anywhere in the application, pass `{ scope: APPLICATION_SCOPE }` as the `subscribe()` method's optional fourth parameter. See [Define the Scope of the Message Service](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-channel-scope.md).

To stop receiving messages from the Lightning message service, call `unsubscribe()`, passing in a subscription reference. The `subscription` object contains a reference to the subscription you want to unsubscribe from. This example calls `unsubscribeToMessageChannel()`, which calls `unsubscribe()` and then sets `subscription` to null.

```javascript
// lmsSubscriberWebComponent.js
import { LightningElement, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { reduceErrors } from "c/ldsUtils";

// Import message service features required for subscribing and the message channel
import {
  subscribe,
  unsubscribe,
  APPLICATION_SCOPE,
  MessageContext,
} from "lightning/messageService";
import recordSelected from "@salesforce/messageChannel/Record_Selected__c";

import NAME_FIELD from "@salesforce/schema/Contact.Name";
import TITLE_FIELD from "@salesforce/schema/Contact.Title";
import PHONE_FIELD from "@salesforce/schema/Contact.Phone";
import EMAIL_FIELD from "@salesforce/schema/Contact.Email";
import PICTURE_FIELD from "@salesforce/schema/Contact.Picture__c";

const fields = [NAME_FIELD, TITLE_FIELD, PHONE_FIELD, EMAIL_FIELD, PICTURE_FIELD];

export default class LmsSubscriberWebComponent extends LightningElement {
  subscription = null;
  recordId;

  Name;
  Title;
  Phone;
  Email;
  Picture__c;

  @wire(getRecord, { recordId: "$recordId", fields })
  wiredRecord({ error, data }) {
    if (error) {
      this.dispatchToast(error);
    } else if (data) {
      fields.forEach((item) => (this[item.fieldApiName] = getFieldValue(data, item)));
    }
  }

  @wire(MessageContext)
  messageContext;

  // Encapsulate logic for Lightning message service subscribe and unsubsubscribe
  subscribeToMessageChannel() {
    if (!this.subscription) {
      this.subscription = subscribe(
        this.messageContext,
        recordSelected,
        (message) => this.handleMessage(message),
        { scope: APPLICATION_SCOPE },
      );
    }
  }

  unsubscribeToMessageChannel() {
    unsubscribe(this.subscription);
    this.subscription = null;
  }

  // Handler for message received by component
  handleMessage(message) {
    this.recordId = message.recordId;
  }

  // Standard lifecycle hooks used to subscribe and unsubsubscribe to the message channel
  connectedCallback() {
    this.subscribeToMessageChannel();
  }

  disconnectedCallback() {
    this.unsubscribeToMessageChannel();
  }

  // Helper
  dispatchToast(error) {
    this.dispatchEvent(
      new ShowToastEvent({
        title: "Error loading contact",
        message: reduceErrors(error).join(", "),
        variant: "error",
      }),
    );
  }
}
```

**note:** If you create an API module component that isn’t a `LightningElement`, you can’t use `@wire(MessageContext)` to create the `MessageContext` object. Instead, import `createMessageContext()` and `releaseMessageContext()` methods from `lightning/messageService`. Use `createMessageContext()` to create the Context object and assign it to a field, like `messageContext`. Then, pass `messageContext` into the `subscribe()` method. The context isn’t automatically released for API module components. Call `releaseMessageContext(messageContext)` to remove any subscriptions associated with your component’s message context.

**See Also**

- [Component Reference: lightning/messageService](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-message-service)

<!-- document id=62dbf9eee9fc2c167ca0e2321b75398bea58e2fee9426458e00610e4e9d5f055 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-containers.md -->

# Supported App Containers for Base Components

Base components are designed and built to be platform-agnostic, which means they can be used across different apps - Lightning Experience, Experience Builder sites, Salesforce mobile app, and even with open-source LWC. However, many base components have dependencies on the Salesforce platform. For example:

- `lightning-record-edit-form`, `lightning-record-form`, and `lightning-record-view-form` work with Salesforce record data only. The same applies to `lightning-input-field` and `lightning-output-field`.
- API modules that implement Lightning Data Service, like `lightning/uiRecordApi` and `lightning/uiGraphQLApi`
- API modules that make calls to Salesforce APIs like `lightning/platformUtilityBarApi` and `lightning/serviceKnowledgeApi`

For supported container information for a base component, refer to the Targets panel for a base component in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

Base components can be used on Lightning Web Runtime (LWR) sites. However, only a subset of base components support [server-side rendering](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.html).

**See Also**

- [Use Components in Salesforce Targets](https://developer.salesforce.com/docs/platform/lwc/use/use.md)
- [Version Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/create/create-version-components.md)

<!-- document id=a82f0500651cf044101787341f9884b6ed2119790ec790948d0be4be686e4e49 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-supported-attributes.md -->

# Supported Attributes for the Property Tag in the js-meta.xml File

The `js-meta.xml` file for a custom Lightning web component can have the `targetConfig` of `lightningCommunity__Default`. In this case, certain attributes for the property tag have additional considerations when they're used with a property that references a custom property type.

These are the attributes that you can use for the property tag.

- name
- type
- datasource
- default
- description
- exposedTo
- filter
- label
- max
- min
- placeholder
- required
- screenResponsive

Here are the implications of using some of these attributes with a property that references a custom property type.

| Attribute          | Implications                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`             | Salesforce supports five standard property types for Lightning web components in Experience Builder: `String`, `Integer`, `Boolean`, `ContentReference`, and `Color`. You can use all these types together with properties that reference custom property types. If the Lightning web component is used in a site or managed package, you can update the `type` value if the original value references an `ExperiencePropertyTypeBundle` or a custom `LightningTypeBundle` and the updated value is referencing a custom `LightningTypeBundle`. Check to be sure there are no breaking changes in the schema of the new type. (For information on breaking changes, see [Object-Based Custom Lightning Types Modification Guidelines](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-object.html) in the Lightning Types Developer Guide.) |
| `exposedTo`        | This attribute is required if you use the `screenResponsive` attribute. The valid value is `css`. This feature works for LWR sites only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `screenResponsive` | For properties that reference custom property types that have an underlying JSON schema type of string, integer, or number, you can specify this attribute to indicate whether the property is screen responsive. This feature works for LWR sites only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `translatable`     | When you specify `translatable="true"`, you indicate that this component property can hold different values for each language that you support in your Experience Cloud site. You can specify the translatable attribute in a property tag only when the custom property type that's being referenced has an underlying JSON schema type of string. For example, you can add `translatable="true"` to properties that reference these types. `lightning__textType` `lightning__multlineTextType` `lightning__richTextType` `lightning__urlType` `lightning__dateType` When you specify `translatable="true"` for a property of `type="lightning__richTextType"`, the property's value is exported in rich text format in the .xlf file via the Export Content feature in Experience Builder. All other types are exported as plain text.                                         |

**See Also**

- [`lightningCommunity__Default` Target](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-community-default.html)

<!-- document id=d1daa1df428a3e20b57ca50ce7159d3ada8c50099bdc2cd0eacf505bfdfe5dad url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-supported-browsers.md -->

# Supported Browsers

Lightning Web Components supports the same browsers as Lightning Experience. See the [supported browsers for Lightning Experience](https://help.salesforce.com/articleView?id=getstart_browsers_sfx.htm).

Salesforce ended support for Internet Explorer 11 in Lightning Experience and Salesforce Classic on January 1, 2023. After Winter '24, you can no longer use Internet Explorer 11 and other legacy browsers to view or access Lightning Experience. If you have code that uses one of the unsupported browsers, you can delete it. We recommend accessing Lightning Experience in the latest version of a supported browser.

## Browser Extensions

While there are many third-party browser extensions that personalize and enhance your Salesforce experience, we recommend that you check [AppExchange](https://appexchange.salesforce.com/) for browser extensions and apps from Salesforce partners, or the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) for base components that match your requirements.

Salesforce doesn't provide support for third-party browser extensions. Using third-party browser extensions is at your own risk. Salesforce can’t prevent these extensions from accessing your Salesforce data, nor can we detect that there’s any attempt to access your data.

## Browser Extensions with DOM Manipulation

Some third-party browser extensions inject custom scripts to manipulate the DOM. We don't recommend nor support such third-party browser extensions for these reasons:

- Browser extensions that manipulate the DOM (such as inserting or removing elements in the DOM) can interfere with the stability of Lightning Experience and lead to unexpected behavior.
- Browser extensions that don’t follow Salesforce security standards can fail to work properly in Lightning Experience.
- The internal DOM structure of Lightning Experience can change in a future release, and compatibility with a third-party browser extension isn’t guaranteed.

If you need to work with the DOM, check if you can [use a JavaScript library via `lightning/platformResourceLoader`](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md) instead.

**See Also**

- [Leveraging the Newest ESXX Features in LWC](https://developer.salesforce.com/blogs/2021/02/leveraging-the-newest-esxx-features-in-lwc.html)
- [_Salesforce Developers' Blog_: The Lightning Platform plans to end support for IE11 in Lightning Experience & Salesforce Classic](https://developer.salesforce.com/blogs/2022/06/ending-support-for-ie11-on-the-lightning-platform)
- [_Salesforce Help_: Considerations for Microsoft Internet Explorer](https://help.salesforce.com/s/articleView?id=xcloud.getstart_browser_considerations_ie.htm)

<!-- document id=a111f0007521a17d259853d3cf0ea30e126153ab61d7b691a2ffbadba2fc6634 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-data-types.md -->

# Supported Data Types in Flows

Not all custom Lightning web component data types are supported in flows. You can map only these types and their associated collection types between flows and custom Lightning web components.

| Flow Data Type                                    | Lightning Web Components Data Type                          | Valid Values                                                                                                                                                                                                                                                              |
| ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Apex (Flow Label: Apex-Defined)                   | Custom Apex class                                           | Apex classes that define `@AuraEnabled` fields. Supported data types in an Apex class are Boolean, Integer, Long, Decimal, Double, Date, DateTime, and String. Each data type supports single values and Lists.                                                           |
| Boolean                                           | Boolean                                                     | True values: <ul><li>`true`</li><li>`1`</li><li>An equivalent expression</li></ul>False values:<ul><li>`false`</li><li>`0`</li><li>An equivalent expression</li></ul>                                                                                                     |
| Currency                                          | Integer                                                     | Numeric value or equivalent expression                                                                                                                                                                                                                                    |
| Date                                              | Date                                                        | `"YYYY-MM-DD"` or equivalent expression                                                                                                                                                                                                                                   |
| DateTime (Flow Label: Date/Time)                  | DateTime                                                    | `"YYYY-MM-DDThh:mm:ssZ"` or equivalent expression                                                                                                                                                                                                                         |
| Email                                             | String                                                      | Email addresses                                                                                                                                                                                                                                                           |
| Number                                            | Number                                                      | Numeric value or equivalent expression                                                                                                                                                                                                                                    |
| Multipicklist (Flow Label: Multi-Select Picklist) | String                                                      | String value or equivalent expression using a semi-colon delimited format: "Blue; Green; Yellow"                                                                                                                                                                          |
| Percent                                           | Double                                                      | Percent values                                                                                                                                                                                                                                                            |
| Phone                                             | String                                                      | Phone numbers. Values can include alphabetic characters.                                                                                                                                                                                                                  |
| Picklist                                          | String                                                      | String value or equivalent expression                                                                                                                                                                                                                                     |
| sObject (Flow Label: Record)                      | The API name of the specific object such as Account or Case | Map of key-value pairs or equivalent expression. Flow record values map only to attributes whose type is the specific object. For example, an account record variable can be mapped only to an attribute whose type is Account. Flows don’t support the Object data type. |
| String (Flow Label: Text)                         | String                                                      | String value or equivalent expression                                                                                                                                                                                                                                     |
| URL                                               | String                                                      | URL values. Client applications commonly display URLs as hyperlinks.                                                                                                                                                                                                      |

<!-- document id=39fa1d20c8ace1e43469f222b35ebf6e843aa6ec380d28d3a703951e41900a29 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-types.md -->

# Supported Expression Types

Template expressions can contain any JavaScript expression that is valid in a template context. This topic enumerates and provides a wide range of examples of supported expression types. For some restrictions on expressions in an HTML template, see [HTML Syntax Compatibility](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-expressions-compatibility.md).

## Literals

All JavaScript literal types are supported in template expressions.

### String Literals

While you don't need an expression to display a simple string in a template, string literals can be useful when composing user interface messages. See [Template Literals](#template-literals).

```html
<template>
  <div>{'Hello World'}</div>
</template>
```

### Numeric Literals

All numeric literal formats are supported:

```html
<template>
  <!-- Integer literals -->
  <div>{42}</div>

  <!-- Float literals -->
  <div>{42.42}</div>

  <!-- Binary literals -->
  <div>{0b1001011}</div>

  <!-- Octal literals -->
  <div>{0o42}</div>

  <!-- Hexadecimal literals -->
  <div>{0x42}</div>

  <!-- Exponentiation -->
  <div>{2 ** 3}</div>
</template>
```

### Boolean Literals

```html
<template>
  <div>{true}</div>
  <div>{false}</div>
</template>
```

### Null Literal

```html
<template>
  <div>{null}</div>
</template>
```

## Template Literals

Template literals allow you to embed expressions inside string literals using `${}` syntax.

```html
<template>
  <div>{`User: ${firstName} ${lastName}`}</div>
  <div>{`Status: ${isActive ? 'Active' : 'Inactive'}`}</div>
  <div>{`Price: $${price.toFixed(2)}`}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class TemplateLiteralsComponent extends LightningElement {
  firstName = "John";
  lastName = "Doe";
  isActive = true;
  price = 99.99;
}
```

_Tagged template literals_ are also supported:

```html
<template>
  <div>{formatCurrency`Total: ${amount}`}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class TaggedTemplateComponent extends LightningElement {
  amount = 100;

  formatCurrency(strings, amount) {
    return `$${amount.toFixed(2)}`;
  }
}
```

See [Tagged Templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) at MDN for additional details regarding tagged template literals.

**note:** Being too adventurous with tagged templates can lead to hard-to-understand template markup. Template expressions are intended to simplify your code. Take advantage of it.

## Identifiers and Member Expressions

Direct property access and member expressions are fully supported.

```html
<template>
  <div>{ hello().world }</div>
  <div>{ anotherWorld.sayHello() }</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class IdentifiersComponent extends LightningElement {
  hello() {
    return {
      world: "Hi there!",
    };
  }

  anotherWorld = {
    sayHello: () => "Hello from a function!",
  };
}
```

## Ternary Operators

Conditional expressions using the ternary operator (`? :`) for dynamic content.

```html
<template>
  <div>{isLoggedIn ? 'Welcome back!' : 'Please log in'}</div>
  <div>{age >= 18 ? 'Adult' : 'Minor'}</div>

  <!-- Compact form without spaces -->
  <div>{darkMode?nowItsDark:seeTheLight}</div>

  <!-- Nested ternary -->
  <div>{score > 80 ? 'Excellent' : score > 60 ? 'Good' : 'Needs Improvement'}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class TernaryComponent extends LightningElement {
  isLoggedIn = true;
  age = 25;
  score = 75;
  darkMode = true;
  nowItsDark = "Dark value";
  seeTheLight = "Light value";
}
```

## Logical Operators

Logical AND (`&&`) and OR (`||`) operators for conditional rendering and fallback values.

```html
<template>
  <div>{user && user.name}</div>
  <div>{error || 'No error occurred'}</div>
  <div>{isValid && isSubmitted && 'Form submitted successfully'}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class LogicalOperatorsComponent extends LightningElement {
  user = { name: "John Doe" };
  error = null;
  isValid = true;
  isSubmitted = true;
}
```

## Unary Operators

Various unary operators are supported.

### Logical NOT

```html
<template>
  <div>{!foo}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class LogicalNotComponent extends LightningElement {
  foo = true;
}
```

### Bitwise NOT

```html
<template>
  <div>{~foo}</div>
  <div>{~bar}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class BitwiseNotComponent extends LightningElement {
  foo = 5;
  bar = 10;
}
```

### typeof Operator

```html
<template>
  <div>{typeof foo}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class TypeofComponent extends LightningElement {
  foo = "test";
}
```

### void Operator

```html
<template>
  <div>{void bar}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class VoidComponent extends LightningElement {
  bar = "value";
}
```

## Binary Operators

All binary operators are supported for various operations.

### Arithmetic Operators

```html
<template>
  <div>{high + low}</div>
  <div>{high - low}</div>
  <div>{high * low}</div>
  <div>{high / low}</div>
  <div>{high ** low}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ArithmeticComponent extends LightningElement {
  high = 10;
  low = 3;
}
```

### Relational Operators

```html
<template>
  <div>{big > little}</div>
  <div>{little > big}</div>
  <div>{big >= little}</div>
  <div>{big === little}</div>
  <div>{big !== little}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class RelationalComponent extends LightningElement {
  big = 10;
  little = 5;
}
```

**important:** Expressions must be HTML compliant because they are parsed as HTML. The “`<”` character in text node expressions like `{foo < bar}` would be interpreted as the opening of an HTML tag, causing a parsing error. However, `<` is allowed in attribute expressions when properly quoted.

- In text nodes: Use `{bar > foo}` instead of `{foo < bar}`
- In attributes: `{foo < bar}` works when quoted: `attr="{foo < bar}"`

See [HTML Syntax Compatibility](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-expressions-compatibility.md) for additional details.

### Bitwise Operators

```html
<template>
  <div>{foo & bar}</div>
  <div>{foo | bar}</div>
  <div>{foo ^ bar}</div>
  <div>{foo >> bar}</div>
  <div>{bar >> foo}</div>
  <div>{bar >>> foo}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class BitwiseComponent extends LightningElement {
  foo = 12; // 1100 in binary
  bar = 5; // 0101 in binary
}
```

## Function Calls

Call methods and functions directly in templates.

**tip:** Put your formatting functions in a separate [API module component](https://developer.salesforce.com/docs/platform/lwc/js/js-share-code.md) that you can easily import into any component that use them.

```html
<template>
  <div>{formatCurrency(price)}</div>
  <div>{getFullName(firstName, lastName)}</div>
  <div>{items.map(item => item.name).join(', ')}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class FunctionCallsComponent extends LightningElement {
  price = 99.99;
  firstName = "John";
  lastName = "Doe";
  items = [{ name: "Item 1" }, { name: "Item 2" }, { name: "Item 3" }];

  formatCurrency(price) {
    return `$${price.toFixed(2)}`;
  }

  getFullName(first, last) {
    return `${first} ${last}`;
  }
}
```

## Optional Call Expressions

Optional chaining for function calls is supported.

```html
<template>
  <div>{foo?.(bar)}</div>
  <div>{baz?.buzz?.(42)}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class OptionalCallComponent extends LightningElement {
  bar = "test";

  connectedCallback() {
    this.foo = (value) => `Called with: ${value}`;
    this.baz = {
      buzz: (value) => `Buzz called with: ${value}`,
    };
  }
}
```

## Array Expressions

Create and manipulate arrays inline.

```html
<template>
  <div>{[firstName, lastName].join(' ')}</div>
  <div>{items.length > 0 ? `Found ${items.length} items` : 'No items'}</div>
  <div>{[1, 2, 3, 4, 5].reduce((a, b) => a + b, 0)}</div>
  <div>{[1, bar, 'baz']}</div>
  <div>{['flop', floo, 2].join('')}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ArrayExpressionsComponent extends LightningElement {
  firstName = "John";
  lastName = "Doe";
  items = ["item1", "item2", "item3"];
  bar = "bar value";
  floo = "floo value";
}
```

## Object Expressions

Create object literals and access their properties.

```html
<template>
  <div>{({ name: 'John', age: 30 }).name}</div>
  <div>{({ status: 'active' }).status}</div>
</template>
```

## Optional Chaining and Nullish Coalescing

Safe property access, and null and undefined handling.

```html
<template>
  <div>{user?.profile?.name ?? 'Anonymous'}</div>
  <div>{settings?.theme || 'default'}</div>
  <div>{data?.items?.length ?? 0}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class OptionalChainingComponent extends LightningElement {
  user = {
    profile: {
      name: "John Doe",
    },
  };
  settings = { theme: "dark" };
  data = { items: [1, 2, 3] };
}
```

## Computed Properties

Dynamic property access using bracket notation.

```html
<template>
  <div>{user['firstName']}</div>
  <div>{items[selectedIndex]}</div>
  <div>{config[`${prefix}Setting`]}</div>
  <div>{bar.baz.arr[quux]}</div>
  <div>{bar.arr[baz.quux]}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ComputedPropertiesComponent extends LightningElement {
  user = { firstName: "John" };
  items = ["item1", "item2", "item3"];
  selectedIndex = 1;
  config = { mySetting: "value" };
  prefix = "my";
  bar = {
    arr: ["a", "b", "c"],
    baz: {
      arr: ["x", "y", "z"],
    },
  };
  baz = { quux: 0 };
  quux = 2;
}
```

## Arrow Functions

Arrow functions can be used for inline transformations and callbacks.

```html
<template>
  <div>{items.map(item => item.name.toUpperCase())}</div>
  <div>{numbers.filter(n => n > 10).length}</div>
  <div>{users.find(user => user.id === currentId)?.name}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ArrowFunctionsComponent extends LightningElement {
  items = [{ name: "apple" }, { name: "banana" }, { name: "cherry" }];
  numbers = [5, 15, 25, 35];
  users = [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
    { id: 3, name: "Charlie" },
  ];
  currentId = 2;
}
```

### Assignment Inside Arrow Functions

Assignment operations are allowed inside arrow functions.

```html
<template>
  <button onclick="{() => myField = 'foo'}">Set Label</button>
  <button onclick="{() => foo++}">Increment Foo</button>
  <div>Field: {myField}</div>
  <div>Foo: {foo}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class AssignmentComponent extends LightningElement {
  myField = "";
  foo = 0;
}
```

## Iterator Support

Expressions work within iterator directives.

```html
<template>
  <template for:each="{getBentoItems()}" for:item="okazu">
    <div key="{okazu}">
      <a onclick="{() => taberu(okazu)}">
        one
      </a>
    </div>
  </template>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class IteratorComponent extends LightningElement {
  allItems = ["sushi", "tempura", "miso", "ramen"];

  getBentoItems() {
    return this.allItems.filter((item) => item !== "ramen");
  }

  taberu(item) {
    alert(`Eating ${item}`);
  }
}
```

See [Example: Render Lists with Template Expressions](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-html-expressions-example-lists-iterators.md) for an extended example and discussion of using iterators in template expressions.

## LWC Directive Compatibility

Complex expressions work with LWC directives like `if:true`.

```html
<template>
  <template if:true="{state.isTrue && user?.isActive}">
    {foo} {bar}
  </template>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class DirectiveComponent extends LightningElement {
  state = { isTrue: true };
  user = { isActive: true };
  foo = "foo value";
  bar = "bar value";
}
```

<!-- document id=aa00fcefccdfd01c6efdf0b9c8cf2cecf1bd65ac5d11655c7d3187682482fe78 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-supported-javascript.md -->

# Supported JavaScript

To develop Lightning web components, use the latest versions of JavaScript.

LWC supports the same browsers as Lightning Experience—the latest stable versions of Edge, Chrome, Firefox, and Safari. To develop Lightning web components for these browsers, you can use any JavaScript feature that the browser supports and that Lightning Locker allows.

[Lightning Web Security (LWS)](/docs/platform/lightning-components-security/guide/lws-intro.html) is a newer security architecture for Lightning components that Salesforce first introduced in Spring ’22. LWS is based on the latest web standards and helps prevent unsafe code behavior by running components in virtual JavaScript sandboxes. To writer code that's compatible with LWS, use [LWS tools](/docs/platform/lightning-components-security/guide/lws-tools.html).

[Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html) is the legacy security architecture for Lightning components. It provides component isolation and security that allows code from many sources to execute and interact using safe, standard APIs and event mechanisms. To write code that’s compatible with Locker, use [Locker tools](/docs/platform/lightning-components-security/guide/locker-tools.html).

Both LWS and Lightning Locker enforce [JavaScript strict mode](/docs/platform/lightning-components-security/guide/js-strict-mode-intro.html).

**tip:** To learn JavaScript (or if you want a refresher), start with the [Modern JavaScript Development](https://trailhead.salesforce.com/en/content/learn/modules/modern-javascript-development?trail_id=learn-to-work-with-javascript) Trailhead module.

This developer guide explains how to develop Lightning web components and documents the LWC-specific JavaScript functions, such as for wire adapters that let you work with Salesforce data.

This developer guide doesn’t document standard JavaScript or teach JavaScript fundamentals. Standard JavaScript is documented in the [Mozilla Developer Network (MDN) JavaScript Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference). If you’re looking for documentation for a function, try MDN first. For example, if you’re looking for information about `addEventListener()`, use MDN.

**note:** Salesforce ended support for [Internet Explorer 11](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-browsers.md) on January 1, 2023. After Winter '24, you can no longer use Internet Explorer 11 and other legacy browsers to view or access Lightning Experience.

**See Also**

- [Leveraging the Newest ESXX Features in LWC](https://developer.salesforce.com/blogs/2021/02/leveraging-the-newest-esxx-features-in-lwc.html)
- [_Salesforce Help_: Considerations for Microsoft Internet Explorer](https://help.salesforce.com/s/articleView?id=xcloud.getstart_browser_considerations_ie.htm)

<!-- document id=a629393e1778ac4f4ccf8fcfb706748cc03c45f5e39af3b46c313671e58a8ed7 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-supported-APIs.md -->

# Supported Salesforce APIs

Lightning web components are supported for use with many Salesforce APIs. You can access these APIs by importing the specified `lightning` namespaced modules. Not all features or endpoints on a listed Salesforce API are supported.

- CRM Analytics API

  - : Work with CRM Analytics datasets and dashboards. Analytics lenses are currently not supported. See the [lightning/analyticsWaveApi wire adapters and functions](https://developer.salesforce.com/docs/platform/lwc/reference/analytics/reference-lightning-analytics-wave-api.md).

- Einstein Discovery API

  - : Retrieve Einstein Discovery stories. Einstein predictions and models are currently not supported. See the [lightning/analyticsSmartDataDiscoveryApi wire adapters and functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-lightning-analytics-smart-data-discovery-api.md).

- Einstein Generative AI Models API

  - : Use Apex classes and REST endpoints that connect your application to LLMs from Salesforce partners, including Azure OpenAI and OpenAI. See the [Models API documentation](https://developer.salesforce.com/docs/einstein/genai/overview).

- EMP API

  - : Subscribe to a streaming channel and listen to event messages. See the [lightning/empApi module](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-emp-api).

- Lightning Console API

  - : Work with workspace tabs and utility bars on a Lightning app. See the [Lightning Console API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_js_getting_started.htm). The navigation item API isn't supported yet.

- Metadata API

  - : Deploy or retrieve a Lightning web component bundle from an org. See the [LightningComponentBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_lightningcomponentbundle.htm) metadata type.

- Mobile SDK

  - : Run LWC in hybrid apps. See the [Mobile SDK Development Guide](https://developer.salesforce.com/docs/atlas.en-us.mobile_sdk.meta/mobile_sdk/).

- Service Cloud Voice Toolkit API

  - : Access Service Cloud Voice features. See the [Service Cloud Voice Implementation Guide](https://developer.salesforce.com/docs/atlas.en-us.voice_developer_guide.meta/voice_developer_guide/voice_lc_toolkit_lwc.htm).

- Service Knowledge API

  - : Work with Knowledge articles. See the [`lightning/serviceKnowledgeApi` Module](https://developer.salesforce.com/docs/platform/lwc/reference/service-knowledge/reference-lightning-service-knowledge-api.md).

- Tooling API

  - : Work with a Lightning web component bundle using Tooling API. See the [LightningComponentBundle](https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_lightningcomponentbundle.htm) and [LightningComponentResource](https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_lightningcomponentresource.htm) objects.

- UI API

  - : Work with records, list views, and more. See the [Lightning Data Service wire adapters and functions](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md).

Lightning web components aren’t supported for use with these tools. To use a Lightning web component with these tools, wrap the component in an Aura component.

- Lightning Console Navigation Item API
- Conversation Toolkit API
- Omni Toolkit API

**See Also**

- [Supported Salesforce Targets and Tools](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-supported-experiences.md)
- [Reference](https://developer.salesforce.com/docs/platform/lwc/reference/reference.md)

<!-- document id=3fd9c11ead4f901c089617c553d6286f4bff6180352ad4d72077ef35c4b295f3 url=/developer/current/en-us/lwc/lwc/guides/get-started/get-started-supported-experiences.md -->

# Supported Salesforce Targets and Tools

Lightning web components are supported for use with many Salesforce targets and tools. When you’re developing a component, specify its targets in the component’s [configuration file](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md).

- Lightning Experience
- Salesforce Mobile App
- Lightning App Builder
- Experience Builder
- Lightning Web Runtime
- Standalone Apps
- Lightning Console Apps
- Utility Bars
- Flows
- Quick Actions in Lightning Experience
- Custom Tabs
- Gmail and Outlook integration
- Embedded Service Chat
- Lightning Components for Visualforce using Lightning Out (beta)
- Lightning Out 2.0 and Lightning Out (beta)
- OmniScripts
- First-Generation Managed Packages
- Second-Generation Managed Packages
- Unlocked Packages
- Unmanaged Packages
- Change Sets
- URL-Addressable Components

For more information, see [Use Components in Salesforce Targets](https://developer.salesforce.com/docs/platform/lwc/use/use.md).

Lightning web components aren’t supported for use with these tools. To use a Lightning web component with these tools, wrap the component in an Aura component.

- Chatter Extensions
- Global Actions
- List View Actions
- Related List View Actions
- Standard Action Overrides

**See Also**

- [Supported Salesforce APIs](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-supported-APIs.md)
- [Lightning Web Components and Aura Components Working Together](https://developer.salesforce.com/docs/platform/lwc/interop/interop-intro.md)
- [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md)

<!-- document id=6d3a982661e2d949a749ea992f53b99c26a0ea29c0fd15d7e43761e46f9ec52b url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-sanitize-svg.md -->

# SVG Allowlist for Lightning Web Security

SVG can be targeted by cross-site scripting (XSS) attacks due to its permissive approach to loading and executing external resources. To prevent XSS attacks, Lightning Web Security (LWS) applies SVG sanitization rules when it encounters potentially malicious content.

**important:** LWS doesn’t [sanitize](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize.md) input text. Your code must validate or sanitize any user input.

The SVG language includes an extensive list of [elements](https://developer.mozilla.org/en-US/docs/Web/SVG/Element) that you can use inside the `<svg>` tag.

Here is a list of elements that LWS considers safe and allows to remain in an `svg` element after sanitization. LWS removes elements that aren’t in this list.

- `a, altglyph, altglyphdef, altglyphitem, animatecolor, animatemotion, animatetransform, audio`
- `canvas, circle, clippath`
- `defs, desc`
- `ellipse`
- `filter, font`
- `g, glyph, glyphref`
- `hkern`
- `image`
- `line, lineargradient`
- `marker, mask, mpath`
- `path, pattern, polygon, polyline`
- `radialgradient, rect`
- `stop, switch, symbol`
- `text, textpath, title, tref, tspan`
- `use`
- `video, view, vkern`

For example, this `svg` element contains a `g` element, which is allowed, and a `script` element, which isn’t allowed.

```html
<svg>
  <g></g>
  <script></script>
</svg>
```

After sanitization, this code becomes:

```html
<svg><g></g></svg>
```

**See Also**

- [How LWS Sanitizes Static Resources in SVG Elements](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize-svg-static-resource.md)

<!-- document id=37933e2b1b026b150c3f13a53b78cd54dac72eee005d0776e7f18f92c86065d6 url=/developer/current/en-us/lwc/lwc/guides/state-management/state-management-define-syntax.md -->

# Syntax Introduction: A Simple Counter

To understand the structure and syntax of using `defineState` to build a state manager, let's start with a simple but functional example. This example implements a counter state manager. It allows you to create the counter, increment the counter, and get the current counter value.

```javascript
// c/simpleCounter/counterManager.js
import { defineState } from "@lwc/state";

// Use the `defineState` function to define the values
// and actions your state manager provides
const counterManager = defineState(
  // This anonymous JavaScript function is the implementation
  // for a state manager.
  // `atom`, `computed`, and `setAtom` are state management functions
  // available in the context of `defineState`.

  // Your state manager can accept any number of arguments to define
  // its initial state. Here, this state manager can accept one argument
  // `initialValue` to set the beginning counter value, or use a
  // default value of zero.
  ({ atom, computed, setAtom }, initialValue = 0) => {
    // Create the counter, the state for this state manager.
    // An `atom` represents a single, reactive piece of data.
    // Changes to an atom trigger updates in components or
    // re-computation of derived values.
    const count = atom(initialValue);

    // Create an action to modify the state by incrementing it
    const increment = () => {
      setAtom(count, count.value + 1);
    };

    // Return an object that defines the public API of counterManager
    return {
      count,
      increment,
    };
  },
);
export default counterManager;
```

A state manager like `counterManager` is a function that creates instances of the state manager. Arguments you pass to the state manager function are available to the state manager instance as parameters when it initializes. Each state manager instance has its own set of values. Use values and actions from the state manager instance in your component template and JavaScript.

For example, to use the `counterManager` state manager in a component, save the result of calling it. Then access state manager values and actions through the saved reference.

```javascript
// c/simpleCounter/simpleCounter.js
import { LightningElement } from "lwc";
import counterManager from "./counterManager";

export default class SimpleCounter extends LightningElement {
  counter = counterManager(100);

  // Create an action handler that uses the counterManager `increment` action
  handleIncrement() {
    this.counter.value.increment();
  }
}
```

<!-- prettier-ignore -->
```html
<!-- c/simpleCounter/simpleCounter.html -->
<template>
  <lightning-card title="Example: Simple Counter">
    <section class="slds-p-around_small">
      <p>Count: {counter.value.count}</p>
    </section>

    <section class="slds-p-around_small">
      <lightning-button label="Increment" onclick={handleIncrement}></lightning-button>
    </section>
  </lightning-card>
</template>
```

## Understand the `counterManager` Example

Even this simple example uses some advanced JavaScript features. Let's break down the syntax a little bit at a time, to try to clarify the specifics.

- `defineState((...) => { ... })`: The `defineState` function takes a single argument: a callback function. The callback function is the `{ ... }` part, which we expand on in a moment.

- `({ atom, computed, setAtom }, initialValue = 0)`: The callback function defines the state manager. The function _is_ your state manager. The function can accept an arbitrary number of parameters, which you can use for setting the initial state.

  - The first argument passed to the function is an object containing the state primitives: `atom`, `computed`, and `setAtom`. Your state manager uses these primitives to define and change the values that it exposes.
  - After that object, your state manager can accept one or more parameters — here `initialValue` — to configure the state manager instance. You can define parameters and default values as you would for any other JavaScript function.

* `const count = atom(initialValue)`: Inside the state manager, define your state. Here, `atom()` creates a reactive variable named `count`. The value of `count` is the only state managed in this example.

* `const increment = () => { ... }`: This is an action, which will be part of this state manager's public interface. It's just a function that encapsulates the logic for changing the state. Actions are the only way consumers of your state manager can change its internal state.

* `setAtom(count, ...)`: Within the `increment` action, and anywhere else you need to modify state, use the `setAtom` primitive. This ensures that, when your state changes, LWC's reactivity system is notified of that change.

* `return { count, increment }`: Your state manager completes when it returns an object that defines the public API for your state manager instance. Components can access `<instance>.value.count` to read the state and `<instance>.value.increment()` to call the action.

## Atom Data Types

The `atom()` function creates a reactive "atomic" value, which is essentially a wrapper around a piece of data that LWC can use to make components and other state managers reactive to changes in that data. An atom can be a simple value, like a number, or it can be a more complex value, like an object or array.

**note:** You can wrap any JavaScript value, but it's recommended to stick to JSON-serializable values or `undefined` for best compatibility.

## Next Steps

If this is your first time using JavaScript with this structure, read through it a few times. It's not easy to understand the first time, or even the second.

To cement your understanding, start with this example and modify it, perhaps to add a second simple action, like `double`. Take it even further, and turn it into a game leveling manager. Your state manager should track and increment a second atom, `currentLevel` when certain incremental thresholds of `count` are reached. Allow the threshold to be set from an argument provided when an instance is created, and reset `count` whenever you level up. Give it a go, and see how much you learn!

<!-- document id=e8c663aa012357d908b8203687c3512dd369ed06c6d4966531d82bb47e6e342a url=/developer/current/en-us/lwc/lwc/guides/create/create-dom-synthetic.md -->

# Synthetic Shadow

Synthetic shadow is a [polyfill](https://www.npmjs.com/package/@lwc/synthetic-shadow) that mimics native shadow DOM behavior. Salesforce maintains the polyfill to support backwards compatibility for legacy browsers. Currently, Lightning Experience and Experience Builder sites use synthetic shadow by default. It's also available in LWC OSS as an import or in [Lightning Web Runtime](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.html?q=shadow) as a configuration option.

**note:** All browsers supported by Lightning Experience provide native shadow support, so the synthetic shadow polyfill is no longer necessary. Salesforce is committed to migrating from synthetic shadow to native shadow via the use of [mixed shadow mode (beta)](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.md).

## Component Rendering in Synthetic Shadow

When you render a component in synthetic shadow, LWC appends an attribute to mimic native shadow behavior. Let's say you have a custom component `c-hello-input` with several `lightning-input` components. Here's how it renders in the DOM.

```html
<c-hello-input lwc-66unc5l95ad-host>
  <lightning-input class="slds-form-element" lwc-66unc5l95ad-host> ... </lightning-input>
  <lightning-input class="slds-form-element" lwc-66unc5l95ad-host> ... </lightning-input>
</c-hello-input>
```

LWC generates the `lwc-66unc5l95ad-host` attribute as an obfuscated string on `lightning-input` to scope CSS within the component, which mimics native shadow DOM behavior. For example, if you provide styling for `lightning-input`, the CSS scope token is appended to the element at runtime.

**note:** Don't rely on these attributes, as they are an internal implementation that can change anytime. See [Anti-Patterns for Styling Components](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-antipatterns.md).

For custom components in [LWC API version 58.0](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-api-versioning.md) and earlier, the CSS looks like this at runtime.

```css
lightning-input[c-helloInput_helloInput] {
  border: 1px solid red;
}
```

For custom components in LWC API version 59.0 and later, the CSS looks like this at runtime.

```css
lightning-input[lwc-66unc5l95ad-host] {
  border: 1px solid red;
}
```

## Component Styling in Synthetic Shadow

Component styling in synthetic shadow is generally similar to the styling in native shadow DOM. See [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css.md).

In synthetic shadow, your component styles are implemented at the global document level, but using attributes to scope the styles. LWC appends your style in the format `<style> type="text/css">div[lwc-66unc5l95ad-host] { border: 1px solid red }</style>` to the `<head>` element in the DOM. In native shadow DOM, the styles remain in your component.

In synthetic shadow, a shared stylesheet at the top level of your document can style all components on a page. For example, SLDS styling is available to all components on a page in Lightning Experience without getting loaded on each component.

To import your CSS via a static resource and apply the styles globally in synthetic shadow, [use `loadstyle` from `lightning/platformResourceLoader`](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md). The runtime behavior is similar to SLDS in Lightning Experience as SLDS isn't scoped to your component.

To use styles that are scoped to your component, use the component's `.css` file or import the CSS module [using `@import`](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css-share.md).

## Cascading Order for Component Styles

In synthetic shadow, the following order applies for selector specificity starting with highest first.

- CSS defined in component CSS file (scoped)
- CSS imported using @import (scoped)
- CSS imported with `loadStyle` (global)

**See Also**

- [Style Components with CSS Stylesheets](https://developer.salesforce.com/docs/platform/lwc/guide/css/create-components-css.md)
- [Run-time Differences on the Salesforce Platform](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-oss.md#run-time-differences-on-the-salesforce-platform)
- [Build Components in Mixed Shadow Mode (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.md)

<!-- document id=31d5301b6dd30f40f27b6a85ebc987dc8e8cfb2fd2c55b2720af436e4648e071 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions.md -->

# Template Expressions

Add sophisticated presentation logic to your LWC template files, and remove extra code from your component implementation. Beginning in Spring ’26, a component that renders a user interface can use complex JavaScript expressions directly in its HTML template file. Use complex template expressions anywhere you use basic properties.

One superpower of Lightning Web Components is its templating system, which uses the virtual DOM to render components intelligently and efficiently. Complex template expressions extends this capability to include a comprehensive subset of JavaScript expressions, enabling more dynamic and expressive templates while maintaining LWC’s performance characteristics and security model.

Complex template expressions can be used wherever basic properties are supported. Set the `apiVersion` of your component to 66.0 or later to enable complex template expressions for that component.

<!-- document id=6d3d8ba9186bc32b0cd671303d6197f4da2ba6fe445c76e97bab913e2c49e439 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-test-custom-type-editor.md -->

# Test a Custom Property Type or Editor

After you link your custom property type or editor to your custom Lightning web component, deploy the component to your org and test it to see if it works.

Drag the component to the canvas in Experience Builder and look at the component property panel. Make sure that the expected property editors appear, and that the validations match what you expect based on your property type schema. Use each custom property editor to change that property's value and verify that the component property in the canvas updates accordingly.

**See Also**

- _Metadata API Developer Guide_: [Deploying and Retrieving Metadata with the Zip File](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm)

<!-- document id=387b6d147579e46238113bd9dcec141269b68a6e21a9278012511337ecbdffcc url=/developer/current/en-us/lwc/lwc/guides/testing/testing.md -->

# Test Lightning Web Components

Jest is a powerful tool with rich features for writing JavaScript tests. Use Jest to write unit tests for all of your Lightning web components.

Run Jest tests at the command line or (with some configuration) within your IDE. Jest tests don’t run in a browser or connect to an org, so they run fast. When run in “watch mode” they give you immediate feedback while you’re coding. Jest tests work only with Lightning web components, they don’t work with Aura components.

Write Jest tests to:

- Test a component in isolation
- Test a component’s public API (`@api` properties and methods, events)
- Test basic user interaction (clicks)
- Verify the DOM output of a component
- Verify that events fire when expected

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo is filled with Jest tests. Look for Jest tests in the `__tests__` folders within the Lightning web components in `force-app/main/default/lwc`.

**See Also**

- [Jest: Delightful JavaScript Testing](https://jestjs.io/)
- [Lightning Aura Components Developer Guide: Testing Components with Lightning Testing Service](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/lightning_testing_intro.htm)

<!-- document id=4f85500d4944e6d5911262ac5efaf26a1d5b8f226f19aafefaa6ae66324d25f7 url=/developer/current/en-us/lwc/utam/guide/test-sf-applications.md -->

# Testing Salesforce Applications

Let's learn how to test Lightning Experience and the Salesforce mobile app using page objects provided by Salesforce.

## Downloads

Salesforce page objects artifacts are published in:

- [Maven](https://mvnrepository.com/artifact/com.salesforce.utam/salesforce-pageobjects) for Java.

To find the latest version compatible with the current production Salesforce release, see the dependency in the [utam-java-recipes](https://github.com/salesforce/utam-java-recipes) repo.

- [npm](https://www.npmjs.com/package/salesforce-pageobjects) for JavaScript.

To find the latest version of the artifact, see the README in npm or the dependencies in the [utam-js-recipes](https://github.com/salesforce/utam-js-recipes) repo. For example, the npm artifact README indicates compatibility with the supported Salesforce release.

UTAM compiler and core versions compatible with the page objects artifact can be found in pom.xml or package.json of the recipes repositories, for example:

```
<utam.framework.version>1.0.15</utam.framework.version>
```

```
"wdio-utam-service": "1.0.2"
```

## How to Use Salesforce Page Objects

From a browser, to find which page object to use, see [here](https://developer.salesforce.com/docs/platform/utam/guide/find-sf-page-objects.md).

## Inventory of Salesforce Page Objects

The only way to get a full list of published Salesforce page objects is to download the Javadoc jar file, unpack it, and view the Javadoc in your browser. Even if you are using generated JavaScript files, the Javadoc HTML pages are useful because the classes and methods are the same.

To download the Javadoc jar file:

- In [Maven Central](https://search.maven.org/), search for the artifact using the keyword "utam".
- Pick the `salesforce-pageobjects` artifact and click on the version that you're using.
- Click the `Downloads` link and select `javadoc.jar`.
  ![Artifact with Java docs](https://developer.salesforce.com/docs/media/utam/search-download.png)
- Unpack `javadoc.jar` locally (`jar xf ./path/to/salesforce-pageobjects-${version}-javadoc.jar`) and open `index.html` in your browser.
- To use the Javadoc to find what you need, see [Find Packaged Salesforce Page Objects](https://developer.salesforce.com/docs/platform/utam/guide/find-sf-page-objects.md#find-packaged-salesforce-pageobject).

## How to write UI tests for Salesforce App

We provide examples of UI tests in our recipes repositories:

- [JavaScript](https://github.com/salesforce/utam-js-recipes)

- [Java](https://github.com/salesforce/utam-java-recipes)

<!-- document id=437249c03232a1df0c6ece233a627bc072c4e8b9639939ee33ff61959b698a84 url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-property-editor-contract.md -->

# The Property Editor Contract and Property Sheet

To work smoothly in Experience Builder, the component that you create for your custom property editor must satisfy the property editor contract. This contract determines the input value that the editor component has access to and how the editor component persists this value in the overall component's property sheet. The property sheet, a collection of all the property editors for a given Experience Builder component, injects the relevant information into each property editor in the component.

The property editor contract exposes these public properties for the custom property editor component to access.

- label
- description
- required
- value
- errors
- schema

Here's a detailed look at the contract that describes the type of data for each of the public properties.

```javascript
interface PropertyEditorContract {
  label: string;
  description: string;
  required: boolean;
  value: any;
  errors: PropertyError[];
  schema: JSONSchema;
}

interface PropertyError {
  message: string;
}
```

When a user enters a value into a property editor, the property sheet expects the editor to throw a single `CustomEvent` called `valuechange` to send the value to Experience Builder. This code sample shows an interface for the object payload that's expected for the `valuechange` event. Think of this interface as the output of the property editor.

```javascript
interface PropertyChangedEventPayload {
  value: any;
}
```

After the event fires, the property sheet validates the entered value against the property editor's property type schema and persists the value to the component on the canvas in Experience Builder. If any errors occur during the validation process, they're injected back into the editor via the errors property of the property editor. (See [General Guidelines for Creating a Custom Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-general-guidelines.md) for more information to avoid common mistakes when you create a property editor component.)

In the Custom Article component example, the default editor for the `textAlignment` property, which is `type=String`, is a combobox. To replace that with a button group where users can visually click to select the alignment, create a custom Lightning web component to act as the property editor. In the Custom Article component example, this custom property editor component is called `alignmentCPE`. (Download the [sample components](https://github.com/salesforce-experiencecloud/custom-property-editor-code-samples/tree/master/lightningTypeExamples) to follow along.)

The component class of `alignmentCPE` must follow the property editor contract. This code snippet shows a basic editor component class for the property editor. Notice how the public properties of the component—value, label, schema, and errors—follow the property editor contract. Also notice how the editor is firing the `valuechange` event when users click a new alignment option.

```javascript
export default class AlignmentCPE extends LightningElement {
 @api value;
 @api label;
 @api schema; // the JSON Schema derived from the accompanying property type.
 @api errors;

 @track buttons = [...]

 handleAlignmentClick(event) {
        const value = event.target.value;
        this.value = value;
        this.dispatchEvent(new CustomEvent("valuechange",
           {detail: {value: this.value}}));
    }
}
```

**Supported @salesforce Modules**

You can use these @salesforce modules in a custom property editor to enhance the editor component.

- [@salesforce/community/Id](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html#salesforcecommunity)
- [@salesforce/community/basePath](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html#salesforcecommunity)
- [@salesforce/site/Id](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html#salesforcesite)

**See Also**

- [Decide on the Validation for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-validation.md)
- [Decide on the Editor for Each Property in the Component](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-decide-editor.md)
- [General Guidelines for Creating a Custom Property Editor](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-general-guidelines.md)

<!-- document id=c89057e92772e5477c6be46ae24ae2e37f585e29e819258796b2f5ec9c3f4119 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-analytics.md -->

# Third-Party Analytics Libraries Blocked by Lightning Web Security

Analytics libraries such as Google Analytics and Adobe Analytics require access to the entire page unrestricted. This requirement conflicts with the Lightning Web Security (LWS) requirement that code belonging to one namespace isn’t allowed to access data from a different namespace.

LWS prevents the third-party analytics scripts from accessing code running in the browser outside the JavaScript sandboxes. Only platform code is allowed to run outside sandboxes. LWS also prevents analytics scripts from accessing global objects in JavaScript sandboxes because the scripts don’t belong to the namespaces reserved for the sandboxes.

Experience Cloud sites can use a workaround to enable analytics libraries to work with Lightning Locker. This approach can also work if LWS is enabled in the org instead of Lightning Locker. The workaround applies only to Experience Cloud sites because Experience Builder gives admins access to the `head` markup of the sites. Other Salesforce applications and components don’t allow such access. See the [_Experience Cloud Developer Guide_](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_security_locker_example.htm).

<!-- document id=423a103127a116124a6e136a66b6a0b843de386f39f0c8c1bc0781feb326fa23 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-js.md -->

# Third-Party Library Considerations for Lightning Web Security

Third-party scripts can encounter issues when running with Lightning Web Security (LWS) enabled if they have these behaviors.

## Third-Party Library Sets Up on Global `window` Object

Some third-party scripts expect to add themselves to the global `window` object. LWS confines them to a sandbox where they access a virtual copy of the global `window` object.

To ensure that the code runs in the global scope of the LWS sandbox instead of attempting to access the actual global scope, modify the script code to assign `self` to `global`.

```javascript
(function (global) {
  global = global || self;
  global.myFunction = function () {};
})(this);
```

In this code, `this` is passed to the closure function as `global`. With LWS, `this` and `global` are undefined, so this code makes sure that `global` evaluates as the sandbox `global`.

## Third-Party Library Sets Strict Mode

If a third-party library script explicitly sets `"use strict"`, the browser can throw errors when your components use the script while running in LWS.

For example, errors occur if the script attempts to set something in the global object. LWS implicitly enforces most strict mode restrictions, but allows writing to virtual global objects in its JavaScript sandboxes. Setting strict mode explicitly in code interferes with LWS.

The workaround is to remove `"use strict"` in the third-party script.

Alternatively, modify the third-party code to assign `self` to `global` as shown in the [Third-Party Library Sets Up on Global `window` Object](#third-party-library-sets-up-on-global-window-object) section.

:::Note

If you’ve addressed these issues and the library still isn’t compliant, ask the library maintainers to update the code to comply with LWS, or, if the project is open-source, contribute the changes yourself. Another option is to fork the repository, make the changes, and build your own version of the library. It’s your responsibility to make sure any third-party libraries work with your Lightning components before deployment.

:::

<!-- document id=90b0236f4bdb6b2dd529485abcd5b12fc7c4f9ae760f8261b812c8e5bfd377b0 url=/developer/current/en-us/lwc/lwc/guides/create/create-use-third-party-intro.md -->

# Third-Party Web Components


Using third-party web components in LWC can save you time recreating the same components in LWC. To use third-party web components, [enable Lightning Web Security](/docs/platform/lightning-components-security/guide/lws-enable.html) first. Lightning Locker doesn't support the use of custom elements, a key building block of third-party web components.

To work with third-party web components, review these guidelines.

- [Use Third-Party Web Components in LWC](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-third-party-components.md)
- [Work with Custom Elements](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-custom-elements.md)
- [Pass Data to a Custom Element](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-third-party-pass-data.md)
- [Append Styles to a Custom Element](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-third-party-styles.md)

<!-- document id=49c8117eaba5a03200ccffa2736115dd4680a12f19aabea7a026995610cdacec url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-custom-elements.md -->

# Third-Party Web Components With Lightning Locker

Lightning Locker blocks the use of third-party web components to prevent security risks on the Salesforce platform.

Web components are custom elements. To define a custom element, you must use the `customElements.define` API. However, this API allows you to globally register a component by its tag name. Registering a tag name globally is a security risk because an attacker could create an instance of any registered custom element and potentially gain access to sensitive information. Lightning Locker’s `SecureWindow` wrapper blocks the `customElements` methods that create custom web components.

The `SecureWindow` wrapper list in the [Locker API Viewer](https://developer.salesforce.com/docs/component-library/tools/locker-service-viewer) tool shows that `customElements` is not supported.

<!-- document id=54f8b0c891d843c0513c1faaf6922e8b4ddd09c682aca8c19c44b3190c3b7631 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-app-builder-tips.md -->

# Tips for Working with Lightning App Builder

Keep these guidelines in mind when creating components to expose in Lightning App Builder.

## Component Tips

- Make components fill 100% of the width (including margins) of the region that they display in. See [Make a Component Width-Aware](https://developer.salesforce.com/docs/platform/lwc/use/use-width-aware.md).
- If components require interaction, provide an appropriate placeholder behavior in Lightning App Builder.
- Don’t display a blank box. Think of how other sites work. For example, Facebook displays an outline of the feed before the actual feed items come back from the server. The outline improves the user’s perception of UI responsiveness.
- If a component depends on a fired event, give it a default state that displays before the event fires.
- Use [Salesforce Design System](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-slds.md) to style components.

## Configuration File Tips

- Set a friendly name for the component using the `masterLabel` tag in the configuration file.
- Use the [configuration file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) to expose properties to the Lightning App Builder.
- We strongly recommend including supported form factor information in the configuration file for all your components.
- Give all properties a label with a friendly display name.
- Provide descriptions to explain the expected data and any guidelines, such as data format or expected range of values. Description text appears as a tooltip in the Lightning App Builder’s property editor.
- Give your required properties default values. When a component that has required properties with no default values is added to the App Builder, it appears invalid, which is a poor user experience.
- Use basic supported types (string, integer, boolean) for any exposed properties.
- When defining a component property, make sure that it has the same type assigned (String, Integer, Boolean) in the `.js` file and in the configuration file. If the assigned types don’t match, the type assignment from the configuration file takes precedence.
- Specify a min and max attribute for integer properties to control the range of accepted values.
- String properties can provide a datasource with a set of predefined values allowing the property to expose its configuration as a picklist.
- If a component is used on a Lightning page or in a managed package, we prevent you from making destructive changes that can break the component. Some examples of these destructive changes are:
  - Removing object tags if the component is in use on a record page for that object.
  - Removing page type support if the component is in use on that type of page.
  - Changing min or max property values if the component is in use on a Lightning page.

## Limitations

- The Lightning App Builder doesn’t support the Map, Object, or java:// complex types.
- Once a component is in use on a Lightning page, you can only increase the supported form factors for the component, not decrease them.
- Pull to refresh doesn’t work for custom Lightning web components in the Salesforce mobile app.

<!-- document id=be0cf99ab2d5ae785ba871621d540a85822fb51f22b1d052c8f13d961f870322 url=/developer/current/en-us/lwc/lwc/guides/use/use-config-for-agentforce-tips.md -->

# Tips for Writing AI Component Descriptions

AI component descriptions are used only in orgs that have Setup with Agentforce enabled. For more information, see [Setup with Agentforce](https://help.salesforce.com/s/articleView?id=xcloud.setup_agentforce_overview.htm&type=5).

When writing an AI-related component description to make your component accessible to Agentforce in Setup, consider these questions to craft a comprehensive description.

- Audience: Who is the intended user of this component?
- Functionality: What task or purpose does this component provide?
- Benefit: Why would someone want to use this component?
- Context: In which situations or environments is this component typically used?

The more information that you include, the more easily Agentforce can determine whether the component fits a user’s needs when they need help creating a Lightning page.

- When specifying what the component does and its intended use cases, include detailed examples of scenarios where this component is a good choice.
  - Poor: "A component for adding content," or "For general use."
  - Good: "The component enables users to add and style text content for dashboards, supporting features such as hyperlinks, bullet points, and text alignment. Ideal for adding formatted text sections such as instructions, annotations, or content summaries within dashboards on record pages."
- Describe in detail the configurable options, limitations, and unique features that differentiate this component from others.
  - Poor: "You can style the text."
  - Good: "...supports text styling features such as bold, italics, underlining, bullet lists, numbered lists, and hyperlink embedding."
- Mention any limitations or scenarios where the component isn’t suitable. For example, "Doesn’t support dynamic data binding or embedding external media."
- Avoid technical jargon. Write your description using language that an end user uses to define their requirements.
  - Poor: “This component supports CRUD operations on records.”
  - Good: “This component lets users add, edit, view, and delete records, making it easy to manage and update information displayed on the dashboard.”

<!-- document id=2b4b236432dbfa0c9e5c3ed08a00f005c05b6f1b21876a52a6124f34deeccc49 url=/developer/current/en-us/lwc/lwc/guides/use/use-toast.md -->

# Toast Notifications

A component can send a toast notification that pops up to alert users of a success, error, or warning. A toast can also simply provide information.

There are several ways to display a toast.

- `lightning/toast` - This is the preferred method to display a toast. Call the `show()` method on the [`lightning/toast` module](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast). `lightning/toast` supports inline links in both the toast title and message.
- `lightning/platformShowToastEvent` - Dispatch the `ShowToastEvent` event using your toast attributes. This module isn't supported on login pages in Aura sites, LWR sites for Experience Cloud, and standalone apps. Inline links are not supported in the toast title.

To manage your toasts on a page, use the `lightning/toastContainer` module. For example, you can specify the toast position or the maximum number of toasts to be displayed.

## Display a Toast Using `lightning/toast`

To display a toast using `lightning/toast`, import the module and call the `show()` method. Provide a title using the required `label` property. The toast `message` property is optional. Both properties support inline links using the placeholder syntax `{N}` or `{linkName}`. For more information, see the [`lightning/toast` specification](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast?type=Specifications.

![A toast notification displaying as an info banner with inline links.](https://developer.salesforce.com/media/toast_display.png '{"class": "image-full", "title": "A toast notification"}')

```javascript
// toastExample.js
import { LightningElement } from "lwc";
import LightningToast from "lightning/toast";

export default class ToastExample extends LightningElement {
  async handleToastClick() {
    await LightningToast.show(
      {
        label: "Sample title with {0} and {1}",
        labelLinks: [
          {
            url: "https://v1.lightningdesignsystem.com/components/toast/",
            label: "SLDS link",
          },
          {
            url:
              "https://v1.lightningdesignsystem.com/accessibility/guidelines/global-focus/#toasts",
            label: "toast guideline",
          },
        ],
        message: "Sample message with {salesforceLink} and {slackLink}",
        messageLinks: {
          salesforceLink: {
            url: "http://www.salesforce.com",
            label: "Salesforce link",
          },
          slackLink: {
            url: "https://slack.com",
            label: "Slack link",
          },
        },
        mode: "sticky",
        variant: "info",
      },
      this,
    );
  }
}
```

## Display a Toast Using `lightning/platformShowToastEvent`

`lightning/platformShowToastEvent` uses an event-based mechanism to display a toast, and it's not supported in environments like LWR sites for Experience Cloud or standalone apps. We recommend that you use [`lightning/toast`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast) instead.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo has a `miscToastNotification` component that lets you customize and send a toast so that you can try out the variations.

![A toast notification displaying as a green banner in the LWC Recipes sample app.](https://developer.salesforce.com/media/toast_event.png '{"class": "image-full", "title": "A toast notification"}')

The HTML template builds the toast that you see in the screenshot.

<!-- prettier-ignore -->
```html
<!-- miscToastNotification.html -->
<template>
  <lightning-card title="miscToastNotification" icon-name="custom:custom19">
    <div class="slds-m-around_medium">
      <lightning-input label="Title" value={_title} onchange={titleChange}></lightning-input>
      <lightning-input
        label="Message"
        value={message}
        onchange={messageChange}>
      </lightning-input>
      <lightning-combobox
        label="Variant"
        value={variant}
        onchange={variantChange}
        options={variantOptions}>
      </lightning-combobox>
      <p class="slds-m-vertical_small">
        <lightning-button label="Show Notification" onclick={showNotification}></lightning-button>
      </p>
    </div>
  </lightning-card>
</template>
```

Simply import `ShowToastEvent` from `lightning/platformShowToastEvent`. Create and dispatch a `ShowToastEvent` event with `title`, `message`, `variant`, and `mode` properties. This example uses the default value for `mode`, so it’s not included.

```javascript
// miscToastNotification.js
import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class MiscToastNotification extends LightningElement {
  titleText = "Sample Title";
  messageText = "Sample Message";
  variant = "error";
  variantOptions = [
    { label: "error", value: "error" },
    { label: "warning", value: "warning" },
    { label: "success", value: "success" },
    { label: "info", value: "info" },
  ];

  titleChange(event) {
    this.titleText = event.target.value;
  }

  messageChange(event) {
    this.messageText = event.target.value;
  }

  variantChange(event) {
    this.variant = event.target.value;
  }

  showNotification() {
    const evt = new ShowToastEvent({
      title: this.titleText,
      message: this.messageText,
      variant: this.variant,
    });
    this.dispatchEvent(evt);
  }
}
```

## Manage Toasts on a Page

Customize the toast behavior on a page using the `lightning/toastContainer` module for these use cases.

- Specify the maximum number of toasts that can be displayed on a page. The default is 3.
- Set the position at the top or bottom of a page. The default is top-center.
- Set the container position on a page. The default is fixed.

For more information, see the [`lightning/toastContainer` specification](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast-container?type=Specifications.

To manage your toasts, import the `lightning/toastContainer` module and create an instance of the toast container component. Only one instance of toast container is supported on a page.

![Multiple toast notifications displaying in the top right of the page.](https://developer.salesforce.com/media/toast_container.png '{"class": "image-full", "title": "Multiple toast notifications in the top right corner"}')

```javascript
// toastExample.js
import { LightningElement } from "lwc";
import ToastContainer from "lightning/toastContainer";

export default class ToastExample extends LightningElement {
  connectedCallback() {
    const toastContainer = ToastContainer.instance();
    toastContainer.maxToasts = 5;
    toastContainer.toastPosition = "top-right";
  }
}
```

The `lightning/toastContainer` module manages toasts that are created using the `lightning/toast` and `lightning/platformShowToast` modules. If you have different components that use either module on a single page, the toasts created by those modules are subject to the toast container's configuration.

When the page displays the maximum number of toasts, any attempt to display an additional toast results in the toast being displayed only when a toast is closed or dismissed. For example, the `maxToasts` value is 5 and there are 5 toasts already displayed on a page. When you try to open another toast, that toast is hidden until you close or dismiss at least one of the toasts that's currently displayed.

**See Also**

- [Component Reference: `lightning/platformShowToastEvent`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-show-toast-event)
- [Component Reference: `lightning/toastContainer`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-toast-container)

<!-- document id=649777cd856c2823ac6759fa001b5aee76e8f845f8ede439121eceda094d5fa8 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-tools.md -->

# Tools for Lightning Web Security

To help you develop secure code that runs with Lightning Web Security (LWS), Salesforce provides these tools.

- [ESLint Rules](https://github.com/salesforce/lwsec-docs-mirror/tree/main/packages/%40locker/eslint-plugin-locker/docs/rules)

  - : To help you find areas in your code that trigger LWS [distortions](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md#distortions), ESLint rules perform static code analysis. You can install them on your development machine and run them on your source code. See [Install ESLint Rules for Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-lint.md).

- [Lightning Web Security Console](https://developer.salesforce.com/tools/lws-console)

  - : To help you determine if code issues are related to LWS, Lightning Web Security Console performs dynamic checking on your JavaScript code as it runs in a sandbox. See [Evaluate JavaScript in Lightning Web Security Console](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-console.md).

- [Lightning Web Security Distortion Viewer](https://developer.salesforce.com/tools/lws-distortion-viewer)
  - : LWS Distortion Viewer describes the distortions’ effects on APIs. See [Look Up Distortion Details in Lightning Web Security Distortion Viewer](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-distortion-viewer.md).

<!-- document id=d2e6fb975a2498ab7120be0d322c83d44645f140cbf7df392450942c476253d4 url=/developer/current/en-us/lwc/utam/guide/tools.md -->

# Tools for UTAM

Write UTAM tests faster and easier with optional assistive tools.

The [UTAM Generator](https://developer.salesforce.com/docs/platform/utam/guide/generator-get-started.md) tool generates UTAM JSON files from HTML files.

These tools identify the best page objects to test on a given page.

- The [UTAM Browser Extension](https://developer.salesforce.com/docs/platform/utam/guide/browser-extension.md) for Google Chrome analyzes Salesforce application pages.
- [Mobile Inspector](https://developer.salesforce.com/docs/platform/utam/guide/mobile-inspector.md) analyzes Salesforce mobile hybrid application pages.

<!-- document id=6ffe02193da5b87e6ee373eba7ae0edc995d386edd46a7966c50e3f05f3d713a url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-troubleshoot.md -->

# Troubleshoot Issues Related to Lightning Web Security

Developers can sometimes encounter some issues when developing and testing components to run in Lightning Web Security (LWS). Follow these troubleshooting steps, and check whether your issue is addressed within these topics.

1. [Determine if LWS is enabled or disabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-is-enabled.md). If you suspect that the correct security architecture isn’t in effect, see [Delayed Enabling or Disabling of LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-caching.md).

2. Eliminate common issues that can be related to LWS.

   - [Properties Evaluate as `undefined` in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-undefined.md)
   - [Static Resources with async Functions Behave Inconsistently](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-async.md)
   - [Cloned Objects Behave Differently in LWS Compared to Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-clone-objects.md)

3. Ensure that you’re following the coding guidelines outlined in [Build Components to Work with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-build-components.md).

   - [Avoid Mutating Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mutation-alternatives.md)
   - [Avoid Using Map Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-map.md)
   - [Avoid Custom Properties on Standard JavaScript Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-standard-objects.md)
   - [Specify a MIME Type for Blob Objects](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-mime.md)
   - [Script Tags Transformed to Fetch Calls](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-script-tags.md)
   - [Access to iframe Content in LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-iframes.md)
   - [URL Protocol Schemes Allowed](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-url-schemes.md)
   - [Aura Endpoints Disallowed by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-aura-endpoints.md)
   - [Analytics Libraries Blocked by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-analytics.md)
   - [Salesforce Global Variables Blocked by LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-restricted-globals.md)
   - [Third-Party Library Considerations for LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-js.md)
   - [Local Storage Limitations](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-local-storage.md)
   - [Objects Passed Between Components Are Proxied](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-proxies.md)
   - [Understand How LWS Architecture Affects Component Performance](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-performance.md)

4. Be aware of how [LWS sanitizes HTML and SVG elements](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-sanitize.md).

5. Be aware of [LWS limitations](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-limitations.md).

If you try these troubleshooting techniques without success, you can [disable Lightning Web Security in scratch orgs](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable-scratch-orgs.md) and continue to troubleshoot. We recommend that you reenable Lightning Web Security as soon as possible.

**See Also**

- [Debug with Lightning Web Security Enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-debug.md)

<!-- document id=f6e12f44fdf9f89d66a787c0cf3bfa4a3d043b462a6d96aed47ba0c7ac7ab9f9 url=/developer/current/en-us/lwc/slds_linter/guides/support/support-troubleshoot.md -->

# Troubleshoot SLDS Linter

If you experience an issue with SLDS Linter, take a look at these common issues and learn how to fix them.

## Unable to Locate the Code Containing an Error or Warning

If you ‌select an error or warning in the report, the SARIF viewer doesn’t automatically go to the line of code. In such cases, follow these steps in VS Code.

1. In the SARIF viewer window, select **Locate**.
2. In your File Explorer or code editor, locate the file.
3. Select the errors in the SARIF viewer to go directly to the relevant line of code.

## Error Due to Unsupported Node.js Version

If the Node.js version is lower than v18.4.0, this error is displayed.

`SLDS Linter CLI works best with Node.js version v18.4.0 or later.`  
 `We recommend using the latest [Active LTS](https://nodejs.org/en/about/previous-releases) version of Node.js.`

To resolve this error, upgrade to the latest [Active Long Term Support](https://nodejs.org/en/about/previous-releases) (LTS) version of Node.js.

<!-- document id=9cb416ce0848672a28675ff67f6056384caf825f80dee1a373e24637ee14cb89 url=/developer/current/en-us/lwc/utam/guide/tutorial-playground.md -->

# Tutorials

Learn to write UTAM tests with live-coding tutorials on the [UTAM.dev tutorials site](https://utam.dev/tutorial/introduction).

The tutorials teach you how to write JSON page objects for your application components, as well as test code that calls the page object methods. Tutorial tests are written in JavaScript.

## Tutorial Pages

Each tutorial includes instructions and live coding panels.

- [Introduction](https://utam.dev/tutorial/introduction)

  - : Start here to complete the full tutorial experience in order.

- [Hello World](https://utam.dev/tutorial/hello-world)

  - : Outline the mental model of creating a page object for a component.

- [Write a Test](http://utam.dev/tutorial/write-tests)

  - : Use the same HTML and JSON as the Hello World tutorial to explain the basics of writing a test with UTAM code.

- [Root Page Objects](https://utam.dev/tutorial/root)

  - : Explain the importance of the `root` page object.

- [Basic Elements](https://utam.dev/tutorial/basic-element)

  - : Break down the JSON page object as a tree of elements that map to the DOM of the corresponding page.

- [Web Components and Shadow DOM](https://utam.dev/tutorial/web-components)

  - : Learn how to cross a shadow boundary using UTAM.

- [Simple Selectors](https://utam.dev/tutorial/simple-selectors)

  - : Learn how to select things in a page with UTAM JSON grammar.

- [Selector String Parameter](https://utam.dev/tutorial/selector-param-string)

  - : Write a CSS selector that accepts a string dynamically.

- [Selector Number Parameter](https://utam.dev/tutorial/selector-param-number)

  - : Write a CSS selector that accepts a number dynamically.

- [Basic Actions](https://utam.dev/tutorial/basic-actions)

  - : Call the basic actions API to get, set, and wait for UI element state without walking the DOM.

- [Editable Actions](https://utam.dev/tutorial/editable-actions)

  - : Create an element with `"type": "editable"` that has access to basic action APIs that can set and clear text.

- [Clickable Actions](https://utam.dev/tutorial/clickable-actions)

  - : Test an app with clickable buttons.

- [Lists](https://utam.dev/tutorial/lists)

  - : Return all the elements from a list.

- [Get List Item by Index](https://utam.dev/tutorial/list-index)

  - : Get a list item by its index.

- [Get List Items by Pattern](https://utam.dev/tutorial/list-pattern)

  - : Use a pattern to select items from a list.

- [Get List Items by Attribute](https://utam.dev/tutorial/list-attribute)

  - : Use a selector to target specific elements you need in a test.

- [Filter a List of Elements Using `stringEquals`](https://utam.dev/tutorial/filter-elements-string-equals)

  - : When you can't use a selector to get the elements you need, use an element filter.

- [Filter a List of Elements Using `stringContains`](https://utam.dev/tutorial/filter-elements-string-contains)

  - : When you can't use a selector to get the elements you need, use an element filter.

- [Filter a List of Elements Using `findFirst`](https://utam.dev/tutorial/filter-elements-find-first)

  - : Return only the first filtered element.

- [Filter a List of Elements Using `isTrue`](https://utam.dev/tutorial/filter-elements-is-true)

  - : Use the `isTrue` matcher to filter a list of Trailhead units to show only visible (incomplete) units.

- [Custom Elements](https://utam.dev/tutorial/custom-element)

  - : Test page objects that are composed of other page objects.

- [Filter Custom Elements](https://utam.dev/tutorial/filter-custom-elements)

  - : Use declarative filtering in a JSON page object to allow a test to get a list of contacts filtered by a search string in the contact's title. This use case builds on the [Custom Elements](https://utam.dev/tutorial/custom-element) and [Filter a List of Elements Using `stringContains`](https://utam.dev/tutorial/filter-custom-elements) tutorials.

- [Nullable Elements](https://utam.dev/tutorial/nullable-elements)

  - : Use a nullable element for an element that isn't always present on the page.

- [Container Elements](https://utam.dev/tutorial/container-element)

  - : Select a component with a `slot` or a `div` acting as a container for other components.

- [Compose Method](https://utam.dev/tutorial/compose-method)

  - : Compose several actions into a single method by declaring them in a `compose` array.

- [Compose Custom Actions](https://utam.dev/tutorial/compose-custom)

  - : Combine several actions applied to the basic elements into one composed method.

- [Compose vs. Expose Root Element](https://utam.dev/tutorial/compose-root)

  - : Expose an element's root as a public editable element or declare compose methods to set and get the value.

- [Compose Argument References](https://utam.dev/tutorial/compose-argument-references)

  - : Reuse an argument in multiple statements in a compose method.

- [Chain Compose Statements](https://utam.dev/tutorial/compose-chain)

  - : Chain multiple compose statements in a test.

- [Imperative Extensions](https://utam.dev/tutorial/compose-utility)

  - : Create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar.

- [Explicit Wait](https://utam.dev/tutorial/wait-for)

  - : Simulate a UI test that waits for an element to appear as the result of a user action.

- [Wait for an Element Before Loading](https://utam.dev/tutorial/load-element-contains)

  - : Intercept the `load` method and override it by adding an explicit wait for an element to be rendered.

- [Todo App](https://utam.dev/tutorial/todo-app)

  - : Experiment writing UTAM page objects and test code against a real app.

<!-- document id=5464b9e61b92a11dba489fab9b0e2b03a418daa9c019834428a346826441044a url=/developer/current/en-us/lwc/lwc/guides/create/ts.md -->

# TypeScript Type Definitions for LWC (Developer Preview)

**note:** This feature is available as a developer preview. This feature isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality developed with these commands or tools.

Beginning in Winter '25, you can use Salesforce type definitions with TypeScript v5.4.5 to develop Lightning web components (LWCs).

**important:** Before you start this workflow, make sure you have already installed the [Visual Studio (VS) Code Salesforce Extension Pack](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode). If you aren't using VS Code, you have to manually install these Node Package Manager (npm) packages in your project:

- [`@salesforce/lightning-types`](https://www.npmjs.com/package/@salesforce/lightning-types)
- [`lwc`](https://www.npmjs.com/package/lwc)

For more guidance, see [Manually Install the Lightning Types Package](#manually-install-the-lightning-types-package).

To use type definitions in your LWC project, follow these steps:

1. [Enable TypeScript Support](#enable-typescript-support-for-your-lwc-project)
2. [Add the TypeScript Package](#add-the-typescript-package-to-your-lwc-project)
3. [Compile TypeScript Components to JavaScript](#compile-your-typescript-components-to-javascript)

For a list of available Salesforce types, see [Salesforce Lightning Types](#salesforce-lightning-types).

## What are the Benefits of Using Type Definitions?

TypeScript is a superset of JavaScript that can improve developer productivity and code quality. It supports build-time type checking, which helps catch errors in your code and improves code reliability. To boost code discoverability and quality, use type-based auto-completion and static type analysis in development environments like [Visual Studio Code (VS Code)](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-editor-linter-org.md). Other benefits of TypeScript development include greater type safety and easier code maintainability.

## Enable TypeScript Support for Your LWC Project

Before you can add TypeScript files to your LWC project, you have to configure your project to support TypeScript code.

First, in your project's `settings.json`, set the feature flag `salesforcedx-vscode-lwc.preview.typeScriptSupport` to `true`.

```
{
  "salesforcedx-vscode-lwc.preview.typeScriptSupport": true
}
```

Save your changes to automatically create a `tsconfig.json` file in the `lwc` folder, or the folder that contains your project's components. If you don't see a new `tsconfig.json`, restart VS Code.

```
.../lwc
    ├──contact
    ├──account
    ├──tsconfig.json
```

**note:** TypeScript’s `experimentalDecorators` is no longer supported. You must either specify `"experimentalDecorators": false` or remove the option from your `tsconfig.json` file.

Here's an example of a complete `tsconfig.json` file with the correct `compilerOptions` settings for TypeScript support.

```
{
  // These sections are automatically generated

  "extends": "../../../../.sfdx/tsconfig.sfdx.json",
  "include": [
    "**/*.ts",
    "../../../../.sfdx/typings/lwc**/*.d.ts"
  ],
  "exclude": [
    "**/__tests__/**"
  ],

  // You have to manually add the compilerOptions section

  "compilerOptions": {
    "experimentalDecorators": false
  }
}
```

## Add the TypeScript Package to Your LWC Project

Add TypeScript to your project via the npm registry. The following `npm` command downloads TypeScript and sets a project dependency on the `typescript` package in your `package.json`. The minimum supported version is v5.4.5.

```
npm install typescript --save-dev
```

## Compile Your TypeScript Components to JavaScript

The LWC compiler doesn't compile TypeScript files. Before you can deploy TypeScript LWCs, you must convert your TypeScript code to Javascript.

![TypeScript Compilation to JavaScript Workflow](https://developer.salesforce.com/media/TS_to_JS_workflow.png)

When you deploy your components, the Salesforce platform doesn't store or save your TypeScript code. Your TypeScript files exist only on the client-side: either on your local machine or in your source control system. **You** are in charge of managing them.

For example, here's an example of what a deployed TypeScript component (`contact`) looks like in your local project directory, prior to being compiled to JavaScript.

```
.../lwc/contact
    ├──contact.html
    ├──contact.ts
    ├──contact.css
    ├──contact.js-meta.xml
```

To convert all of your TypeScript code to JavaScript, run `tsc` on the command line for your entire `lwc` directory.

```bash
# From the project root directory
npx tsc --project ./path/to/lwc
```

This command generates a JavaScript version of each of your TypeScript components. Here's an example of the compiled component folder output for the sample component `contact`.

```
.../lwc/contact
    ├──contact.html
    ├──contact.js     # JavaScript file produced by the TypeScript compiler
    ├──contact.ts
    ├──contact.css
    ├──contact.js-meta.xml
```

For more guidance on managing TypeScript and JavaScript code in your project, see [Use a Source Control System](#use-a-source-control-system).

## Write Jest Tests for TypeScript Components

The `sfdx-lwc-jest` test runner compiles TypeScript test files out of the box, so you don't need to make any `jest.config.js` changes. To add a TypeScript test for an LWC, follow these steps.

### Step 1: Write the Test File

Save the test as `.test.ts` under the component's `__tests__` folder. The test structure is the same as a JavaScript test.

For the full test structure, matchers, and patterns, see [Write Jest Tests for Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-create-tests.md). For background on Jest's TypeScript support, see [Jest: Getting Started — Using TypeScript](https://jestjs.io/docs/getting-started#using-typescript). For guidance on the non-null assertion operator (`!`), see [Use Non-Null Assertions Safely](#use-non-null-assertions-safely).

### Step 2: Install Jest Type Definitions

Install the Jest type definitions as a dev dependency so your editor recognizes Jest globals like `describe`, `it`, and `expect`.

```bash
npm install --save-dev @types/jest
```

### Step 3: Update tsconfig.json

Add `"jest"` to the `types` array in your `tsconfig.json` `compilerOptions`. For the rest of the settings, see [Enable TypeScript Support for Your LWC Project](#enable-typescript-support-for-your-lwc-project).

```
"compilerOptions": {
  "types": ["jest"]
}
```

### Step 4: Run the Test

Run TypeScript tests with the same `npm run test:unit` script that runs JavaScript tests.

```bash
npm run test:unit
```

## Convert an Existing JavaScript Component to TypeScript

Do you have a JavaScript LWC in your project's `lwc` folder that you want to convert to TypeScript? Follow these steps to update your component.

1. In the component folder, change the component to TypeScript by changing the extension of the script file from `.js` to `.ts`.
2. Run the TypeScript compiler and resolve any compilation errors that occur.

To resolve any errors that occur during this process, see [Migrating from JavaScript: Moving to TypeScript Files](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#moving-to-typescript-files).

## Salesforce Lightning Types

While TypeScript support for LWC is in developer preview, the types in `@salesforce/lightning-types` are limited. We're working on adding more type definitions to this package. You can see a complete list of available types in [the package README](https://www.npmjs.com/package/@salesforce/lightning-types?activeTab=readme).

The [VS Code Salesforce Extension Pack](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-editor-linter-org.html) automatically installs type definitions for `lwc`, `@salesforce/apex`, `@salesforce/schema`, `lightning/messageService`, and some wire adapters. Type definitions provided by the Extension Pack are subject to change, and will be moved to the `@salesforce/lightning-types` package by the end of the developer preview.

If you aren't using VS Code, you have to manually install these packages in your project.

### Manually Install the Lightning Types Package

First, we recommend installing `@salesforce/lightning-types` using npm, like this:

```
npm install --save-dev @salesforce/lightning-types
```

Then, create a new `d.ts` file in your project that imports all the type definitions from `@salesforce/lightning-types`. This sample file `salesforce.d.ts` contains the recommended import statement, and the file is nested in its project's `types` directory.

```
import "@salesforce/lightning-types";
```

Finally, in your project's `tsconfig.json` file, add a reference to your new `.d.ts` file. You should also update the `paths` compiler option. Every LWC module you use must be mapped in this section.

```
{
  "include": [
    "**/*.ts",
    "../../../../.sfdx/typings/lwc/**/*.d.ts",
    "../../../../types/salesforce.d.ts",
    "**/*.d.ts"
  ],
  "compilerOptions": {
    "paths": {
      "c/button": ["./src/modules/button/button.ts"],
      "c/bar": ["./src/modules/bar/bar.ts"],
    }
  }
}
```

Now, in your TypeScript component files, you can import Salesforce Lightning types like this:

```
import LightningButton from "lightning/button";
```

## Lightning Base Components

The `@salesforce/lightning-types` package provides type definitions for some base components. These type definitions help you write type-based code when working with base components. Importing `@salesforce/lightning-types` is required once per project, as shown by the `salesforce.d.ts` file.

For example, here's a custom component that uses the `lightning-button` base component.

```
import { LightningElement, api } from 'lwc';
import LightningButton from 'lightning/button';
export default class Hello extends LightningElement {
    // @ts-ignore
    @api
    greeting = 'World';
    buttonLabel = 'Submit';
    private buttonRef: LightningHTMLElement<LightningButton> | null = null;

    renderedCallback() {
        const element = this.template.querySelector('lightning-button') as LightningHTMLElement<LightningButton> | null;
    }
    handleClick(event: CustomEvent) {
        if (this.buttonRef) {
            console.log("Button label:", this.buttonRef.label);
        }
    }
}
```

The example uses `this.template.querySelector()` to find the first `lightning-button` component in the template. Because the `querySelector` method can return _any_ element, but we expect to receive a `lightning-button`, we use a type assertion to get the correct type. Component classes are instances of `LightningElement`, but elements used in templates are instances of `HTMLElement`, so we use the `LightningHTMLElement` helper to get the correct type.

```
<template>
    <lightning-card title="Hello Button" icon-name="custom:custom14">
        <div class="slds-var-m-around_medium">Hello, {greeting}!</div>
        <lightning-button label={buttonLabel} onclick={handleClick}></lightning-button>
    </lightning-card>
</template>
```

**note:** The VS Code Salesforce Extension Pack doesn't currently support the `LightningHTMLElement` helper type. We're working on resolving this issue before TypeScript transitions out of Developer Preview.

## Ambient Modules

If your project uses a component that doesn't have type definitions available, you can declare an ambient module and define your own types. Here's an example of an ambient module for the `VendorButton` class:

```
declare module "vendor/button" {
  import { LightningElement } from "lwc";

  export class VendorButton extends LightningElement {
    handleClick(event: ClickEvent): void;
    label?: string;
  }
}
```

We're working on creating new types for first-party Salesforce modules. For more information, see [Salesforce Lightning Types](#salesforce-lightning-types).

## Considerations and Limitations

After you integrate TypeScript into your LWC project, be aware of these restrictions.

### Manage Your TypeScript Version

You're wholly responsible for managing custom TypeScript configurations and TypeScript compiler upgrades for your project. To learn what's new for each release of TypeScript, review the Release Notes in [TypeScript Documentation](https://www.typescriptlang.org/docs/).

### Use a Source Control System

If you integrate TypeScript into your project, we recommend you manage your code using a source control system like Git. TypeScript code isn't stored on the Salesforce platform. You can't deploy TypeScript code or retrieve it from the platform.

### Use Non-Null Assertions Safely

The `shadowRoot` property of an element and the `template` property of a component are always defined in shadow DOM rendering mode and always null in light DOM rendering mode. To satisfy the type checker, you can safely add a non-null assertion (`!`) for components that use shadow DOM. If you use the `!` assertion for components using light DOM, it will result in a runtime error.

**`this.template` inside a component**

Use `this.template!` only when the component uses shadow DOM. In a light DOM component, `this.template` is always `null` at runtime. 

**`shadowRoot` on an element returned by `createElement`**

Use `element.shadowRoot!` only when the element was created from a shadow DOM component. For a light DOM component, `element.shadowRoot` is always `null`. Note that this applies to the element, not the `this.shadowRoot` inside the parent component, which is always `null`.

### Using Decorators with the VS Code Extension

The Salesforce VS Code extension automatically adds types for LWC into your project. However, the included types are incompatible with setting the `experimentalDecorators` compiler options to `false`. Although this setting is required, it causes TypeScript to report an error every time you use a decorator.

To suppress this error, add either `// @ts-ignore` or `// @ts-expect-error` on the line preceding each decorator usage, like this:

```
export default class extends LightningElement {
  // @ts-ignore
  @api myString?: string;

  // @ts-expect-error
  @api myNumber?: number;
}
```

**note:** We're working on resolving this issue before TypeScript transitions out of Developer Preview. We recommend that you plan to remove this error suppression once we've updated the tools and data types such that they are no longer required.

### TypeScript Limitations

For now, LWC support for TypeScript excludes these use cases.

- Using TypeScript with the Salesforce CLI
- Source map debugging using TypeScript
- Non-Salesforce types
- Type definitions for custom Salesforce fields and objects

<!-- document id=8da04ddeec562ce1edf457e7f2cf6b73c2a957583bce1339307ff9abfe0ccf3f url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-performance.md -->

# Understand How LWS Architecture Affects Component Performance

Custom Lightning components always run with either Lightning Locker or Lightning Web Security (LWS). If LWS is disabled, Lightning Locker is enabled. In many cases, components exhibit better performance running with LWS than with Lightning Locker. However, sometimes LWS can have a noticeable performance impact on your components. To give you insight about why your components can run into performance issues with LWS, let’s dig a little deeper into the LWS architecture.

## Security Concerns With Multiple Namespaces

A Lightning page can include components created by multiple companies. For example, components created by an organization’s developer team must run concurrently with components created by Salesforce. If you distribute components in managed packages, your components must run concurrently with components created by Salesforce and the components of the customer who installs your packages.

The components from each origin have a unique namespace, which is a Salesforce requirement for components to be installed into an org. Without a security layer such as Lightning Locker or LWS, the components all have access to the same browser resources and data as if they were all in the same namespace. Such is the nature of all web applications. The chances for unintentional interference between components from different namespaces are high. For example, if a component in namespace `c` changes a global object, the object is mutated for all the components and for the Salesforce platform. Code that tries to use that object after it’s mutated can potentially be unable to perform the intended action. If a component creates data in the page for the use of its namespace, components in other namespaces can also access the data and change it.

For example, suppose a component changes a global function as shown in this code sample.

```javascript
Object.prototype.toString = function () {
  return "";
};
```

The change affects all other objects on the page. This other code sample that’s using that mutated global function always returns the unexpected value.

```javascript
if (myObj.toString() === "expected") {
  // We got the expected value
} else {
  // We got an unexpected value
}
```

## LWS Uses Virtualization to Isolate Namespaces

To understand the reasons for performance issues that components can have when running with LWS, you must be familiar with the concepts discussed in [Virtualization of the Browser](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md#virtualization-of-the-browser).

As a browser virtualization engine, LWS creates virtual environments called sandboxes for each namespace. A namespace sandbox is a copy of the host environment that can only be accessed by components that belong to the namespace.

By default, custom components use the namespace `c`, and LWS creates a `c` sandbox for them. Let’s say that your Lightning page uses your custom components, and also uses components from a managed package that uses the namespace `other`. LWS isolates code that’s running in the namespace `c` sandbox from side effects and changes of code running in the namespace `other` sandbox, and vice versa. If you add components from another namespace called `third` to the page, LWS creates another sandbox for the `third` namespace, and isolates the code from the `c` and `other` namespace sandboxes.

Most importantly, LWS isolates all the sandboxes from the browser’s host environment. The client side of the Salesforce platform runs in the host environment. The platform includes technologies such as the Lightning framework for Aura and Lightning Web Components, Lightning Data Service, and LWS itself. These platform technologies must be protected from malicious or inadvertent access by non-platform code.

The most critical JavaScript object that must be protected in the host environment is the DOM’s `window` global object. Components from namespace `third` must not be able to intentionally or unintentionally modify global variables that could have a negative side effect on the components from the `c` or `other` namespaces. Even more importantly, a non-platform component must not be able to make changes that affect platform code like Aura or LWC. Such changes could have an impact on the entire application.

For example, imagine that an LWC `third-some-cmp` modified some `Array.prototype` functions. If the LWS sandboxes weren’t in effect, those changes affect the host environment, and components like `c-example-cmp` and `other-cmp-example`. When code in the host environment or the other namespaces uses the modified `Array.prototype` functions to manipulate data in arrays, unexpected or harmful behavior can occur.

As another example, imagine some JavaScript from module `other/myFunctions` modifying a cookie called `session`. A component `c-example-cmp` also modifies a cookie called `session`. Without LWS sandboxing, code from different namespaces can accidentally read or modify the same cookie.

## How LWS Enables Interaction of Namespaces

LWS creates a virtual browser environment in a sandbox for each namespace, and allows only namespace code to execute inside this sandbox. At the same time, LWS allows code running inside a sandbox to interact with code running in another sandbox or with the browser’s host environment and the DOM.

This diagram shows the browser host environment and objects related to it in blue. The sandboxes and objects related to them are in red.

![Diagram showing proxy objects in sandboxes and host environment](https://developer.salesforce.com/media/lws_proxy_diagram.png)

In order to allow [marshaled access](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/%3Chttps://en.wikipedia.org/wiki/Marshalling_(computer_science)>) to objects between sandboxes and the host environment, LWS uses [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) objects. Here are a few scenarios using proxies that this diagram demonstrates.

- The solid blue X object ![Object called X created in host environment](https://developer.salesforce.com/media/lws-x-blue-solid.png) is created in and owned by the host environment. LWS allows `c` namespace components to access this object by creating the dashed blue X proxy ![Proxy for X object](https://developer.salesforce.com/media/lws-x-blue-dash.png) in the sandbox. If code in sandbox `c` modifies the blue X proxy ![Proxy for X object](https://developer.salesforce.com/media/lws-x-blue-dash.png) in any way, those modifications are only reflected inside sandbox `c`, and not in the target blue X object ![Target object called X](https://developer.salesforce.com/media/lws-x-blue-solid.png) owned by the host environment.
- The solid red Y object ![Object called Y created in c sandbox](https://developer.salesforce.com/media/lws-y-red-solid.png) is created in and owned by code in namespace `c`. Code in sandbox `c` can pass this object as an argument to a function that’s owned by the host environment. For example, the host environment function can be owned by LWC or Lightning Data Service. LWS provides a dashed red Y proxy object ![Proxy for Y object in host environment](https://developer.salesforce.com/media/lws-y-red-dash.png) for the host environment’s function to interact with.
- If code in sandbox `c` interacts with the solid red Z object ![Object Z created in other sandbox](https://developer.salesforce.com/media/lws-z-red-solid.png) that’s owned by namespace `other`, LWS provides an indirect Z proxy ![Indirect Z proxy created in c sandbox](https://developer.salesforce.com/media/lws-z-red-dot.png) for sandbox `c` code to interact with it. The proxy is indirect because it doesn’t interact directly with the target red Z object ![Target Z object](https://developer.salesforce.com/media/lws-z-red-solid.png). Instead, the indirect Z proxy interacts with the dashed red Z proxy ![Z proxy in host environment](https://developer.salesforce.com/media/lws-z-red-dash.png) in the host environment. LWS provides the dashed red Z proxy ![Z proxy in host environment](https://developer.salesforce.com/media/lws-z-red-dash.png) for code to interact with red Z object ![Target Z object](https://developer.salesforce.com/media/lws-z-red-solid.png) outside of the `other` namespace.
- The solid red W object ![Object W in third sandbox](https://developer.salesforce.com/media/lws-w-red-solid.png) is created in and owned by code in namespace `third`, so the dashed red W proxy object ![Proxy W in host environment](https://developer.salesforce.com/media/lws-w-red-dash.png) is created in the host environment. The indirect W proxy ![Indirect proxy W in other namespace](https://developer.salesforce.com/media/lws-w-red-dot.png) in namespace `other` enables code in that namespace to interact with the target W object ![Object W in third sandbox](https://developer.salesforce.com/media/lws-w-red-solid.png) through the W proxy ![Proxy W in host environment](https://developer.salesforce.com/media/lws-w-red-dash.png) in the host environment.

In summary, LWS provides:

- a proxy object in a sandbox whenever code in the sandbox interacts with an object that’s owned by the host environment
- a proxy object in the host environment whenever code in the host environment interacts with an object that’s owned by a sandbox
- an indirect proxy object in a sandbox whenever code in the sandbox interacts with an object that’s owned by another sandbox

In any sandbox environment, when code modifies a proxy object, the proxy target remains unchanged. LWS protects the target object, whether the target object is also a proxy object or the original object.

**tip:** LWS uses the proxy objects to implement the [distortions](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-architecture.md#distortions) to prevent behavior that’s not secure.

## Performance Side Effects of LWS Proxies

The use of proxies has a performance cost due to the extra processing required. This cost is negligible when there are a few thousand proxies, but as the number of proxies grows into the tens of thousands, the performance impact becomes observable.

### Effects on Applications That Handle Large Quantities of Data

Salesforce testing shows that if an application is already pushing limits that lead to degraded performance, LWS magnifies this effect. For instance, consider an app or component that’s handling a large collection of objects in the tens of thousands. When the large collection is traversed and processed with Lightning Locker enabled, you likely don’t notice performance issues. However, if LWS is enabled, the performance degradation can be noticeable.

This example shows component code that uses the global object [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set). Global objects are owned by the host environment, so LWS creates a proxy Set object in the component’s namespace sandbox. Each access of the Set object goes through the proxy object, which increases the processing cost.

```javascript
// The performance degradation of new Set(bigArray)
// is not that noticeable
const bigArray = [
  /* array with 1,000 entries */
];
const bigSet = new Set(bigArray);

// The performance degradation of new Set(hugeArray)
// is very noticeable
const hugeArray = [
  /* array with 100,000 entries */
];
const hugeSet = new Set(hugeArray);
```

To extend this example, consider a custom component that retrieves a large amount of data from Lightning Data Service or an Apex controller.

```javascript
import { LightningElement, wire, track } from 'lwc';
import getCustomData from '@salesforce/apex/CustomController.getCustomData';

export default class CustomDataProcess extends LightningElement {
    @track customData;
    @track error;
    @wire(getCustomData)
    processCustomData({ error, data }) {
        for (let i = 0; i < data.length; i++) {
            data[i] += data[i] + 1;
            // more code for getting or setting the array elements
        }
    }

    processCustomDataNoWire() {
        getCustomData().then(data =>
            for (let i = 0; i < data.length; i++) {
                data[i] += data[i] + 1;
                // more code for getting or setting the array elements
            }
        )
    }

}
```

The data retrieved from the Apex controller is equivalent to the solid blue X object ![Object called X created in host environment](https://developer.salesforce.com/media/lws-x-blue-solid.png) discussed in [How LWS Enables Interaction of Namespaces](#how-lws-enables-interaction-of-namespaces), meaning that it’s created in and owned by the host environment. To access the data from within the custom code, which exists in the component’s namespace sandbox, each call requires passing through a blue X proxy object ![Proxy for X object](https://developer.salesforce.com/media/lws-x-blue-dash.png). With large quantities of data, this extra processing leads to performance degradation.

To optimize performance, follow these guidelines.

- Move the operation and calculation into the Apex controller so the processing is done on the server side. Don’t perform it on the client side.
- To continue processing on the client side, clone the data so that it’s equivalent to a solid red Y object ![Object called Y created in c sandbox](https://developer.salesforce.com/media/lws-y-red-solid.png) instead of a solid blue X object ![Object called X created in host environment](https://developer.salesforce.com/media/lws-x-blue-solid.png). If the data is created in the component’s namespace sandbox instead of in the host environment, then creation of a blue X proxy object ![Proxy for X object](https://developer.salesforce.com/media/lws-x-blue-dash.png) isn’t required.

Here’s the component code adjusted so that the data is cloned into the component’s namespace sandbox before processing.

```javascript

import { LightningElement, wire, track } from 'lwc';
import getCustomData from '@salesforce/apex/CustomController.getCustomData';

export default class CustomDataProcess extends LightningElement {
    @track customData;
    @track error;

    @wire(getCustomData)
    processCustomData({ error, data }) {
        // Clone the blue data object into red.
        let redData = JSON.parse(JSON.stringify(data));
        for (let i = 0; i < redData.length; i++) {
            redData[i] += redData[i] + 1;
            // more code for getting or setting the array elements
        }
    }

    processCustomDataNoWire() {
        getCustomData().then(data =>
            // Clone the blue data object into red.
            let redData = JSON.parse(JSON.stringify(data));
            for (let i = 0; i < redData.length; i++) {
                redData[i] += redData[i] + 1;
                // more code on getting or setting the array elements
            }
        )
    }
}
```

### Effects on Applications with a Large Number of Components

Another case where LWS can degrade performance is an application that instantiates a large number of components or DOM elements. In particular, if all the components are rendered and present in the DOM at the same time, you can notice performance degradation. DOM operations are expensive, and you must be mindful about what you do in the DOM and how often you do it.

Suppose an app is using a third-party component that performs many DOM operations, and the app spawns many instances of this component. This activity by itself can push the limits of the browser. With LWS disabled, the performance effects can take a long time to see. With LWS enabled, you see the performance effects sooner.

See this article on web.dev [How large DOM sizes affect interactivity, and what you can do about it](https://web.dev/articles/dom-size-and-interactivity) for more information.

## Improvements to LWS Performance

Salesforce continues to examine the effects of LWS on the performance of your custom components. We’re working on ways to improve performance and achieve the same level of security for LWS.

In the meantime, we recommend that you examine your code to find opportunities to reduce heavy DOM usage. When creating large collections of objects, minimize the use of global objects such as Set, Map, and TypedArray. Use plain JavaScript objects instead.

<!-- document id=8897119d7b7237f609de289075f22424040a989183c65f64d8426305114a77a6 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-architecture.md -->

# Understand Lightning Out 2.0 Architecture

Learn how Lightning Out 2.0 provides ‌access to Salesforce on external host pages while securely encapsulating embedded Lightning web components (LWCs). Examine the Lightning Out 2.0 app code and understand how the elements interact with each other and the host page.

## Lightning Out 2.0 JavaScript Library

Include the Lightning Out 2.0 JavaScript library as a script on the external host page.

```html
<script
  type="text/javascript"
  async=""
  src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
></script>
```

The Lightning Out 2.0 code block that the Lightning Out 2.0 App Manager provides includes the `script` element and its attributes. See [Build a Lightning Out 2.0 App](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5) in _Salesforce Help_.

## Lightning Out 2.0 App Component

When a host page initializes the Lightning Out 2.0 script, custom [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) are created in the context of the external host page. One of these components is `lightning-out-application`, which contains the base configuration for the Lightning Out 2.0 app. It doesn’t have a UI element.

```html
<lightning-out-application
  frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
  app-id="18_DIGIT_SALESFORCE_ID"
  components="c-my-lwc,complex_ns-lwc-component"
>
</lightning-out-application>
```

`lightning-out-application` requires three attributes.

- `frontdoor-url`
  - : The frontdoor URL used to establish the Salesforce session. You must set this attribute dynamically at run time. See [Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_auth.htm&type=5) in _Salesforce Help_.
- `app-id`
  - : The 18-digit Lightning Out 2.0 app ID, for example `1Usfi200000006TCAQ`. You can find this value in the Lightning Out 2.0 App Manager in Setup. If you created a Lightning Out 2.0 app before Spring ’26, this attribute isn’t required.
- `components`
  - : A comma-separated list of LWC components to embed in the external page. Use the format `c-my-component`, where hyphens (`-`) separate the namespace and the parts of the component name. If the namespace is mixed cased, separate the parts of the namespace with an underscore (`_`). For example, enter `complex_ns-lwc-component` for complexNs/lwcComponent. You must also add the components to the Lightning Out 2.0 app in the Lightning Out 2.0 App Manager. See [Build a Lightning Out 2.0 App](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5) in _Salesforce Help_.

The Lightning Out 2.0 code block that the Lightning Out 2.0 App Manager provides includes `lightning-out-application`, as well as the `app-id` and `components` attributes.

## Lightning Out 2.0 Web Components

The other Lightning Out 2.0 web components mirror the LWC components added to the Lightning Out 2.0 app. The names of these components are defined in the `components` attribute of `lightning-out-application`.

```html
<c-my-lwc style="--custom-color: brown;"></c-my-lwc>
<complex_ns-lwc-component
  ex-attr="ex-value"
  other-ex-attr="other-ex-value"
></complex_ns-lwc-component>
```

Each Lightning Out 2.0 web component contains an iframe that becomes the root of a [closed shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM). Because the iframe is in the shadow DOM, JavaScript on the host page can’t directly see or manipulate content inside the iframe. Inside the iframe, the actual LWC component runs in the Salesforce context instead of the context of the host page.

On each Lightning Out 2.0 web component, you can set values for any attribute that the corresponding LWC component supports. Passing an unsupported attribute doesn't trigger compilation or run-time errors, but that attribute’s value isn’t set on the LWC component. You can set supported attributes declaratively with HTML, programmatically with JavaScript, or as JSON properties in the Lightning Out 2.0 App Manager.

For example, the Lightning Out 2.0 component `c-my-lwc` has a `style` attribute set to `"--custom-color: brown;"`. `style` is a global attribute, and the LWC component `c-my-lwc` has the CSS custom property `--custom-color` defined in its stylesheet. Therefore, the Lightning Out 2.0 component `c-my-lwc` can pass this attribute to the LWC component `c-my-lwc` in the iframe and override its styling. To learn more about passing attributes, see [Set Component Styles and Properties in a Lightning Out 2.0 App](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-component-properties.md).

## Lightning Out 2.0 Markup

To show how the elements of a Lightning Out 2.0 app work together, here’s the expanded markup for a Lightning Out 2.0 app as it’s embedded in a host page.

```html
<!-- Host page context-->
<body>
  <!--Lightning Out 2.0 JS library -->
  <script
    type="text/javascript"
    async=""
    src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js"
  ></script>
  <!-- Lightning Out 2.0 web component: base configuration -->
  <lightning-out-application
    app-id="18_DIGIT_SALESFORCE_ID"
    frontdoor-url="https://MY_DOMAIN_NAME.salesforce.com/secur/frontdoor.jsp?..."
    components="c-my-lwc"
  >
  </lightning-out-application>
  <!-- Lightning Out 2.0 web component -->
  <c-my-lwc style="--custom-color: brown;">
    <!-- shadow DOM open -->
    <iframe>
      <html>
        <!-- Salesforce context -->
        <body>
          <!-- Lightning web component -->
          <c-my-lwc style="--custom-color: brown;"></c-my-lwc>
        </body>
      </html>
    </iframe>
    <!-- shadow DOM close -->
  </c-my-lwc>
</body>
```

## Lightning Out 2.0 Lifecycle Events

To track the lifecycle of a Lightning Out 2.0 app, Lightning Out 2.0 fires these custom events.

- `lo.application.ready`: Fires if a Salesforce session is successfully established.
- `lo.application.error`: Fires if a Salesforce session can’t be established. The `detail` property of the event has two properties.
  - `message`: The error message.
  - `originalError`: The original error generated inside the Salesforce context.
- `lo.component.ready`: Fires if a Lightning Out 2.0 component successfully renders with the embedded LWC component.
- `lo.component.error:` Fires if a Lightning Out 2.0 component either fails to render or encounters an error from the embedded LWC component during run time. The `detail` property of this event has two properties.
  - `message`: The error message.
  - `originalError`: The original error generated inside the Salesforce context.

## Lightning Out 2.0 Initialization Flow

With these events in mind, let’s summarize the Lightning Out 2.0 app initialization flow.

1. An end user opens the host page.
2. The host page uses the [UI Bridge API](https://help.salesforce.com/s/articleView?language=en_US&id=xcloud.frontdoor_singleaccess.htm&type=5) to exchange a valid Salesforce access token or Session ID for a frontdoor url. If the end user isn’t already logged into Salesforce, the OAuth authorization flow is initiated.
3. After receiving the frontdoor URL, the host page sets the `frontdoor-url` attribute on `lightning-out-application`.
4. The Lightning Out 2.0 script uses the frontdoor URL to initialize the `lightning-out-application` app and establish a Lightning Out 2.0 session.
5. If the session is established successfully, the Lightning Out 2.0 app fires the `lo.application.ready` custom event.
6. The other Lightning Out 2.0 web components are initialized. Each component contains an iframe that becomes the root element of a shadow DOM.
7. Inside the iframes, the corresponding custom LWC components are initialized. The LWC components run in the Salesforce context.
8. The Lightning Out 2.0 web components, still running in the context of the host page, render the iframes that contain the embedded LWC components.
9. If the components render successfully, the Lightning Out 2.0 app fires the `lo.component.ready` custom event.

**See Also**

- [_Salesforce Help_: Set Up Authentication for Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_2_intro.htm&type=5)
- [_Salesforce Help_: Build a Lightning Out 2.0 App](https://help.salesforce.com/s/articleView?id=platform.lightning_out_build.htm&type=5)
- [Set Component Styles and Properties in a Lightning Out 2.0 App](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-component-properties.md)
- [Handle Lightning Out 2.0 App Events](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-events.md)

<!-- document id=8c385a7ed64cc45dedf771a3ac4281c120624be5b1ec69ee498e8feeb5cffc2d url=/developer/current/en-us/lwc/lwc/guides/data/data-wire-service-about.md -->

# Understand the Wire Service

The wire service provisions an immutable stream of data to the component. Each value in the stream is a newer version of the value that precedes it.

**important:** Objects passed to a component are read-only. To mutate the data, a component should make a shallow copy of the objects it wants to mutate. It’s important to understand this concept when working with data. See [Data Flow](https://developer.salesforce.com/docs/platform/lwc/create/create-components-data-flow.md).

We call the wire service reactive in part because it supports reactive variables, which are prefixed with `$`. If a reactive variable changes, the wire service provisions new data. We say “provisions” instead of “requests” or “fetches” because if the data exists in the client cache, a network request may not be involved.

**tip:** The wire service delegates control flow to the Lightning Web Components engine. Delegating control is great for read operations, but it isn’t great for create, update, and delete operations. As a developer, you want complete control over operations that change data. That’s why you perform create, update, and delete operations with an [imperative JavaScript function](https://developer.salesforce.com/docs/platform/lwc/reference/reference-lightning-ui-api-record.md) instead of with the wire service.

## Wire Service Syntax

Import a wire adapter using [named import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) syntax. Decorate a property or function with `@wire` and specify the wire adapter. Each wire adapter defines a data type.

The wire service provisions an immutable stream of data. The data is not guaranteed to be the same, even when the _adapterConfig_ object content is the same.

```javascript
// Syntax
import { adapterId } from 'adapterModule';
@wire(adapterId, adapterConfig)
propertyOrFunction;
```

- `adapterId` (Identifier)—The identifier of the wire adapter.
- `adapterModule` (String)—The identifier of the module that contains the wire adapter function, in the format `namespace/moduleName`. To import a module in JavaScript, use the format `lightning/ui*Api` instead of `lightning-ui-*-api`. For example, `lightning/uiRecordApi`.
- `adapterConfig` (Object)—A configuration object specific to the wire adapter. Configuration object property values can be either strings or references to objects and fields imported from `@salesforce/schema`. Properties in the `{adapterConfig}` object can’t be undefined. If a property is undefined, the wire service doesn’t provision data, and both `data` and `error` stay undefined. For an example, see the [pagination tip in `getListRecordsByName`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-list-records-by-name.md#usage). Don’t update a wire adapter configuration object property in `renderedCallback()` as it can result in an infinite loop.

Read the data that's returned by the wire adapter using a property or function.

`propertyOrFunction`—A private property or function that receives the stream of data from the wire service.

- If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property.
- If a function is decorated with `@wire`, the results are returned in an object with a `data` property and an `error` property.


**note:** The `data` property and the `error` property are hardcoded values in the API. You must use these values for most wire adapters. The [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/graphql/reference-graphql.md) uses `errors` instead of `error`, which maintains compatibility with the GraphQL response specification.

## Import References to Salesforce Objects and Fields

When you use a wire adapter in a [`lightning/ui*Api`](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md) module, we strongly recommend importing references to objects and fields. Salesforce verifies that the objects and fields exist, prevents objects and fields from being deleted, and cascades any renamed objects and fields into your component's source code. It also ensures that dependent objects and fields are included in change sets and packages. Importing references to objects and fields ensures that your code works, even when object and field names change.

**tip:** To follow along with some code samples, see the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. Look for components whose names start with `wire`.

If a component isn’t aware of which object it’s using, use strings instead of imported references. Use [`getObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-object-info.md) to return the object’s fields. All wire adapters in the [`lightning/ui*Api`](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md) modules respect object CRUD rules, field-level security, and sharing. If a user doesn’t have access to a field, it isn’t included in the response.

**note:** Currently, name changes don’t cascade thoroughly into source code for approximately two hours. For a component used in App Builder, this timing is also important if the component’s meta.xml file uses `<objects>` to constrain the object home or record home.

To access object and field API names, use an `import` statement. All object and field imports come from `@salesforce/schema` [scoped packages](https://docs.npmjs.com/misc/scope).

To import a reference to an object, use this syntax.

```javascript
import objectName from "@salesforce/schema/object";
import objectName from "@salesforce/schema/namespace__object";

import POSITION_OBJECT from "@salesforce/schema/Position__c";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
```

To import a reference to a field, use this syntax.

```javascript
import FIELD_NAME from "@salesforce/schema/object.field";

import POSITION_LEVEL_FIELD from "@salesforce/schema/Position__c.Level__c";
import ACCOUNT_NAME_FIELD from "@salesforce/schema/Account.Name";
```

To import a reference to a field via a relationship, use this syntax.

```javascript
import SPANNING_FIELD_NAME from "@salesforce/schema/OBJECT.RELATIONSHIP.FIELD";

import POSITION_HIRINGMANAGER_NAME_FIELD__c from "@salesforce/schema/Position__c.HiringManager__r.Name__c";
import ACCOUNT_OWNER_NAME_FIELD from "@salesforce/schema/Account.Owner.Name";
```

To reference parent objects and fields, you can specify up to three **relationship fields** using the format `<SObjectName>.<relationship-1>.<relationship-2>.<relationship-3>.<fieldName>`.

**tip:** For objects, we use the naming convention `OBJECTNAME_OBJECT`. For fields, we use the naming convention `FIELDNAME_FIELD`. We use these naming conventions to make code easier to understand. They’re guidelines, not rules.

This code imports the `Account.Name` field and uses it in a wire adapter’s configuration object.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";
import ACCOUNT_NAME_FIELD from "@salesforce/schema/Account.Name";

export default class Record extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields: [ACCOUNT_NAME_FIELD] })
  record;
}
```

This code is almost identical, but it uses a string to identify the `Account.Name` field. This code doesn’t get the benefits that you get from importing a reference to the field.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

export default class Record extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields: ["Account.Name"] })
  record;
}
```

## Import References for Compound Fields

Name fields, address fields, and geolocation fields are compound fields. A compound field is accessible as a single, structured field, or as individual constituent fields. The value contained in the compound field and the values in the constituent fields both map to the same data stored in Salesforce.

In a read operation, you can import a reference to a compound field or to its constituent fields. For example, in a read operation, you can use `Contact.Name`, which is a compound field.

```javascript
import NAME_FIELD from "@salesforce/schema/Contact.Name";
```

For create and update operations on compound fields using `lightning/ui*Api` functions like [`updateRecord(recordInput, clientOptions)`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-update-record.md), you must import the constituent fields. For example, import `Contact.FirstName` and `Contact.LastName` instead of `Contact.Name`. Remember to include all the required constituent fields. For example, to create a contact, the `LastName` field is required.

```javascript
import FIRSTNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LASTNAME_FIELD from "@salesforce/schema/Contact.LastName";
```

A compound address field is supported through its constituent fields. To access an address field, use its constituent fields with string syntax.

```javascript
const STREET_FIELD = "Contact.MailingStreet";
const CITY_FIELD = "Contact.MailingCity";
```

A compound geolocation field is supported through its constituent fields. To access a geolocation field, use its constituent fields with string syntax.

```javascript
// User.Place_of_birth__c is a compound custom field of type Geolocation
const PLACE_OF_BIRTH_LAT_FIELD = "User.Place_of_birth__Latitude__s";
const PLACE_OF_BIRTH_LON_FIELD = "User.Place_of_birth__Longitude__s";
```

**tip:** The [Build a Bear-Tracking App with Lightning Web Components](https://trailhead.salesforce.com/content/learn/projects/lwc-build-flexible-apps) Trailhead project uses the compound geolocation field and transforms the latitude and longitude data into map markers.

## Import Limitations

Salesforce supports many object or field suffixes to represent different types of data. Lightning Web Components supports the import of references to standard objects, as well as the import of references to custom objects (`__c`) only. For example:

```javascript
import POSITION_OBJECT from "@salesforce/schema/Position__c";
```

Consider these workarounds for importing references to some other object or field suffixes.

- Person Accounts
  - : A `__pc` field represents a person account, which stores information about an individual person by combining certain account and contact fields into a single record. Every custom field created in the Contact object is available for person accounts in the Account object using the `__pc` suffix, but this syntax doesn't work in an `import` statement.

    Instead of importing a `__pc` field from the Account object, import the custom field from the Contact object to get the benefits of referential integrity.

    ```javascript
    import PA_CONTACT_CUSTOM_FIELD from "@salesforce/schema/Contact.myCustomField__c";
    ```

    Later in the JavaScript file, you can directly access the `Account.myCustomField__pc` field that references `Contact.myCustomField__c`. For example:

    ```javascript
    paField = "Account.myCustomField__pc";
    ```

- External Objects
  - : An `__x` suffix represents an external custom object, which is similar to a custom object, except that it maps to data that’s stored outside your Salesforce org.

    To retrieve data from an external custom object, call a method in an Apex class that gets the data with a SOQL query.

**note:** `Knowledge__kav` cannot be imported in a custom component. To use a field on `Knowledge__kav` with a wire adapter, pass in the field directly using the `fields: ['Knowledge__kav.Title']` syntax.

## Mark a Configuration Object Property as Dynamic and Reactive

In the wire adapter’s configuration object, prefix a value with `$` to reference a property of the component instance. The `$` prefix tells the wire service to treat it as a property of the class and evaluate it as `this.propertyName`. The property is reactive. If the property’s value changes, new data is provisioned and the component rerenders.

Use the `$` prefix for top-level values in the configuration object. Nesting the `$` prefix such as in an array like `['$accountIds']` makes it a literal string, which is not dynamic or reactive.

In this example, `$recordId` is dynamic and reactive.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord, getFieldValue } from "lightning/uiRecordApi";

import REVENUE_FIELD from "@salesforce/schema/Account.AnnualRevenue";

const fields = [REVENUE_FIELD];

export default class WireGetValue extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields })
  account;

  get revenue() {
    return getFieldValue(this.account.data, REVENUE_FIELD);
  }
}
```

A value without a `$`, like the value of the `fields` property in a previous example, is a static value, `[AccountNameField]`.

You can designate these types of configuration object properties as dynamic and reactive.

- Private properties
- Properties defined by a getter-setter pair
- Properties decorated with `@api`

## Decorate a Property with `@wire`

Wiring a property is useful when you want to consume the data or error as-is.

If the property decorated with `@wire` is used as an attribute in the template and its value changes, the wire service provisions the data and triggers the component to rerender. The property is private, but reactive.

This code applies `@wire` to the `record` property.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";
import ACCOUNT_NAME_FIELD from "@salesforce/schema/Account.Name";

export default class Record extends LightningElement {
  @api recordId;

  @wire(getRecord, { recordId: "$recordId", fields: [ACCOUNT_NAME_FIELD] })
  record;
}
```

The property is assigned a default value after component construction and before any other [lifecycle event](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md).

The default value is an object with `data` and `error` properties of `undefined`.

```javascript
{ data: undefined, error: undefined }
```

Therefore, you can access the property’s value in any function, including functions used by the template or used as part of the component’s lifecycle.

```javascript
@wire(getRecord, { recordId: "$recordId", fields: [ACCOUNT_NAME_FIELD] })
wiredRecord({ data, error }) {
  // do something with data and error
}
```

**note:** Since you pass in an object to an `@wire` function, the parameter order is irrelevant. You can use either `data, error` or `error, data`. The order matters only when you are destructuring arrays.

The object supplied to the property (in this example, `record`) has this shape.

- `data` (Any type)—The value supplied by the adapter.
- `error` (Error)—An error if the adapter wasn’t able to supply the requested data or if the adapter wasn’t found. Otherwise, this property is `undefined`.

When data becomes available from the wire adapter, it’s set in the `data` property (`error` remains `undefined`). When newer versions of the data are available, `data` is updated.

If an error occurs in the adapter, for example when retrieving the data, `error` is populated with an error object (`data` is set to `undefined`).

You can use one `@wire` output as another `@wire` input. For example, you could use `$record.data.fieldName` as an input to another wire adapter.

## Decorate a Function with `@wire`

Wiring a function is useful to perform logic whenever new data is provided or when an error occurs. The wire service provisions the function an object with `error` and `data` properties, just like a wired property.

The function is invoked whenever a value is available, which can be before or after the component is connected or rendered.

```javascript
// wireFunction.js
import { LightningElement, api, track, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

export default class WireFunction extends LightningElement {
  @api recordId;
  @track record;
  @track error;

  @wire(getRecord, { recordId: "$recordId", fields: ["Account.Name"] })
  wiredAccount({ data, error }) {
    if (data) {
      this.record = data;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.record = undefined;
    }
  }
  get name() {
    return this.record.fields.Name.value;
  }
}
```

<!-- prettier-ignore -->
```html
<!-- wireFunction.html -->
<template>
  <lightning-card title="Wire Function" icon-name="standard:contact">
    <template lwc:if={record}>
      <div class="slds-m-around_medium">
        <p>{name}</p>
      </div>
    </template>
    <template lwc:if={error}>
      <c-error-panel errors={error}></c-error-panel>
    </template>
  </lightning-card>
</template>
```

## Wire Service Data Lifecycle

A wire adapter is evaluated only when its configuration is complete, which occurs when you define a value for all dynamic parameters for the call. For example, this can take longer if you use a parent component that retrieves data using a wire and then passes on the result to a child component, which in turn uses the result to retrieve data from another wire.

When the component is initialized, it fires the `constructor()`. Assuming the configuration on the wire adapter is complete, a Lightning Data Service (LDS) wire provisions an empty object containing the `data` and `error` properties, each with an `undefined` default value.

Next, the `connectedCallback()`, `render()`, and `renderedCallback()` lifecycle hooks are fired in that order.

When data becomes available from the wire adapter, it’s set in the `data` property while `error` remains `undefined`. When newer versions of the data are available, LDS emits a value on the wire. If the component uses the data to change the content of its template, the `render()` and `renderedCallback()` hooks are fired again.

**note:** An LDS wire can emit data multiple times without the component changing its configuration. LDS controls these emits, and they aren't related to the LWC component lifecycle.

Consider these guidelines when using a wire adapter.

- [Apex wire adapters](https://developer.salesforce.com/docs/platform/lwc/apex/apex-wire-method.md) are also LDS-based. Wire adapters listed in the [Reference section](https://developer.salesforce.com/docs/platform/lwc/reference/reference.md) are LDS-based unless otherwise specified.
- Wire adapter calls are asynchronous unless data is cached. Therefore, the order of response and promise resolution are not sequential.
- Data can be returned at any time. Although LDS tries to return the data as soon as possible, multiple layers of caching involved in your request can impact how quickly you get the data. If data is already available in LDS cache, it's returned without a network call. If data is not in the cache, then the wire evaluation results in a network call.
- Don't depend on receiving data from a wire adapter at any specific point in your component lifecycle. The wire can receive data as often as necessary and at any time. Use the wire adapter as a way to retrieve the data you need. The framework determines when, how, how often, and from where to get that data.
- If you asynchronously change a record using an Apex trigger or an auto-launched flow, the wire adapter won't be re-evaluated.
- To manually refresh wire adapter data, use [`refreshApex()`](https://developer.salesforce.com/docs/platform/lwc/apex/apex-result-caching.md) for Apex wire adapters or [`refreshGraphQL()`](https://developer.salesforce.com/docs/platform/lwc/reference/graphql/reference-refreshgraphql.md) for GraphQL wire adapters. Refresh once after a mutating operation completes. Don't use refresh functions in a polling pattern with `setTimeout()` or `setInterval()`, as polling creates unnecessary server load.

**See Also**

- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)
- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)
- [@salesforce Modules](https://developer.salesforce.com/docs/platform/lwc/reference/reference-salesforce-modules.md)
- [Lifecycle Hooks](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md)

<!-- document id=86162f3c07e6af88e72c2a1befbba7e94199473fd83fe1967a7168fe8afad1e9 url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshview-unregisterrefreshcontainer.md -->

# `unregisterRefreshContainer()`

Stops a container from receiving refresh events.

## Syntax

```typescript
import { LightningElement, wire } from "lwc";
import { unregisterRefreshContainer } from "lightning/refresh";

export function unregisterRefreshContainer(refreshID);
```

## Parameters

`refreshID`—(Required) A numeric `refreshNode.handle` value that uniquely identifies the node of this container on the refresh tree. You obtain the `refreshNode.handle` value when you call [`registerRefreshContainer()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-registerrefreshcontainer.md).

## Returns

None.

## Usage

Use the `unregisterRefreshContainer()` method to remove a refresh container’s registration from the refresh tree. Child contexts are temporarily retained to ensure that they are refreshed, in case unregistration takes place mid-refresh.

You must unregister your component’s container callback methods in `disconnectedCallback()`.

```javascript
import { unregisterRefreshContainer } from 'lightning/refresh';

disconnectedCallback() {
  unregisterRefreshContainer(this.refreshContainerID);
}

```

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=f0dd0d0fc1addeee08e72a634a84471af7037177132cc8c7eb93dbe6145635cd url=/developer/current/en-us/lwc/lwc/guides/reference/refreshview/reference-lightning-refreshview-unregisterrefreshhandler.md -->

# `unregisterRefreshHandler()`

Removes a component’s refresh handler method from the refresh process.

## Syntax

```typescript
import { LightningElement, wire } from "lwc";
import { unregisterRefreshHandler } from "lightning/refresh";

export function unregisterRefreshHandler(refreshID);
```

## Parameters

`refreshID`—(Required) A numeric `refreshNode.handle` value that uniquely identifies the node of this component on the refresh tree. You obtain the `refreshNode.handle` value when you call [`registerRefreshHandler()`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refreshview-registerrefreshhandler.md).

## Returns

None.

## Usage

Use the `unregisterRefreshHandler()` method to remove a refresh handler's registration from the refresh tree. Child contexts are temporarily retained to ensure that they are refreshed, in case unregistration takes place mid-refresh.

You must unregister your component’s handler callback methods in `disconnectedCallback()`.

```javascript
import { unregisterRefreshHandler } from 'lightning/refresh';

disconnectedCallback() {
  unregisterRefreshHandler(this.refreshHandlerID);
}

```

**See Also**

- [Use RefreshView API](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-api.md)
- [RefreshView API Example](https://developer.salesforce.com/docs/platform/data/refreshview/data-refreshview-example.md)

<!-- document id=61bbcdf8154a7f7eb40ecdf77a6f86b1c0520261ba60fdac5a3d13d5cd0708b3 url=/developer/current/en-us/lwc/lwc/guides/reference/wire-adapters/reference-wire-adapters-editor-update-content.md -->

# `updateContent`

Updates the `title` and `contentBody` of the content item in the content editor of an enhanced CMS workspace. Updates are persisted when the user clicks Save in the content editor.

You can use `this.context.data.schema.schema.properties` to return the list of `contentBody` property fields for the content type.

## Syntax

```javascript
import { LightningElement, wire } from 'lwc';
import { updateContent }  from experience/cmsEditorApi;
class Example extends LightningElement{
  // change the content in the editor
  updateContent({
    "title": "new title",
    "contentBody: {
      "name": "New name",
      "description": "New description",
      "excerpt": "new-excerpt"
    }
  }).then(() => {
      //handle success
  })
}
```

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                        | Required?                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `contentBody`  | Object | The JSON representation of the content body, which varies depending on the content type. See [JSON File Format for Content in Salesforce CMS](https://help.salesforce.com/s/articleView?id=xcloud.cms_import_content_json.htm) in Salesforce Help. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `title`        | String | The new title of the content item in the editor.                                                                                                                                                                                                   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves when the `updateContent` response is returned.
- `error`—A validation error for invalid fields.

<!-- document id=d887f1dd0c6358c37fbf401a37d49b89ad6877c3398fed10e3e1e95503483d90 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-data-connector.md -->

# `updateDataConnector`

Updates a CRM Analytics data connector.

## Syntax

```javascript
import { updateDataConnector } from 'lightning/analyticsWaveApi';
updateDataConnector({ connectorIdOrApiName: string, dataConnector : DataConnectorInput }): Promise<DataConnector>
```

## CRM Analytics API Resource

```html
PATCH /wave/dataConnectors/${connectorIdOrApiName}
```

`updateDataflowJob` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataconnectors_connectorid.htm).

## Parameters

| Parameter Name         | Type   | Description                                                                                                                                                                                                    | Required?                                  |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `connectorIdOrApiName` | String | The ID or developer name of the data connector.                                                                                                                                                                | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `dataConnector`        | Object | The data connector instance to update. Use a [Data Connector Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_data_connector_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Data Connector](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_data_connector.htm) response.

## Usage

There are several ways to use `updateDataConnector`. For example, you can display a list of data connectors and update the connection properties, label, or description.

This example adds an update button to a page with data connectors. The page must contain form elements for the information required to update the connector, like the label. Updating a data connector displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateDataConnector } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateDataConnector extends LightningElement {
  @api dcId; // or fetch the ID of the data connector
  dataConnector = {
    label: "My SFDC Ext Connector",
    description: "My updated connection to another SFDC org",
  };

  update(event) {
    updateDataConnector({ connectorIdOrApiName: this.dcId, dataConnector: this.dataConnector })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Data Connector updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating data connector",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateDataConnector()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update"
    icon-name="utility:play"
    icon-position="right"
    onclick={Update}
  ></lightning-button>
</template>
```

<!-- document id=0978cebf418ce02984a9ddd110efb6bbbcb4d1bf4d462d4bcaecb0f602b58b55 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-dataflow-job.md -->

# `updateDataflowJob`

Updates a CRM Analytics dataflow job, which is the equivalent of clicking **Stop** for a data prep recipe, a data sync, or a dataflow in the Tableau CRM Data Manager UI.

## Syntax

```javascript
import { updateDataflowJob } from 'lightning/analyticsWaveApi';
updateDataflowJob({ dataflowjobId: string, dataflowJob: { command: string } }): Promise<DataflowJob>
```

## CRM Analytics API Resource

```html
PATCH /wave/dataflowjobs/${dataflowjobId}
```

`updateDataflowJob` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataflowjobs_id.htm).

## Parameters

| Parameter Name  | Type   | Description                                                                                                   | Required?                                  |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `dataflowjobId` | String | The dataflow job ID.                                                                                          | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `command`       | String | The job command to execute. <ul><li>`start`</li><li>`stop`</li></ul> Must be `stop` to update a dataflow job. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Dataflow Job](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataflow_job.htm) response.

## Usage

There are several ways to use `updateDataflowJob`. For example, you can display a list of dataflow jobs and enable stop on each queued or running recipe on the list.

This example adds a stop button to a page with recipes. Stopping a recipe displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { updateDataflowJob } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class UpdateDataflowJob extends LightningElement {
  @api dfjobId; // or fetch the ID of the dataflow job
  command = 'start';

  stop(event) {
    updateDataflowJob({ dataflowjobId: this.dfjobId, dataflowJob: { this.command } })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Success',
            message: 'Recipe job stopped',
             variant: 'success'
                    })
          );
        })
        .catch(error => {
          this.dispatchEvent(
            new ShowToastEvent({
              title: 'Error stopping recipe job',
              message: error.body.message,
              variant: 'error'
            })
          );
        });
  }
}

```

This button calls the `updateDataflowJob()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Stop"
    icon-name="utility:stop"
    icon-position="right"
    onclick={stop}
  ></lightning-button>
</template>
```

<!-- document id=ec80023b6345ec7cc20e5d30d19854bf0da6332bab0340d70808605d25bfbfb5 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-dataset.md -->

# `updateDataset`

Updates a specific CRM Analytics dataset by ID.

## Syntax

```javascript
import { updateDataset } from 'lightning/analyticsWaveApi';
updateDataset({ datasetIdOrApiName: string, dataset: DatasetInput }): Promise<Dataset>
```

## CRM Analytics API Resource

```html
PUT /wave/datasets/${datasetIdOrApiName}
```

`updateDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_dataset_id.htm).

## Parameters

| Parameter Name       | Type   | Description                                                                                                                                                                      | Required?                                  |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The ID or API name of the dataset.                                                                                                                                               | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `dataset`            | Object | The dataset to update. Use a [Dataset Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_dataset_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset.htm) response.

## Usage

Use `updateDataset` to allow users to change descriptions, labels, and more. This example adds an update button to a page with datasets. The page must contain form elements for the information required to update the dataset. Updating a dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateDataset } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateDataset extends LightningElement {
  @api dId; // or fetch the ID of the dataset
  dataset = {
    label: "Updated dataset",
  };

  update(event) {
    updateDataset({ datasetIdOrApiName: this.dId, dataset: this.dataset })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Dataset updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating dataset",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Dataset"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=e6bce916875eb7b7505d23068f776687a2b777e550f7d9ec44486caf1aa2e90f url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-dataset-version.md -->

# `updateDatasetVersion`

Updates a specific CRM Analytics dataset version by dataset ID and version ID.

## Syntax

```javascript
import { updateDatasetVersion } from 'lightning/analyticsWaveApi';
updateDatasetVersion({ datasetIdOrApiName: string, versionId: string, datasetVersion: DatasetVersionInput }): Promise<DatasetVersion>
```

## CRM Analytics API Resource

```html
PUT /wave/datasets/${datasetIdOrApiName}/versions/${versionId}
```

`updateDatasetVersion` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_datasets_id_versions_id.htm).

## Parameters

| Parameter Name       | Type   | Description                                                                                                                                                                                              | Required?                                  |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetIdOrApiName` | String | The ID or API name of the dataset.                                                                                                                                                                       | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `versionId`          | String | The ID of the dataset version.                                                                                                                                                                           | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `datasetVersion`     | Object | The dataset version to update. Use a [Dataset Version Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_dataset_version_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Dataset Version](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_dataset_version.htm) response.

## Usage

Use `updateDatasetVersion` to allow users to update the predicate. This example adds an update button to a page with dataset versions. The page must contain form elements for the information required to update the dataset version. Updating a dataset version displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateDatasetVersion } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateDatasetVersion extends LightningElement {
  @api dId; // or fetch the ID of the dataset
  @api vId; // or fetch the ID of the dataset version
  datasetVersion = {
    predicate: "<predicate value>",
  };

  update(event) {
    updateDatasetVersion({
      datasetIdOrApiName: this.dId,
      versionId: this.vId,
      datasetVersion: this.datasetVersion,
    })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Dataset version updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating dataset version",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateDatasetVersion()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Dataset Version"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=86b98423bc733367088eae5f71b94ab66743765c212c671b0c07de0056908d1a url=/developer/current/en-us/lwc/lwc/guides/reference/calendarservice/reference-lightning-calendarservice-updateevent.md -->

# `updateEvent(updatedEvent, options)`

Updates an event in the device’s calendar.

**note:** Using `updateEvent()` is an inherently dangerous action, as it allows event data to be irreversibly altered. Use caution when using this functionality in your component. At an absolute minimum, consider adding a confirmation window for your users that clearly states the outcome of the action, with an option for them to cancel if they wish.

## Syntax

```
import { getCalendarService } from 'lightning/mobileCapabilities';
updateEvent(updatedEvent: Event,
  options: CalendarServiceOptions
  ): Promise<Object>
```

## Parameters

- `updatedEvent`—(Required) An `Event` object with updated data to replace the existing data in the corresponding event on the device’s calendar.
- `options`—(Required) A [`CalendarServiceOptions`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-calendarservice-data-types.md) object to configure the CalendarService request.

## Returns

A Promise object that resolves as a coerced version of the `Event` parameter. If an error is encountered, an error message is returned.

## Usage

Use this function to update an event on a device’s calendar.

```javascript
myCalendarService
  .updateEvent(updatedEvent, options)
  .then((results) => {
    this.updatedEvent = results;
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    +console.error("Error message: " + error.message);
  });
```

For more information on when and why CalendarService coerces (changes) event data, see [Implicit Data Coercion](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice_in_a_lightning_component.htm#implicitdatacoercion).

**See Also**

- [Use the CalendarService API](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_calendarservice_in_a_lightning_component.htm)

<!-- document id=ab38f159836b2766d6e068e8d83380473a51e173133e9c3abc397d34542584f9 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-update-list-info.md -->

# `updateListInfoByName`

Use this wire adapter to update a list view’s metadata.

## Syntax

```javascript
import { updateListInfoByName } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

updateListInfoByName({
  objectApiName: ACCOUNT_OBJECT,
  listViewApiName: "MyAccountListView",
  label: "NewListViewLabel",
});
```

## User Interface API Resource

```html
PATCH /ui-api/list-info/${objectApiName}/${listViewApiName}
```

See [Update List View Metadata](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_views_md_patch.htm).

## Parameters

| Parameter Name      | Type     | Description                                                                                                                                                                               | Required?                               |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`     | String   | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html).                                                          | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName`   | String   | The API name of a list view, such as `AllAccounts`.                                                                                                                                       | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `displayColumns`    | String[] | The display columns (field API names) for the list.                                                                                                                                       |                                         |
| `filterLogicString` | String   | The filter logic string, such as `(1 OR 2) and 3`. Indexes start with 1.                                                                                                                  |                                         |
| `filteredByInfo`    | Object   | Filtering information for the list. Type [List Filter By Info Input[]](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_list_filter_by_info_input.htm). |                                         |
| `label`             | String   | The list’s display label. For example, All Accounts.                                                                                                                                      |                                         |
| `listShares`        | String[] | Objects the list is shared with, if `visibility` is set to `Shared`.                                                                                                                      |                                         |
| `scope`             | Object   | The scope information for the list. See [List Scope Input](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_list_scope_input.htm).                      |                                         |
| `visibility`        | String   | The list’s visibility. Valid values are: <ul><li>`Private`</li><li>`Public`</li><li>`Shared`</li></ul>.                                                                                   |                                         |

## Returns

- `data`—[List Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_metadata.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/guide/data-error.html)

## Usage

This code example updates the list view’s label on the button click.

<!-- prettier-ignore -->
```html
<!-- wireUpdateListInfoByName.html -->
<template>
   <lightning-card title="wireUpdateListInfo">
       <lightning-button variant="brand" label="Update List View" title="Primary action" onclick={updateListView} class="slds-m-left_x-small"></lightning-button>
       <template lwc:if={label}>
           <div class="slds-m-around_medium">
               <p key={label}>New ListView Label: {label}</p>
           </div>
       </template>
   </lightning-card>
</template>
```

```javascript
// wireUpdateListInfoByName.js
import { updateListInfoByName } from "lightning/uiListsApi";
import { LightningElement, api } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class UpdateListInfo extends LightningElement {
  error;
  label;
  @api async updateListView() {
    updateListInfoByName({
      objectApiName: ACCOUNT_OBJECT.objectApiName,
      listViewApiName: "AllAccounts",
      label: "New Label",
    })
      .then((result) => {
        this.label = result.data.label;
      })
      .catch((error) => {
        this.error = error;
      });
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=c2feb6201f481d8e689ff611d0ae78d21a6d05e5ea7d615cc2042cc806151a26 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-update-list-preferences.md -->

# `updateListPreferences`

Use this wire adapter to update the preferences for a list view.

## Syntax

```javascript
import { updateListPreferences } from "lightning/uiListsApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";

export default class UpdateListPrefExample extends LightningElement {

  updateListPreferences({
    objectApiName: ACCOUNT_OBJECT,
    listViewApiName: "AllAccounts",
  });
}
```

## User Interface API Resource

```html
PATCH /ui-api/list-preferences/${objectApiName}/${listViewApiName}
```

See [Update List View Preferences](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_list_preferences_update.htm).

## Parameters

| Parameter Name    | Type     | Description                                                                                                                                                                  | Required?                               |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `objectApiName`   | String   | The API name of a [supported object](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.html).                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `listViewApiName` | String   | The API name of a list view, such as `AllAccounts`.                                                                                                                          | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `columnWidths`    | Object   | The column-width preferences for the list. Pass in a key-value pair with the name of the column and an integer.                                                              |                                         |
| `columnWrap`      | Object   | The column-wrapping preferences for the list. Pass in a key-value pair with the name of the column and a boolean.                                                            |                                         |
| `listReference`   | Object   | The reference information for the list.                                                                                                                                      |                                         |
| `orderedBy`       | String[] | The ordering preference for the list. Type [List Order Input[]](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_list_order_by_input.htm). |                                         |

## Returns

- `data`—[List Info](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_list_metadata.htm)
- `error`–[FetchResponse](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)

## Usage

This code example updates a list view’s preferences and displays the updated values.

<!-- prettier-ignore -->
```html
<!-- wireUpdateListPreferences.html -->
<template>
   <lightning-card title="wireUpdateListPreferences">
       <lightning-button variant="brand" label="Update List View Preferences" title="Primary action" onclick={updateListViewPrefs} class="slds-m-left_x-small"></lightning-button>
       <template lwc:if={columnWidths}>
           <div class="slds-m-around_medium">
               <template for:each={columnWidths} for:item="col">
                   <li key={col}>{col}</li>
               </template>
           </div>
       </template>
   </lightning-card>
</template>
```

```javascript
// wireUpdateListPreferences.js
import { updateListPreferences } from "lightning/uiListsApi";
import { LightningElement, api } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
export default class UpdateListPrefs extends LightningElement {
  error;
  columnWidths;
  @api async updateListViewPrefs() {
    updateListPreferences({
      objectApiName: ACCOUNT_OBJECT.objectApiName,
      listViewApiName: "AllAccounts",
      columnWidths: {
        Type: 200,
        "Owner.Alias": 200,
        Phone: 200,
        BillingState: 250,
        Name: 250,
      },
    })
      .then((result) => {
        this.columnWidths = Object.entries(result.data.columnWidths);
      })
      .catch((error) => {
        this.error = error;
      });
  }
}
```

**See Also**

- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-error.md)
- [Salesforce Objects Supported by lightning/ui\*Api Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-supported-objects.md)

<!-- document id=ddb719b4fc7f88d43e9527df3056fd02778dabf01905923b03a7b00df23037b3 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-partial-wave-folder.md -->

# `updatePartialWaveFolder`

Performs a partial a specific CRM Analytics folder by ID.

## Syntax

```javascript
import { updatePartialWaveFolder } from 'lightning/analyticsWaveApi';
updatePartialWaveFolder({ folderId: string, folder: BaseWaveFolderInput }): Promise<WaveFolder>
```

## CRM Analytics API Resource

```html
PATCH /wave/folders/${folderId}
```

`updatePartialWaveFolder` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders_id.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                       | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `folderId`     | String | The ID of the folder.                                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `folder`       | Object | The folder to update. Use a [Base Wave Folder Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_base_wave_folder_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Wave Folder](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_folder.htm) response.

## Usage

Use `updatePartialWaveFolder` to allow users to update minimal folder details, like the label and icon. This example adds an update button to a page with folders. The page must contain form elements for the information required to update the folder. Updating a folder displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updatePartialWaveFolder } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdatePartialWaveFolder extends LightningElement {
  @api fId; // or fetch the ID of the folder
  folderObj = {
    label: "Updated folder",
  };

  update(event) {
    updateWaveFolder({ id: this.fId, folder: this.folderObj })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Folder updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating folder",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updatePartialWaveFolder()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Folder"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=6021aba9433cb00f183e2d317a577c035ac66c814dc3e12f78935978aec6cd2f url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-recipe.md -->

# `updateRecipe`

Updates a specific data prep recipe by ID.

## Syntax

```javascript
import { updateRecipe } from 'lightning/analyticsWaveApi';
updateRecipe({ id: string, recipeObject: RecipeInput }): Promise<Recipe>
```

## Data Prep Recipe API Resource

```html
PATCH /wave/recipes/${id}
```

`updateRecipe` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes_id.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                             | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `id`           | String | The ID of the recipe.                                                                                                                                                                                   | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recipeObject` | Object | The recipe to update. Use a [Recipe Input](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_requests_recipe_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Recipe](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_responses_recipe.htm) response.

## Usage

Use `updateRecipe` to allow users to change licenses, labels, and more. This example adds an update button to a page with recipes. The page must contain form elements for the information required to update the recipe. Updating a recipe displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateRecipe } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateRecipe extends LightningElement {
  @api rId; // or fetch the ID of the recipe
  recipeObj = {
    label: "Updated recipe",
    licenseAttributes: { type: "Sonic" },
  };

  update(event) {
    updateRecipe({ id: this.rId, recipeObject: this.recipeObj })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Recipe updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating recipe",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateRecipe()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Recipe"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=5eefdb8ea5220f1321152f30bb978e1b8e114b83483247722a472435a5bbc39d url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-recipe-notification.md -->

# `updateRecipeNotification`

Updates the notification settings for a specific data prep recipe by ID.

## Syntax

```javascript
import { updateRecipeNotification } from 'lightning/analyticsWaveApi';
updateRecipeNotification({ id: string, recipeNotification: RecipeNotificationInput }): Promise<RecipeNotification>
```

## Data Prep Recipe API Resource

```html
PUT /wave/recipes/${id}/notification
```

`updateRecipeNotification` uses this [Data Prep Recipe API resource](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_resources_recipes_id_notification.htm).

## Parameters

| Parameter Name       | Type   | Description                                                                                                                                                                                                                                    | Required?                                  |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `id`                 | String | The ID of the recipe.                                                                                                                                                                                                                          | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `recipeNotification` | Object | The recipe notification to update. Use a [Recipe Notification Input](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_requests_recipe_notification_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Recipe Notification](https://developer.salesforce.com/docs/atlas.en-us.salesforce_recipes_api.meta/salesforce_recipes_api/sforce_recipes_api_responses_recipe_notification.htm) response.

## Usage

Use `updateRecipeNotification` to allow users to change recipe alert timings, notification levels, and more. This example adds an update button to a page with recipes. The page must contain form elements for the information required to update the notification, like the alert timing. To display a toast message when updating a recipe notification, use the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateRecipeNotification } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateRecipeNotification extends LightningElement {
  @api rId; // or fetch the ID of the recipe
  notification = {
    longRunningAlertInMins: 30,
    notificationLevel: "Always",
  };

  update(event) {
    updateRecipeNotification({ id: this.rId, recipeNotification: this.notification })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Recipe notification updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating recipe notification",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateRecipeNotification()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Recipe Notification"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=8a8657079982f4eb91c1b1b829aa963f8d43469c0ac53df7ab5672b9a526fe62 url=/developer/current/en-us/lwc/lwc/guides/reference/reference-update-record.md -->

# `updateRecord(recordInput, clientOptions)`

Updates a record. Provide the record Id of the record to update in `recordInput`.

## Syntax

```javascript
import { updateRecord } from 'lightning/uiRecordApi';
updateRecord(recordInput: Record, clientOptions?: Object): Promise<Record>
```

## User Interface API Resource

```html
PATCH /ui-api/records/{recordId}
```

`updateRecord` uses this [User Interface API resource](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_patch.htm), but doesn’t support all its parameters.

## Parameters

<!-- W-10283033: This adapter accepts input values listed at https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_patch.htm-->

| Parameter Name  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                    | Required?                               |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `recordInput`   | Object | A [`RecordInput`](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_requests_record_input.htm) object used to update the record. To create the object, call[`generateRecordInputForUpdate(record, objectInfo)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-generate-record-input-update.md). Alternatively, create the `RecordInput` object by passing in the fields and their values. See the [Usage](#usage) section. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `clientOptions` | Object | To check for conflicts before you update a record, pass `const clientOptions = {'ifUnmodifiedSince' : lastModifiedDate}`. Get `lastModifiedDate` via a wire service adapter that returns a record object: `const lastModifiedDate = record.fields.LastModifiedDate.value;`.                                                                                                                                    |                                         |

`recordInput` has several properties.

| `recordInput` Property | Type    | Description                                                                                                                                                                                                                                                                                                                                                                   | Required?                               |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `fields`               | Map     | Map of field names to field values. See [Update a Record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_record_patch.htm) in the _User Interface API Developer Guide_.                                                                                                                                                                  | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `apiName`              | String  | To create a record, specify the API name of an object from which to create the record. To update a record, use `null` or don’t pass this property.                                                                                                                                                                                                                            |                                         |
| `triggerOtherEmail`    | Boolean | For a case, specifies whether to send email to users outside the organization. In Salesforce, this email can be triggered by creating, editing, or deleting a contact for a case. The default value is `false`.                                                                                                                                                               |                                         |
| `triggerUserEmail`     | Boolean | For a case or a lead, specifies whether to send email to users in the organization. In the Salesforce user interface, this email can be triggered by various events: resetting a password, creating a user, changing the case owner, or adding comments to a case. The default value is `false`. For case owner changes, also set `useDefaultRule=true`, or no email is sent. |                                         |
| `useDefaultRule`       | Boolean | For a case or lead, specifies whether to use the default (active) assignment rule. If you specify `useDefaultRule`, don’t specify an `assignmentRuleId`. The default value is `false`. For an Account, specifies whether to apply the default territory assignment rules.                                                                                                     |                                         |
| `allowSaveOnDuplicate` | Boolean | Specifies whether to save a duplicate record. The default value is `false`.                                                                                                                                                                                                                                                                                                   |                                         |

## Returns

A Promise object that resolves with the updated record. The record contains data for the fields in the record layout.

## Usage

Before you use this wire adapter, make sure that there isn’t an easier way to update the data. To create a form for working with records, consider the [`lightning-record-*-form` components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md).

**note:** Create a custom form only if you need more customization than the `lightning-record-*-form` components allow.

This example creates a custom form that updates a record. It uses a `getSingleRecord` Apex controller to load the `FirstName` and `LastName` fields for a single contact record. (Name is a compound field. To edit the name, you must use the FirstName and LastName fields.)

As a custom behavior, the **Update Contact** button is disabled when one or both name fields are empty. The Id field is for reference only and is disabled so users can’t edit it.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="LdsUpdateRecord" icon-name="standard:record">
    <div class="slds-m-around_medium">
      <template lwc:if={contact.data}>
        <lightning-input label="Id" disabled value={contact.data.Id}></lightning-input>
        <lightning-input
          label="First Name"
          value={contact.data.FirstName}
          data-field="FirstName"
          onchange={handleChange}
          class="slds-m-bottom_x-small"
        ></lightning-input>
        <lightning-input
          label="Last Name"
          value={contact.data.LastName}
          data-field="LastName"
          onchange={handleChange}
          class="slds-m-bottom_x-small"
          required
        ></lightning-input>
        <lightning-button
          label="Update Contact"
          variant="brand"
          onclick={updateContact}
          disabled={disabled}
        ></lightning-button>
      </template>
      <template lwc:elseif={contact.error}>
        <!-- handle Apex error -->
      </template>
    </div>
  </lightning-card>
</template>
```

Changes are updated using `updateRecord`. Requiredness is not enforced on the client-side. To display field-level errors on invalid fields, call `reportValidity()`.

**note:** If you use the [`lightning-record-*-form` components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md), all fields are displayed based on your Salesforce schema. For example, it automatically handles requiredness on the client-side for required fields. To customize how the form works, use `updateRecord`. For example, you can prevent users from leaving the non-required FirstName field blank to improve data completeness, or disable the button when specific fields aren’t valid.

```javascript
import { LightningElement, track, wire } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { updateRecord } from "lightning/uiRecordApi";
import { refreshApex } from "@salesforce/apex";
import getSingleContact from "@salesforce/apex/ContactController.getSingleContact";
import FIRSTNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LASTNAME_FIELD from "@salesforce/schema/Contact.LastName";
import ID_FIELD from "@salesforce/schema/Contact.Id";

export default class LdsUpdateRecord extends LightningElement {
  disabled = false;
  @track error;

  @wire(getSingleContact)
  contact;

  handleChange(event) {
    // Display field-level errors and disable button if a name field is empty.
    if (!event.target.value) {
      event.target.reportValidity();
      this.disabled = true;
    } else {
      this.disabled = false;
    }
  }

  updateContact() {
    const allValid = [...this.template.querySelectorAll("lightning-input")].reduce(
      (validSoFar, inputFields) => {
        inputFields.reportValidity();
        return validSoFar && inputFields.checkValidity();
      },
      true,
    );

    if (allValid) {
      // Create the recordInput object
      const fields = {};
      fields[ID_FIELD.fieldApiName] = this.contactId;
      fields[FIRSTNAME_FIELD.fieldApiName] = this.template.querySelector(
        "[data-field='FirstName']",
      ).value;
      fields[LASTNAME_FIELD.fieldApiName] =
        this.template.querySelector("[data-field='LastName']").value;

      const recordInput = { fields };

      updateRecord(recordInput)
        .then(() => {
          this.dispatchEvent(
            new ShowToastEvent({
              title: "Success",
              message: "Contact updated",
              variant: "success",
            }),
          );
          // Display fresh data in the form
          return refreshApex(this.contact);
        })
        .catch((error) => {
          this.dispatchEvent(
            new ShowToastEvent({
              title: "Error creating record",
              message: error.body.message,
              variant: "error",
            }),
          );
        });
    } else {
      // The form is not valid
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Something is wrong",
          message: "Check your input and try again.",
          variant: "error",
        }),
      );
    }
  }
}
```

The `getSingleContact` Apex method returns a single contact record.

```apex
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static Contact getSingleContact() {
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WITH USER_MODE
            LIMIT 1
        ];
    }
}
```

**See Also**

- [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)
- [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/data/data-table-inline-edit.md)

<!-- document id=04889983a2019e83d1f25a07888d5dc83124bb1db95e6157e1fd1745073a2957 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-replicated-dataset.md -->

# `updateReplicatedDataset`

Updates a CRM Analytics replicated dataset by ID.

## Syntax

```javascript
import { updateReplicatedDataset } from 'lightning/analyticsWaveApi';
updateReplicatedDataset({ id: string, replicatedDataset: ReplicatedDatasetInput }): Promise<ReplicatedDataset>
```

## CRM Analytics API Resource

```html
PATCH /wave/replicatedDatasets/${id}
```

`updateReplicatedDataset` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id.htm).

## Parameters

| Parameter Name      | Type   | Description                                                                                                                                                                                                                   | Required?                                  |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `id`                | String | The ID of the replicated dataset.                                                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `replicatedDataset` | Object | The replicated dataset information to update. Use a [Replicated Dataset Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_replicated_dataset_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Replicated Dataset](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_dataset.htm) response.

## Usage

There are several ways to use `updateReplicatedDataset`. For example, you can display a list of replicated datasets and update the connection mode, the full refresh setting, or the pass through filter.

This example adds an update button to a page with replicated datasets. The page must contain form elements for the information required to update the replicated dataset, like the connection mode. Updating a replicated dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateReplicatedDataset } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateReplicatedDataset extends LightningElement {
  @api rdId; // or fetch the ID of the replicated dataset
  rdataset = {
    connectionMode: "full",
    fullRefresh: true,
  };

  update(event) {
    updateReplicatedDataset({ id: this.rdId, replicatedDataset: this.rdataset })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Replicated dataset updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating replicated dataset",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateReplicatedDataset()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update"
    icon-name="utility:play"
    icon-position="right"
    onclick={Update}
  ></lightning-button>
</template>
```

<!-- document id=79550c147734bae2c6b8edafae6891bff4635d6f2aa98633e43e03b2561d77d5 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-replicated-dataset-fields.md -->

# `updateReplicatedFields`

Updates the collection of fields for a CRM Analytics replicated dataset by ID. This method merges the target replicated dataset's fields with the collection provided. Each field requires the `name` attribute, and a `fieldType` attribute is also required if it's a new field. This method can't be used to delete existing fields, but they can be skipped, which removes the field from active replication.

## Syntax

```javascript
import { updateReplicatedFields } from 'lightning/analyticsWaveApi';
updateReplicatedFields({ id: string, replicatedFields: ReplicatedFieldCollectionInput }): Promise<ReplicatedFieldCollection>
```

## CRM Analytics API Resource

```html
PATCH /wave/replicatedDatasets/${id}/fields
```

`updateReplicatedFields` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_replicateddatasets_id_fields.htm).

## Parameters

| Parameter Name     | Type   | Description                                                                                                                                                                                                                                                                              | Required?                                  |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `id`               | String | The ID of the replicated dataset.                                                                                                                                                                                                                                                        | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `replicatedFields` | Object | The collection of fields to merge into the existing fields for the replicated dataset. Use a [Replicated Field Collection Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_replicated_field_collection_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Replicated Field Collection](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_replicated_field_collection.htm) response.

## Usage

There are several ways to use `updateReplicatedFields`. For example, you can display a list of replicated datasets and the fields for each replicated dataset.

This example adds an update button to a page with replicated datasets. The page must contain form elements for the information required to update or create fields for the replicated dataset, like the `name` and `fieldType`. Updating the fields for a replicated dataset displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from 'lwc';
import { updateReplicatedFields } from 'lightning/analyticsWaveApi';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

export default class UpdateReplicatedFields extends LightningElement {
  @api rdId; // or fetch the ID of the replicated dataset
  replicatedFields = {
    "fields" : [
      { "name" : "Field1","isSkipped" : true }, // Updating this field
      { "name" : "Field2" } // Leaving this field unchanged
      { "name" : "Field3", "fieldType" : "text", "label" : "Field Three" } // Adding a new field
    ]
  };

  update(event) {
    updateReplicatedFields({ id: this.rdId, replicatedFields : this.replicatedFields })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Success',
            message: 'Replicated dataset fields updated',
            variant: 'success'
          })
        );
      })
      .catch(error => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: 'Error updating replicated dataset fields',
            message: error.body.message,
            variant: 'error'
          })
        );
      });
  }
}
```

**note:** All fields in the existing collection must be present in the PATCH request. For fields that aren’t updated, only the `name` is required.

This button calls the `updateReplicatedFields()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update"
    icon-name="utility:play"
    icon-position="right"
    onclick={Update}
  ></lightning-button>
</template>
```

<!-- document id=6205e8bb52dcdf4f4dfab2cfb8fff03195aba8c5b4d06f99a44f22cfed6fb2c7 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-schedule.md -->

# `updateSchedule`

Updates the schedule for a CRM Analytics data prep recipe, data sync, or dataflow.

## Syntax

```javascript
import { updateSchedule } from 'lightning/analyticsWaveApi';
updateSchedule({ schedule: { assetId: string, schedule: ScheduleInput } }): Promise<Schedule>
```

## CRM Analytics API Resource

```html
PUT /wave/asset/${assetId}/schedule
```

`updateSchedule` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_schedule.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                                                                                                                                               | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `assetId`      | String | The ID of the dataflow, recipe, or data sync.                                                                                                                                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `schedule`     | Object | The schedule to create or update for the dataflow, recipe, or data sync. Use a [Schedule Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_schedule_input.htm). Schedules are hourly, daily, weekly, monthly (relative), monthly (specific), and event based. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Schedule](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_schedule.htm) response.

## Usage

There are several ways to use `updateSchedule`. For example, you can display a list of recipes or dataflows and allow the user to update the scheduled run time.

This example adds a schedule button to a page with recipes. Setting the schedule for a recipe displays a toast message using the `lightning/platformShowToastEvent` module. Note that you should include a UI to enable a user to pick the schedule type and attributes. This example assumes an hourly schedule.

```javascript
import { LightningElement, api } from "lwc";
import { updateSchedule } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateSchedule extends LightningElement {
  @api assetId; // or fetch the ID of the asset
  hourlySchedule = {
    daysOfWeek: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
    lastHour: 20,
    hourlyInterval: 3,
    time: {
      hour: 2,
      minute: 30,
      timeZone: "America/Los_Angeles",
    },
    frequency: "hourly",
  };

  schedule(event) {
    updateSchedule({ assetId: this.id, schedule: this.hourlySchedule })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Schedule updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating schedule",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateSchedule()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Schedule"
    icon-name="utility:date_time"
    icon-position="right"
    onclick={schedule}
  ></lightning-button>
</template>
```

<!-- document id=291bcd27e3b4d02263625395d6a7fe140f1b212dd889cc42c87d1db3b797dc41 url=/developer/current/en-us/lwc/lwc/guides/reference/service-knowledge/reference-knowledge-update-view-stat.md -->

# `updateViewStat(articleOrVersionId)`

Increases the article view count of a [KnowledgeArticle](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/sforce_api_objects_knowledgearticle.htm) or [KnowledgeArticleVersion](https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/sforce_api_objects_knowledgearticleversion.htm) record.

## Syntax

```javascript
import { updateViewStat } from "lightning/serviceKnowledgeApi";
updateViewStat({ articleOrVersionId: string });
```

## Knowledge API Resource

```html
/connect/knowledge/article/view-stat
```

`updateViewStat` uses this [Knowledge Article View Stat Resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_knowledge_article_view_stats.htm).

## Parameters

| Parameter Name       | Type   | Description                                                       | Required?                                  |
| -------------------- | ------ | ----------------------------------------------------------------- | ------------------------------------------ |
| `articleOrVersionId` | String | The ID of the KnowledgeArticle or KnowledgeArticleVersion record. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- `data`— An empty object
- `error`—[FetchResponse](https://developer.salesforce.com/docs/platform/data/data-error.md)

## Usage

This example shows how you can provide the record context to the `articleOrVersionId` parameter using `@api recordId`.

```javascript
import { LightningElement, api } from "lwc";
import { updateViewStat } from "lightning/serviceKnowledgeApi";

export default class Example extends LightningElement {
  @api recordId;

  increaseArticleViewCount() {
    updateViewStat({ articleOrVersionId: this.recordId })
      .then((response) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Article View Count is successfully increased",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating view count of article",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateViewStat()` method.

```
<template>
   <lightning-button
       variant="brand-outline"
       label="Increase Article View Count"
       onclick={increaseArticleViewCount}
       class="slds-m-left_x-small">
   </lightning-button>
 </template>
```

<!-- document id=8891bb5155c8da1ca4ce7e335c54ffc0af8dde9e4d480a1a881a925f7ac8b3bf url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-wave-folder.md -->

# `updateWaveFolder`

Updates a specific CRM Analytics folder by ID.

## Syntax

```javascript
import { updateWaveFolder } from 'lightning/analyticsWaveApi';
updateWaveFolder({ folderId: string, folder: BaseWaveFolderInput }): Promise<WaveFolder>
```

## CRM Analytics API Resource

```html
PUT /wave/folders/${folderId}
```

`updateWaveFolder` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_folders_id.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                                                       | Required?                                  |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `folderId`     | String | The ID of the folder.                                                                                                                                                                             | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `folder`       | Object | The folder to update. Use a [Base Wave Folder Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_base_wave_folder_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Wave Folder](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_wave_folder.htm) response.

## Usage

Use `updateWaveFolder` to allow users to change folder name, label, status, sharing, and more. This example adds an update button to a page with folders. The page must contain form elements for the information required to update the folder. Updating a folder displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateWaveFolder } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateWaveFolder extends LightningElement {
  @api fId; // or fetch the ID of the folder
  folderObj = {
    label: "Updated folder",
    isPinned: false,
  };

  update(event) {
    updateWaveFolder({ id: this.fId, folder: this.folderObj })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Folder updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating folder",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateWaveFolder()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Folder"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=30dc4aa7a7dad1b43895ea2ccc01d80541ef25da7764ec988e4b0f434a899455 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-update-xmd.md -->

# `updateXmd`

Updates a specific CRM Analytics user Xmd by dataset ID.

## Syntax

```javascript
import { updateXmd } from 'lightning/analyticsWaveApi';
updateXmd({ datasetId: string, versionId: string, xmd: XmdInput }): Promise<Xmd>
```

## CRM Analytics API Resource

```html
PUT /wave/datasets/${datasetId}/versions/${versionId}/xmds/user
```

`updateXmd` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_xmd_main.htm).

## Parameters

| Parameter Name | Type   | Description                                                                                                                                                           | Required?                                  |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `datasetId`    | String | The ID of the dataset.                                                                                                                                                | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `versionId`    | String | The ID of the dataset version.                                                                                                                                        | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `xmdType`      | String | The type of the Xmd. The only valid value for update is `user`.                                                                                                       | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `xmd`          | Object | The Xmd to update. Use an [Xmd Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_xmd_input.htm) resource. | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with the [Xmd](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_xmd.htm) response.

## Usage

Use `updateXmd` to allow users to change formats for measures and dimensions in a dataset. This example adds an update button to a page with datasets. The page must contain form elements for the information required to update the Xmd for a dataset. Updating an Xmd displays a toast message using the `lightning/platformShowToastEvent` module.

```javascript
import { LightningElement, api } from "lwc";
import { updateXmd } from "lightning/analyticsWaveApi";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class UpdateXmd extends LightningElement {
  @api dId; // or fetch the ID of the dataset
  @api dvId; // or fetch the ID of the dataset version
  xmd = {
    measures: [
      {
        conditionalFormatting: {},
        field: "LastModifiedDate_day_epoch",
        format: {
          delimiters: {},
        },
        label: "Last Mod Date",
        showInExplorer: true,
      },
    ],
  };

  update(event) {
    updateXmd({ datasetId: this.dId, versionId: this.dvId, xmd: this.xmd, xmdType: "user" })
      .then(() => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Success",
            message: "Xmd updated",
            variant: "success",
          }),
        );
      })
      .catch((error) => {
        this.dispatchEvent(
          new ShowToastEvent({
            title: "Error updating Xmd",
            message: error.body.message,
            variant: "error",
          }),
        );
      });
  }
}
```

This button calls the `updateXmd()` method.

<!-- prettier-ignore -->
```html
<template>
  <lightning-button
    label="Update Xmd"
    icon-name="utility:play"
    icon-position="right"
    onclick={update}
  ></lightning-button>
</template>
```

<!-- document id=6815e1ce8a3743b09115a8ce2bc234ba247e342c3afadc74b9211031357c35d2 url=/developer/current/en-us/lwc/lwc/guides/create/create-version-upgrade.md -->

# Upgrade a Component's API Version

To apply bug fixes and enable new features that are available in a later API version, upgrade your component's API version.

**note:** A warning in an API version can become an error in the next API version. We recommend that you test each version and upgrade one version at a time.

To upgrade your component API version:

1. [Publish your component](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-sfdx-scratch-org.md). Fix any warnings in the SFDX console.
2. Run your component in a sandbox. Fix any warnings in the browser DevTools console.
3. Increment the [`apiVersion` in the `*.js-meta.xml` file](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) for your component to the next version.
4. Publish your component again and verify that you no longer see any warnings.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
</LightningComponentBundle>
```

For example, if you specify an [`apiVersion` value](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md) of 58.0, your component continues to behave as it did in API version 58.0 (Summer '23). Your component doesn't include the bug fixes and enhancements that are introduced in version 59.0 and later.

**note:** Regardless of `apiVersion`, custom components always use the latest version of Lightning Data Service and Lightning base components.

<!-- document id=906f629112dfd154f9f042aa26742a40026c3f1b33cb4a702a5f0fd4634fe2d5 url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-url-schemes.md -->

# URL Protocol Schemes Allowed

Lightning Web Security (LWS) restricts the [`HTMLObjectElement.data`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/data) attribute and the `src` attribute for `iframe` elements to values that use the `http://` and `https://` schemes. URL schemes like `javascript://` aren’t allowed.

**See Also**

- [Use Blob Objects for Download Links](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-blob-download.md)

- [HTMLObjectElement.data in LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#HTMLObjectElement_data-setter)

- [HTMLIFrameElement.src in LWS Distortion Viewer](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#HTMLIFrameElement_src-setter)

<!-- document id=d05b77fb1c638c9e8c503f7e482a1bae1b46bd58761a601f55d764b42046218c url=/developer/current/en-us/lwc/lwc/guides/data/data-considerations.md -->

# Usage Considerations for Working with Records

Working with records using base components make Lightning Data Service available to you without additional configuration, but there are a few custom use cases to consider.

Consider the following use cases.

- To display a record form based on a record type, which includes picklist values based on the record type, get the record type Id.
- To notify a parent component about a successful record submission, dispatch and handle a custom event.

## Get Record Type Id

Picklist fields display values according to your record types. When working with `lightning-record-form` or `lightning-record-edit-form`, you must provide a record type Id if you have multiple record types on an object and you don’t have a default record type. Otherwise, the default record type Id is used.

To retrieve record type information, use the [`getObjectInfo` wire adapter](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-object-info.md).

## Example: Use the record-type-id Attribute

Display a record create form based on a record type by providing the `record-type-id` attribute. This example shows a form that you can place on an account record page. The form displays fields, which include a picklist with values based on the given record type Id.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="Record Form with Record Type" icon-name="standard:account">
    <div lwc:if={objectInfo.data} class="slds-m-around_medium">
      <lightning-record-form
        object-api-name={objectApiName}
        record-type-id={recordTypeId}
        fields={fields}
      >
      </lightning-record-form>
    </div>
  </lightning-card>
</template>
```

Import the `getObjectInfo` module and a reference to the account object. The `recordTypeId` getter returns the Id that matches the record type name `Special Account`.

```javascript
import { LightningElement, api, wire, track } from "lwc";
import { getObjectInfo } from "lightning/uiObjectInfoApi";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import PHONE_FIELD from "@salesforce/schema/Account.Phone";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class RecordFormWithRecordType extends LightningElement {
  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;

  @track objectInfo;

  // Define fields to display in form
  // Industry field is a picklist
  fields = [NAME_FIELD, PHONE_FIELD, INDUSTRY_FIELD];

  @wire(getObjectInfo, { objectApiName: ACCOUNT_OBJECT })
  objectInfo;

  get recordTypeId() {
    const rtis = this.objectInfo.data.recordTypeInfos;
    return Object.keys(rtis).find((rti) => rtis[rti].name === "Special Account");
  }
}
```

The `recordTypeInfos` property returns a map of record type Ids that are available in your org.

## Handle a Custom Event on a Form

The `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form` components come with event handling via `onsubmit`, `onsuccess`, and `onerror` attributes. To pass your form data to the container component, create a custom event.

Let’s say you have a container component `c-wrapper`, and your form is in the component `c-account-creator`. Let’s pass the Id of the new record to the container component. In `c-wrapper`, create an instance of `c-account-creator`.

<!-- prettier-ignore -->
```html
<!-- wrapper.html -->
<template>
  <c-account-creator onnewrecord={handleNewRecord}></c-account-creator>
</template>
```

When the record is created successfully, the `newrecord` event is dispatched by the `onsuccess` handler on `lightning-record-form`, which then calls the `handleNewRecord` method with the record Id.

```javascript
// wrapper.js
import { LightningElement } from "lwc";

export default class Wrapper extends LightningElement {
  recordId;

  /**
   * Handles the new record event.
   */
  handleNewRecord(evt) {
    const recordId = evt.detail.data.id;
    this.recordId = recordId;
  }
}
```

In `c-account-creator`, the `createStatus` property displays a message with the Id of the newly created record.

**note:** The Id is not available on the `submit` event. Use the `success` event to return the Id.

<!-- prettier-ignore -->
```html
<!-- c-account-creator -->
<template>
  <lightning-record-form
    object-api-name={accountObject}
    fields={accountFields}
    mode="edit"
    onsuccess={handleAccountCreated}
  >
  </lightning-record-form>
  <span class="slds-m-around_small status">{createStatus}</span>
</template>
```

The `handleAccountCreated` method handles the `success` event.

```javascript
import { LightningElement } from "lwc";
import ACCOUNT_OBJECT from "@salesforce/schema/Account";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import WEBSITE_FIELD from "@salesforce/schema/Account.Website";

/**
 * Creates Account records.
 */
export default class AccountCreator extends LightningElement {
  /** Status message when creating an Account. */
  createStatus = "";

  accountObject = ACCOUNT_OBJECT;

  accountFields = [NAME_FIELD, WEBSITE_FIELD];

  /** Handles successful Account creation. */
  handleAccountCreated(evt) {
    this.createStatus = `Account record created. Id is ${evt.detail.id}.`;

    const event = new CustomEvent("newrecord", {
      detail: { data: evt.detail },
    });
    this.dispatchEvent(event);
  }
}
```

## Override Standard Actions

To replace standard actions like **New**, **Edit**, **View**, **Clone**, or **List** buttons on object pages (similar to standard action overrides in Visualforce), wrap your Lightning web component in an Aura component that implements the `lightning:actionOverride` interface.

For an example of overriding the **New** action to prepopulate default field values, see [Handle Default Field Values Using an Override Action](https://developer.salesforce.com/docs/platform/lwc/use/use-navigate-default.md#handle-default-field-values-using-an-override-action).

To learn about which experiences support Lightning web components directly, see [Supported Experiences](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-experiences.md).

**note:** Quick Actions are different from action overrides. Quick Actions add custom buttons to page layouts, while action overrides replace standard platform buttons. To add custom actions with Lightning web components, see [Use Quick Actions](https://developer.salesforce.com/docs/platform/lwc/use/use-quick-actions.md).

<!-- document id=32281c8b2293867e17d9b2e5089c59a30a2a27c281951d2678a70f3ced752926 url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-patterns-global.md -->

# Use a Base Component with Global Attributes

As base components use many of the visual elements that come with HTML, they can use the [global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes) that are common to HTML elements.

**note:** While global attributes are common to all HTML elements, they may have no effect on some elements. Similarly, some global attributes have no effect on or don't apply to a base component.

## Global Attribute Support

Some global attributes have no effect on or don't apply to a base component.
For example, the `lightning-button` Specification tab lists out several global attributes - `name`, `type`, `value` - that are consistent with the [`<button>` HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). However, global attributes such as `autofocus` aren't supported on `lightning-button` as they don't get passed down to the `<button>` element in the base component.

Base components can use a global attribute and surface it as a public property under a different attribute name. This technique is often used if the base component is made up of several HTML elements that use the same attribute values.

Let's take a look at the [`lightning-badge`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-badge) base component, which composes multiple `<span>` elements and an `<svg>` element for icon support. Based on its internal logic, `lightning-badge` can display text without an icon or text with an icon. So you may expect that [the `title` global attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute) for hover text applies to the icon.

```html
<!-- If you do this -->
<lightning-badge label="Alpha" icon-name="standard:event" title="Event"></lightning-badge>
```

However, if you apply `title` on `lightning-badge`, it applies only to the `lightning-badge` wrapper element, and not on the icon.

<!-- prettier-ignore -->
```html
<!-- You get this in the DOM -->
<lightning-badge title="Event" class="slds-badge">
  <span class="slds-badge__icon slds-badge__icon_left">
    <span class="slds-icon_container slds-current-color">
      <!--Icon markup here -->
    </span>
  </span>Alpha
</lightning-badge>
```

In this case, `lightning-badge` surfaces an `icon-alternative-text` attribute and passes it down to the `title` attribute internally. So you use the `icon-alternative-text` attribute to get hover text on `lightning-badge`.

```html
<!-- Do this instead -->
<lightning-badge
  label="Alpha"
  icon-name="standard:event"
  icon-alternative-text="Alpha Event"
></lightning-badge>
```

Using the `icon-alternative-text` attribute passes down the value to the `title` attribute for the icon.

<!-- prettier-ignore -->
```html
<!-- You get this in the DOM -->
<lightning-badge class="slds-badge">
  <span class="slds-badge__icon slds-badge__icon_left">
    <span title="Alpha Event" class="slds-icon_container slds-current-color">
      <!-- Icon markup here -->
    </span>
  </span>Alpha
</lightning-badge>
```

To verify which attributes are supported, we recommend that you review the [specification](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-badge?type=Specifications and the [reference documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-badge?type=Develop) of the base component you're working with.

**note:** You can see how a base component renders in the DOM to understand its expected behavior. But don’t rely on any internal markup or CSS classes of a base component because they can change in future releases.

## Pass a Class to a Base Component

Passing in a custom class or an SLDS utility class using the class attribute applies the class to the wrapper element on the base component.

<!-- prettier-ignore -->
```html
<!-- If you do this -->
<lightning-button
  label="Submit"
  onclick={handleClick}
  class="slds-m-left_x-small other-custom-class"
></lightning-button>
```

While the internal elements of the base component maintains its SLDS classes, the classes you added via the `class` attribute are appended to the outer `lightning-button` element.

```html
<!-- You get this in the DOM -->
<lightning-button class="slds-m-left_x-small other-custom-class">
  <button
    type="button"
    class="slds-button 
        slds-button_neutral"
  >
    Submit
  </button>
</lightning-button>
```

**note:** You can see how a base component renders in the DOM to understand its expected behavior. But don’t rely on any internal markup or CSS classes of a base component because they can change in future releases.

To understand which attributes are supported, including ARIA attributes for accessibility support, review the base component's [reference documentation](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-component-library.md).

**See Also**

- [Use a Base Component in Markup](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-patterns.md)
- [Style Components with Lightning Design System](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-slds.md)
- [Anti-Patterns for Styling Components](https://developer.salesforce.com/docs/platform/lwc/create/css/create-components-css-antipatterns.md)
- [Access HTML Global Attributes in JavaScript](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-names.md)

<!-- document id=8590df6155f12289886ce04447829aca0d006ff6ac978cd1bd0f187e397d74f4 url=/developer/current/en-us/lwc/lwc/guides/afv/afv-lwc.md -->

# Use Agentforce Vibes for LWC Development

Agentforce Vibes is an AI coding assistant that's available as a VS Code extension or natively within the cloud-hosted Agentforce Vibes IDE. Use Agentforce Vibes to build, test, document, and modernize your Lightning Web Components (LWC) code. Its LWC expertise comes from a library of _skills_, which are focused sets of knowledge base and instructions that Agentforce Vibes loads when your request matches what a skill does. We recommend that you use skills to accelerate and enhance your LWC development experience.

To get started, review these topics.

- [Skills for LWC Development](https://developer.salesforce.com/docs/platform/lwc/guide/afv-lwc-skills.md)
- [DX MCP Tools for LWC (Beta)](https://developer.salesforce.com/docs/platform/lwc/mcp/mcp-intro.md)

**See Also**

- [_Agentforce Vibes Developer Guide_: Set Up Agentforce Vibes](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-admin-setup.html)

<!-- document id=29fdd950e1efedfb031ad23707d893d916d9036378d24e2deae85efc538a88fb url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-blob-download.md -->

# Use Blob Objects for Download Links

Lightning Web Security (LWS) blocks the use of `data:` URIs in anchor links because that approach has various security issues. Use a `blob:` URI instead.

This example shows an approach to creating a dynamic plain text file download link that uses a `data:` URI. This approach requires allowing `data:` URIs generally, which is insecure.

```javascript
// EXAMPLE OF INSECURE DOWNLOAD LINK
// This technique is prevented by LWS
const textEncoded = `data:text/plain,${encodeURIComponent( 'text string' )}`;
let anchorTag = document.createElement('a');
anchorTag.setAttribute('href', textEncoded);
anchorTag.setAttribute('download', 'nameoffile.crt');
anchorTag.click();
```

Instead, create a `Blob` to hold the data, and use the `blob:` URL scheme to make it available for download.

```javascript
const blob = new Blob(['text string'], { type: 'text/plain' });
const blobUrl = URL.createObjectURL(blob);
const anchorTag = document.createElement('a');
anchorTag.setAttribute('href', blobUrl);
anchorTag.setAttribute('download', 'nameoffile.crt');
anchorTag.click();
URL.revokeObjectURL(blobUrl);
```

`data:` URIs embed content directly inline as a URL. This creates several security risks that LWS blocks. A `blob:` URL is bound to the origin that created it — it inherits the page’s origin, and is subject to same-origin policy. This and other attributes make `blob:` a controlled, auditable mechanism for a legitimate use case (file downloads) without the open-ended risks of `data:`.

<!-- document id=d027ee77ea3475e8339a27147d2769a70669595ab6e8f1bf1e82e9878566e16b url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-expressions-use.md -->

# Use Complex Expressions to Compute Values

Template expressions support a wide range of computations within a component template. Use template expressions to reduce or eliminate the need for display-only properties or getters.

## The Limits of Basic Property Binding

With [simple property binding](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-getter.md), dynamically computing a value for a property used in a template requires you to:

- Define a getter that computes the value in the component class, and then
- Reference that getter in the template.

```html
<template>
  {propertyName}
</template>
```

```javascript
import { LightningElement } from "lwc";
export default class Component extends LightningElement {
  get propertyName() {
    // Compute a value for propertyName
  }
}
```

Template expressions are more powerful than basic property binding. They can contain any JavaScript expression that is valid in a template context. Additionally, complex expressions can be used for inline computations, which reduces the need for getters that solely compute or format values for a component’s user interface.

## Compute and Format Values for Display Using Expressions

Template expressions are more powerful than basic property binding. They can contain any JavaScript expression that is legal in a template context. Complex expressions can be used for inline computations, which reduces the need for getters that solely compute or format values for a component’s user interface.

The following example illustrates a range of template expressions used to display user and status information. Additional examples covering specific syntax and use cases are offered throughout the documentation.

```html
<template>
  <!-- Template literals -->
  <div>{`Hello ${name}, welcome!`}</div>

  <!-- Ternary operators -->
  <div>{isLoggedIn ? 'Welcome back!' : 'Please log in'}</div>

  <!-- Logical operators -->
  <div>{user && user.name}</div>
  <div>{error || 'No error'}</div>

  <!-- Function calls -->
  <div>{formatDate(timestamp)}</div>

  <!-- Array expressions -->
  <div>{[firstName, lastName].join(' ')}</div>

  <!-- Complex chaining -->
  <div>{user?.profile?.settings?.theme ?? 'default'}</div>
</template>
```

```javascript
import { LightningElement } from "lwc";

export default class ExampleComponent extends LightningElement {
  name = "World";
  isLoggedIn = true;
  user = { name: "John Doe" };
  error = null;
  timestamp = Date.now();
  firstName = "John";
  lastName = "Doe";

  formatDate(timestamp) {
    return new Date(timestamp).toLocaleDateString();
  }
}
```

<!-- document id=8331a46c764e81b769e3650084c94c556e8ff14c47a3693741f1d70806dce248 url=/developer/current/en-us/lwc/lwc/guides/use/use-packaging-lwc.md -->

# Use Components From a Managed Package

Managed packages can provide helpful functionality for your org. Some managed packages include managed Lightning web components. After installing a managed package via AppExchange, you can reference a managed Lightning web component (LWC) that's included in a managed package by using it in your custom component.

**important:** Authors of managed packages must test with both [Lightning Locker](/docs/platform/lightning-components-security/guide/locker-intro.html) and [Lightning Web Security (LWC)](/docs/platform/lightning-components-security/guide/lws-intro.html) to make sure their components work in both environments. To ensure that the managed package works in orgs where LWS isn't enabled, don't rely on [LWS-only features](/docs/platform/lightning-components-security/guide/get-started-compare-lws-locker.html#summary-of-lws-only-features). We recommend installing and testing the managed package in a sandbox first before installing it in your production orgs.

## Use a Managed LWC in a Custom Component

A Lightning web component in a managed package has a different namespace than your own. We recommend that you refer to the documentation on the managed package.

When you use an LWC from a managed package in your custom component, use kebab case (dash-separated). Similarly, the global attributes you use in the LWC HTML template must use kebab case.

For example, if the managed package contains an LWC in the `lwc_partner` namespace and the managed component name is `account-verification`, you can reference the component like this.

```html
<!-- myComponent.html -->
<template>
  <lwc_partner-account-verification attribute-name="value"> </lwc_partner-account-verification>
</template>
```

## Use a Managed LWC in a Salesforce Target

A managed LWC can be used in different LWC targets, which you can verify with the corresponding managed package documentation. For example, if you use the managed LWC in your custom LWC, you can surface the managed LWC in various targets by updating the `<targets>` configuration tag.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
  </targets>
</LightningComponentBundle>
```

**See Also**

- [ISVforce Guide](https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=62ac7b9ef05f6e4ff7da72bc786401e0146d71ab88036fb907862dbb9a9e346c url=/developer/current/en-us/lwc/lwc/guides/use/use.md -->

# Use Components in Salesforce Targets

Learn how to use Lightning web components in different targets, including Lightning Experience, the Salesforce mobile app, and Experience Builder sites.

To make a component available for use in different targets, define the metadata values in the component's `.js-meta.xml` configuration file. Depending on your target, you can use one of these point-and-click tools to customize how your users interact with the component on a page:

- [Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-app-builder.md)
- [Experience Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-community-builder.md)
- [Flow Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-screens.md)
- [Email Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-email-builder-component-steps.md)

You can also make your component available in these targets:

- [CRM Analytics dashboards](https://developer.salesforce.com/docs/platform/lwc/guide/use-analytics-dashboard.md)
- [Custom tabs](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-custom-tab.md)
- [Lightning console app](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-console-app.md)
- [Quick actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-quick-actions.md)
- [Outlook and Gmail integrations](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-app-builder-email-app-pane.md)
- [Utility bar](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-utility-bar.md)

Additionally, you can [package and distribute components](https://developer.salesforce.com/docs/platform/lwc/guide/use-packaging.md) to other Salesforce users and organizations on AppExchange.

**See Also**

- [Supported Salesforce Targets and Tools](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-supported-experiences.md)
- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)

<!-- document id=b30b600b201f8706cb1f4d3dbbae4b44a2bfb5df16148d4e599cd7dcf83ee760 url=/developer/current/en-us/lwc/lwc/guides/use/use-standalone-apps.md -->

# Use Components in Standalone Aura Apps

You can use custom Lightning web components in a standalone Aura app. Standalone apps are also called Lightning apps in the Developer Console.

The naming convention to reference a Lightning web component is `<namespace:camelCaseComponentName>`, which is the same as the naming convention for usage of a Lightning web component in an Aura component.

This standalone Aura app uses the `myComponent` Lightning web component in the default `c` namespace.

<!-- prettier-ignore -->
```html
<!-- sampleApp.app -->
<aura:application>
  <c:myComponent />
</aura:application>
```

**See Also**

- [Compose Aura Components from Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/interop/interop-aura-composition.md)
- [Lightning Aura Components Developer Guide: App Overview](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/apps_overview.htm)

<!-- document id=f5c7cfd5d676cf7385b4fc03d990a3108e252daa723262ff4a02c4e19a7ec5f0 url=/developer/current/en-us/lwc/lwc/guides/use/use-visualforce.md -->

# Use Components in Visualforce Pages

Implement new functionality with Lightning web components, and then add the components to existing Visualforce pages.

**important:** Lightning Components for Visualforce is based on Lightning Out (beta), a powerful and flexible feature that lets you embed Aura and Lightning web components into almost any web page. When used with Visualforce, some aspects of Lightning Out (beta) are simplified. For example, you don’t need to implement your own authentication or configure a connected app.

Otherwise, using Lightning Components for Visualforce is similar to using Lightning Out (beta). See [Use Components Outside Salesforce with Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out.md).

There are three steps to add a Lightning web component to a Visualforce page.

## Step 1: Add the Lightning Components for Visualforce JavaScript Library

Add `<apex:includeLightning/>` at the beginning of your Visualforce page. This component loads the JavaScript file that Lightning Components for Visualforce uses.

## Step 2: Create and Reference a Lightning Out (Beta) App

Create a Lightning Out (beta) app, a special type of standalone Aura app. Make the app globally accessible and extend `ltng:outApp`. Declare dependencies on any Lightning definitions, such as the components that your Lightning Out (beta) app uses.

**important:** The Lightning Components for Visualforce JavaScript library loads from the org that the Visualforce page is in, so your Lightning Out (beta) app must exist in the same org as the Visualforce page.

This example Lightning Out (beta) app uses the `<aura:dependency>` Aura tag to indicate that it uses the standard Lightning component, `lightning:button`.

```xml
<!--lwcvf.app-->
<aura:application access="GLOBAL" extends="ltng:outApp">
  <aura:dependency resource="lightning:button" />
</aura:application>
```

Add an `<aura:dependency>` tag for every Lightning web component that you use. Use the `<namespace:camelCaseComponentName>` naming convention to reference a custom Lightning web component.

**note:** Extending from `ltng:outApp` adds Salesforce Lightning Design System (SLDS) resources to the page so that your Lightning web components have SLDS styling. If you don’t want to add SLDS resources, extend from `ltng:outAppUnstyled` instead.

To reference this app on your Visualforce page, use the following JavaScript code, where `theNamespace` is the namespace prefix for the app. That is, either your org’s namespace, or the namespace of the managed package that provides the app.

```javascript
$Lightning.use("theNamespace:lwcvf", function () {});
```

If the app is defined in your org instead of a managed package, use the default `c` namespace, as shown in the next example. If your org doesn’t have a namespace defined, you _must_ use the default namespace.

For further details about creating a Lightning Out (beta) app, see [Lightning Out (Beta) Dependencies](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-dependencies.md).

## Step 3: Create a Component on a Visualforce Page

Finally, add your top-level component to a page using `$Lightning.createComponent(String type, Object attributes, String domLocator, function callback)`.

Let’s look at a sample Visualforce page that creates a `lightning:button` using the `lwcvf.app` from the previous example.

```visualforce
<apex:page>
    <apex:includeLightning />

    <div id="lightningvf" />

    <script>
        $Lightning.use("c:lwcvf", function() {
          $Lightning.createComponent("lightning:button",
              { label : "Press Me!" },
              "lightningvf",
              function(cmp) {
                console.log("button was created");
                // do some stuff
              }
          );
        });
    </script>
</apex:page>
```

The `$Lightning.createComponent()` call creates a button with a “Press Me!” label. The button is inserted in a DOM element with the ID `lightningvf`. After the button is added and active on the page, the callback function is invoked and executes a `console.log()` statement. The callback receives the component created as its only argument. In this simple example, the button isn't configured to do anything.

**important:** You can call `$Lightning.use()` multiple times on a page, but all calls must reference the same Lightning Out (beta) app.

For further details about using `$Lightning.use()` and `$Lightning.createComponent()`, see [Lightning Out (Beta) Markup](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-markup.md).

## Browser Third-Party Cookies

Lightning components set cookies in a user’s browser. Since Lightning components and Visualforce are served from different domains, those cookies are considered third-party cookies. Your users must allow third-party cookies in their browser settings. See [Lightning Out (Beta) Requirements](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-third-party-cookies.md).

**See Also**

- [Use Components Outside Salesforce with Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out.md)

<!-- document id=deb0f18e5bd0c177a2c5a68e599f6e62598c8035389df12ce27a2bff099ccdf4 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out.md -->

# Use Components Outside Salesforce with Lightning Out (Beta)

**tip:** We recommend using [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.md) instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md).

To run components outside of Salesforce servers, use a Lightning Out (beta) app, a special type of standalone Aura app. Whether it’s a Node.js app running on Heroku or a department server inside the firewall, add your components as dependencies to the Lightning Out (beta) app. Then run the Lightning Out (beta) app wherever your users are.

**important:** This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at [Agreements and Terms](https://www.salesforce.com/company/legal/agreements/).

Developing Lightning web components that you can deploy anywhere is generally the same as developing them to run within Salesforce. Everything that you know about component development still applies. The difference is how you embed your app in the remote web container, or origin server.

To configure your Lightning Out (beta) app, include the Lightning Out (beta) JavaScript library in the page on the origin server. Then add markup that loads your Lightning Out (beta) app and its components. Your Lightning Out (beta) app initializes over a secure connection and is inserted into the DOM of the page. Then your component code takes over and runs the show.

**note:** This approach is different from embedding an app using an iframe. Components running via Lightning Out (beta) are full citizens on the page. If you choose to, you can enable interaction between your standalone Lightning Out (beta) app and the page or app you’ve embedded it in. This interaction is handled using Lightning events.

In addition to some straightforward markup, there’s a modest amount of setup and preparation within Salesforce to enable the secure connection between Salesforce and the origin server. And, because the origin server is hosting the app, you need to manage authentication with your own code.

This setup process is similar to what you’d do for an application that connects to Salesforce using the Lightning Platform REST API, and you should expect it to require an equivalent amount of work.

**See Also**

- [Idea Exchange: Lightning Components Anywhere / Everywhere](https://success.salesforce.com/ideaView?id=08730000000cJO9AAM)
- [Lightning Out Supports Lightning Web Components (LWC) — Explained!](https://medium.com/@ElToroIT/lightning-web-components-support-lightning-out-5a79c513302f)

<!-- document id=b03a3158fce153d01b78d64372aa4ad8674f1c99a692f8a4f8d25b9b953c71b7 url=/developer/current/en-us/lwc/lwc/guides/lightning-out/lightning-out-intro.md -->

# Use Components Outside Salesforce with Lightning Out 2.0

Embed custom Lightning web components (LWC) into external, non-Salesforce apps by using Lightning Out 2.0, a special Salesforce app that you create and configure in Setup. Use the generated markup to embed the app into a page of your company’s external app. Unlike Lightning Out (beta), Lightning Out 2.0 is built on Lightning Web Runtime (LWR) and encapsulates embedded components in iframes within a shadow DOM. This new approach keeps the components more secure while still allowing for fast and responsive interactions with the external app.

To get started, review these topics.

- [Understand Lightning Out 2.0 Architecture](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-architecture.md)
  - : Learn how Lightning Out 2.0 provides access to Salesforce on external host pages while securely encapsulating embedded Lightning web components (LWCs). Examine the Lightning Out 2.0 app code and understand how the elements interact with each other and the host page.
- [Set Component Styles and Properties in a Lightning Out 2.0 App](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-component-properties.md)
  - : Tailor your Lightning Out 2.0 app to the specific branding requirements of an external app. Set Cascading Style Sheets (CSS) custom properties, including Salesforce Lightning Design System (SLDS) styling hooks, as style attributes directly in the context of the external app. You can also set or override values on other properties defined for your custom LWC components.
- [Handle Lightning Out 2.0 App Events](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-events.md)
  - : Lightning Out 2.0 app components load in iframes instead of directly on the host page. To overcome communication restrictions across iframe boundaries, Lightning Out 2.0 wraps custom events in messages using `window.postMessage()`. This internal implementation allows event listeners on one side of the iframe boundary to detect events dispatched from the other side. From your perspective, events are still created and handled with the standard `EventTarget` and `CustomEvent` interfaces.
- [Lightning Out 2.0 Limitations](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-limitations.md)
  - : Be aware of current Lightning Out 2.0 limitations.
- [How Lightning Out 2.0 Compares to Lightning Out (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-compare.md)
  - : Lightning Out 2.0 is generally available. It’s a new feature that completely replaces—and isn’t an extension of—Lightning Out (beta), which is still subject to Beta Service Terms. Learn how the architecture and features currently available in Lightning Out 2.0 compare to those in Lightning Out (beta). The feature comparison list is updated as more Lightning Out 2.0 features are added.

**tip:** To review the required org settings and learn how to create a Lightning Out 2.0 app in Setup, see [Extend Salesforce to External Apps with Lightning Out 2.0](https://help.salesforce.com/s/articleView?id=platform.lightning_out_intro.htm&type=5) in _Salesforce Help_.

<!-- document id=427b120b915ffb62e9e7e494c828ec2bfac81501dc0341d4d3b27363b1d53a96 url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-aura.md -->

# Use Custom Aura Tokens

A Lightning web component’s CSS file can use a custom Aura token that's created in your org or installed from an unmanaged package.

**important:** Salesforce recommends that you use [Styling Hooks](https://www.lightningdesignsystem.com/platforms/lightning/styling-hooks/) instead of design tokens if possible. While existing design tokens still work in SLDS 1, styling hooks are the future of customization for Lightning web components and Aura components.

Capture the essential values of your visual design into custom Aura tokens. Define a token value once and reuse it in your Lightning component’s CSS. Tokens make it easy to ensure that your design is consistent, and even easier to update your design as it evolves.

**tip:** Since Winter '24, we recommend that you use global color styling hooks instead of custom Aura tokens, where possible, to align with the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) 2.1 color contrast standards. See [Lightning Design System: Migration Guide](https://www.lightningdesignsystem.com/accessibility/color-contrast/migration-guide/).

Create a custom Aura token in the Developer Console by creating a Lightning Tokens bundle. For example, this tokens bundle has a custom Aura token called `myBackgroundColor`.

```html
<aura:tokens>
  <aura:token name="myBackgroundColor" value="#f4f6f9" />
</aura:tokens>
```

Custom Aura tokens aren’t new, but now you can use them in a Lightning web component’s CSS file by using the standard `var()` CSS function. Prepend `--c-` to the custom Aura token.

```css
/* myLightningWebComponent.css */
color: var(--c-myBackgroundColor);
```

**See Also**

- [Lightning Aura Components Developer Guide: Defining and Using Tokens](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/tokens_using.htm)
- [SLDS 1: Global Color Styling Hooks](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks/)

<!-- document id=5f986598c70de20a113c9e48b5cdd52af2611d08947c0a9abc2ff94e94a559f0 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-intro.md -->

# Use DX MCP Tools for LWC (Beta)

Salesforce Developer Experience (DX) Model Context Protocol (MCP) tools for LWC provide a powerful set of capabilities for component and app development, enabling advanced code intelligence, context-aware suggestions, and seamless integration with Salesforce metadata. MCP tools help streamline the development workflow, improve productivity, and ensure your code follows best practices.

As of August 2026, MCP tools for LWC are superseded by [LWC skills](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

We recommend that you use the MCP tools through [Agentforce Vibes Extension](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-overview.html). Agentforce Vibes is pre-configured with the [Salesforce DX MCP Server (Beta)](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm). This setup offers the most integrated and robust experience, including real-time code analysis, context-driven completions, and direct access to Salesforce data models.

For developers using other clients, such as Cursor or VS Code with Copilot, install the [Salesforce DX MCP Server (Beta)](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm) to enable the LWC MCP tools.

## Enable the Toolsets

When configuring the DX MCP server and the Agentforce Vibes extension, [several MCP tools are enabled by default](#tool-availability). To enable all the tools in these toolsets, pass in the toolset names (`aura-experts`, `lwc-experts`, and `experts-validation`) using the `--toolsets` flag. As some tools can call other tools in the toolset, enabling all toolsets is recommended if you expect to use these tools for LWC development.

```json
{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp@latest",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--toolsets",
        "lwc-experts,aura-experts,experts-validation"
      ]
    }
  }
}
```

To specify individual tools, use the `--tools` flag instead.

```json
{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp@latest",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--tools",
        "guide_figma_to_lwc_conversion,create_lwc_component_from_prd"
      ]
    }
  }
}
```

Some tools are marked NON-GA and are not yet generally available. To use these tools, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

```json
{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp@latest",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--toolsets",
        "lwc-experts, aura-experts, experts-validation",
        "--allow-non-ga-tools"
      ]
    }
  }
}
```

For more information, see [Install and Configure the Salesforce DX MCP Server (Beta)](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_server.htm) in the _Salesforce DX Developer Guide_.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


## LWC Toolset

The `lwc-experts` toolset provides tools to assist with LWC development, testing, optimization, and best practices.

- [LWC Development Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)
- [LWC Testing Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)
- [Lightning Data Service Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)
- [Figma to LWC Conversion Tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-design.md)
- [SLDS Guideline Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-slds.md)
- [Migration Verification Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-migration.md)
- [LWC Security Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-security.md)

## Aura Toolset

The `aura-experts` toolset provides tools for Aura component analysis, blueprinting, and Aura-to-LWC migration expertise.

- [Aura-to-LWC Migration Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md)

## LWC Validation Toolset

The `experts-validation` toolset provides tools for validating and scoring LWC components for production readiness across accessibility, security, and other best practices.

- [Validation MCP Tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-validate.md)

For other available toolsets, see [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm).

**note:** MCP Tools for LWC uses generative AI, which can produce inaccurate or harmful responses. The output generated by AI is often nondeterministic. Before using the generated output, review it for accuracy and safety. You assume responsibility for how the outcomes are applied to your organization.

## Tool Availability

When using the MCP tools through the Agentforce Vibes Extension, several tools are enabled by default:

- [guide_lwc_development](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)
- [orchestrate_lwc_component_creation](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)
- [guide_component_accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)
- [create_lwc_component](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)

For more information, see [Tool Activation in the Salesforce DX MCP Server](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-mcp.html#tool-activation-in-the-salesforce-dx-mcp-server) in the _Agentforce Vibes Extension Dev Guide_.

## LWC and Aura Toolsets Benefits

The LWC and Aura toolsets analyze your Aura components to understand:

- Component structure and hierarchy
- Event handling patterns
- Data binding approaches
- Custom interfaces and dependencies
- Third-party integrations

Using these MCP tools, you can get a detailed migration plan including:

- Dependency analysis and order of conversion
- Risk assessment for complex components
- Time estimates for each component
- Compatibility considerations

With the [orchestrated migration tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md#orchestrated-migration), you can generate modern LWC equivalents from existing Aura sources. Migrated components include:

- Standard LWC component class structure
- Template conversion with proper binding
- CSS with LWC-specific optimizations
- Jest test suites for the new components

**See Also**

- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [_Salesforce Developers Blog_: Vibe Code Lightning Web Components with Salesforce DX MCP](https://developer.salesforce.com/blogs/2025/10/vibe-code-lightning-web-components-with-salesforce-dx-mcp)

<!-- document id=4df18db6a6034a0fbb52fecf2735d0f0070b0bbe7c0f9ef5a52dfeb235efdc1a url=/developer/current/en-us/lwc/lwc/guides/js-props/js-props-getters-setters.md -->

# Use Getters and Setters to Modify Data

To execute logic each time a public property is set, write a custom setter.

If you write a setter for a public property, you must also write a getter. Annotate either the getter or the setter with `@api`, but not both.

**note:** For consistency, the examples in this guide and in the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes) annotate the getter and present the getter before the setter.

To hold the property value inside the getter and setter, use a field. This example uses the `_uppercaseItemName` property, which is prefixed with an underscore to indicate that the property is private.

This sample `<c-todo-item>` component converts a string to uppercase.

```html
<!-- todoItem.html -->
<template> {itemName} </template>
```

The property value is provided to the template via the getter.

```javascript
// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  _uppercaseItemName;

  @api
  get itemName() {
    return this._uppercaseItemName;
  }

  set itemName(value) {
    this._uppercaseItemName = value.toUpperCase();
  }
}
```

You can also handle errors in your getter with a try-catch block.

```javascript
// todoItem.js
import { LightningElement, api } from "lwc";
export default class TodoItem extends LightningElement {
  _uppercaseItemName;

  @api
  get itemName() {
    try {
      return this._uppercaseItemName;
    } catch (e) {
      return "";
    }
  }

  set itemName(value) {
    this._uppercaseItemName = value.toUpperCase();
  }
}
```

**tip:** For another example of using a getter and setter, see the `apiSetterGetter` and `todoList` components in the [lwc-recipes sample repo](https://github.com/trailheadapps/lwc-recipes).

**See Also**

- [Reactivity](https://developer.salesforce.com/docs/platform/lwc/reactivity/reactivity.md)
- [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter.md)

<!-- document id=73c6c49ac6a66defa12e3635a1b4189563d951877d98ad83aaebc22b090fa053 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-html-use.md -->

# Use HTML Templates

Write templates using standard HTML and a few directives that are unique to Lightning Web Components.

When a component renders, the `<template>` tag is replaced with the name of the component, `<namespace-component-name>`.

```html
<!-- myComponent.html -->
<template>
  <div class="slds-var-m-around_medium">Hello World</div>
</template>
```

For example, in the browser console, a component with the template `myComponent.html` renders as `<c-my-component>`, where `c` is the default namespace.

```html
<c-my-component>
  <div class="slds-var-m-around_medium">Hello, World!</div>
</c-my-component>
```

HTML templates also render data to the DOM. Use simple syntax to declaratively bind a component’s template to data in the component’s JavaScript class.

## Nested Templates

A template can include nested `<template>` tags with directives.

Directives are special HTML attributes, like `lwc:if` and `for:each`, which give you more power to manipulate the DOM in markup.

Nested `<template>` tags must include one of the following directives: `for:each`, `iterator:iteratorname`, `lwc:if`, `lwc:else`, `lwc:elseif`, or `if:true|false`.

**note:** Nested `<template>` tags can't be used with other directives or HTML attributes. Invalid template usage is ignored—the template and its children aren't rendered in the DOM, and a warning is returned when you load the component.

For example, instead of using the `class` attribute on a nested `<template>` tag, use the `class` attribute on a `<div>` or `<span>` tag instead.

## HTML Template Considerations

Your components can throw an error or a warning for an invalid HTML syntax. If you use VS Code, we recommend installing the [Salesforce Extensions Pack](https://developer.salesforce.com/tools/vscode/en/getting-started/install#salesforce-extensions-for-visual-studio-code). This extension flags malformed or incorrect code while you type, which is helpful when working with template directives.

For more information on which directives are supported on the root or nested `<template>` tag, see [HTML Template Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md).

**See Also**

- [Render DOM Elements Conditionally](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.md)
- [Render Lists](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.md)
- [HTML Template Errors](https://developer.salesforce.com/docs/platform/lwc/reference/reference-template-errors.md)

<!-- document id=6a2b09c5dacdd29cab5ee1db99d28a99d67f2d058e041282b59ebeea8fa773af url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-variants.md -->

# Use Lightning Base Component Design Variations

Many Lightning base components have several design variations. Each design variation gives a component a different look.

Base component design variations correspond to variations in Lightning Design System (SLDS). For example, `lightning-button` supports design [variations](https://v1.lightningdesignsystem.com/components/buttons/#Variations) that apply different colors for text and background to the buttons.

If a base component has design variations, it has a `variant` attribute. Use the `variant` attribute to pick the design variation.

This example creates a button with the `brand` design variation, which provides a blue background color on the button.

<!-- prettier-ignore -->
```html
<lightning-button
  variant="brand"
  label="Submit"
  title="submit form"
  onclick={handleClick}
></lightning-button>
```

If you don’t specify `variant`, or if you specify an unsupported value, the component uses the default value. For `lightning-button`, the default variant is `neutral`.

If you don’t see a design variation that you like, or if a component doesn’t have a `variant` attribute, use [Lightning Design System classes](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds.md) to achieve the styling you want.

For example, to apply a margin utility class to the `lightning-button` base component, use `class="slds-m-left_medium"`.

<!-- prettier-ignore -->
```html
<lightning-button
  variant="brand"
  label="Submit"
  title="submit"
  onclick={handleSubmit}
  class="slds-m-left_medium"
></lightning-button>
```

You can also apply utility classes to elements nested in some base components. In this example, the body of the `lightning-card` base component uses the `slds-p-horizontal_small` padding utility class.

```html
<lightning-card title="Hello">
  <lightning-button label="New" slot="actions"></lightning-button>
  <p class="slds-p-horizontal_small">Card Body (custom component)</p>
  <p slot="footer">Card Footer</p>
</lightning-card>
```

If you can’t find a suitable design variation or SLDS class, consider using [styling hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties.md).

**tip:** View the design variations and interactive examples for base components in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

<!-- document id=f9312dd455cbc7903b33236a4213fd3ea482fb0d24492fe1674f306f453a8a6f url=/developer/current/en-us/lwc/lwc/guides/create/css/create-components-css-design-tokens.md -->

# Use Lightning Design System Design Tokens (Deprecated)

**important:** The SLDS [design tokens](https://v1.lightningdesignsystem.com/design-tokens/) are still present and work normally in SLDS 1 themes, but aren't included in SLDS 2 themes. SLDS 2 replaces design tokens with a system of CSS custom variables called global styling hooks.

The Salesforce Cosmos theme uses SLDS 2. To reflect the Salesforce Cosmos theme or a custom SLDS 2 theme’s styling in your custom components, use the [accent category global styling hooks](https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks/t/867457a887) to define accent colors in your components. By using these hooks instead of design tokens, your components can adapt to the brand colors featured in the org's Themes and Branding settings. The global styling hooks can work with SLDS 1 and SLDS 2 themes, including custom themes based on SLDS 2.

See these resources for help preparing your components for use in SLDS 2 themes.

- [Brand Your Org in Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.brand_your_org_in_lightning_experience.htm&type=5)
- [Transition to SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2)
- [Get Started > Developers](https://www.lightningdesignsystem.com/2e1ef8501/p/547b38-developers)
- [Styling Hooks Developer Best Practices](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks/b/607020)

Even if you aren't planning to transition to SLDS 2 yet, we recommend that you use global color styling hooks instead of design tokens, where possible, to align with the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) 2.1 color contrast standards. See [Lightning Design System: Migration Guide](https://v1.lightningdesignsystem.com/accessibility/color-contrast/migration-guide/).

Design tokens are named entities that store visual design attributes, such as margins and spacing values, font sizes and families, or hex values for colors.

Lightning web components can use any [SLDS 1 design token marked Global Access](https://v1.lightningdesignsystem.com/design-tokens/).

**note:** If you get the error: `No TOKEN named {tokenName} found`, you're probably using a token that isn't marked Global Access. Either use a global token or use a [custom Aura design token](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-aura.md).

Previously, to reference a design token in your Lightning web component’s CSS, you used the `--lwc-` prefix and reference the token name in `camelCase`. This syntax works in SLDS 1, but not SLDS 2.

This example shows how to reference the SLDS 1 `spacingSmall` token.

```css
/* myWebComponent.css */
div {
  margin-right: var(--lwc-spacingSmall);
}
```

This example shows how to use an equivalent `spacing` global styling hook that works with SLDS 1 and SLDS 2.

```css
/* myWebComponent.css */
div {
  margin-right: var(--slds-g-spacing-2);
}
```

**note:** At compile time, we replace the variables with their actual values, which means that at run time, references to the variables don’t work. For example, you can’t use the standard APIs `CSSStyleDeclaration.getPropertyValue()` or `CSSStyleDeclaration.setPropertyValue()` on the variables.

**See Also**

- [Lightning Design System: Global Color Styling Hooks](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks/)

<!-- document id=71781d50d18662bcd7dd0c88677bbfa99373b69854cdc1f865c9ec0d602382a1 url=/developer/current/en-us/lwc/lwc/guides/reference/state-managers/reference-state-managers-use.md -->

# Use `lightning/stateManager*` State Managers

Here are details of how to create and use built-in state managers.

## Creation and Lifecycle

Setting aside best practices, the basic process of using a built-in state manager is the same for all the state managers.

1. Create an instance of a state manager using its factory (default) function.
2. Wait for the state manager to retrieve the expected data, or return an error.
3. If there's an error, handle it.
4. After the data is loaded, do something with it.

**important:** In practice, if your usage pattern is this simple, use the wire service instead. To clearly illustrate the essential concepts here, we've over-simplified the example code in this topic. See [Best Practices for State Manager Design](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-design.md) for more guidance on how built-in state managers are intended to be used.

### Factory Function

Create an instance of a built-in state manager using its factory (default) function. For example:

```javascript
// ...
import smRecord from "lightning/stateManagerRecord";
import NAME_FIELD from "@salesforce/schema/Account.Name";
import OWNER_NAME_FIELD from "@salesforce/schema/Account.Owner.Name";
import PHONE_FIELD from "@salesforce/schema/Account.Phone";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class Example extends LightningElement {

  @api theRecordId;

  // Create an instance of `lightning/stateManagerRecord`
  const myRecord = smRecord({
    recordId: theRecordId,
    fields: [NAME_FIELD, INDUSTRY_FIELD],
    optionalFields: [PHONE_FIELD, OWNER_NAME_FIELD]
  });

  // ...
}
```

After it’s created, check the status of and access data in the state manager through the [standard properties](#standard-properties).

### Configuration Functions

The factory function requires you to provide all required parameters at once. You can reconfigure a state manager instance with `setConfig()`, and provide difference values for all the same parameters. This function is available on all built-in state managers.

You can also update the configuration of a state manager instance by changing individual parameters as needed. Each parameter has its own `set` function.

For example, [`lightning/stateManagerObjectInfo`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-object-info.md) has a single _setParameter_ function, `setObjectApiName()`. [`lightning/stateManagerRelatedListRecords`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-related-list-records.md) has several `set` functions, one for each parameter. The specific functions available are listed on the individual state manager reference topics.

## Standard Properties

All built-in state managers have the following properties.

### `status`

- "unconfigured" — the state manager doesn’t have sufficient configuration information to proceed.
- "loading" — the state manager is in the process of obtaining data.
- "loaded" — the state manager has loaded data and set the `data` property.
- "error" — there was an error loading the data. The `error` property contains additional information.

### `data`

When the state manager `status` property is "loaded", the `data` property is in a valid state, and can be used by consumers of the state manager. The form and structure of `data` depend on the specific state manager.

### `error`

When the state manager `status` property is "error", the `error` property is in a valid state, and contains details of the specific error. If there's a configuration error with the state manager itself, for example, missing or invalid parameters used in the factory function, `error` is usually a simple string. If the error is with the request or response, `error` can be a [`FetchResponse`](https://developer.salesforce.com/docs/platform/data/data-error.md). However, error handling is complex. See [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/data/data-error.md) for a thorough explanation.

## Refresh Action

State managers that expose data without a simple, concrete identity — such as a related list — expose an imperative `refresh` action. Call `refresh()` to force a state manager to fetch the latest data from the server.

These state managers expose `refresh()`:

- [`lightning/stateManagerRelatedListRecords`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-manager-related-list-records.md)

When you call `refresh()` on a state manager instance, it returns a `Promise<void>`.

```javascript
import { LightningElement, api } from "lwc";
import smRelatedListRecords from "lightning/stateManagerRelatedListRecords";
import CONTACT_NAME from "@salesforce/schema/Contact.Name";

export default class RelatedContacts extends LightningElement {
  @api recordId;

  contacts = smRelatedListRecords({
    parentRecordId: this.recordId,
    relatedListId: "Contacts",
    fields: [CONTACT_NAME],
  });

  async handleRefresh() {
    await this.contacts.value.refresh();
  }
}
```

### Refresh Behavior by Status

You can call `refresh()` only when the state manager's `status` is `loaded`. In that state, the state manager re-fetches data from the server. The `status` remains `loaded` during the refresh. The returned Promise resolves after the refreshed data is available on the state manager's `data` property.

For any other `status`, `refresh()` rejects the returned Promise without fetching data.

### Offline Behavior

Offline behavior for `refresh()` is undefined. Don't rely on any specific behavior when the client is offline.

## Reactivity

State managers are full participants in the reactivity system of the LWC Framework. However, there are a few nuances to understand how to ensure that your state managers are reactive in all the ways you expect.

### Standard Reactivity

Built-in state managers use the same underlying logic as wire adapters and react to the same changes as the wire adapters do. Specifically:

- Any record changes made by the Lightning Data Service (LDS) imperative `updateRecord` and `deleteRecord` functions
- Any record changes made via GraphQL mutations
- Changes detected as part of `notifyRecordUpdateAvailable` or `getRecordNotifyChange` processing
- Changes noticed while ingesting data from any other UI API call. For example, if you perform a `getRecordUi` call and LDS notices that an object info has changed then any affected values on instances of the object info and object infos state managers are updated.

### Reactivity by Changing the Configuration

The simplest kind of reactivity is triggering updates to a state manager by explicitly changing its configuration. See [Configuration Functions](#configuration-functions).

Components that reference values from a changed state manager automatically refresh as needed.

### Reactivity Using State Management Functions

To create a state manager that is reactive to values without requiring an explicit configuration change, wrap the dependent values in one of the state management functions, either `atom()` or `computed()`. You can do this when creating a state manager instance, using the factory function, or later by using one of the [configuration functions](#configuration-functions).

For example, here's a slightly modified excerpt from the [Nested State Manager Example](https://developer.salesforce.com/docs/platform/state-management/state-management-example-nested.md):

```javascript
import { defineState } from "@lwc/state";
import smRecord from "lightning/stateManagerRecord";
// ...
export default defineState(({ atom, computed, setAtom }, recordId, objectApiName) => {
    // This custom state manager's configuration is an `atom()`
    const config = atom({ recordId, objectApiName });

    // Changing the config uses the state management function `setAtom()`
    const setRecordId = (recordId) =>
      setAtom(config, { recordId, objectApiName: config.value.objectApiName });
    const setObjectApiName = (objectApiName) =>
      setAtom(config, { recordId: config.value.recordId, objectApiName });

    // ...
    // The custom state manager uses nested, built-in state managers.
    // When the built-in state manager instance is created, it passes in
    // the atom, `config`, so that `smRecord` will automatically be
    // updated anytime the config changes.
    const initialRecord = smRecord(
      computed([config], ({ recordId, objectApiName } = {}) => {
        // ...
        // IMPORTANT: This code is slightly revised for clarity;
        // See the original sample for complete syntax
```

The `stateManagerRecord` instance is part of the implementation of the custom state manager. It's reactive to changes in the custom state manager's configuration because the configuration `smRecord` receives in its factory function is an `atom()`.

### Non-reactive Events

State managers, including built-in state managers, react to updates that take place through Lightning Data Service (LDS). (Subject to implementation details explained in the preceding section.)

State managers can't react to changes that happen outside of LWC Framework reactivity mechanisms. For example, imperative Apex calls that change data.

**See Also**

- [Example: Use a Built-in State Manager](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-use-example.md)
- [Best Practices for State Manager Design](https://developer.salesforce.com/docs/platform/lwc/guide/reference-state-managers-design.md)

<!-- document id=896a8ff5a3cedda401d82ea3f7000b8427a3e69671becdffcdbc5e3852189a55 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-testing.md -->

# Use LWC Testing MCP Tools (Beta)

The LWC testing MCP tools enhances your testing experience by providing helpful guidance and testing best practices. These MCP tools are superseded by [the `experience-lwc-test` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

- `orchestrate_lwc_component_testing` - Provides comprehensive testing workflow and test generation guidance
- `create_lwc_jest_tests` - Generates comprehensive Jest test suites
- `review_lwc_jest_tests` - Reviews and validates Jest test implementations
- `run_lwc_accessibility_jest_tests` - Provides accessibility testing utilities and Jest integration for LWC
- `guide_utam_generation` - Provides UI Test Automation Model (UTAM) Page Object generation guidelines and best practices.

To use these tools, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


Here are some possible prompts that invoke the LWC testing MCP tools.

## Component Testing Workflow (`orchestrate_lwc_component_testing`)

Ask about testing workflow for accessibility, Jest tests, and more.

- Create a test plan covering render states, user events, wires, and errors.
- Add accessibility tests and guidance on interpreting failures.
- Generate Jest test examples covering wire adapters, Apex mocks, and DOM assertions.

## Generate Jest tests (`create_lwc_jest_tests`)

Ask about generating Jest tests that cover your use cases.

- Generate Jest tests for this component covering load, success, empty, and error states.
- Create tests for this component including user interactions, DOM updates, and wire errors.
- Mock lightning/uiRecordApi (getRecord, getFieldValue) and test events for this component.

## Review Jest tests (`review_lwc_jest_tests`)

Ask about reviewing and validating Jest tests and identifying coverage gaps.

- Validate that tests for this component follow LWC Jest best practices and proper cleanup.
- Review tests for this component and suggest missing cases and mocking improvements.
- Assess tests for this component for async handling and coverage gaps.

## Accessibility and Jest Tests (`run_lwc_accessibility_jest_tests`)

Ask about generating or evaluating accessibility tests for a component.

- Add Jest accessibility tests for this component’s default, error, and interactive states.
- Generate test cases for focus order, ARIA roles, and keyboard navigation.
- Diagnose these failing a11y assertions and propose code/test fixes to pass accessibility checks.

## Generate UTAM Guidelines (`guide_utam_generation`)

Ask about UI Test Automation Model (UTAM) guidelines and best practices for UI-based testing.

- Generate a UTAM JSON page object from my component.
- Analyze this JavaScript file and create a UTAM page object for the HTML snippets.
- Build a UTAM definition for my component using standard CSS selectors.

**note:** The `guide_utam_generation` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [ UI Test Automation Model](https://utam.dev/)

<!-- document id=4b22c2ef81f2219699e2d875a839f05469678cbee26a694f6a4dc0bed8236e08 url=/developer/current/en-us/lwc/lwc/guides/use/use-mobile-capabilities.md -->

# Use Mobile Device Features

Mobile capabilities let you use mobile device features from within a Lightning web component. Access camera and location detection hardware, and platform features like contacts and calendar data, right from your component code. Build Lightning apps that feel like native mobile apps using these mobile-specific features.

Complete details are available in the _[Mobile and Offline Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/),_ an essential companion to this guide when doing mobile development.

**See Also**

- [Use Mobile Device Features in Mobile Apps](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/capabilities.htm)
- [`lightning/mobileCapabilities` Module](https://developer.salesforce.com/docs/platform/lwc/reference/mobile-capabilities/reference-lightning-mobilecapabilities.md)

<!-- document id=db52b44ccd81e9c8be95d797018355eb8fb5b87a60ca5633c1072c89d49c1370 url=/developer/current/en-us/lwc/lwc/guides/data/refreshview/data-refreshview-api.md -->

# Use RefreshView API

To use RefreshView API, import the `lightning/refresh` module.

The `lightning/refresh` module also replaces `force:refreshView` for Aura and exposes:

- The [`RefreshEvent`](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshevent-data-type.md) event that a module can fire to signal a refresh.
- Methods that allow components to register to receive the dispatched refresh event and begin the refresh process.
- Methods that allow components to register callback methods that are invoked as part of the refresh process.
- [Status](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshstatus-constants.md) definitions such as `RefreshComplete`, `RefreshCompleteWithError`, and `RefreshError`.

## Register Refresh Handler Methods in LWC

You must register components belonging to refresh-enabled views to be included in the refresh process.

To participate in a view refresh, a component registers a handler method. Use the [`registerRefreshHandler()`](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshview-registerrefreshhandler.md) method in a component’s `connectedCallback()` to register a handler method.

**important:** The parameters passed in the `registerRefreshHandler()` method require a different format when the component is running in an org that hasn't enabled Lightning Web Security (LWS) and is still using Lightning Locker.

A handler method is invoked after a container has received a `RefreshEvent`. Registered containers compose a "refresh tree" of registered refresh handlers, the order of which emulates the DOM. The containers then invoke the callback refresh methods of the participant components, which have registered a refresh handler.

**Example for Org with LWS Enabled**

```javascript
import { LightningElement } from "lwc";
import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
export default class RefreshHandler extends LightningElement {
  refreshHandlerID;
  connectedCallback() {
    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
  }
  disconnectedCallback() {
    unregisterRefreshHandler(this.refreshHandlerID);
  }
  refreshHandler() {
    // example usage case for refresh participant
    // fetch some data and report status once complete
    let endPoint = "https://api.<your company>.com";
    return new Promise((resolve) => {
      fetch(endPoint, {
        method: "GET",
      });
      resolve(true);
    });
  }
}
```

**Example for Org with Lightning Locker Enabled**

```javascript
import { LightningElement } from "lwc";
import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
export default class RefreshHandler extends LightningElement {
  refreshHandlerID;
  connectedCallback() {
    this.refreshHandlerID = registerRefreshHandler(
      this.template.host,
      this.refreshHandler.bind(this),
    );
  }
  disconnectedCallback() {
    unregisterRefreshHandler(this.refreshHandlerID);
  }
  refreshHandler() {
    // example usage case for refresh participant
    // fetch some data and report status once complete
    let endPoint = "https://api.<your company>.com";
    return new Promise((resolve) => {
      fetch(endPoint, {
        method: "GET",
      });
      resolve(true);
    });
  }
}
```

Registered refresh methods in the refresh tree are invoked in a breadth-first order from the registered container’s node. This approach ensures that higher level (parent) handlers resolve before lower level (child) handlers are invoked.

The registered refresh handler callback must:

- Return a `Promise` that resolves to a `Boolean`:
  - `true` if the component has completed operations for a refresh and the refresh process can continue down the refresh tree from this node
  - `false` to prevent the refresh process from continuing to child elements of this node
- Perform necessary view update operations in accordance with current state.
- Ensure data and state are resynchronized, if necessary.
- Show appropriate UI during the process, such as spinners or toasts.

You must also unregister your component’s handler methods in `disconnectedCallback()` as shown in the previous example.

## Signal a Refresh with `RefreshEvent`

To start a view refresh, fire the `RefreshEvent` event, defined in `lightning/refresh`. This event makes a request to a container to begin the refresh process. This event can be fired from any component.

```javascript
import { LightningElement } from "lwc";
import { RefreshEvent } from "lightning/refresh";

export default class RefreshButton extends LightningElement {
  // signal a refresh programmatically
  // or via a button click
  beginRefresh() {
    this.dispatchEvent(new RefreshEvent());
  }
}
```

## Register to Receive `RefreshEvent`

To begin the refresh process on the user’s view, an application controller in each container must register to receive `RefreshEvent`. Use the `registerRefreshContainer()` method in the container’s `connectedCallback()` to register to receive `RefreshEvent`.

**important:** The parameters passed in the `registerRefreshContainer()` method require a different format when the component is running in an org that hasn't enabled LWS and is still using Lightning Locker.

**note:** If you’re adding a component to an active page, you don’t need to create a container to receive `RefreshEvent`. Add a container only if you want to determine the scope of your refresh.

**Example for Org with LWS Enabled**

```javascript
import { LightningElement } from "lwc";
import {
  registerRefreshContainer,
  unregisterRefreshContainer,
  REFRESH_ERROR,
  REFRESH_COMPLETE,
  REFRESH_COMPLETE_WITH_ERRORS,
} from "lightning/refresh";

export default class RefreshContainer extends LightningElement {
  refreshContainerID;
  connectedCallback() {
    this.refreshContainerID = registerRefreshContainer(this, this.refreshContainer);
  }
  disconnectedCallback() {
    unregisterRefreshContainer(this.refreshContainerID);
  }
  refreshContainer(refreshPromise) {
    console.log("refreshing");
    return refreshPromise.then((status) => {
      if (status === REFRESH_COMPLETE) {
        console.log("Done!");
      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
        console.warn("Done, with issues refreshing some components");
      } else if (status === REFRESH_ERROR) {
        console.error("Major error with refresh.");
      }
    });
  }
}
```

**Example for Org with Lightning Locker Enabled**

```javascript
import { LightningElement } from "lwc";
import {
  registerRefreshContainer,
  unregisterRefreshContainer,
  REFRESH_ERROR,
  REFRESH_COMPLETE,
  REFRESH_COMPLETE_WITH_ERRORS,
} from "lightning/refresh";

export default class RefreshContainer extends LightningElement {
  refreshContainerID;
  connectedCallback() {
    this.refreshContainerID = registerRefreshContainer(
      this.template.host,
      this.refreshContainer.bind(this),
    );
  }
  disconnectedCallback() {
    unregisterRefreshContainer(this.refreshContainerID);
  }
  refreshContainer(refreshPromise) {
    console.log("refreshing");
    return refreshPromise.then((status) => {
      if (status === REFRESH_COMPLETE) {
        console.log("Done!");
      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
        console.warn("Done, with issues refreshing some components");
      } else if (status === REFRESH_ERROR) {
        console.error("Major error with refresh.");
      }
    });
  }
}
```

Passing `this` to `registerRefreshContainer` binds an event listener to the element for `RefreshEvent`. When a registered refresh container receives `RefreshEvent`, the refresh process begins on its refresh tree.

**note:** `RefreshEvent` follows DOM event bubbling rules, so the refresh container beginning this process is the nearest registered ancestor to the signaling component.

The registered container’s callback — in this example `refreshContainer()` — is invoked when the container receives `RefreshEvent`. The callback receives a `Promise` as a parameter when the refresh process begins. When the refresh process finishes, this `Promise` is resolved with a `RefreshStatus` value.

To manage processes surrounding the refresh, use the registered container’s callback method. For example:

- Instrumenting begin/end
- Showing spinners
- Error handling
- Toasts

As shown in the `RefreshEvent` example, you must also unregister the view controller as a refresh container in `disconnectedCallback()` using the `unregisterRefreshContainer()` method.

**See Also**

- [Considerations for Using RefreshView API](https://developer.salesforce.com/docs/platform/lwc/guide/data-refreshview-considerations.md)
- [`lightning/refresh` module](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refresh.md)
- [RefreshStatus Constants](https://developer.salesforce.com/docs/platform/reference/refreshview/reference-lightning-refreshstatus-constants.md)

<!-- document id=3a89108d9682d307343744546a447a7ed6a2672618f07ba2e5705941e4e91fd9 url=/developer/current/en-us/lwc/lwc/guides/afv/afv-lwc-skills.md -->

# Use Skills for LWC Development

Invoke skills by describing what you want in natural language. Agentforce Vibes selects the matching skill automatically. In the next section, sample prompts demonstrate phrasing patterns that trigger each skill. In your prompts, you can use "Lightning web component" or "LWC component" interchangeably.

For full details on the skills, see the [Salesforce Skills Library on GitHub](https://github.com/forcedotcom/afv-library/tree/main/skills/generating-custom-lightning-type).

**note:** Generative AI can produce inaccurate or harmful responses. The output generated by AI is often nondeterministic. Before using the generated output, review it for accuracy and safety. You assume responsibility for how the outcomes are applied to your organization.

LWC and other Salesforce-specific skills are enabled by default with Agentforce Vibes. See [Skills in Agentforce Vibes](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-skills.html).

## Build and Create Components

These skills create new Lightning web components and modernize existing ones, from picking the right base components to documenting and converting them to TypeScript.

### experience-lwc-generate

Builds Lightning web components, or brings an existing one into compliance with modern LWC best practices, covering areas such as project structure, `@api` properties and methods, custom events, LMS, lifecycle hooks, reactivity, templates, styling, and metadata in `.js-meta.xml`.

Sample prompts include:

- "Build an LWC component that displays a filterable list of cases."
- "Modernize this component and fix its parent-child component communication."

### experience-lwc-design-generate

Creates a component from a Figma design, a Product Requirements Document (PRD), or another design artifact, orchestrating the full workflow from requirements through code generation, optimization, linting, and testing.

Sample prompts include:

- "Build an LWC component from this Figma design."
- "Generate an LWC component from this PRD."

### experience-lwc-base-components-integrate

Picks the right Lightning Base Component (`lightning-*`) for a UI task, retrieves its full API, and wires it into your LWC code.

Sample prompts include:

- "Which Lightning base component should I use for a multi-column editable table?"
- "I need a modal with a record form inside it. Use the right base components."

### experience-lwc-typescript-migrate

Converts an LWC JavaScript file to TypeScript with full type annotations and a matching `.d.ts` file that exposes only the component's `@api` surface.

Sample prompts include:

- "Convert this LWC to TypeScript and add types to the @api properties."
- "Generate a .d.ts file with the public type definitions for this component."

## Manage Data

These skills connect your components to Salesforce data, such as applying Lightning Data Service best practices, building GraphQL queries, and turning data needs into validated specifications.

### experience-lds-best-practices-apply

Reviews or implements Lightning Data Service best practices in an LWC, from choosing UI API vs. Apex, keeping the UI in sync with `refreshApex` and `notifyRecordUpdateAvailable`, to importing references from `@salesforce/schema`.

Sample prompts include:

- "Should I use UI API or Apex to load this record data?"
- "My data is stale after I save. Fix this LWC so it refreshes correctly."

### experience-lds-graphql-generate

Generates, integrates, and tests Lightning Data Service GraphQL queries and mutations, which include introspecting the org schema, building schema-validated queries, and wiring them into an LWC via the `lightning/graphql` adapters.

Sample prompts include:

- "Wire a GraphQL query into this LWC to fetch the account name and its open opportunities."
- "Create an LDS GraphQL mutation to update the contact's email and verify it against my org."

### experience-lds-data-requirements-generate

Turns an ambiguous, natural-language data need into a PRD-ready specification with validated Salesforce object and field API names and a recommended data access API (GraphQL, UI API, or Apex).

Sample prompts include:

- "I want to show account data on this component. Figure out which fields and which API to use."
- "Turn 'get the contact's info and recent activity' into a concrete data requirement spec."

## Migrate Components

These skills convert components from other frameworks, such as Aura or React, into LWC components.

### experience-aura-lwc-migrate

Converts an existing Aura component bundle (`.cmp`, controller, helper, renderer, CSS, interface, event) to LWC through a workflow that consists of analysis, PRD, enhancement, and generation.

Sample prompts include:

- "Migrate this Aura component to LWC."
- "Convert these aura:attribute definitions and force:recordData usage into modern LWC equivalents."

## Test and Preview

These skills verify your components before you ship them, generating Jest tests and UTAM page objects, and previewing components at runtime in a local dev environment.

### experience-lwc-test

Creates, enhances, or validates Jest unit tests and UTAM page objects for LWC through a workflow that consists of reviewing and validation. The workflow protects passing tests from regression and enables mocking of wire adapters correctly.

Sample prompts include:

- "Generate Jest tests for this LWC, including the wire adapter mocks."
- "The tests for this component are missing coverage. Add the missing cases and a UTAM page object."

### experience-lwc-runtime-observe

Runs Salesforce Lightning Preview for apps or single components and extracts the runtime DOM for inspection — `sf lightning dev`, [Live Preview](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-test-components.md), and shadow DOM extraction.

Sample prompts include:

- "Preview this component locally and show me the rendered HTML."
- "Start the local dev server and extract the shadow DOM for this app."

## Review Quality

These skills audit your components against Salesforce quality standards for accessibility, mobile offline support, right-to-left internationalization, and Lightning Web Security compliance.

### experience-lwc-accessibility-validate

Reviews component markup, JavaScript, and CSS for WCAG 2.2 accessibility violations across focus management, ARIA, color contrast, and keyboard interaction, and provides remediation guidance.

Sample prompts include:

- "Review this component for accessibility issues and fix any WCAG violations."
- "Check the keyboard navigation and ARIA attributes on this LWC for screen reader support."

### experience-lwc-rtl-validate

Reviews an LWC component for right-to-left (RTL) internationalization correctness, producing code-level fixes for CSS logical properties, bidirectional text, keyboard semantics, and RTL-aware SLDS class usage.

Sample prompts include:

- "Review this component for RTL and i18n correctness."
- "Replace the physical left/right CSS properties in this component with logical equivalents."

### experience-lwc-security-validate

Reviews an LWC component for Lightning Web Security (LWS) compliance and Product Security framework violations, producing either a severity-ranked finding list with remediations or a SARIF score report.

Sample prompts include:

- "Review this component for Lightning Web Security violations."
- "Score this component's security compliance and flag any dangerous DOM operations."

<!-- document id=4851788c6867587bb51eab8e110e93685f9f74a69f2b385a964728d590f47ac6 url=/developer/current/en-us/lwc/slds_linter/guides/use/use-work-with-code-analyzer.md -->

# Use SLDS Linter Rules with Salesforce Code Analyzer

To set up and use SLDS Linter rules with Salesforce Code Analyzer, complete these prerequisites and follow these steps.  
By default, Code Analyzer is configured to include rules from the ESLint configuration. The SLDS Linter rules are part of the default ESLint configuration in Code Analyzer and have the tag `SLDS`. To view the SLDS rules supported in Code Analyzer, run this command:

```
sf code-analyzer rules --rule-selector SLDS --view detail
```

## Prerequisites

1. Install Salesforce CLI using one of the methods listed in [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm) in the Salesforce CLI Setup Guide.
2. Install the Code Analyzer CLI plug-in by running this command in a terminal (macOS and Linux) or a command prompt (Windows).

   ```
    sf plugins install code-analyzer
   ```

   For more information about the CLI and Code Analyzer, see [Use CLI Commands to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze.html) in the Salesforce Code Analyzer Developer Guide.

   Alternatively, install the Code Analyzer VS Code Extension.  
   See [Use the VS Code Extension to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.html) in the Salesforce Code Analyzer Developer Guide.

## Run Code Analyzer

1. Verify that the Code Analyzer plug-in is installed by running the `sf plugins` command.

   ```
   sf plugins
   ```

   The output shows the core and user plug-ins currently installed in Salesforce CLI. If Code Analyzer is installed, an entry like this one appears in the output. Depending on your environment, the returned Code Analyzer version can vary.

   ```
   code-analyzer 5.2.2 (5.2.2)
   ```

2. Run Code Analyzer to analyze your files using the `sf code-analyzer run` command. Add flags to analyze a single file, multiple files or all files in your current directory.  
   For detailed information about the `code-analyzer run` command, see [code-analyzer Commands](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_code-analyzer_commands_unified.htm#cli_reference_code-analyzer_run_unified).

   ### Examples

   Analyze the `hardcoded-values.css` file using all the ESLint rules that have the tag `slds`.

   ```
     # Run on a specific file
     sf code-analyzer run --rule-selector eslint:slds --workspace ./small-set/hardcoded-values.css
   ```

   Analyze all the files in the `./small-set` directory using the ESLint rules that have the tag `slds`.

   ```
    # Run on a specific folder with a specific tag
    sf code-analyzer run --rule-selector eslint:slds --workspace ./small-set/
   ```

   Analyze all the files in an entire directory using the ESLint rules that have the tag `slds`.

   ```
    # Run on an entire directory
    sf code-analyzer run --rule-selector eslint:slds --workspace .
   ```

After the analysis is completed, Code Analyzer displays the analysis results in a human-readable format. The results contain several details including the severity of the violation, the name of the rule associated with the violation and so on. To interpret the various details that are displayed in the results, see [Use CLI Commands to Analyze Your Code](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/analyze.html#interpret-the-run-results) in the Salesforce Code Analyzer Developer Guide.  
To learn about the SLDS Linter rules and understand how to fix the violations, see [SLDS Linter Rules](https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html).

<!-- document id=0d0a607b210ac3fdb01dd0059d63b689c9d05381e8588ded7eaaa018e7acbf15 url=/developer/current/en-us/lwc/slds_linter/guides/use/use-custom-config-files.md -->

# Use SLDS Linter with Custom Configuration Files

You can enable or disable the rules used by SLDS Linter. To do so, use the `emit` command to generate custom configuration files and edit them to disable the rules that you don’t want to run. Then, use the edited files to run SLDS Linter and generate reports.

## (Optional) Install Recommended Extensions

To enhance your linting and error analysis experience while using custom configuration files, we recommend that you install this additional extension.
</br> By default, the linting issues present in the code aren’t highlighted in the custom configuration files. Installing this extension makes it easier to locate these issues, as they’re highlighted with squiggly lines.

[ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint): Applicable for linting HTML, Component (CMP), and Cascading Style Sheet (CSS) files. The ESLint extension checks your code and highlights any violations of the ESLint rules with squiggly lines.

## Set Up Custom Configuration Files

Follow these steps to set up your custom configuration files.

### 1. Export custom configuration files

To export the ESLint configuration file used by the SLDS Linter Command Line Interface (CLI), run the `emit` command.

```
npx @salesforce-ux/slds-linter@latest emit
```

This command creates or overwrites the existing `.eslint.config.mjs` file at the root of your project directory.

### 2. (Optional) Configure additional plug-ins

To use ESLint along with other plug-ins, modify the default configuration in the `.eslint.config.mjs` file. Import each additional plug-in that you want to use and edit the `extends` property to load the plug-in’s configuration.  
For example, to use the CSS plug-in, add the CSS plug-in configuration to the `.eslint.config.mjs` file.

#### Before Example

This shows the `.eslint.config.mjs` file containing the default configuration that is emitted.

```
// eslint.config.mjs

import { defineConfig } from "eslint/config";
import { sldsCssPlugin } from"@salesforce-ux/eslint-plugin-slds";
export default defineConfig([
  {
    plugins: {
      ...sldsCssPlugin()
    },
    extends: ["@salesforce-ux/slds/recommended"]        ....
  },
]);
```

#### After Example

This shows the `.eslint.config.mjs` file with the CSS plug-in configuration included.

```
// eslint.config.mjs

import { defineConfig } from 'eslint/config';
import css from '@eslint/css';
import { sldsCssPlugin }
from '@salesforce-ux/eslint-plugin-slds';

export default defineConfig([
  {
   // Define the plug-ins you are using
   plugins: {
      css: css,
      ...sldsCssPlugin()
    }
   // Extend plug-in configurations
    extends: ["@salesforce-ux/slds/recommended", "css/recommended"]
  }
]);
```

### 3. Disable rules

To disable specific rules in the `.eslint.config.mjs` file, comment the rule entry by using `//`.

#### Before Example

```
"@salesforce-ux/slds/enforce-bem-class": "error"

"@salesforce-ux/slds/no-deprecated-classes-slds2": "error"

"@salesforce-ux/slds/modal-close-button-issue": "error"
```

#### After Example

```
// "@salesforce-ux/slds/enforce-bem-class": "error"

// "@salesforce-ux/slds/no-deprecated-classes-slds2": "error"

"@salesforce-ux/slds/modal-close-button-issue": "error"
```

<!--
### 3. Define CSS properties

To validate specific CSS properties for each Stylelint rule, go to the `.stylelint.config.mjs` configuration file and use the `propertyTargets` option to specify 1 or more CSS properties for each rule. This is an optional configuration to list a few CSS properties. By default, all ‌CSS properties are validated.

#### Example

For the `no-hardcoded-values-slds2` rule, the `propertyTargets` option is set to validate two CSS properties: `color` and `background-color`.

```
//.sstylelint.config.mjs

"slds/no-hardcoded-values-slds2":
[
true,
{
"severity": "warning",
"propertyTargets": ["color", "background-color"]
}
]
```
-->

### 4. Lint your code

To lint your code based on the modified custom configuration file, use the `lint` command with this argument.

`--config-eslint`  
Supplies the `.eslint.config.mjs` file.

#### Example

Lint HTML and CMP files based on a ESLint configuration file.

```
npx @salesforce-ux/slds-linter@latest lint "**/{aura,lwc}/**/*.{html,cmp}" --config-eslint .eslint.config.mjs
```

### 5. Generate reports

To generate reports containing all the lint issues, use the `report` command with the `--format` option.

#### Example

Generate a SARIF report.

```
npx @salesforce-ux/slds-linter@latest report --config-eslint .eslint.config.mjs --format sarif
```

Generate a CSV report.

```
npx @salesforce-ux/slds-linter@latest report --config-eslint .eslint.config.mjs --format csv
```

<!-- document id=db1654677abc2fceda0ef41e632f7649508aff083ba0a1cdfdeb3ab0907aa7fe url=/developer/current/en-us/lwc/lwc/guides/use/use-svg-in-component.md -->

# Use SVG Resources

You can add an SVG resource to your component in two ways. Add it directly to your component's HTML template. Upload the SVG resource as a static resource and import it in your component's JavaScript file.

SVG (Scalable Vector Graphics) is an XML-based image format that lets you define lines, curves, shapes, and text. Here's an example of a file that contains a red rectangle, green circle, and white text that says “SVG”.

```xml
<svg version="1.1" baseProfile="full" width="300" height="200" xmlns="http://www.w3.org/2000/svg">
    <rect width="100%" height="100%" fill="red"></rect>
    <circle cx="150" cy="100" r="80" fill="green"></circle>
    <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
</svg>
```

As you can see, each shape has a tag that describes what it is (for example, `rect` is a rectangle), its dimensions, and color.

## Add an SVG Resource Directly to an HTML Template

To include an SVG resource in your HTML template, enclose it in `<template>` tags like any other element.

```xml
<template>
    <svg version="1.1" baseProfile="full" width="300" height="200" xmlns="http://www.w3.org/2000/svg">
        <rect width="100%" height="100%" fill="red"></rect>
        <circle cx="150" cy="100" r="80" fill="green"></circle>
        <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
    </svg>
</template>

```

## Import an SVG Resource as a Static Resource

1.  In the SVG file, add an `id` attribute to the `<svg>` tag.

    ```xml
    <svg version="1.1" baseProfile="full" width="300" height="200" xmlns="http://www.w3.org/2000/svg" id="logo">
        <rect width="100%" height="100%" fill="red"></rect>
        <circle cx="150" cy="100" r="80" fill="green"></circle>
        <text x="150" y="125" font-size="60" text-anchor="middle" fill="white">SVG</text>
    </svg>

    ```

2.  Upload the SVG resource to your org as a [static resource](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md).
3.  In your component's JavaScript file, import the static resource. Define a field that concatenates the reference to the static resource with its `id`.

    ```javascript
    // myComponent.js
    import { LightningElement } from "lwc";
    import SVG_LOGO from "@salesforce/resourceUrl/logo";

    export default class myComponent extends LightningElement {
      svgURL = `${SVG_LOGO}#logo`;
    }
    ```

4.  Reference the field in your HTML template with the SVG `<use>` element.

    <!-- prettier-ignore -->
    ```html
    <!-- myComponent.html -->
    <template>
      <svg xmlns="http://www.w3.org/2000/svg" width="300" height="200">
        ;
        <use href={svgURL}></use>
      </svg>
    </template>
    ```

## Supported SVG Tags

Lightning web components support a restricted list of SVG tags.

- `<svg>`
- `<a>`
- `<altglyph>`
- `<altglyphdef>`
- `<altglyphitem>`
- `<animatecolor>`
- `<animatemotion>`
- `<animatetransform>`
- `<audio>`
- `<canvas>`
- `<circle>`
- `<defs>`
- `<desc>`
- `<ellipse>`
- `<filter>`
- `<font>`
- `<g>`
- `<glyph>`
- `<glyphref>`
- `<hkern>`
- `<image>`
- `<line>`
- `<lineargradient>`
- `<marker>`
- `<mask>`
- `<mpath>`
- `<path>`
- `<pattern>`
- `<polygon>`
- `<polyline>`
- `<radialgradient>`
- `<rect>`
- `<stop>`
- `<switch>`
- `<symbol>`
- `<text>`
- `<title>`
- `<tref>`
- `<tspan>`
- `<video>`
- `<view>`
- `<vkern>`
- `<use>`

**See Also**

- [Component SVG Icon](https://developer.salesforce.com/docs/platform/lwc/create/create-components-svg-icon.md)
- [_Salesforce Help_: Defining Static Resources](https://help.salesforce.com/articleView?id=pages_static_resources_create.htm)

<!-- document id=ab7dfca45efb3c5ddcb487d295fa21a5adc417a9fae69d5de4ea8a3c0ba689a6 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-aura.md -->

# Use the Aura-to-LWC Migration Tools (Beta)

The Aura-to-LWC conversion MCP tools are part of the `aura-experts` toolset. These MCP tools are superseded by [the `experience-aura-lwc-migrate` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

To use the `aura-experts` toolset, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file. We recommend that you specify both `lwc-experts` and `aura-experts` toolsets as the latter can call on tools in the `lwc-experts` toolset for Aura-to-LWC conversion workflows.

```json
{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp@latest",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--toolsets",
        "lwc-experts,aura-experts"
      ]
    }
  }
}
```

For more information, see [Install and Configure the Salesforce DX MCP Server (Beta)](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp_server.htm) in the _Salesforce DX Developer Guide_.

The `aura-experts` toolset includes these tools to facilitate Aura-to-LWC conversion.

- `create_aura_blueprint_draft` - Creates a comprehensive Product Requirements Document (PRD) blueprint for Aura component migration. Analyzes Aura component files and generates framework-agnostic specifications suitable for LWC migration, including business requirements, technical patterns, and migration guidelines.

- `enhance_aura_blueprint_draft` - Enhances an existing draft PRD with expert analysis and identiy any migration unknowns. Takes a draft blueprint and applies specialized Aura expert knowledge to resolve dependencies, add technical insights, and improve the migration specifications for better LWC implementation guidance.

- `transition_prd_to_lwc` - Provides migration bridge guidance for creating LWC components from Aura specifications. Takes the enhanced PRD and generates specific implementation guidance, platform service mappings, and step-by-step instructions for building the equivalent LWC component.

- `orchestrate_aura_migration` - Orchestrates the complete Aura-to-LWC migration workflow. Provides end-to-end guidance for the entire migration process, from initial analysis through final implementation, including best practices, tooling recommendations, and quality assurance steps.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


## Migration Tools

Here are some possible prompts that invoke the migration and integration MCP tools.

### Create Aura Blueprint Draft (`create_aura_blueprint_draft`)

Ask about analyzing an Aura component and generating a PRD blueprint that contains the component's structure, functionality, and requirements.

- Analyze these Aura components and draft a migration PRD blueprint with UX, data, and events. `<paste files>`
- Generate a framework-agnostic LWC specification from these Aura files, including requirements and constraints. `<paste files>`
- Extract business rules and user flows from the Aura code and outline LWC acceptance criteria. `<paste files>`

### Enhance Aura Blueprint Draft (`enhance_aura_blueprint_draft`)

Ask about enhancing the PRD blueprint and resolving unknowns.

- Review this draft PRD, resolve unknowns/dependencies, and add technical risks and mitigations. `<paste draft>`
- Enrich the blueprint with SLDS guidance and platform service mappings (LDS, UI API, Navigation). `<paste draft>`
- Turn vague requirements into testable specs with measurable acceptance criteria and a closed questions log. `<paste draft>`

### Dispatch Component Creation (`transition_prd_to_lwc`)

Ask about implementing an LWC component based on the enhanced blueprint.

- From the enhanced PRD, produce an LWC component breakdown, file scaffolds, public API, wires, and events. `<paste PRD>`
- Map Aura patterns (component/app events, attributes) to LWC equivalents and provide code scaffolds. `<paste PRD>`
- Generate a step-by-step LWC build plan with migration bridge notes and an implementation checklist. `<paste PRD>`

### Orchestrate Aura-to-LWC Migration (`orchestrate_aura_migration`)

Ask about a comprehensive migration plan with a testing and verification strategy.

- Create an end-to-end Aura-to-LWC migration plan with phases, timeline, and QA gates. `<paste context>`
- Define a verification strategy: Jest unit tests, a11y checks, UI regression, and parity matrix. `<paste context>`
- Produce a risk register, rollback strategy, and environment/deployment steps for the migration. `<paste context>`

## Migration Workflow

Choose one of these methods to use the `aura-experts` toolset for Aura-to-LWC migration.

- Orchestrated migration: This is the recommended migration workflow. Use `orchestrate_aura_migration` to analyze an Aura component, draft a PRD, enhance the draft, and then dispatch LWC creation in one go. Orchestrated migration is preferred if the Aura component is small or medium and self-contained with no dependencies. The tool calls on the other migration tools.
- Controlled migration: Run the steps separately to review and tweak at each stage. The tools can be run sequentially to generate a PRD of the Aura component's requirements for LWC migration (`create_aura_blueprint_draft`), followed by enhancing the blueprint (`enhance_aura_blueprint_draft`), and then creating the corresponding LWC component (`transition_prd_to_lwc`). Controlled migration is useful if you need to iterate and align with product stakeholders or if there are unknown external dependencies.

### Orchestrated Migration

When using orchestrated migration, `orchestrate_aura_migration` runs the migration tools in order, using the output of one to inform the next step. You can tweak the inputs before you proceed to run the next tool. Each tool provides detailed instructions for completing that phase of the migration.

1. Drafts a PRD in YAML format using `create_aura_blueprint_draft`.
2. Enhances the PRD using `enhance_aura_blueprint_draft`.
3. Confirms migration readiness using `transition_prd_to_lwc`.
4. Generate LWC component files using `create_lwc_component`.
5. Optimize and test the component using `orchestrate_lwc_component_optimization`.

For example, you can invoke the `orchestrate_aura_migration` tool by running this prompt.

```bash
Convert this Aura component to LWC using the official Aura to LWC migration assistant or the most complete automated process available.
Handle all technical details for me and follow LWC best practices, as well generate jest tests for it.
```

### Controlled Migration

We recommend that you use the [orchestrated migration](#orchestrated-migration) workflow where possible. With controlled migration, you create a prompt that invokes the next step, which gives you more control over the input for each step. Here are the recommended steps to run a controlled migration.

1. Draft PRD from Aura using `create_aura_blueprint_draft` with the full Aura bundle files mapped into a JSON.
2. Feed the draft to `enhance_aura_blueprint_draft` to enhance UX, data, events, accessibility, and acceptance criteria.
3. Confirm migration readiness using `transition_prd_to_lwc` to translate the enhanced PRD into LWC generation instructions.
4. Generate LWC using `create_lwc_component_from_prd` with the PRD body to create LWC scaffolding.

After your LWC code is generated, we recommend that you optimize and test the component using these tools.

- [Best practices](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md): `guide_lwc_best_practices`
- [Accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md): `guide_component_accessibility`
- [Data integrity](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md): `guide_lds_development`, `guide_lds_referential_integrity`, `guide_lds_data_consistency`
- [Testing workflow](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md): `orchestrate_lwc_component_testing`

**note:** To run a comprehensive assessment of your conversion, consider using the [migration verification tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-migration.md).

## Usage Considerations

When using the tools, keep these considerations in mind.

- Include the entire Aura bundle as partial input reduces PRD quality.
- Be explicit about event payloads, public API, and cross-component communication as it improves generated LWC quality.
- Iterate blueprint generation (draft and enhance) several times before dispatching creation.

**note:** MCP Tools for LWC uses generative AI, which can produce inaccurate or harmful responses. The output generated by AI is often nondeterministic. Before using the generated output, review it for accuracy and safety. You assume responsibility for how the outcomes are applied to your organization.

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [Migration Strategy](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-strategy.md)
- [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-introduction.md)

<!-- document id=1533d03765956f071569b1d1ecaf228de212580032603c37a887aa2371f13ae6 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-design.md -->

# Use the Figma to LWC Conversion Tool (Beta)

The `guide_figma_to_lwc_conversion` tool accelerates LWC development by providing Salesforce Lightning Design System (SLDS) guidelines and facilitating the conversion of Figma designs to LWC specifications. The MCP tool is superseded by [the `experience-lwc-design-generate` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

To use the `guide_figma_to_lwc_conversion` tool, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

## Prerequisites

Before you can use the Figma to LWC MCP tool, create a Figma account if you don't already have one. To work with the Figma to LWC conversion tool:

1. [Get a Figma access token](#1-get-a-figma-access-token)
2. [Connect to the Framelink MCP server](#2-connect-to-the-framelink-mcp-server)
3. [Send a prompt](#3-send-a-prompt)

This video shows you how you can generate an LWC component using both tools.

::video{src="https://www.youtube.com/embed/vhkghBqrHL4" title="Generate LWC Components from Figma" type="youtube" }

## 1. Get a Figma Access Token

A Figma access token lets you pull your Figma design data from your IDE. When creating a Figma access token, select the `file_content:read` scope. You don't need any other scope to work with the Figma to LWC conversion tool. See the [Framelink documentation](https://www.framelink.ai/docs/quickstart#figma-access-token).

## 2. Connect to the Framelink MCP server

Using the Framelink MCP server enables Agentforce Vibes (or another IDE) to read Figma files. To connect to the server, update your MCP configuration file. After you update the configuration file, the Framelink MCP server automatically downloads and starts.

For more information on configuring the MCP server for Agentforce Vibes (VS Code), Cursor, and other IDEs, see the [Framelink documentation](https://www.framelink.ai/docs/quickstart#configure-ide).

**note:** Rate limits apply when you use the Framelink MCP server. Check that you have the right license before calling the tool. See the [Figma Developers documentation](https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/).

## 3. Send a Prompt

Ask about generating a component based on a Figma design.

- Convert this Figma design to LWC. Link to Figma file: `https://www.figma.com/design/<your-unique-design-url>`
- Extract design tokens such as for spacing, color, radius, and typography from Figma and map them to SLDS variables. Link to Figma file: `https://www.figma.com/design/<your-unique-design-url>`
- Generate an LWC component breakdown and file scaffold plan from this Figma frame. Link to Figma file: `https://www.figma.com/design/<your-unique-design-url>`

**note:** The `guide_figma_to_lwc_conversion` tool fetches data using the Framelink MCP Server and is subject to its rate limits.

When you send a prompt, the `guide_figma_to_lwc_conversion` tool is called. The tool provides guidance on how to build the LWC component. Next, the `figma_data_tool` tool from the Framelink MCP server is called, which reads the Figma design file you provide and loads its data in the conversation. Finally, the `create_lwc_component_from_prd` tool is called with the design file data, leading to the final LWC conversion.

## Figma to LWC Conversion Guidelines

To improve the quality of your conversion, we recommend that you follow these guidelines.

### Prepare Your Figma Design

Preparing your Figma design ensures a more accurate LWC code output. To prepare your Figma design, follow these design requirements.

- Use consistent naming conventions for components
- Organize layers logically with proper grouping
- Include all component states, such as hover, active, or disabled
- Define responsive breakpoints if needed

We recommend that you follow these best practices.

- Use SLDS components and patterns when possible
- Include proper spacing and typography scales
- Define interaction behaviors in design comments
- Export all necessary assets, such as icons and images

### Figma Design Analysis

The LWC MCP tool includes automated cross-browser compatibility checks, SLDS design system compliance, accessibility validation (WCAG), and performance optimization. The tool analyzes your Figma designs to understand:

- Component structure and hierarchy
- Layout patterns and responsive behavior
- Typography and spacing systems
- Color schemes and theming
- Interactive elements and states

Based on the Figma design analysis, the tool generates:

- LWC code with semantic HTML structure
- LWC-optimized CSS with SLDS integration
- Component JavaScript with proper property bindings
- Responsive design patterns
- Accessibility attributes

### Customize and Deploy

After you review the generated code and component structure, test the component in a sandbox or scratch org. You can further customize your component in these areas:

- Adjust responsive breakpoints
- Add business logic and data binding
- Integrate with Lightning Data Service
- Configure component properties

### Optimize and Test

Just like with any LWC migration, we recommend that you consider these next steps before deploying to your Salesforce org.

- Enhance functionality using business logic and data integration
- Optimize performance using the [`orchestrate_lwc_component_optimization` tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md)
- Improve accessibility using the [accessibility audit and testing tools](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-introduction.md)

<!-- document id=d4b4506c138e5b0dae90e0e35e87475d35ef946102b269ab0aea09a76eba0923 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-base-components.md -->

# Use the Lightning Base Components MCP Tools (Beta)

The base components MCP tools help you identify the right base components for your use case, while providing usage guidance and examples. These MCP tools are superseded by [the `experience-lwc-base-components-integrate` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

- `guide_lbc_usage` - Provides an index of base components to help identify which components you can use
- `explore_lbc_components` - Provides guidance on base component usage

To use these tools, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


## Lightning Base Component Usage Guide Tool (`guide_lbc_usage`)

The `guide_lbc_usage` tool provides descriptions of available base components. It identifies appropriate candidates and invokes `explore_lbc_components` to produce usage examples and guidance on how to use the components.

To use this tool, ask about which base components are available for your use case. Example prompts include:

- Are there any base components that help with layout?
- Use a base component to show links for hierarchical navigation
- I want to show records using cards. Is there a base component for that?

## Lightning Base Component Explorer Tool (`explore_lbc_components`)

The `explore_lbc_components` tool is invoked by the `guide_lbc_usage` tool, providing complete guidance on how to use a base component and showing usage examples. It also provides details for properties, events, and slots. You must use the `guide_lbc_usage` tool first, which identifies which component names to pass to `guide_lbc_usage`.

Only base components in the [Lightning Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/) are available on this tool. Legacy base components (Aura) aren't supported by this tool. For guidance on API modules like `lightning/recordApi`, use the [`explore_lds_uiapi` tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md) or review the [API modules documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/api.html) instead.

<!-- document id=8458bebb880dc2888c18518c86ec405b39d2db5c71c46b93a575d71959c6284a url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-lds.md -->

# Use the Lightning Data Service MCP Tools (Beta)

The Lightning Data Service (LDS) MCP tools help you work better with Salesforce records by providing guidance on the UI API and applying data consistency and referential integrity best practices. These MCP tools are superseded by [the `experience-lds-best-practices-apply` and `experience-lds-graphql-generate` skiils](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

- `guide_lds_development` - LDS development guidelines and component integration
- `guide_lds_data_consistency` - Data consistency patterns and best practices for using LDS-based components and wire adapters
- `guide_lds_referential_integrity` - Referential integrity patterns for LDS data management
- `explore_lds_uiapi` - Explores and documents LDS UI API capabilities
- `orchestrate_lds_data_requirements` - Analyzes and clarifies LDS data requirements to produce PRD-ready specifications
- `guide_lds_graphql` - Provides guidelines on implementing GraphQL patterns to work with Salesforce data through the GraphQL wire adapter
- `fetch_lds_graphql_schema` - Fetches static GraphQL schema information that contains all the common types referred to by Salesforce GraphQL schemas
- `create_lds_graphql_read_query` - Provides guidelines for creating GraphQL read queries

To use these tools, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


Here are some possible prompts that invoke the LDS MCP tools.

## Explore UI API (`explore_lds_uiapi`)

The `explore_lds_uiapi` tool provides UI API documentation, wire adapters, and type definitions for LWC development.

To use this tool, ask about using UI API for LWC development. Example prompts include:

- List the available UI API wire adapters and when to use each.
- Generate the UI API field schema and types for `Account.Name, Account.Industry, Contact.Email`.
- Compare imperative vs wired UI API calls for fetching and updating records.

## Data Consistency Guide (`guide_lds_data_consistency`)

Ths `guide_lds_data_consistency` tool provides guidance on implementing data consistency patterns when working with Salesforce record data.

To use this tool, ask about maintaining data consistency using LDS-based wire adapters and other data strategies. Examples prompts include:

- Explain how to use `getRecordNotifyChange` to keep multiple components in sync.
- Recommend strategies to handle concurrent edits and stale data with LDS.
- Outline cache invalidation rules when creating, updating, and deleting related records.

## LDS Development Guide (`guide_lds_development`)

The `guide_lds_development` tool provides LDS guidelines covering data consistency, referential integrity, and choosing UI API vs Apex, with review checklists and links to specialized knowledge tools.

To use this tool, ask about evaluating a component using LDS development guidelines. Example prompts include:

- Recommend when to use base components (`lightning-record-form`) vs custom LDS wires.
- Provide a checklist for building a record editor: validation, errors, toasts, and refresh.
- Suggest performance tips for LDS-heavy pages (field minimization, batching, memoization).

## Referential Integrity Guide (`guide_lds_referential_integrity`)

The `guide_lds_referential_integrity` tool provides guidance on implementing referential integrity best practices to make your LWC code resilient against object or field name changes.

To use this tool, ask about referential integrity recommendations. Example prompts include:

- Describe how to prevent orphaned contact records when deleting a parent account.
- Recommend validations before updating lookups to maintain relationship integrity.
- Handle missing or soft-deleted related records gracefully in UI and data flows.

## Orchestrate LDS Data Requirements (`orchestrate_lds_data_requirements`)

The `orchestrate_lds_data_requirements` tool provides workflow guidance for analyzing and clarifying LDS data requirements to produce PRD-ready specifications.

To use this tool, ask about LDS data requirements covering objects and fields, relationships, data operations, security, offline considerations, and recommended UI API adapters vs Apex.

- Generate a step-by-step LDS data requirements spec for my LWC.
- Help me define objects, fields, and adapters for my LWC using LDS.
- Create a PRD-ready LDS data access plan for my LWC.

The `orchestrate_lds_data_requirements` tool calls `explore_lds_uiapi` to access the latest UI API documentation for LWC development. It can also call the `guide_lds_graphql` tool to facilitate GraphQL query generation.

## GraphQL API Guide (`guide_lds_graphql`)

The `guide_lds_graphql` tool gets detailed guidance on implementing GraphQL patterns in LWC when working with Salesforce data through GraphQL API.

To use this tool, ask about working with Salesforce data through a standalone query or via the GraphQL wire adapter. Example prompts include:

- Design a read query for Account by Id with paginated Contacts, sorted by LastModifiedDate and filtered Opportunities.
- How do I create a GraphQL query to read accounts with contact information?
- Use `create_lds_graphql_read_query` to query contacts with their related Account (query accounts on contacts).
- Create a GraphQL query for displaying a case queue. Query case by status and priority, with cursor-based pagination.

The tool can further prompt you to select an introspection method: manual, Connect API, or Salesforce CLI. You can't skip introspection because the LDS GraphQL workflow requires it to avoid invalid field and relationship names. Alternatively, the tool prompts you to provide information such as the relationship name so it can generate a query without introspection.

The `guide_lds_graphql` tool can invoke these tools to help with task completion.

- [`fetch_lds_graphql_schema`](#graphql-api-schema-fetch_lds_graphql_schema): Provides Salesforce's static GraphQL schema information
- [`create_lds_graphql_read_query`](#graphql-read-query-create_lds_graphql_read_query): Generates a GraphQL read query based on the user prompt

**note:** These tools aren't guaranteed to be invoked by `guide_lds_graphql`. See [LWC MCP Tools Usage Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-considerations.md)

For known limitations on using GraphQL with LWC, see [GraphQL Wire Adapter Limitations](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc-limitations.html) in the _GraphQL API Developer Guide_.

## GraphQL API Schema (`fetch_lds_graphql_schema`)

The `fetch_lds_graphql_schema` tool retrieves the full GraphQL introspection schema from a connected Salesforce org and saves it to the local filesystem, returning the file path and metadata.

To use this tool, you can ask about GraphQL schema information, which contains all the common types referred to by Salesforce GraphQL schemas. Example prompts include:

- Show me the GraphQL schema for the account object.
- Retrieve input operator definitions for Date, DateTime, and Picklist filtering.
- List scalar types, enums, and directives for the GraphQL wire adapter.

## GraphQL Read Query (`create_lds_graphql_read_query`)

The `create_lds_graphql_read_query` tool is called as part of the `guide_lds_graphql` workflow only. Don't use this tool directly.

The `create_lds_graphql_read_query` tool provides guidance on creating GraphQL read queries for LDS. For example, it facilitates creating GraphQL read queries, including query structure and syntax, field selection best practices, filtering and sorting techniques, and wire adapter integration.

If you try to invoke the `create_lds_graphql_read_query` tool, the tool prompts you to run the `guide_lds_graphql` tool first. Alternatively, you can invoke the `create_lds_graphql_read_query` tool by asking about creating or modifying a read query.

## GraphQL Mutation Query (`create_lds_graphql_mutation_query`)

The `create_lds_graphql_mutation_query` tool is called as part of the `guide_lds_graphql` workflow only. Don't use this tool directly.

The tool provides guidance on creating GraphQL mutation queries for LDS, such as for creating, updating, and deleting record data.

## GraphQL Query Test (`test_lds_graphql_query`)

The `test_lds_graphql_query` tool tests a GraphQL query against a connected Salesforce org and returns the result. `test_lds_graphql_query`
is invoked only from the `create_lds_graphql_read_query` and `create_lds_graphql_mutation_query` MCP tools.

**See Also**

- [Salesforce DX Developer Guide: DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [GraphQL API Developer Guide](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-about.html)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/data/data-guidelines.md)
- [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/data/data-ui-api.md)

<!-- document id=8de6de007d74a25e0b0fda4a1ccbec6b0f30f19a1c4c5dcff4ad81a058df98ae url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-security.md -->

# Use the Lightning Web Security (LWS) MCP Tools (Beta)

The `guide_lws_security` tool analyzes components based on product security and Lightning Web Security Guidelines, helping you identify vulnerabilities and recommend fixes. This MCP tool is superseded by [the `experience-lwc-security-validate` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

To use this tool, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

Here are some possible prompts that invoke the security tool.

## LWS Security Guide (`guide_lws_security`)

Ask about how to align your code with LWC security best practices.

- Analyze this component to flag XSS/DOM injection risks for lwc:dom="manual" and innerHTML. Suggest fixes for this component.
- Generate a secure LWC and Apex checklist for create, read, update, delete operations. Consider field-level security, WITH SHARING, SOQL injection prevention, and input validation.
- Audit the third‑party libraries under Lightning Web Security and CSP, and recommend safe integration patterns.

The tool identifies anti-patterns in the LWC code based on Lightning Web Security best practices, returning an assessment with recommendations for next steps.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [_Security for Lightning Components Developer Guide_: Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-intro.html)

<!-- document id=48993506e70cbf702abf27bdece8bf5cbd5ecd24f98789bae4e4028e4b48a178 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-lwc.md -->

# Use the LWC Development MCP Tools (Beta)

The LWC development MCP tools speed up component creation from PRD specifications and facilitate various aspects of LWC development. These MCP tools are superseded by [LWC skills](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

- `guide_lwc_development` - Comprehensive LWC development workflow and implementation guidelines
- `guide_lwc_best_practices` - Offers LWC development best practices and coding standards guidance
- `create_lwc_component_from_prd` - Creates LWC components from PRD specifications with proper structure and best practices
- `orchestrate_lwc_component_creation` - Step-by-step component creation workflow guidance
- `orchestrate_lwc_component_optimization` - Performance optimization and best practices for LWC
- `guide_component_accessibility` - Provides accessibility guidelines and testing instructions for Lightning web components
- `guide_lwc_rtl_support` - Right-to-Left (RTL) internationalization support and RTL development guidance
- `orchestrate_lwc_slds2_uplift` - Analyzes LWC code along with SLDS Linter output to fix issues using Salesforce Lightning Design System 2 (SLDS 2) knowledge, and migration guidance for upgrading to SLDS 2
- `explore_slds_blueprints` - Retrieves guidelines for the SLDS component blueprints that you need.
- `guide_slds_blueprints` - Provides comprehensive SLDS component blueprint guidelines, reference documentation, and a complete index of all available blueprints organized by category.
- `explore_slds_styling` - Provides usage patterns, accessibility notes, and validation checklists for semantic color styling hooks. For all other styling hooks, the tool provides the category, description, optional usage and other properties.
- `guide_slds_styling` - Provides comprehensive SLDS styling hook guidelines, reference documentation, and a complete overview of available styling hooks by category, including principles, patterns, and accessibility notes.

To use these tools, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


Here are some sample prompts that invoke the LWC development MCP tools.

## Development Workflow Guidelines (`guide_lwc_development`)

The `guide_lwc_development` tool provides guidance on LWC development by analyzing your requirements, building incrementally and testing thoroughly.

To use this tool, ask about evaluating a component based on development workflow guidelines. Example prompts include:

- Outline the end-to-end workflow to build a list of case records with UI API, including error states.
- Provide a development checklist for this component in these areas: data, events, a11y, tests, performance.
- Compare when to use UI API vs Apex for a record update and recommend an approach.

## LWC Best Practices (`guide_lwc_best_practices`)

The `guide_lwc_best_practices` tool provides LWC best practices, identifying issues and making necessary adjustments to your LWC code. The tool provides a detailed report of the identified issues and the changes made.

To use this tool, ask about reviewing a component based on LWC best practices. Example prompts include:

- Review this component for LWC best practices and suggest improvements.
- Recommend patterns for state management and eventing for this component.
- Identify anti-patterns in this code and propose compliant alternatives.

## Create LWC Components From PRD (`create_lwc_component_from_prd`)

The `create_lwc_component_from_prd` tool delivers structured instructions for analyzing PRDs and creating LWC implementations that follow Salesforce best practices.

To use this tool, ask about creating a component based on a PRD. Example prompts include:

- Create an LWC component named accountList from this PRD: `<paste PRD>`
- From the PRD below, generate the contactCard component. `<paste PRD>`
- Generate an LWC component that displays a list of cases using getListUi based on this PRD. `<paste PRD>`

The `create_lwc_component_from_prd` tool can invoke these tools to help with task completion.

- [`guide_figma_to_lwc_conversion`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-design.md): Provides SLDS guidelines and best practices for creating the component UI
- [`orchestrate_lwc_component_optimization`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md): Optimizes the component
- [`orchestrate_lwc_component_testing`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-testing.md): Create tests for the component
- [`explore_lds_uiapi`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md): Gets the documentation for adapters and data types when using Lightning Data Service (LDS)
- [`guide_lds_graphql`](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md): Helps you use GraphQL API to work with Salesforce data

**note:** These tools aren't guaranteed to be invoked by `create_lwc_component_from_prd`. See [LWC MCP Tools Usage Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-considerations.md).

## Component Creation Workflow (`orchestrate_lwc_component_creation`)

The `orchestrate_lwc_component_creation` tool guides users through the entire process from gathering requirements to testing and optimization.

To use this tool, ask about guidelines on creating a component. Example prompts include:

- Outline step-by-step tasks to build a contact list component.
- Recommend data access (UI API vs Apex) and eventing approach for this component.
- Provide an a11y checklist (roles, labels, keyboard, focus) tailored to this UI.

## Component Optimization Workflow (`orchestrate_lwc_component_optimization`)

The `orchestrate_lwc_component_optimization` tool offers guidance on optimizing your components for performance, maintainability, and best practices.

To use this tool, ask about optimizing a component and proposing performance strategies. Example prompts include:

- Recommend virtualization or pagination for long lists and heavy DOM updates.
- Propose strategies to reduce wire traffic via field minimization, batching, and caching.
- Provide a performance checklist for TTI, CPU cost, paint, and memory.

## LWC Accessibility Guidelines (`guide_component_accessibility`)

The `guide_component_accessibility` tool provides detailed knowledge about accessibility guidelines for LWC.

To use this tool, ask about reviewing a component based on LWC accessibility guidelines. Example prompts include:

- Review this component for accessibility and list concrete fixes with code examples.
- Provide a step-by-step plan to run a11y Jest tests for this component and interpret failures.
- Generate an ARIA/keyboard checklist for this component and verify focus management.

## Right-to-Left (RTL) Guidelines (`guide_lwc_rtl_support`)

The `guide_lwc_rtl` tool provides detailed knowledge about RTL internationalization guidelines for LWC.

To use this tool, ask about evaluating a component based on RTL guidelines. Example prompts include:

- Assess this component for RTL readiness and list CSS logical property changes.
- Provide RTL testing steps and visual checks for this component.
- Convert these LTR styles to RTL-safe equivalents and explain choices: `<paste CSS>`

## SLDS 2 Uplift Workflow (`orchestrate_lwc_slds2_uplift`)

The `orchestrate_lwc_slds2_uplift` tool provides guidance on SLDS 2 best practices for LWC.

**note:** The `orchestrate_lwc_slds2_uplift` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

To use this tool, ask about enhancing a component based on SLDS 2 guidelines and best practices. Also ask about migrating a component to use SLDS 2. Example prompts include:

- Run the SLDS 2 uplift workflow on SLDS components. Group violations by rule and component. Include a brief rationale per rule and call out any rules requiring manual remediation.
- Analyze this component for SLDS 2 issues. Generate a brief summary listing files changed, rules fixed, and remaining violations. Ensure no visual regressions by avoiding disruptive class removals without substitutions.
- Identify hardcoded color values, SLDS class overrides, and instances where deprecated design tokens can be updated to SLDS 2 styling hooks and suggest compatible replacements. Map each finding to an SLDS Linter rule. Output a table with columns: Rule, File Location, Problem, Recommended Fix. Provide a step-by-step fix order to minimize cascading changes.
- Uplift this component to SLDS 2—list class/token replacements and provide before/after diffs.
- Create an SLDS 2 migration guide for this component and call out any breaking changes.
- Generate a step-by-step SLDS 2 uplift checklist for my components with search/replace patterns and sample updates.

## Explore SLDS Blueprints (`explore_slds_blueprints`)

The `explore_slds_blueprints` tool provides detailed guidance for SLDS blueprints. To use this tool, ask for the blueprints by using one of these optional parameters.

**note:** The `explore_slds_blueprints` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

- Name: Returns the blueprint that matches the name you provide
- Category: Filter by blueprint categories (Actions, Input, Layout, Navigation, Display, Data, Feedback, Overlay, and Complex Components)
- Search: Filter blueprints by name or description
- Component: Filter by a base component name, such as `lightning-button` or `lightning-card`
- SLDS class: Filter by SLDS class name, such as `slds-button` or `slds-accordion`
- Styling hook: Filter by styling hook names, such as `--slds-c-accordion-heading-color`

Example prompts include:

- What is `.slds-button.slds-button_icon`?
- Show the component blueprint specifications for `.slds-wrap`.
- Show example markup for `.slds-assistive-text`.

## SLDS Blueprints Guidance (`guide_slds_blueprints`)

The `guide_slds_blueprints` tool provides SLDS blueprints guidance and reference documentation organized by category, along with usage principles and how to use blueprints vs base components.

**note:** The `guide_slds_blueprints` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

To use this tool, ask about the available SLDS component blueprints and how to use them. Example prompts include:

- Give me an overview of the available SLDS component blueprints.
- What are the accessibility considerations for SLDS component blueprints?
- What button component blueprints are available?

## Explore SLDS Styling Hooks (`explore_slds_styling`)

The `explore_slds_styling` tool provides guidance for SLDS styling hooks with support for exact lookup, fuzzy matching, prefix search, and wildcard patterns.

**note:** The `explore_slds_styling` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

To use this tool, ask about SLDS styling hooks by using one of these optional search capabilities.

- Hooks: Search with an array of hook names, for example, `["--slds-g-color-accent-1", "--slds-g-color-accent-2"]`
- Prefix: Match all hooks starting with a prefix, such as `--slds-g-color-accent-`
- Search: Search term with support for wildcards (_) and fuzzy matching, such as `accent` or `--slds-g-color-accent-_`
- Category: Filter by hook category (color, font, spacing, sizing, border, shadow, timing, dimension)
- Subcategory: Filter by hook subcategory (semantic, palette, system)
- Type: Filter by value type (color, dimension, font-family, font-size, font-weight, line-height, shadow, timing)
- Detail level: Controls the output verbosity (summary, detailed, full)

Example prompts include:

- Explain how to use the `--slds-g-color-surface-container-1` styling hook and provide an example.
- What is `--slds-g-color-accent-1`?
- What styling hooks start with `--slds-g-color-error`?

## SLDS Styling Hooks Guidance (`guide_slds_styling`)

The `guide_slds_styling` tool provides SLDS styling hooks guidance and reference documentation for different styling hooks categories, including principles, patterns, and accessibility notes for each category.

**note:** The `guide_slds_styling` tool is not yet generally available (NON-GA). To use this tool, specify the `--allow-non-ga-tools` flag in your DX MCP Server configuration.

To use this tool, ask about styling hooks and how they work by targeting one of these optional topic areas.

- Overview: Using SLDS styling hooks that ensure components are theme-aware, maintainable, and automatically adapt to brand customizations, dark mode, density settings, and accessibility requirements
- Colors: Using SLDS color styling hooks, covering semantic, system, and palette hook options with guidance on how to use each type to maintain accessibility, support theming, and create visual hierarchy
- Spacing: Using SLDS spacing styling hooks to establish consistent, accessible spacing and visual hierarchy that adapts to user density preferences
- Typography: Using SLDS typography styling hooks that control font size, weight, line height, and readability through systematic font scales and base sizes to establish visual hierarchy and accessibility across interfaces
- Sizing: Using SLDS sizing styling hooks to establish consistent, accessible spacing and visual hierarchy that adapts to user density preferences
- Borders: Using SLDS borders and radius styling hooks that control border width and corner curvature to establish visual structure and consistency across UI elements
- Shadows: Using SLDS shadow styling hooks that establish visual hierarchy, depth, elevation, and focus states through depth levels, directional shadows, and accessible focus indicators

Example prompts include:

- Give me an overview of the SLDS styling hooks that are available.
- Show me how the SLDS 2 color styling hooks work.
- What are the SLDS typography styling hooks that are available?

## LWC Compilation Error Reference (`reference_lwc_compilation_error`)

The `reference_lwc_compilation_error` tool provides guidance on fixing error codes that can be returned during compilation.

To use this tool, ask about an LWC compilation error code. Example prompts include:

- How do I fix error code LWC1034?
- Tell me more about LWC1011.
- Show me recommendations for LWC1035.

For more information on LWC error codes, see [Error Codes and Messages](https://lwc.dev/guide/error_codes).

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [Run Jest Tests for LWC](https://developer.salesforce.com/docs/platform/lwc/testing/unit-testing-using-jest-run-tests.md)

<!-- document id=e0cd2b09eca60d3f5ee8b19abe6980ad59f269db0e418295586fe91b8f377516 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-migration.md -->

# Use the Migration Verification Tools (Beta)

The migration verification tools facilitate and verify the completeness of your Aura-to-LWC and Lightning Out migrations.

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

To use this tool, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

Here are some possible prompts that invoke the migration tool.

## Verify Aura-to-LWC Migration Completeness (`verify_aura_migration_completeness`)

The `verify_aura_migration_completeness` tool provides a completeness checklist to facilitate an Aura-to-LWC conversion.

To use this tool, ask about the LWC conversion result of an Aura component. Example prompts include:

- Audit these Aura components and produce an LWC migration completeness checklist with gaps and blockers.
- Validate parity between Aura and LWC versions; list missing features, events, and styling differences.
- Recommend replacements for Aura-only features (navigation, events, eval) using LWC-safe patterns.

The tool evaluates your LWC conversion and provides an assessment of your code, providing a checklist with recommendations. You also get a completeness metrics based on functional and UI parity, event handling, data binding, modularity, error handling, localization, security, performance, and other best practices. This tool can also be invoked from the [`orchestrate_lwc_component_creation` tool](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md) when running an Aura-to-LWC migration.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


## Verify Lightning Out Migration (`guide_lo_migration`)

The `guide_lo_migration` tool provides guidance for Lightning Out (beta) to [Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/lightning-out/lightning-out-intro.md) migration, following a comprehensive workflow that covers architecture, lifecycle, and other patterns for the correct integration.

To use this tool, ask about migrating your Lightning Out code. Example prompts include:

- Evaluate this component for a Lightning Out 2.0 migration and identify any issues.
- Share instructions for Lightning Out 2.0 migration with event and styling recommendations
- Show me how to migrate this component to use Lightning Out 2.0 and explain the steps.

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)
- [Use the Aura-to-LWC Migration Tools (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-aura.md)
- [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/migrate/migrate-introduction.md)

<!-- document id=39ce87d90f9d30cba978391a0865be63027e8a399911ab5964cd1c74abe506a2 url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-slds.md -->

# Use the SLDS Guideline Tool (Beta)

The `guide_figma_to_lwc_conversion` tool provides Salesforce Lightning Design System (SLDS) guidelines and best practices to accelerate your LWC development, covering accessibility, responsive design, and correct component usage. This MCP tool is superseded by [the `experience-lwc-design-generate` skill](https://developer.salesforce.com/docs/platform/lwc/afv/afv-lwc-skills.md).

**note:** MCP Tools for LWC is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

To use this tool, pass the `--toolsets` flag as part of the `args` property of your MCP configuration file and specify `lwc-experts`. See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

## SLDS Design Guidelines (`guide_figma_to_lwc_conversion`)

The `guide_figma_to_lwc_conversion` tool offers SLDS guidelines and best practices for creating LWC components, such as SLDS implementation, accessibility standards, component usage, and responsive design patterns.

To use this tool, ask about developing accessible and responsive components using SLDS.

- Show me an SLDS pattern for a responsive record detail page with tabs and related lists.
- Explain how I can override the SLDS styles on a card.
- Recommend how to make this component responsiveness using the SLDS grid system.

**note:** Many SLDS patterns are available as a base component with built-in HTML attributes, methods, and events to speed up development. See the [Component Reference](https://developer.salesforce.com/docs/platform/lwc/get-started/get-started-component-library.md#component-reference) for more information.

**See Also**

- [Salesforce DX MCP Server](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_mcp.htm)
- [LWC MCP Tools Reference](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-reference.md)

<!-- document id=bcfa28301b0a625a6418a06b184558309dd9f806917f228f29926101870a949f url=/developer/current/en-us/lwc/lwc/guides/mcp/mcp-validate.md -->

# Use the Validation MCP Tools (Developer Preview)

The validation MCP tools assess your components and evaluate them against validator requirements. When the validation workflow is complete, you get a readiness score and a list of identified issues with recommendations.

**note:** Validation MCP tools for LWC is available as a developer preview. Feature isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality in production with these commands or tools.

To use these tools, pass the `--toolsets` flags as part of the `args` property of your MCP configuration file and specify `experts-validation`. Alternatively, pass in the `--tools` flag with these tool names.

- `validate_and_optimize` - Performs a one-time analysis for guidance to validate and optimize your component.
- `score_issues` - Computes a readiness score (0-100) and quality grade.

See [Use DX MCP Tools for LWC](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-intro.md) for configuration details.

**important:** When working with these tools using Agentforce Vibes Extension, you must enable the `a4d-general-rules-no-edit.md` and `a4d-lwc-rules-no-edit.md` global rules. The `a4d-general-rules-no-edit.md` rule is enabled by default. For more information on configuring rules in Agentforce Vibes, see [Agentforce Rules](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html) in the _Agentforce Vibes Extension Developer Guide_.


These validation tools are also available for use with [Salesforce Multi-Framework](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-mcpvalidate.html).

## Validate and Optimize Tool (`validate_and_optimize`)

The `validate_and_optimize` tool scores code quality across multiple validators:

- Code Analyzer: [run_code_analyzer](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/mcp.html)
- Accessibility: [guide_component_accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)
- Security: [guide_lws_security](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-security.md)
- Data: [guide_lds_data_consistency](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lds.md)
- LWC best practices: [guide_lwc_best_practices](https://developer.salesforce.com/docs/platform/lwc/guide/mcp-lwc.md)

Each validator runs and invokes the `score_issues` tool, producing a **readiness score** (0–100) and a **quality grade**.

**note:** Validators are weighted by importance — security issues impact the overall score far more than best-practice issues.

To use this tool, ask about validating your component or app. Example prompts include:

- Validate and score `componentName`
- Validate and score `componentName` for accessibility and security
- Is my app production-ready?

## Scoring Tool (`score_issues`)

The `score_issues` tool is invoked by the `validate_and_optimize` tool, after the latter tool runs each validator, and again at the end to provide an overall readiness score.

The tool computes a readiness score (0-100) and a quality grade (`prototype`, `draft`, `review-for-production`). You get a list of identified issues with recommendations on how to fix them. You can choose to fix them automatically and re-validate your component.

| Grade                   | Score | Meaning                            |
| ----------------------- | ----- | ---------------------------------- |
| `review-for-production` | ≥ 90  | Ready for human review             |
| `prototype`             | 60–89 | Functional but has notable issues  |
| `draft`                 | < 60  | Significant issues need addressing |

### Impact of a single issue on a validator's score

An issue in your code can be identified as an error, warning, or note. Each issue results in points taken off from the total score.

| Finding   | Score | Points Lost |
| --------- | ----- | ----------- |
| 1 error   | 80    | −20         |
| 1 warning | 96    | −4          |
| 1 note    | 100   | ~0          |

### Validator weights in the overall score

Aggregate scoring uses a weighted average across all the validators, weighted based on tier.

| Tier        | Weight | Validators                                                                                |
| ----------- | ------ | ----------------------------------------------------------------------------------------- |
| **Blocker** | 50     | `guide_lws_security`                                                                      |
| Critical    | 30     | `run_code_analyzer`                                                                       |
| Important   | 20     | `guide_component_accessibility`, `guide_lwc_best_practices`, `guide_lds_data_consistency` |

For example, a single security error alone can drop the overall score from 100 to 93.

<!-- document id=245313e45ba4032235b828235d9a0a8062009253ddf16ae55efd534daba1b73a url=/developer/current/en-us/lwc/lwc/guides/data/data-wire-service.md -->

# Use the Wire Service to Get Data

To read Salesforce data, Lightning web components use a reactive wire service. Use `@wire` in a component’s JavaScript class to specify a Lightning Data Service (LDS) wire adapter. The wire adapter defines the data shape that the wire service provisions in an immutable stream.

The LDS wire adapters are built on User Interface API or Connect API resources. Each wire adapter provides different Salesforce data and metadata, from individual records and lists of records, to object and layout schema. For example, the `lightning/uiRecordApi` module provides wire adapters to get record data or get default data that's needed to create a record. See the [Reference](https://developer.salesforce.com/docs/platform/lwc/reference/reference.md) section for supported wire adapters.

**note:** Before you use a wire adapter, make sure that there isn’t an easier way to get the data. To view, edit, or create records using a form-based interface, consider the [`lightning-record*form` components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md).

To improve performance, always use the wire adapter that returns the least amount data that your use case requires. For example, `getRecord` returns record data, while `getObjectInfo` returns metadata for an object and its fields. To see the data a wire adapter returns, see the **Returns** section for each wire adapter in [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md).

**See Also**

- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about.md)
- [Use the Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components.md)

<!-- document id=781efac3deafd09a6d3f1f97b624a0cb8315b85a89acfb7269a1d14bb935acbd url=/developer/current/en-us/lwc/lwc/guides/data/data-wire-base-components.md -->

# Use the Wire Service with Base Components

To simplify record data display and manipulation and speed up development, use base components.

**note:** The easiest way to let users view, edit, and create Salesforce records is to use the `lightning-record*form` components. See [Compare Base Components](https://developer.salesforce.com/docs/platform/lwc/data/data-get-user-input.md).

## Get User Input Using Base Components

To create a custom user interface or if `lightning-record*form` doesn’t meet your requirements, consider using the wire service with other base components. For example, use the `lightning-input` and `lightning-formatted-*` components to build custom forms or display record data.

Refer to the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference//) for more information about these components.

- `lightning-checkbox-group`

  - : Displays two checkboxes or more for selecting single or multiple options.

- `lightning-combobox`

  - : Displays a dropdown list (picklist) of selectable options.

- `lightning-input`

  - : Displays a field depending on the specified type for user input.

- `lightning-input-address`

  - : Displays compound fields for address input.

    For an example of using `lightning-input` with the wire service, see the `ldsCreateRecord` component in the [github.com/trailheadapps/lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

- `lightning-input-location`

  - : Displays compound fields for geolocation input.

- `lightning-input-name`

  - : Displays compound fields for name input.

- `lightning-input-rich-text`

  - : Displays a rich text editor with a toolbar for content formatting.

- `lightning-radio-group`

  - : Displays two checkboxes or more for selecting single or multiple options.

- `lightning-textarea`

  - : Displays a multiline text input field.

Although `lightning-input` supports many field types, consider other base components when you are working with different field types.

Let’s say you want to include the salutation picklist with the first and last name fields in your user interface. You can add `lightning-combobox` for the salutation picklist or use `lightning-input-name`. The next example uses `lightning-input-name` to display the salutation, first name, and last name fields with their current values. To determine which base component works best for your use case, refer to the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference//).

## Example: Create a Custom Form

This example creates a custom form to display and edit the values on a contact’s salutation, first name, and last name. The fields display the current values from the contact record.

**note:** You can achieve similar results with fewer lines of code using the `lightning-record*form` components.

```
<template lwc:if={contact.data}>
    <div class="slds-m-around_medium">
        <lightning-input-name
                label="Contact Name"
                first-name={firstname}
                last-name={lastname}
                salutation={salutation}
                options={salutations}
                class="slds-m-bottom_x-small"
                required>
        </lightning-input-name>
    </div>
</template>
```

![Create name fields with lightning-input-name](https://developer.salesforce.com/media/data_base_name.png)

To display the initial value in the fields, use the `getRecord` wire adapter.

To populate the picklist options for `lightning-input-name`, use the `getPicklistValues` wire adapter. This example uses the default record type Id. To display the currently selected salutation value, import the `Contact.Salutation` field reference.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";
import { getPicklistValues } from "lightning/uiObjectInfoApi";

import FIRSTNAME_FIELD from "@salesforce/schema/Contact.FirstName";
import LASTNAME_FIELD from "@salesforce/schema/Contact.LastName";
import SALUTATION_FIELD from "@salesforce/schema/Contact.Salutation";

const namefields = [FIRSTNAME_FIELD, LASTNAME_FIELD, SALUTATION_FIELD];

export default class GetContactName extends LightningElement {
  @api recordId; // provided by the contact record page

  @wire(getPicklistValues, { recordTypeId: "012000000000000AAA", fieldApiName: SALUTATION_FIELD })
  salutationValues;

  @wire(getRecord, { recordId: "$recordId", fields: namefields })
  contact;

  get firstname() {
    return this.contact.data.fields.FirstName.value;
  }

  get lastname() {
    return this.contact.data.fields.LastName.value;
  }

  get salutation() {
    return this.contact.data.fields.Salutation.value;
  }

  // creates the options array for lightning-input-name
  get salutations() {
    let salutationOptions = [];
    Object.entries(this.salutationValues.data.values).forEach((val) => {
      let values = val[1];
      salutationOptions.push({ label: values.label, value: values.value });
    });
    return salutationOptions;
  }
}
```

## Display Record Data Using Base Components

The easiest way to display record data is to use `lightning-record-form` or `lightning-record-view-form`. To display record data in a custom user interface, consider using the following base components. Refer to the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference//) for more information on these components.

- `lightning-formatted-address`

  - : For address compound fields. `lightning-formatted-address` displays an address with a link to the given location on Google Maps. The link is opened in a new tab. A static map can be displayed with the address for better context.

- `lightning-formatted-date-time`

  - : For date or date/time fields. `lightning-formatted-date-time` displays date and time.

- `lightning-formatted-email`

  - : For email fields. `lightning-formatted-email` displays an email as a hyperlink with the `mailto:` URL scheme.

- `lightning-formatted-location`

  - : For geolocation fields. `lightning-formatted-location` displays a geolocation in decimal degrees using the format `latitude, longitude`.

- `lightning-formatted-name`

  - : For name fields. `lightning-formatted-name` displays a name that can include a salutation and suffix.

- `lightning-formatted-number`

  - : For currency, number, and percent fields. `lightning-formatted-number` displays numbers in a specified format.

- `lightning-formatted-phone`

  - : For phone fields. `lightning-formatted-phone` displays a phone number as a hyperlink with the `tel:` URL scheme.

- `lightning-formatted-rich-text`

  - : For rich text fields. `lightning-formatted-rich-text` displays rich text that's formatted with allowlisted tags and attributes.

- `lightning-formatted-text`

  - : For text fields. `lightning-formatted-text` displays text, replaces newlines with line breaks, and adds links.

- `lightning-formatted-time`

  - : For time fields. `lightning-formatted-time` displays time in user's locale format.

- `lightning-formatted-url`

  - : For url fields. `lightning-formatted-url` displays a URL as a hyperlink.

## Example: Display a Custom Record with a Map

This example displays an address on a contact record page with a static map. Clicking the address or map opens the location on Google Maps. Since the `lightning-record-form` and `lightning-record-view-form` components don’t provide a static map, the example uses the `lightning-formatted-address` component.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="Display Contact Address" icon-name="standard:contact">
    <template lwc:if={contact.data}>
      <div class="slds-m-around_medium">
        <lightning-formatted-address
          street={street}
          city={city}
          country={country}
          province={state}
          postal-code={postal}
          show-static-map
        ></lightning-formatted-address>
      </div>
    </template>
  </lightning-card>
</template>
```

![Display an address using lightning-formatted-address.](https://developer.salesforce.com/media/data_base_address.png)

To display address compound fields, use the `getRecord` wire adapter.

```javascript
import { LightningElement, api, wire } from "lwc";
import { getRecord } from "lightning/uiRecordApi";

import STREET_FIELD from "@salesforce/schema/Contact.MailingStreet";
import CITY_FIELD from "@salesforce/schema/Contact.MailingCity";
import STATE_FIELD from "@salesforce/schema/Contact.MailingState";
import COUNTRY_FIELD from "@salesforce/schema/Contact.MailingCountry";
import POSTAL_FIELD from "@salesforce/schema/Contact.MailingPostalCode";

const FIELDS = [STREET_FIELD, CITY_FIELD, STATE_FIELD, COUNTRY_FIELD, POSTAL_FIELD];

export default class GetContactAddress extends LightningElement {
  @api recordId; // provided by the contact record page

  @wire(getRecord, { recordId: "$recordId", fields: FIELDS })
  contact;

  get street() {
    return this.contact.data.fields.MailingStreet.value;
  }

  get city() {
    return this.contact.data.fields.MailingCity.value;
  }

  get state() {
    return this.contact.data.fields.MailingState.value;
  }

  get country() {
    return this.contact.data.fields.MailingCountry.value;
  }

  get postal() {
    return this.contact.data.fields.MailingPostalCode.value;
  }
}
```

<!-- document id=f6ce33c6d3174883cbc608acab149c33011c016fe0ae90e89c43fed8e3d33403 url=/developer/current/en-us/lwc/lwc/guides/js/js-third-party-library.md -->

# Use Third-Party JavaScript Libraries

**tip:** Before you use a third-party JavaScript library, we recommend that you check [AppExchange](https://appexchange.salesforce.com/) for third-party apps that match your requirements. Alternatively, check if a [base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/) provides your desired functionality.

You can use third-party JavaScript libraries with Lightning web components. For example, use a library with interactive charts and graphs or a library that reduces code complexity.

1.  Download the library from the third-party library's site.
2.  Upload the library to your Salesforce organization as [a static resource](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md), which is a Lightning Web Components [content security policy](/docs/platform/lightning-components-security/guide/content-security-policy-intro.html) requirement.
3.  In a JavaScript class that extends `LightningElement`:

    - Import the library by its static resource name.

      ```javascript
      import RESOURCE_NAME from "@salesforce/resourceUrl/RESOURCE_NAME";
      ```

      For example, if you named the static resource `myLib`:

      ```javascript
      import myLib from "@salesforce/resourceUrl/myLib";
      ```

    - Import methods from the `platformResourceLoader` module.

      ```javascript
      import { loadStyle, loadScript } from "lightning/platformResourceLoader";
      ```

      See the [`lightning/platformResourceLoader` reference docs](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-resource-loader).

4.  Load the library and call its functions in a `then()` method.

    ```javascript
    loadScript(this, myLib + "/myLib.js").then(() => {
      let result = myLib.myFunction(2, 2);
    });
    ```

**important:** If your component runs in an org where Lightning Web Security (LWS) isn’t enabled, libraries that are used by your component must meet Lightning Locker requirements. See [Determine Whether a JavaScript Library Is Locker Compliant](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-guidance.md). If the org is using Lightning Web Security (LWS), most third-party libraries work as expected without changes. However, some libraries require changes to work with LWS. See [Third-Party Library Considerations for LWS](/docs/platform/lightning-components-security/guide/lws-js.html).

## DOM Manipulation with JavaScript

Using JavaScript to manipulate the DOM isn’t recommended because the Lightning Web Components engine does it more efficiently. However, there are some third-party JavaScript libraries that take over the DOM.

**note:** Salesforce doesn't provide support for third-party JavaScript libraries. Documentation and examples that demonstrate using a third-party JavaScript library don't constitute an endorsement of the third-party JavaScript library. We recommend that you check the third-party JavaScript library documentation for usage information.

If a call to `appendChild()` manipulates the DOM, styling isn’t applied to the appended element.

When using these libraries in a Lightning web component, add `lwc:dom="manual"` to any HTML element that you want to manipulate with JavaScript. When the engine sees the directive, it preserves encapsulation.

Add the `lwc:dom="manual"` directive to an empty native HTML element. The owner of the component calls `appendChild()` on that element to manually insert the DOM.

```html
<template>
  <div lwc:dom="manual"></div>
</template>
```

## Example: D3 JavaScript Library

This example uses the [D3 JavaScript library](https://d3js.org/) to create an interactive data visualization.

**tip:** You can follow the example using the [`libsD3`](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/libsD3) component from the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. If you had deployed [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) in your org previously, you can skip the first 2 steps. Verify that the `d3` JavaScript library is available in the Static Resources page of your Salesforce org.

![A component displaying a graph of colored dots connected by lines. You can click and drag the dots to change the shape of the graph.](https://developer.salesforce.com/media/third_party_lib.png)

To use the library:

1. Download the D3 JavaScript library at the [lwc-recipes repo](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/staticresources/d3). At the time of writing, the example uses v5.16.0 of the D3 JavaScript Library.

2. Compress the JavaScript and CSS files into a zip file. Name the file `d3.zip`. Upload `d3.zip` to your org as a [static resource](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md).

3. Create a component to contain the graph. Here, the container is an empty `<svg>`. The [`lwc:dom="manual"`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) directive tells LWC that the DOM in the `<svg>` element has been inserted manually.

<!-- prettier-ignore -->
```html
<!-- libsD3.html -->
<template>
  <div class="slds-m-around_medium">
    <svg class="d3" width={svgWidth} height={svgHeight} lwc:dom="manual"></svg>
  </div>
</template>
```

In the component’s JavaScript class, import `loadStyle` and `loadScript` from `lightning/platformResourceLoader`. Import the `d3` static resource as well. Notice that `D3` is the static resource reference for loading the resources, and `d3` is the name of the static resource uploaded to Salesforce.

To create the graph, invoke `loadStyle` and `loadScript` in `renderedCallback()` on the first render. Using `renderedCallback()` ensures that the page loads and renders the container before the graph is created.

Calls to `loadStyle` and `loadScript` return promises. Use `Promise.all()` to aggregate the results and ensure that both files are resolved before invoking the callback. The `then()` callback is invoked only after the load completes and only if no error occurs. To handle any potential error occurring during the load process, you can provide a `catch()` callback.

To initialize the graph in the promise callback, call `initializeD3()`, which reaches into the DOM and gets a reference to the container that displays the graph, here an `<svg>` element.

```javascript
// libsD3.js
/* global d3 */
import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { loadScript, loadStyle } from "lightning/platformResourceLoader";
import D3 from "@salesforce/resourceUrl/d3";
import DATA from "./data";

export default class LibsD3 extends LightningElement {
  svgWidth = 400;
  svgHeight = 400;

  d3Initialized = false;

  async renderedCallback() {
    if (this.d3Initialized) {
      return;
    }
    this.d3Initialized = true;

    try {
      await Promise.all([
        loadScript(this, D3 + "/d3.v5.min.js"),
        loadStyle(this, D3 + "/style.css"),
      ]);
      this.initializeD3();
    } catch (error) {
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Error loading D3",
          message: error.message,
          variant: "error",
        }),
      );
    }
  }

  initializeD3() {
    // Example adopted from https://bl.ocks.org/mbostock/2675ff61ea5e063ede2b5d63c08020c7
    const svg = d3.select(this.template.querySelector("svg.d3"));
    const width = this.svgWidth;
    const height = this.svgHeight;
    const color = d3.scaleOrdinal(d3.schemeDark2);

    const simulation = d3
      .forceSimulation()
      .force(
        "link",
        d3.forceLink().id((d) => {
          return d.id;
        }),
      )
      .force("charge", d3.forceManyBody())
      .force("center", d3.forceCenter(width / 2, height / 2));

    const link = svg
      .append("g")
      .attr("class", "links")
      .selectAll("line")
      .data(DATA.links)
      .enter()
      .append("line")
      .attr("stroke-width", (d) => {
        return Math.sqrt(d.value);
      });

    const node = svg
      .append("g")
      .attr("class", "nodes")
      .selectAll("circle")
      .data(DATA.nodes)
      .enter()
      .append("circle")
      .attr("r", 5)
      .attr("fill", (d) => {
        return color(d.group);
      })
      .call(d3.drag().on("start", dragstarted).on("drag", dragged).on("end", dragended));

    node.append("title").text((d) => {
      return d.id;
    });

    simulation.nodes(DATA.nodes).on("tick", ticked);

    simulation.force("link").links(DATA.links);

    function ticked() {
      link
        .attr("x1", (d) => d.source.x)
        .attr("y1", (d) => d.source.y)
        .attr("x2", (d) => d.target.x)
        .attr("y2", (d) => d.target.y);
      node.attr("cx", (d) => d.x).attr("cy", (d) => d.y);
    }

    function dragstarted(d) {
      if (!d3.event.active) {
        simulation.alphaTarget(0.3).restart();
      }
      d.fx = d.x;
      d.fy = d.y;
    }

    function dragged(d) {
      d.fx = d3.event.x;
      d.fy = d3.event.y;
    }

    function dragended(d) {
      if (!d3.event.active) {
        simulation.alphaTarget(0);
      }
      d.fx = null;
      d.fy = null;
    }
  }
}
```

**note:** In a Lightning web component, you can’t use `document` to query for DOM elements. Instead, use `this.template`. For example, this D3 code sample uses `this.template.querySelector('svg.d3')`. See [DOM Access Containment](/docs/platform/lightning-components-security/guide/locker-dom.html).

## Useful Patterns

Here are some useful patterns for loading your code. This code loads a JavaScript library without a CSS file.

```javascript
loadScript(this, RESOURCE_NAME + "/lib.js").then(() => {
  /* callback */
});
```

This code loads multiple JavaScript files in parallel.

```javascript
Promise.all([
  loadScript(this, RESOURCE_NAME + "/lib1.js"),
  loadScript(this, RESOURCE_NAME + "/lib2.js"),
  loadScript(this, RESOURCE_NAME + "/lib3.js"),
]).then(() => {
  /* callback */
});
```

**See Also**

- [Component Reference: lightning-platform-resource-loader](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-platform-resource-loader)
- [Access Static Resources](https://developer.salesforce.com/docs/platform/lwc/create/create-resources.md)
- [HTML Template Directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md)

<!-- document id=0741e3e5ce206fdcf7444da1d7e767bb7f7293ae207c7c6fbd9ef491036a234f url=/developer/current/en-us/lwc/lwc/guides/create/create-use-third-party-components.md -->

# Use Third-Party Web Components in LWC

Use third-party web components in an LWC app. Third-party web components render as native web components in LWC templates. Although you can use third-party web components in an LWC template file using an iframe or `lwc:dom="manual"`, we recommend rendering the third-party web component as native web components in your LWC templates using `lwc:external`.

**note:** Salesforce doesn't provide support for third-party web components. Documentation and examples that demonstrate using a third-party web component don't constitute an endorsement of the third-party web component. We recommend that you check the third-party web component documentation for usage information.

Third-party web components can be of various JavaScript frameworks or [those written in pure vanilla JS](https://developer.mozilla.org/en-US/docs/Web/Web_Components). The [MDN web components](https://github.com/mdn/web-components-examples/) are examples of third-party web components that you can use with the LWC framework. Similarly, [webcomponents.org](https://www.webcomponents.org/) provides a collection of web components that are based on custom elements and shadow DOM standards.

If you're working with third-party JavaScript libraries, see [Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md) instead.

## Implement Third-Party Web Components

Before you use a third-party web component, we recommend that you check AppExchange for third-party LWC apps or components and [install a managed package](https://developer.salesforce.com/docs/platform/lwc/use/use-packaging-lwc.md) with your desired functionality. Alternatively, check if a [base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/) is suitable for your requirements.

To use non-LWC third-party web components, follow one of these solutions.

- Upload the files as a static resource and load the component using the `loadScript` method from the `lightning/platformResourceLoader` module. You can upload up to 5 MB per static resource. An org can have up to 250 MB of static resources.
- Add a third-party web component as an LWC module with a `.js-meta.xml` configuration file. A [component's JavaScript file](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript.md) can have a maximum file size of 1 MB (1,000,000 bytes).
- Define and register the native web component directly.

## Example: Upload a Web Component as a Static Resource

The third-party web component in this example is similar to the [`lightning-relative-date-time` base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-relative-date-time). Check if a base component meets your requirements before using a third-party web component.

This example uses the [`time-elements` JavaScript file](https://unpkg.com/browse/time-elements@3.0.0/dist/time-elements-legacy.js), which is available as an IIFE.

`time-elements` provides several web components - `local-time`, `relative-time`, `time-ago`, and `time-until`.

Before you can use any of these web components, [upload the JavaScript file as a static resource](https://help.salesforce.com/s/articleView?id=platform.pages_static_resources_create.htm) in your org. In this example, the name of the static resource is `timeElements`.

<!-- prettier-ignore -->
```html
<!--externalExample.html-->
<template>
  <p>
    Relative time (auto-updated every minute):
    <relative-time datetime={date} lwc:external></relative-time>
  </p>
</template>
```

[Import the static resource](https://developer.salesforce.com/docs/platform/lwc/js/js-third-party-library.md) using the `loadScript` function from `lightning/platformResourceLoader`. When the script is loaded, you can initialize the properties for the component.

```javascript
//externalExample.js
import { LightningElement } from "lwc";
import { loadScript } from "lightning/platformResourceLoader";
import timeElements from "@salesforce/resourceUrl/timeElements";

export default class extends LightningElement {
  isCmpInitialized = false;
  error;
  date;

  async renderedCallback() {
    if (this.isCmpInitialized) {
      return;
    }
    this.isCmpInitialized = true;

    try {
      await loadScript(this, timeElements);
      this.initializeComponent();
    } catch (error) {
      this.error = error;
    }
  }
  initializeComponent() {
    this.date = new Date();
  }
}
```

## Example: Add a Web Component as an LWC Module

**tip:** The third-party web component in this example is similar to the [`lightning-helptext` base component](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-helptext). Check if a base component meets your requirements before using a third-party web component.

This example uses the [popup-info component from MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#autonomous_custom_elements). To add the component as an LWC module, create a Lightning web component in the `force-app/main/default/lwc` folder. Let's name it `popupInfo`.

In your template, include the `lwc:external` directive on the `popup-info` element.

<!-- prettier-ignore -->
```html
<!-- popupInfo.html -->
<template>
  <popup-info
    lwc:external
    img={logo}
    data-text="Here's some popup text for your logo'"
  ></popup-info>
</template>
```

In your JavaScript file, create a shadow root and define your element. This example uses a `trailheadLogo` static resource on which the `popup-info` attaches. It also replaces the `"img/default.png"` image path with `{$logo}`, which references the logo that's uploaded as a static resource. For more information on custom element syntax, see [Work with Custom Elements](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-custom-elements.md).

```javascript
//popupInfo.js
import { LightningElement } from "lwc";
import trailheadLogo from "@salesforce/resourceUrl/trailhead_logo";

// Create a class for the element
class PopUpInfo extends HTMLElement {
  constructor() {
    // Always call super first in constructor
    super();

    // Create a shadow root
    this.shadow = this.attachShadow({ mode: "closed" });
  }

  connectedCallback() {
    // Create spans
    const wrapper = document.createElement("span");
    wrapper.setAttribute("class", "wrapper");

    const icon = document.createElement("span");
    icon.setAttribute("id", "test");
    icon.setAttribute("class", "icon");
    icon.setAttribute("tabindex", 0);

    const info = document.createElement("span");
    info.setAttribute("class", "info");

    // Take attribute content and put it inside the info span
    const text = this.getAttribute("data-text");
    info.textContent = text;

    // Insert icon
    const img = document.createElement("img");
    img.src = this.hasAttribute("img") ? this.getAttribute("img") : `{$logo}`;
    icon.appendChild(img);

    // Create some CSS to apply to the shadow dom
    const style = document.createElement("style");

    style.textContent = `
      .wrapper {
        position: relative;
      }
      .info {
        font-size: 0.8rem;
        width: 200px;
        display: inline-block;
        border: 1px solid black;
        padding: 10px;
        background: white;
        border-radius: 10px;
        opacity: 0;
        transition: 0.6s all;
        position: absolute;
        bottom: 20px;
        left: 10px;
        z-index: 3;
      }
      img {
        width: 1.2rem;
      }
      .icon:hover + .info, .icon:focus + .info {
        opacity: 1;
      }
    `;

    // Attach the created elements to the shadow dom
    this.shadow.appendChild(style);
    this.shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

// Register the new element
customElements.define("popup-info", PopUpInfo);

export default class PopupInfo extends LightningElement {
  logo = trailheadLogo;
}
```

While we don't recommend using JavaScript manipulating the DOM, some third-party web components manipulate the DOM using Web APIs like `appendChild` and `removeChild`. For an alternative way to interact with a third-party web component using template directives, see [Example: Generate a Square with Random Attributes](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-custom-elements.md#example-generate-a-square-with-random-attributes).

## Known Issues

Be aware of several known issues.

- `loadScript` doesn't currently support [ECMAScript Modules (ESM)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). For example, `<script type="module">` isn't supported. Import third-party web components using pre-bundled JavaScript files with custom elements in a legacy format such as [IIFE (Immediately-Invoked Function Expression)](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) or [UMD (Universal Module Definition)](https://github.com/umdjs/umd).
- Third-party web components with npm and other dependencies or those that require compilation and bundling aren't supported. LWC doesn't currently support importing from npm.
- Third-party web components that reference an element by ID aren't supported in shadow DOM. For example, if the component uses `document.getElementById('some-id')`, LWC can't access the global HTML document. Use [template refs](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md) where possible.
- Experience Builder sites don't currently support third-party web components when Lightning Web Security (LWS) is enabled.
- LWS doesn't currently support [customized built-in elements](https://html.spec.whatwg.org/multipage/custom-elements.html#customized-built-in-element) using the `extends` option. Customized built-in elements are also not supported in [WebKit browsers such as Safari](https://bugs.webkit.org/show_bug.cgi?id=182671). To learn more about what you can do in a class that extends `HTMLElement`, see [HTML Spec: Custom Elements](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements).

## Usage Guidelines

Follow these guidelines when working with third-party web components.

- Pass data to a third-party web component using an attribute, property, or the `lwc:spread` directive. When passing data to the web component, LWC sets the data as attributes by default, and sets properties only if they exist.
- Pass markup to a slot in a third-party web component similar to passing markup to a slot in a Lightning web component. Slotting for synthetic shadow isn’t supported in third-party web components.
- LWC templates support root `<template>` tags only. If the third-party component requires a nested `<template>` tag, use `document.createElement('template')` in your JavaScript file instead.
- Declarative event bindings in the LWC template can use lowercase event names only. If the third-party web component uses non-lowercase characters or a hyphen in an event name, add the event listener programmatically using `addEventListener()`.
- Observe attribute changes after a third-party web component is rendered by using `observedAttributes()` and `attributeChangedCallback()`.
- `lwc:external` doesn't support [dynamic component creation](https://developer.salesforce.com/docs/platform/lwc/js/js-dynamic-components.md). Custom elements are rendered similarly to a Lightning web component and native HTML elements.
- Registering your custom element before being rendered or after being rendered makes no difference to whether the element is upgraded successfully. When the element is upgraded, the custom element that's registered before being rendered receives a dynamic value but the custom element that's registered after being rendered doesn't receive it.

For more information, see [Pass Data to a Custom Element](https://developer.salesforce.com/docs/platform/lwc/guide/create-use-third-party-pass-data.md).

**See Also**

- [Lightning Web Security FAQ](https://help.salesforce.com/s/articleView?id=000392327&type=1)
- [Salesforce Developers' Blog: What ISV Partners Need to Know About Lightning Web Security](https://developer.salesforce.com/blogs/2022/12/what-isv-partners-need-to-know-about-lightning-web-security)
- [MDN Web Docs: Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
- [HTML Specification: Upgrading elements after their creation](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-upgrades-examples)

<!-- document id=c55a2e0aec120ba07b8659bcc69c15734e1cd51e8936096574166fb597385b1c url=/developer/current/en-us/lwc/utam/guide/generator-get-started.md -->

# UTAM Generator

UTAM Generator is a tool that generates UTAM JSON files from HTML files. An input HTML file can be either a raw HTML downloaded from a browser or a Web Component source code in HTML format, such as a Lightning web component.

Starting from version 2.1.0, the generator supports generation of a UTAM JSON page object from a JavaScript file with hardcoded HTML snippets. For more details, see [Generate from JavaScript](#generate-from-javascript).

**important:** Before you use the generator on a Salesforce page, use the [UTAM browser extension](https://utam.dev/tools/browser-extension) to identify existing page objects provided by Salesforce. You generally need to generate new page objects only for custom components or custom UI that you create.

Use the [generator playground](https://utam.dev/tools/generator-playground) to generate UTAM page objects from HTML or run the generator in your own repository. See the configuration steps in the next sections.

- To run the generator in your own repository, see the configuration steps in the next section.

## Set up project dependencies

The generator artifact is published in [npm](https://www.npmjs.com/package/@utam/generator).

The `package.json` file configures the dependencies for a JavaScript project.

Add a development dependency for the UTAM generator by running one of these commands:

- `yarn add utam --dev`
- `npm install utam --save-dev`

These commands are equivalent and add `utam` to the `devDependencies` property in `package.json`, where `x.y.z` represents the installed version and is the latest version by default.

```json
{
  "devDependencies": {
    "utam": "x.y.z"
  }
}
```

## Set up generate step in package.json

The `package.json` file has a script that runs the `utam-generate` generation CLI command. `utam` is installed locally in your project because you added it to the `devDependencies` in `package.json`.

```json
{
  "scripts": {
    "build": "yarn generate:utam",
    "generate:utam": "utam-generate -c utam-generator.config.json"
  },
  "devDependencies": {
    "utam": "x.y.z"
  }
}
```

## Generator configuration file

You can specify options in the generator configuration file.

Use the `-c` flag of the `utam-generate` CLI to point at the configuration file. In this example, we use `utam-generator.config.json`.

```bash
utam-generate -c utam-generator.config.json
```

Use the `-p` flag of the `utam-generate` CLI to point the generator at multiple configuration files. This approach is useful if you have a repo where you need different configuration options in different subprojects. In most scenarios, the `-c` flag suffices and you don't need to use the `-p` flag.

```bash
utam-generate -p 'path/to/project1/utam.config.json' 'path/to/project2/utam.config.json'
```

**note:** Pass a list of whitespace-separated utam compiler configuration file paths.

The generator configuration options are explained in the next section.

## Generation runner parameters

You don't have to explicitly declare any options for the generator because all options have default values. If your project structure follows the default convention, the compiler works out of the box. In that case, set the generator configuration file to be an empty object, {}.

This section lists all the options supported by the generator runner. For each option, we describe its JSON type, its default value, and what it does.

There are other configuration parameters responsible for how the generator interprets HTML. Those parameters are explained in the [Generator rules guide](/tools/generator-guide).

```json
{
  "inputRootDir": "./", // config file directory name
  "ignore": ["**/node_modules/**"],
  "inputFileMask": ["**/*.html"],
  "outputDir": "__utam__",
  "relativeOutputDir": false,
  "outputFileExtension": ".utam.json",
  "overrideExisting": true,
  "rulesFileMask": ["**/*.rules.json"]
}
```

### `inputRootDir`

- Type: `string`
- Default: `path.dirname(configFilePath)`

The relative path from the configuration file's directory that represents the root directory path. The generator looks recursively in the root directory for HTML files.

Defaults to the configuration file's directory if not specified. For instance, if your `utam-generator.config.json` configuration file is at the package root (the same level as the `package.json` file), the page object root directory defaults to the package root directory.

### `ignore`

- Type: `string[]`
- Default: `["**/node_modules/**"]`

You can specify which folders and files should be ignored and not traversed by the generator.

Defaults to ignore only `**/node_modules/**`.

### `inputFileMask`

- Type: `string[]`
- Default: `["**/*.html"]`

The file mask pattern used by the generator to find HTML input files. It tells the generator
where to start scanning for the source files relative to `inputRootDir`. Declare the file mask as a list of glob patterns.

### `relativeOutputDir`

- Type: `boolean`
- Default: `false`

See `outputDir` for details.

### `outputDir`

- Type: `string`
- Default: `"__utam__"`

The relative path from the `inputRootDir` directory to the target directory for generated UTAM JSON files. The generator writes the JSON page objects to this directory.

If `relativeOutputDir` is set to `false`, a single folder is created under `inputRootDir`.

```txt
<inputRootDir>
├── utam-generator.config.json
├── __utam__
   ├── component1.utam.json
   ├── component2.utam.json
├── src/
   └── modules/
      ├── component1/...
      ├── component2/...
```

If `relativeOutputDir` is set to `true`, the output is generated under the same folder as the source file. The path is relative to the source folder. For example, if `outputDir` is set to `__utam__`, here's where the output is generated:

```txt
<inputRootDir>
├── utam-generator.config.json
├── src/
   └── modules/
      ├── component1/
         └── component1.html
         └── __utam__/
            └── component1.utam.json
      ├── component2/
         └── component2.html
         └── __utam__/
            └── component2.utam.json
```

### `outputFileExtension`

- Type: `string`
- Default: `".utam.json"`

The generated output file has the same name as the source file with `.html` removed and with the `outputFileExtension` added as a suffix. For example, a `myComponent.html` source file generates `myComponent.utam.json`.

### `overrideExisting`

- Type: `boolean`
- Default: `true`

If set to `true`, the generator overrides an existing file with the same name.
By default if `myComponent.utam.json` already exists, it is overridden.

### `rulesFileMask`

- Type: `string[]`
- Default: `["**/*.rules.json"]`

The file mask for component-based individual [generation rules](https://developer.salesforce.com/docs/platform/utam/guide/generator-rules.md).

### `scriptHtmlWrapper`

- Type: `string`
- Default: undefined

An HTML tag that will be used to wrap HTML snippets extracted from a JavaScript file. See [Generate from JavaScript](#generate-from-javascript).
For example, if the value is `'html'`, the output will be `<html>extracted HTML</html>`.

## Generate from JavaScript

You can generate a UTAM page object from a JavaScript file that contains HTML snippets.

To enable the generator to find the HTML snippets in JavaScript files, add the mask for JavaScript files to the `inputFileMask` configuration parameter.

```json
{
  "inputFileMask": ["**/*.html", "**/*.js"]
}
```

The generator now looks into files with the `*.js` extension and extracts HTML code snippets. The generator uses [generator rules](https://developer.salesforce.com/docs/platform/utam/guide/generator-rules.md) to generate UTAM page objects from the extracted snippets.
For example, this JavaScript file contains an HTML snippet:

```js
class Component {
  render() {
    return (
      <div>
        <button>{this.props.name}</button>
      </div>
    );
  }
}
```

The UTAM generator recognizes code in the `div` tag as HTML and generates this JSON:

```json
{
  "elements": [
    {
      "public": true,
      "name": "button",
      "type": ["actionable", "clickable"],
      "selector": {
        "css": "button"
      }
    }
  ]
}
```

If the `scriptHtmlWrapper` configuration parameter is set, the generated code will be wrapped into an HTML tag. For example, if the generator configuration is:

```json
{
  "inputFileMask": ["**/*.html", "**/*.js"],
  "scriptHtmlWrapper": "html"
}
```

The JSON is generated as if the HTML snippet in a JavaScript file was inside an `html` tag.

```json
{
    "root": true,
    "selector": {
        "css": "html"
    },
    "elements": [
        ...
    ]
}
```

<!-- document id=809e01815a7652e9ee60adc7e9369d3e55b7101305614ee794df5d0db5e9f96f url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-validate-input.md -->

# Validate Custom Flow Screen Components

Add validation to your components and customize how you display errors.

- [Validate User Input for Custom Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-user-input-for-custom-components.md)
- [Customize Input Validation Errors for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-input.md)

<!-- document id=9615827d09e268a5649725139d5fbe69a7ee388a7cc2e099e01b49cc11c8f659 url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-validate-user-input-for-custom-components.md -->

# Validate User Input for Custom Flow Screen Components

Add validation to your custom screen components.

To use flow’s validation capabilities, create a function called `validate()` in your component’s JavaScript file. For `errorMessage`, enter your custom error message.

```javascript
// sampleValidate.js
@api
validate() {
  if(/* true conditions */) {
    return { isValid: true };
    }
  else {
    // If the component is invalid, return the isValid parameter
    // as false and return an error message.
    return {
      isValid: false,
      errorMessage: '/*A message that explains what went wrong.*/'
    };
  }
}

```

Arrow function expressions don’t work for validation in components with a `target` of `lightning__FlowScreen`. For example, this arrow function expression does **not** work for flow screen validation:

```javascript
// sampleValidate.js - DOESN'T WORK
@api
validate = () => {
  if(/* true conditions */) {
    return { isValid: true };
    }
  else {
    // This won't be recognized by Flow
    return {
      isValid: false,
      errorMessage: '/*A message that explains what went wrong.*/'
    };
  }
}
```

**See Also**

- [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)
- [Call Apex Methods Imperatively](https://developer.salesforce.com/docs/platform/lwc/apex/apex-call-imperative.md)
- [Customize Input Validation Errors for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-input.md)

<!-- document id=0b249d3877276e210c6d9b64d31289d0322917af486b67630ec369d156187916 url=/developer/current/en-us/lwc/lwc/guides/reference/analytics/reference-analytics-validate-wave-template.md -->

# `validateWaveTemplate`

Validates a CRM Analytics template for org readiness.

## Syntax

```javascript
import { validateWaveTemplate } from 'lightning/analyticsWaveApi';
validateWaveTemplate({ templateIdOrApiName: string, templateValidateParam: TemplateValidateInput }): Promise<TemplateValidate>
```

## CRM Analytics API Resource

```html
POST /wave/templates/${templateIdOrApiName}/validate
```

`validateWaveTemplate` uses this [CRM Analytics API resource](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_resources_templates_validate.htm).

## Parameters

| Parameter Name          | Type   | Description                                                                                                                                                                                                       | Required?                                  |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `templateIdOrApiName`   | String | The ID or API name of the CRM Analytics template.                                                                                                                                                                 | ![Yes](https://developer.salesforce.com/media/checkmark.png) |
| `templateValidateParam` | Object | The input to validate the template with. Use the [Template Validate Input](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_requests_template_validation_input.htm). | ![Yes](https://developer.salesforce.com/media/checkmark.png) |

## Returns

- A Promise object that resolves with a [TemplateValidate](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_rest.meta/bi_dev_guide_rest/bi_responses_template_validate.htm) response.

## Usage

Use `validateWaveTemplate` to allow users to validate a CRM Analytics app template for org readiness. This example shows how to pass in parameter values to override template variables during validation. The results are parsed from JSON to a string for better readability.

```javascript
import { LightningElement } from "lwc";
import { validateWaveTemplate } from "lightning/analyticsWaveApi";

export default class ValidateWaveTemplate extends LightningElement {
  results = "";

  async doValidateWaveTemplate() {
    this.results = "Loading...";
    try {
      const results = await validateWaveTemplate({
        templateIdOrApiName: "<id or api name here>",
        templateValidateParam: {
          // include any variable values to use, which override any template defaults for this call
          values: {
            variable1: "foo",
            variable2: { objectName: "Case" },
          },
        },
      });
      this.results = "Success:\n" + JSON.stringify(results, undefined, 2);
    } catch (e) {
      console.error("validateWaveTemplate error:", e);
      this.results = "Error:\n" + JSON.stringify(e, undefined, 2);
    }
  }
}
```

<!-- document id=4d0628fbe2332df461a5b89fb9910996c958fb6a3466f27c70fe225fc2b64afd url=/developer/current/en-us/lwc/lwc/guides/use/use-flow-validate-external-internal-methods.md -->

# Validation Methods for Screen Components

Screen component validation uses these `@api` interface methods to communicate with Flow Builder. Understand implementation guidelines, best practices, and when the flow calls each method.

## validate()

When a flow user navigates to another screen or finishes the flow, the `validate()` method provides the component’s internal validation status to the flow.

Use the `validate()` method to determine if the component has any internal errors, and return a `{ isValid: true/false, errorMessage: string }` pair. Don't render internal errors inside the `validate()` method. Instead, use a `set()` method to validate properties and return internal error messages as needed.

Consider these best practices for implementing the method.

- To prevent error messages from being shown on load, determine if a change has occurred within the component before showing any errors.
- The set methods are called after the screen loads on the first visit or after a flow user moves to another screen or finishes the flow.
- On the first visit to the screen, avoid showing users an error before they’ve interacted with the rendered components.
- Show errors on screen load when the user is returned to the screen due to `validate()` returning an error. Following the best practices, `@api reportValidity()` causes the internal error to show.

## setCustomValidity(externalErrorMessage)

If a component has an input validation error, the flow can send an external error message to the component by calling the `setCustomValidity(externalErrorMessage)` method only if one of these criteria is true:

- The component is updated reactively.
- A flow user moves to a new screen or finishes the flow.

**note:** The `setCustomValidity(externalErrorMessage)` method is not invoked with the result of the `validate()` method.

Implement this method to store `externalErrorMessage` in the local state. This is not a request from the flow to render error messages. The flow can call this method with an empty string to indicate that the external error has been resolved. In this situation, we recommend not showing the error. The component can render its internal and external errors at a later time in the `reportValidity()` method.

```javascript
  @api
    setCustomValidity(externalErrorMessage) {
        // If an error is already being shown, update its text.
        if (this.externalErrorToRender) {
           this.externalErrorToRender = externalErrorMessage;
        }

        this.cachedExternalErrorMessage = externalErrorMessage;
    }
```

If `externalErrorMessage` is:

- An empty string, then `externalErrorMessage` informs the component that an external error no longer exists.
- Not an empty string, then `externalErrorMessage` contains the external error message corresponding to an input error that occurred from the flow at run time. The external error message is in rich text format.

## reportValidity()

To instruct the component to show internal and external errors, the flow calls the `reportValidity()` method if one of these occurs:

- The flow moves to another screen or finishes and calls the `validate()` method that returns an error.
- The component is updated reactively and has an input validation error.

Implement this method to render error messages in the component’s HTML. Determine how to display both internal and external errors. We recommend that you render all input validation and component validation errors in the `reportValidity()` method.

The flow calls the `reportValidity()` method along with the `setCustomValidity(externalErrorMessage)` method if one of these occurs:

- An external error occurs such as an input validation error, for example:
  - `setCustomValidity(externalErrorMessage)` passes in the external error message.
  - `reportValidity()` requests that the component render the external error message.
- The component has no external error but the component reports an error in the `validate() `method during a request to navigate away from the screen, for example:
  - `setCustomValidity(externalErrorMessage)` is called with an empty string because the flow had no external error to report.
  - `reportValidity()` requests that the component render the internal error message.

## Method Timeline

Understand when the flow calls the validation methods.

- `validate()`: Called when the flow moves to the next screen or finishes.
- `setCustomValidity(externalErrorMessage)`: Called if an external error message exists or if the external error message is changed to an empty string.
- `reportValidity()`: Based on these criteria, the flow calls the method.
  | First Load of Flow Screen? | Previously Has External Error? | Has External Error? | Has Internal Error? | reportValidity() Called? | Why? |
  | -------------------------- | ------------------------------ | ------------------- | ------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | True | Not applicable | True | True | True | Must render external error |
  | True | Not applicable | True | False | True | Must render external error |
  | True | Not applicable | False | True | True | Must render internal error that’s returned from the validate() method to show that the component failed due to moving to next screen or finishing the flow |
  | True | Not applicable | False | False | False | No errors to report |
  | False | False | True | True | True | Must render external error |
  | False | False | True | False | True | Must render external error |
  | False | False | False | True | False | Optionally render internal error based on your implementation |
  | False | False | False | False | False | Optionally render internal error based on your implementation |
  | False | True | False | True | True | Must not render external error because it’s an empty string. Optionally render the internal error based on your implementation. |
  | False | True | False | False | True | Must not render external error because it’s an empty string. Optionally render the internal error based on your implementation. |

**See Also**

- [Example: Custom Validation for Components in Flows](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-example.md)
- [Customize Input Validation Errors for Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-flow-validate-external-internal-input.md)

<!-- document id=c27f45984f2b00351d02c769ce30d108f31e460f833d13b716d96f101efc071a url=/developer/current/en-us/lwc/lwc/guides/create/create-version-components.md -->

# Version Lightning Web Components

Version your Lightning web components to ensure that your components aren’t affected when Salesforce ships new features, bug fixes, and performance improvements that change existing behavior. Update the API version for your components to use new features and improvements. Versioning also helps Salesforce deprecate legacy features when necessary.

| AVAILABLE API VERSIONS                       |
| -------------------------------------------- |
| Available in LWC API v59.0 and later         |
| Required in Spring ’25 (API v63.0) and later |

LWC began support for versioning custom components in Winter '24. Beginning in Spring ’25, versioning custom components is **required**, even if your component uses an older API version.

## Transition Unversioned Components

Components that were previously saved without setting an API version continue to run as before. However, the next time you modify the component, you'll need to set the API version, too. Attempting to save an unversioned component to Salesforce results in an error.

To aid transitioning unversioned components to versioned, Salesforce adds an `apiVersion` tag to unversioned components when you retrieve them from Salesforce. The API version added is the same as the component already uses. This ensures that the component's behavior won't change when you save it with the new `apiVersion` tag.

## Versioning Provides Stability

A component sets a version so that it can depend on a specific version of Salesforce. The API version you set for a component tells the LWC framework to behave as it did for the Salesforce release corresponding to the specified API version for that component. This ensures a stable execution environment for your components.

A component is set to only one API version. That is, every HTML, CSS, and JavaScript file of a component uses the same API version.

LWC allows composition of components that use different API versions. You can use components with different API versions on the same page. You can also use a component with one API version inside of, or to contain, a component with a different API version.

**tip:** It's a best practice to update the API version of your components whenever you modify them, so that they take advantage of the latest features and bug fixes.

## Use the `apiVersion` Tag to Specify an API Version

To specify a component's API version, set the `apiVersion` key in the `.js-meta.xml` file for the component.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    ...
    <apiVersion>58.0</apiVersion>
    ...
</LightningComponentBundle>
```

## Validation of API Version Values

`apiVersion` values are validated when you save a component to Salesforce. Vaidation errors prevent your component from being saved to Salesforce.

- The earliest valid API version is 45.0, which corresponds to Summer ’23.
- The earliest practical API version is 58.0. API versions 58.0 and earlier all correspond to Summer ’23.
- API version 59.0 was the first to introduce versioning for custom components. This corresponds to Winter ’24.
- The latest valid API version is the current release of Salesforce.

Setting an API version outside this range or using a non-standard format for the `apiVersion` value can result in a warning or error when you save the component to Salesforce.

**important:** Regardless of `apiVersion`, custom components always use the latest version of Lightning Data Service and Lightning base components.

**See Also**

- [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/reference/reference-configuration-tags.md)
- [Upgrade a Component's API Version](https://developer.salesforce.com/docs/platform/lwc/guide/create-version-upgrade.md)
- [Changes in LWC Framework that Affect Component Behavior](https://developer.salesforce.com/docs/platform/lwc/guide/create-version-changes.md)
- [Salesforce Releases and LWC API Versions](https://developer.salesforce.com/docs/platform/lwc/guide/create-version-alignment.md)
- [Find Salesforce Edition and API version](https://help.salesforce.com/s/articleView?id=000386929&type=1)

<!-- document id=d85a44ef628988162fa335d03e61375e2a7556b7736467b48572c416a5af386e url=/developer/current/en-us/lwc/lwc/guides/create/create-version-considerations.md -->

# Versioning Considerations

Consider these guidelines when working with LWC API versioning.

- Components on the same page or within the same managed package can have different API versions.
- Versioning support began with API version 58.0. If you use an `apiVersion` that's earlier than 58.0, LWC uses 58.0.
- You can't use a future API version. If you set an `apiVersion` that's later than the latest version available, you'll receive an error when you try to save the component to Salesforce.
- Components that previously didn't set an `apiVersion` tag for the component have one added automatically when the component is retrieved from Salesforce. The API version added is the same as the component already uses. This ensures that the component's behavior won't change when you save it with the new `apiVersion` tag.
- LWC API versioning isn't available for Aura components and LWR.
- LWC API versioning is available only for custom components in Lightning Experience or Experience Builder sites that include the `*.js-meta.xml` file.
- LWR doesn't support versioned behavior when custom components are used outside of Lightning Experience or Experience Builder sites. In that context, components use the latest LWC API version.

<!-- document id=7907b5f7ae0ee9d390055438e1e2daa5236f27af51480173808e1403a0cccc8a url=/developer/current/en-us/lwc/lwc/guides/use/use-setup.md -->

# View a List of Lightning Components in Your Org

From Setup, view a list of the Lightning web components and Aura components in your org.

From Setup, enter `Lightning Components` in the Quick Find box, then select **Lightning Components**. From this page you can:

- View the Lightning web components and Aura components in your org.
- View component details. Click a component name or label.
- Open an Aura component in the Developer Console. Click the component name, then click Developer Console.

**note:** To develop Lightning web components, use the Salesforce CLI and the code editor of your choice. See [Set Up Your Development Environment](https://developer.salesforce.com/docs/platform/lwc/install/install-setup-develop.md).

<!-- document id=f2e9d89f363c66b1e966cdcfd500f5d31d1c3e142e920ec7a419d331b8d7e637 url=/developer/current/en-us/lwc/lwc/guides/create/create-components-view-dependencies.md -->

# View Component Dependencies

Use the dependencies tree viewer to see which custom components and Apex classes that a component uses. You can quickly see the structure of a component and navigate to the source for its dependencies.

From Setup, in the Quick Find box, enter `Lightning Components`, and then select **Lightning Components**.

- To see the dependencies for a Lightning web component on the detail page, expand the Lightning web component row by clicking the chevron icon next to its name.
- To see the details for one of the dependencies, click a link in the Name column.

![View component dependency tree](https://developer.salesforce.com/media/view_dependencies.png)

The dependency tree shows up to three levels of dependencies for a component. For example, you can see a component and its nested child, grandchild, and great-grandchild components. To view deeper dependencies, click a link in the Name column for one of the nested components.

**See Also**

- [Compose Components](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-compose.md)

<!-- document id=6cf26f2d86a0dfac201e84feb37214940f0cf1d557cffe45dcf08d13de4f12f5 url=/developer/current/en-us/lwc/lwc/guides/js/js-web-apis.md -->

# Web API Properties

Lightning web components reflect the properties of many Web APIs.

## `Element`

Lightning web components reflect these properties of the [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) interface.

`children`, `classList`, `className`, `firstElementChild`, `getAttribute`, `getAttributeNS`, `getBoundingClientRect`, `getElementsByClassName`, `getElementsByTagName`, `hasAttribute`, `id`, `lastElementChild`, `querySelector`, `querySelectorAll`, `removeAttribute`, `removeAttributeNS`, `setAttributeNS`, `setAttribute`, `shadowRoot`, `slot`

See [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md), [Access Elements the Component Owns](https://developer.salesforce.com/docs/platform/lwc/create/create-components-dom-work.md), and [Pass Markup into Slots](https://developer.salesforce.com/docs/platform/lwc/create/create-components-slots.md).

When Lightning Web Security is enabled in the Salesforce org, [setAttributeNS, setAttribute](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Element_setAttribute-family-apis), and [shadowRoot](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#Element_shadowRoot-getter) are modified by distortions.

## `EventTarget`

Lightning web components reflect these properties of the [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) interface.

`addEventListener`, `dispatchEvent`, `removeEventListener`

See [Communicate with Events](https://developer.salesforce.com/docs/platform/lwc/events/events.md).

## `HTMLElement`

Lightning web components reflect these properties of the [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) interface.

`accessKeyLabel`, `contentEditable`, `dataset`, `dir`, `hidden`, `isContentEditable`, `lang`, `offsetHeight`, `offsetLeft`, `offsetParent`, `offsetTop`, `offsetWidth`, `title`

When Lightning Web Security is enabled in the Salesforce org, [dataset](https://developer.salesforce.com/docs/component-library/tools/lws-distortion-viewer#HTMLElement_dataset-getter) is modified by a distortion.

## `Node`

Lightning web components reflect these properties of the [`Node`](https://developer.mozilla.org/en-US/docs/Web/API/Node) interface.

`childNodes`, `firstChild`, `isConnected`, `lastChild`

See [Run Code When a Component Is Inserted or Removed from the DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks-dom.md).

## WAI-ARIA States and Properties

Lightning web components reflect these [WAI-ARIA states and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques), such as `ariaLabel` and `ariaExpanded`. For example, access the `aria-label` attribute as `ariaLabel` in JavaScript.

The standard properties include:

`ariaActiveDescendant`, `ariaAtomic`, `ariaAutoComplete`, `ariaBusy`, `ariaChecked`, `ariaColCount`, `ariaColIndex`, `ariaColIndexText`, `ariaColSpan`, `ariaControls`, `ariaCurrent`, `ariaDescription`, `ariaDescribedBy`, `ariaDetails`, `ariaDisabled`, `ariaErrorMessage`, `ariaExpanded`, `ariaFlowTo`, `ariaHasPopup`, `ariaHidden`, `ariaInvalid`, `ariaKeyShortcuts`, `ariaLabel`, `ariaLabelledBy`, `ariaLevel`, `ariaLive`, `ariaModal`, `ariaMultiLine`, `ariaMultiSelectable`, `ariaOrientation`, `ariaPlaceholder`, `ariaOwns`, `ariaPosInSet`, `ariaPressed`, `ariaReadOnly`, `ariaRelevant`, `ariaRequired`, `ariaRoleDescription`, `ariaRowCount`, `ariaRowIndex`, `ariaRowIndexText`, `ariaRowSpan`, `ariaSelected`, `ariaSetSize`, `ariaSort`, `ariaValueMax`, `ariaValueMin`, `ariaValueNow`, `ariaValueText`, `ariaBrailleLabel`, `ariaBrailleRoleDescription`

See [ARIA attributes](https://developer.salesforce.com/docs/platform/lwc/create/create-components-accessibility-attributes.md#aria-attributes).

**note:** In LWC OSS v4.0.0, some of the standard WAI-ARIA properties are no longer included as a global polyfill. For more information, see [Deprecated ARIA reflected properties](https://lwc.dev/guide/accessibility#deprecated-aria-reflected-properties).

**See Also**

- [Reflect JavaScript Properties to HTML Attributes](https://developer.salesforce.com/docs/platform/lwc/js-props/js-props-html-attributes.md)

<!-- document id=5d0ade00acbb33af363dcd1c1e98ab61713cb997f3371a9295d8883a1198f22f url=/developer/current/en-us/lwc/lightning-components-security/guides/locker/locker-where.md -->

# What Does Lightning Locker Affect?

Find out what’s affected and what’s not affected by Lightning Locker.
Lightning Locker enforces security and best practices for custom Lightning components you use in:

- Lightning Experience
- Salesforce mobile app
- Experience Builder sites
- Flows
- Standalone apps that you create (for example, myApp.app) to run in Salesforce Classic or Lightning Experience
- Any other app where you can add a custom Lightning component, such as Salesforce Console in Lightning Experience
- Lightning Out
- Visualforce pages in Salesforce Classic
- Visualforce-based sites

Lightning Locker doesn’t affect environments where you don’t use custom Lightning components.

<!-- document id=d47142298258877a17649976a999b43ab404a00e0728febdca622094608ae9d6 url=/developer/current/en-us/lwc/utam/guide/what-is-utam.md -->

# What Is UTAM?

UI Test Automation Model (UTAM) is based on the popular Page Object model design pattern commonly used in Selenium tests. The page object design pattern uses an object-oriented class to decouple a test from the target web page for robustness and easier test maintenance.
Instead of using an object-oriented class to write a page object, a UTAM page object is authored in JSON, and described by an easy-to-understand [UTAM grammar](/docs/platform/utam/references/utam-grammar/grammar.html). These JSON page objects are easy to write and easy to read.

Each web application page or component has a corresponding JSON page object that defines the UI interface for your tests. The UTAM compiler transforms the JSON page objects into JavaScript and Java page objects. You write your tests against the generated JavaScript or Java code. The JSON page object is the single source of truth for all your tests, no matter which testing language you use.

You can write your own page objects and use page objects created by other developers.

UTAM is easy to integrate with nearly any test automation framework. For JavaScript tests, UTAM provides an adapter between UTAM page objects and the browser API that WebdriverIO provides.

## Why Use UTAM?

As a web application, such as Salesforce, changes from release to release, so does the DOM of the pages and components in the app. It is much less effort to update the UTAM page object for each changed component than it is to rewrite complicated UI automation tests. Using UTAM page objects reduces the testing time and pain every time an application UI changes.

At Salesforce, we plan to deliver UTAM page objects for each release. Each UTAM page object is a type. A page object can be composed of other page objects to match the composition of the application. The UTAM compiler generates methods that the test writer may chain to select elements.

UTAM relies on CSS selectors to avoid the need to use potentially problematic XPath locators. With UTAM, some tests are self-healing. If you refactor a component to add a `div` or `span`, simply update the JSON to match. As long as the page object's interface is the same, tests written against it still work.

UTAM also makes it easy to test components that implement Shadow DOM. The UTAM grammar lets you model a component's shadow DOM in a [`shadow` object](/docs/platform/utam/references/utam-grammar/root-elements.html). The UTAM compiler generates methods that cross the shadow boundary to select elements.

## Who Is UTAM For?

UTAM is for the entire web developer and tester community. We plan to release UTAM as open-source software (OSS).

We’re already using UTAM at Salesforce to speed up UI testing. We hope you find it useful too!

<!-- document id=1fc7ea1c8c2a991185feae00767287928e613d0701eabcfbd0cbf2cb9d9a900c url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-when.md -->

# When to Enable Lightning Web Security

Determine whether to enable Lightning Web Security (LWS) in your production org based on the type of components present in your org. LWS is generally available for both Lightning web components (LWC) and Aura components.

New orgs have LWS enabled by default. If you create an org from a template, then that org inherits the LWS setting of the template. If you plan to populate a new org with preexisting or packaged Lightning components, be sure to test first in a sandbox environment with LWS enabled. See [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md).

**note:** If your org contains Experience Cloud sites, see [Experience Builder Sites and LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-lms-ec.md) before enabling LWS.

To determine the type of components that are present in your org, see [Determine if Lightning Web Security Affects Your Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-components-affected.md).

| Components in Org     | OK to Enable LWS in Production? | Testing Approach                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :-------------------- | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No components         | Yes                             | Testing isn’t needed because LWS has no effect if there are no components in your org. However, testing a new release is always recommended in sandboxes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Only LWC or only Aura | Yes, after testing in sandbox   | We strongly recommend that you first enable LWS in a sandbox staging environment for your org. See [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md). If testing shows that your components are working well in the sandbox, enable LWS in a production org. If issues arise, you can return to using Lightning Locker for Lightning components by deselecting the LWS setting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Aura and LWC          | Yes, after testing in sandbox   | We strongly recommend that you first enable LWS in a sandbox staging environment for your org. See [Workflow to Test Your Components with Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-test-workflow.md). If testing shows that your components are working well in the sandbox, enable LWS in a production org. If issues arise, you can return to using Lightning Locker for Lightning components by deselecting the LWS setting. <ul><li>If your org had the LWS setting enabled before Spring ’23 and your org contains custom Aura components, the LWS setting remains enabled and continues to affect only your Lightning web components. Your org was excluded from the LWS for Aura beta, so it didn’t affect your Aura components in Spring ’23. In Summer ’23, if your org was previously excluded from LWS for Aura, LWS remains enabled and continues to affect only Lightning web components.</li><li>The exclusion of some orgs from LWS for Aura applies to production orgs only. LWS for Aura is enabled in Summer ’23 sandboxes for orgs that are excluded, so that you can start testing your Aura components.</li></ul> |

**See Also**

- [Enable Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable.md)
- [Enable and Disable Lightning Web Security in Scratch Orgs](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable-scratch-orgs.md)

<!-- document id=69a48df51c7c1cfc21b0c4b247432000e11d16a7447d8957447efb3684d483fd url=/developer/current/en-us/lwc/lwc/guides/apex/apex-wire-method.md -->

# Wire Apex Methods to Lightning Web Components

To read Salesforce data, Lightning web components use a reactive wire service. Use `@wire` in a component’s JavaScript class to specify an Apex method. You can `@wire` a property or a function to receive the data. To operate on the returned data, `@wire` a function.

To use `@wire` to call an Apex method, annotate the Apex method with `@AuraEnabled(cacheable=true)`. A client-side Lightning Data Service cache is checked before issuing the network call to invoke the Apex method on the server. To refresh stale data, call `refreshApex()`, because Lightning Data Service doesn’t manage data provisioned by Apex.

Use this syntax to import an Apex method and wire it to a component.

```javascript
import apexMethodName from '@salesforce/apex/namespace.classname.apexMethodReference';
@wire(apexMethodName, { apexMethodParams })
propertyOrFunction;
```

- `apexMethodName`—A symbol that identifies the Apex method.
- `apexMethodReference`—The name of the Apex method to import.
- `classname`—The name of the Apex class.
- `namespace`—The namespace of the Salesforce organization. Specify a namespace unless the organization uses the default namespace (`c`), in which case don’t specify it.
- `apexMethodParams`—An object with properties that match the parameters of the `apexMethod`, if needed. If a parameter value is `null`, the method is called. If a parameter value is `undefined`, the method isn’t called. If the Apex method is overloaded, the choice of what method to call is non-deterministic (effectively random), and the parameters passed may cause errors now or in the future. Don't overload `@AuraEnabled` Apex methods.

  **important:** `apexMethodParams` is an object. To pass parameter values to an Apex method, pass an object whose properties match the parameters of the Apex method. For example, if the Apex method takes a string parameter, don’t pass a string directly. Instead, pass an object that contains a property whose value is a string. Using maps isn’t supported for both imperative and wired Apex calls. See [Pass Values to Apex](https://developer.salesforce.com/docs/platform/lwc/guide/apex-call-imperative.md#pass-values-to-apex).

- `propertyOrFunction`—A private property or function that receives the stream of data from the wire service. If a property is decorated with `@wire`, the results are returned to the property’s `data` property or `error` property. If a function is decorated with `@wire`, the results are returned in an object with a `data` property or an `error` property.

  **note:** The `data` property and the `error` property are hardcoded values in the API. You must use these values.

The return value from Apex is serialized if it contains a decimal value. If the decimal value has more than 15 digits of precision, the value is serialized as a JSON string to preserve exact precision. Otherwise, the value is serialized as a JSON number literal. This serialization prevents precision loss for high-precision decimal values that exceed JavaScript's double precision limits. You can handle these values as strings in JavaScript and convert the values as needed.

## Wire an Apex Method to a Property

Let’s look at the `apexWireMethodToProperty` component from the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. This component prints a list of contacts returned by an Apex method.

![A list of contacts in the LWC recipes app.](https://developer.salesforce.com/media/apex_wire_to_prop.png)

To get its data, the component wires an Apex method. The Apex method makes a SOQL query that returns a list of contacts that each have a picture. (This component doesn’t render the pictures, but other sample components do.) As we’ve learned, to return a simple list of contacts, it’s best to use [`getListUi`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-get-list-ui.md). But to use a SOQL query to select certain records, we must use an Apex method.

Remember that the method must be `static`, and `global` or `public`. The method must be decorated with `@AuraEnabled(cacheable=true)`.

```apex
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Picture__c != null
            WITH SECURITY_ENFORCED
            LIMIT 10
        ];
    }
}
```

The component’s JavaScript code imports the Apex method and invokes it via the wire service. The wire service either provisions the list of contacts to the `contacts.data` property, or returns an error to the `contacts.error` property.

```
import { LightningElement, wire } from 'lwc';
import getContactList from '@salesforce/apex/ContactController.getContactList';

export default class ApexWireMethodToProperty extends LightningElement {
    @wire(getContactList) contacts;
}

```

The template uses the [`lwc:if`](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) directive to check whether the `contacts.data` property is truthy. If it is, it iterates over it and renders the name of each contact. If `contacts.error` is truthy, the component renders `<c-error-panel>`.

<!-- prettier-ignore -->
```html
<!-- apexWireMethodToProperty.html -->
<template>
  <lightning-card title="ApexWireMethodToProperty" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <template lwc:if={contacts.data}>
        <template for:each={contacts.data} for:item="contact">
          <p key={contact.Id}>{contact.Name}</p>
        </template>
      </template>
      <template lwc:elseif={contacts.error}>
        <c-error-panel errors={contacts.error}></c-error-panel>
      </template>
    </div>
  </lightning-card>
</template>
```

## Wire an Apex Method with a Dynamic Parameter

Now let’s wire an Apex method that takes a parameter. This component is also in the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo.

![A search field with the letters "Jo" and two contacts listed below it, Michael Jones and Jonathan Bradley.](https://developer.salesforce.com/media/apex_wire_params.png)

The Apex method takes a string parameter called `searchKey`, and returns a list of contacts whose name contains the string.

```apex
// ContactController.cls
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> findContacts(String searchKey) {
        String key = '%' + searchKey + '%';
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Name LIKE :key AND Picture__c != null
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

The component’s JavaScript prefaces the value of the `searchKey` parameter with `$` to indicate that it’s dynamic and reactive. It references a property of the component instance. If its value changes, the template rerenders.

**important:** To `@wire` the component to the Apex method, the first parameter is a string, which is the name of the Apex method—in this case, `findContacts`. The second `@wire` parameter is an object that contains the parameters to pass to the Apex method. So, for example, even though `findContacts` takes a string, we don’t pass a string as the second `@wire` parameter. Instead, we pass an object that contains a property whose value is a string: `{ searchKey: '$searchKey' }`. (If the Apex method took another parameter, we would add another property to the object.)

```
import { LightningElement, wire } from 'lwc';
import findContacts from '@salesforce/apex/ContactController.findContacts';

/** The delay used when debouncing event handlers before invoking Apex. */
const DELAY = 300;

export default class ApexWireMethodWithParams extends LightningElement {
    searchKey = '';

    @wire(findContacts, { searchKey: '$searchKey' })
    contacts;

    handleKeyChange(event) {
        // Debouncing this method: Do not update the reactive property as long as this function is
        // being called within a delay of DELAY. This is to avoid a very large number of Apex method calls.
        window.clearTimeout(this.delayTimeout);
        const searchKey = event.target.value;
        // eslint-disable-next-line @lwc/lwc/no-async-operation
        this.delayTimeout = setTimeout(() => {
            this.searchKey = searchKey;
        }, DELAY);
    }
}

```

The template uses `searchKey` as the `value` of the `<lightning-input>` field.

<!-- prettier-ignore -->
```html
<!-- apexWireMethodWithParams.html -->
<template>
  <lightning-card title="ApexWireMethodWithParams" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <lightning-input
        type="search"
        onchange={handleKeyChange}
        class="slds-m-bottom_small"
        label="Search"
        value={searchKey}
      ></lightning-input>
      <template lwc:if={contacts.data}>
        <template for:each={contacts.data} for:item="contact">
          <p key={contact.Id}>{contact.Name}</p>
        </template>
      </template>
      <template lwc:elseif={contacts.error}>
        <c-error-panel errors={contacts.error}></c-error-panel>
      </template>
    </div>
  </lightning-card>
</template>
```

**tip:** To watch a walk though of this sample code, see **Wire an Apex Method to a Property** in the [Lightning Web Components Video Gallery](https://developer.salesforce.com/tv/lwc-video-gallery/).

## Wire an Apex Method with Complex Parameters

This example demonstrates how to call an Apex method that takes an object as a parameter. The `@wire` syntax is the same for any Apex method, but this example shows a pattern for building and passing an object.

The component has three input fields that take a string, a number, and a number of list items that the component uses to generate a list. The Apex method simply concatenates and returns a string based on the values. When an input value changes, the `@wire` calls the Apex method and provisions new data.

![Form that gathers multiple data types to send to Apex.](https://developer.salesforce.com/media/apexWireMethodComplexParam.png)

<!-- prettier-ignore -->
```html
<!-- apexWireMethodWithComplexParams.html -->
<template>
  <lightning-card title="ApexWireMethodWithComplexParams" icon-name="custom:custom63">
    <div class="slds-var-m-around_medium">
      <lightning-input
        label="String"
        type="string"
        value={stringValue}
        class="string-input"
        onchange={handleStringChange}
      ></lightning-input>
      <lightning-input
        label="Number"
        type="number"
        min="0"
        max="100"
        value={numberValue}
        class="number-input"
        onchange={handleNumberChange}
      ></lightning-input>
      <lightning-input
        label="List items"
        type="number"
        min="0"
        max="10"
        value={listItemValue}
        class="list-item-input"
        onchange={handleListItemChange}
      ></lightning-input>
      <br />
      <template lwc:if={apexResponse.data}>
        <p>{apexResponse.data}</p>
      </template>
    </div>
    <template lwc:elseif={apexResponse.error}>
      <c-error-panel errors={error}></c-error-panel>
    </template>
  </lightning-card>
</template>
```

The Apex method takes an object, `CustomWrapper`.

```
public with sharing class ApexTypesController {
    @AuraEnabled(cacheable=true)
    public static String checkApexTypes(CustomWrapper wrapper) {
        // Using System.debug() isn't good practice for production applications.
        // It's used here to showcase how the received data looks like in Apex.
        System.debug(wrapper);
        // The values are based on the data that is defined in the
        // apexImperativeMethodWithComplexParams Lightning web component.
        String response =
            'You entered "' +
            wrapper.someString +
            '" as String, and "' +
            wrapper.someInteger +
            '" as Integer value. The list contained ' +
            wrapper.someList.size() +
            ' items.';
        return response;
    }
}

```

```
/**
 * Wrapper class used to demonstrate how we can pass complex paramters from LWC.
 */
public with sharing class CustomWrapper {
    @AuraEnabled
    public Integer someInteger { get; set; }
    @AuraEnabled
    public String someString { get; set; }
    @AuraEnabled
    public List<String> someList { get; set; }
}

```

To pass parameter values from a component to an Apex method, use an object. In this example, the Apex method takes an object, `CustomWrapper`, so the component builds a matching object to pass in the `@wire`.

```
import { LightningElement, wire } from 'lwc';
import checkApexTypes from '@salesforce/apex/ApexTypesController.checkApexTypes';

export default class ApexWireMethodWithComplexParams extends LightningElement {
    listItemValue = 0;
    numberValue = 50;
    stringValue = 'Some string';

    parameterObject = {
        someString: this.stringValue,
        someInteger: this.numberValue,
        someList: []
    };

    @wire(checkApexTypes, { wrapper: '$parameterObject' })
    apexResponse;

    handleStringChange(event) {
        this.parameterObject = {
            ...this.parameterObject,
            someString: (this.stringValue = event.target.value)
        };
    }

    handleNumberChange(event) {
        this.parameterObject = {
            ...this.parameterObject,
            someInteger: (this.numberValue = parseInt(event.target.value, 10))
        };
    }

    handleListItemChange(event) {
        const someList = [];
        for (let i = 0; i < event.target.value; i++) {
            someList.push(this.stringValue);
        }
        this.parameterObject = {
            ...this.parameterObject,
            someList
        };
    }
}

```

## Wire an Apex Method to a Function

Now let’s look at the `apexWireMethodToFunction` component from the [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo. This component wires an Apex method call to a function. Because the results are provisioned to a function, the JavaScript can operate on the results. Also, the template accesses the data a bit differently than if results were provisioned to a property.

The rendered component is the same as `apexWireMethodToProperty` (except for the header).

![A list of contacts in the LWC recipes app.](https://developer.salesforce.com/media/apex_wire_to_function.png)

This component calls the same Apex method as `apexWireMethodToProperty`. The method must be `static`, and `global` or `public`. The method must be decorated with `@AuraEnabled(cacheable=true)`.

```apex
// ContactController.cls
public with sharing class ContactController {
    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [
            SELECT Id, Name, Title, Phone, Email, Picture__c
            FROM Contact
            WHERE Picture__c != null
            WITH USER_MODE
            LIMIT 10
        ];
    }
}
```

The component’s JavaScript code imports the Apex method and invokes it via the wire service. The wire service provisions the results to the `wiredContacts()` function via an object with either an `error` or `data` property. If the wire service provisions `data`, it’s assigned to `this.contacts`, which is used in the template. If it provisions `error`, it’s assigned to `this.error`, which is also used in the template. If the value of these properties change, the template rerenders.

```
import { LightningElement, wire } from 'lwc';
import getContactList from '@salesforce/apex/ContactController.getContactList';

export default class ApexWireMethodToFunction extends LightningElement {
    contacts;
    error;

    @wire(getContactList)
    wiredContacts({ error, data }) {
        if (data) {
            this.contacts = data;
            this.error = undefined;
        } else if (error) {
            this.error = error;
            this.contacts = undefined;
        }
    }
}

```

The template uses the `lwc:if` directive to check for the JavaScript `contacts` property. If it exists, it iterates over it and renders the name of each contact. If the `error` property exists, the component renders `<c-error-panel>`.

<!-- prettier-ignore -->
```html
<!-- apexWireMethodToFunction.html -->
<template>
  <lightning-card title="ApexWireMethodToFunction" icon-name="custom:custom63">
    <div class="slds-m-around_medium">
      <template lwc:if={contacts}>
        <template for:each={contacts} for:item="contact">
          <p key={contact.Id}>{contact.Name}</p>
        </template>
      </template>
      <template lwc:elseif={error}>
        <c-error-panel errors={error}></c-error-panel>
      </template>
    </div>
  </lightning-card>
</template>
```

## Work with Multiple Wire Methods

To execute multiple wires consecutively, retrieve data from the first wire and use that data to retrieve more data from the second wire. To ensure that the wires execute consecutively, wait until the first wire completes before you set the required parameters for the second wire. For example, pass a property into the first wire, and then use that property with a second property for the second wire. Then use both properties in a separate function.

```javascript
property1;
property2;
@wire(myApexMethod1, {})
method1result({ data, error }) {
  if(data) {
    this.property1 = data;
    // call another function
    // to do something with property1 and property2
  }
}
@wire(myApexMethod2, {})
method2result({ data, error }) {
  if(data) {
    this.property2 = data;
    // call another function
    // do something with property1 and property2
  }
}
```

To pass in a property value that's dependent on a previous wire call, make the property reactive so that the wire provisions new data when the property's value changes. For an example, see [getPicklistValues](https://developer.salesforce.com/docs/platform/lwc/reference/wire-adapters/reference-wire-adapters-picklist-values.md).

```javascript
property1;
property2;

  @wire(myWireCall, { objectApiName: ACCOUNT_OBJECT })
  results({ error, data }) {
    if (data) {
      this.property1 = data.someField;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.property1 = undefined;
    }
  }

  @wire(myOtherWireCall, { recordTypeId: "$property1", fieldApiName: RATING_FIELD })
  picklistResults({ error, data }) {
    if (data) {
      this.property2 = data;
      this.error = undefined;
    } else if (error) {
      this.error = error;
      this.property2 = undefined;
    }
  }

  doSomething() {
  // do something with property1 and property2
}
```

To work with multiple Apex method calls and then process the results when the component loads, you can call a common function when both property values are available.

**See Also**

- [Client-Side Caching of Apex Method Results](https://developer.salesforce.com/docs/platform/lwc/guide/apex-result-caching.md)
- [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md)
- [Lightning Web Components Video Gallery: Wire an Apex Method to a Property](https://developer.salesforce.com/tv/lwc-video-gallery)

<!-- document id=5ba356a07ac5fb9349977ec5e763f6d1fcd64fae17d2ef0850d46441b8fbb86c url=/developer/current/en-us/lwc/lwc/guides/apex/apex-continuations-apex.md -->

# Work with a Continuation in an Apex Class

To work with a continuation in an Apex class, use the Apex `Continuation` object.

## Prerequisites

Before you can call an external service, you must add the remote site to a list of authorized remote sites in the Salesforce user interface. From **Setup**, in the **Quick Find** box, enter `Remote Site Settings`. Select **Remote Site Settings**, and then click **New Remote Site**. Add the callout URL corresponding to `LONG_RUNNING_SERVICE_URL` in the Apex Class Continuation example below.

**note:** If the callout specifies a named credential as the endpoint, you don’t need to configure remote site settings. A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. In your code, specify the named credential URL instead of the long-running service URL.

## Use the `Continuation` Object

1.  To make a long-running callout, define an Apex method that returns a `Continuation` object. (Don’t worry about the attributes of the `@AuraEnabled` annotation yet. We explain that soon.)

    ```apex
    @AuraEnabled(continuation=true cacheable=true)
    public static Object startRequest() {
        // Create continuation. Argument is timeout in seconds.
        Continuation con = new Continuation(40);
        // more to come here
        return con;
    }
    ```

2.  Set an Apex callback method to be invoked after the callout completes in the `continuationMethod` property of the `Continuation` object. In this example, the callback method is `processResponse`. The callback method must be in the same Apex class.

    ```apex
    con.continuationMethod='processResponse';
    ```

3.  Set the endpoint for a callout by adding an `HttpRequest` object to the `Continuation` object. A single `Continuation` object can contain a maximum of three callouts. Each callout must have a remote site or named credential defined in Setup.

    ```apex
    HttpRequest req = new HttpRequest();
    req.setMethod('GET');
    req.setEndpoint(LONG_RUNNING_SERVICE_URL);
    con.addHttpRequest(req);

    ```

4.  Set data to pass to the callback method in the `state` property of the `Continuation` object. The `state` property has an `Object` type so you can pass in any data type that’s supported in Apex.

    ```apex
    con.state='Hello, World!';
    ```

5.  Code the logic in the Apex callback. When all the callouts set in the `Continuation` object have completed, the Apex callback method, `processResponse`, is invoked. The callback method has two parameters that you can access.

    ```apex
    public static Object processResponse(List<String> labels, Object state)
    ```

    1.  `labels`—A list of labels, one for each request in the continuation. These labels are automatically created.
    2.  `state`—The state that you set in the `state` property in your `Continuation` object.

6.  Get the response for each request in the continuation. For example:

    ```apex
    HttpResponse response = Continuation.getResponse(labels[0]);
    ```

7.  Return the results to the component’s JavaScript file.

## Example: Apex Class with Continuation

Here’s a complete Apex class that ties together all the earlier steps.

```apex
public with sharing class SampleContinuationClass {
    // Callout endpoint as a named credential URL
    // or, as shown here, as the long-running service URL
    private static final String LONG_RUNNING_SERVICE_URL =
        '<insert your callout URL here>';

    // Action method
    @AuraEnabled(continuation=true cacheable=true)
    public static Object startRequest() {
      // Create continuation. Argument is timeout in seconds.
      Continuation con = new Continuation(40);
      // Set callback method
      con.continuationMethod='processResponse';
      // Set state
      con.state='Hello, World!';
      // Create callout request
      HttpRequest req = new HttpRequest();
      req.setMethod('GET');
      req.setEndpoint(LONG_RUNNING_SERVICE_URL);
      // Add callout request to continuation
      con.addHttpRequest(req);
      // Return the continuation
      return con;
    }

    // Callback method
    @AuraEnabled(cacheable=true)
    public static Object processResponse(List<String> labels, Object state) {
      // Get the response by using the unique label
      HttpResponse response = Continuation.getResponse(labels[0]);
      // Set the result variable
      String result = response.getBody();
      return result;
    }
}
```

<!-- document id=46d583b88dada426c0f423363ab98e52d0a5a6c9f65ab288b938b468632bcdd4 url=/developer/current/en-us/lwc/lwc/guides/create/create-use-custom-elements.md -->

# Work with Custom Elements

Third-party web components are [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) that you can create using `customElements.define()`, resulting in custom elements you can reuse in an LWC app. You don't need to use custom elements with LWC unless you're working with third-party web components. When you implement a third-party web component in LWC, we recommend that you refer to that component's documentation for usage information. For the purpose of this article, custom elements and third-party web components are interchangeable.

**note:** [Lightning Web Security (LWS) must be enabled](/docs/platform/lightning-components-security/guide/lws-enable.html) in the Salesforce org because Lightning Locker doesn’t support third-party web components.

A custom element must follow these characteristics.

- Define a component class that extends `HTMLElement`.
- Register the custom element within the `CustomElementRegistry` using [`customElements.define(name, constructor)`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define). The `name` must contain a hyphen and be unique on a page.

Using a `<template>` tag in your custom element is optional. You can create a `<template>` tag using `document.createElement("template");`. You can't use a nested `<template>` tag in your LWC HTML template.

To keep your custom element separate and maintainable, you can define and register the custom element in several ways.

- In the LWC JavaScript file before the LWC component class definition
- In a separate JavaScript file within the LWC bundle

## Define the Custom Element

Third-party web components contain a custom element definition, which extends the [HTMLElement class](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). The custom element definition describes how to show the element and what to do when the element is added or removed.

The [HTML specification](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance) states that the constructor is used to set up initial state, default values, event listeners, and a shadow root.

```javascript
class MyCustomElement extends HTMLElement {
  constructor() {
    super();
    // Custom element created
  }
  connectedCallback() {
    // Element is added to document
  }
  disconnectedCallback() {
    // Element is removed from the document
  }
  static get observedAttributes() {
    return [
      // Array of attribute names to monitor for changes
    ];
  }
  attributeChangedCallback(name, oldValue, newValue) {
    // One of attributes listed above is modified
  }
  adoptedCallback() {
    // Element is moved to a new document
  }
}
// Registers the element
customElements.define("my-custom-element", MyCustomElement);
```

The third-party web component behavior is described in [lifecycle callbacks](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_the_lifecycle_callbacks), such as in `connectedCallback()` or `disconnectedCallback()`.

- `constructor()`-Called when the custom element is initialized. To establish the prototype chain, the constructor must call `super()` first and can specify any pre-rendering processes like setting the content of the shadow. The constructor sets up the initial state and default values, and registers event listeners. The constructor also attaches a shadow root to the custom element using `this.attachShadow()`.
- `connectedCallback()`-Invoked when the custom element is connected to the DOM.
- `disconnectedCallback()`-Invoked when the custom element is disconnected from the DOM.
- `observedAttributes()`-Returns an array of attributes to observe.
- `attributeChangedCallback()`-Invoked when an attribute is added, removed, or changed. Specify the attributes to observe in `observeAttributes()`.
- `adoptedCallback()`-Invoked when the custom element is moved to a new document.

## Attach a Shadow Root to A Custom Element

A custom element attaches a shadow root to its internals using the [`attachShadow()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow) Web API method, which specifies one of these encapsulation modes-`open` or `closed`. Using open mode, third-party custom elements can use `appendChild` to append HTML tags like `<div>` and `<style>` to its shadow root. They can also use `adoptedStyleSheets` and other Web APIs on the shadow root.

```javascript
constructor() {
  // Always call super first in constructor
  super();
  const shadow = this.attachShadow({ mode: "open" });
  const div = document.createElement("div");
  shadow.appendChild(div);
}
```

The custom element renders like this in the DOM.

<!-- prettier-ignore -->
```html
<my-custom-element>
  #shadow-root (open)
  |  <div></div>
</my-custom-element>
```

In closed mode, JavaScript access to the shadow DOM tree is blocked and `shadowRoot` returns null. A custom element can append HTML tags using the [`ShadowRoot.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/innerHTML) property.

**note:** To create a custom element in closed mode, save the reference to the shadow root with a different variable, such as `shadow` or `__shadow`.

```javascript
constructor() {
  // Always call super first in constructor
  super();
  this._shadow = this.attachShadow({ mode: 'closed' });
  this._shadow.innerHTML = "<div></div>";
  }
```

Despite its name, closed mode doesn't completely block access to a custom element's shadow root. For example, a custom element can query a tag in a closed shadow root and update its internals.

```javascript
constructor() {
  // Always call super first in constructor
  super();
  this._shadow = this.attachShadow({ mode: 'closed' });
  this._shadow.innerHTML = "<div></div>";
}

connectedCallback() {
  this._shadow.querySelector('div').textContent = "Hello closed mode";
}
```

The custom element renders like this in the DOM.

<!-- prettier-ignore -->
```html
<my-custom-element>
  #shadow-root (closed)
  |  <div>Hello closed mode</div>
</my-custom-element>
```

For more information, see [_MDN Web Docs_: Element.shadowRoot and the "mode" option](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#element.shadowroot_and_the_mode_option).

## Define and Register a Custom Element

To create the internal shadow DOM structure, a custom element can append content using `.innerHTML` or DOM APIs such as `createElement()` and `appendChild()`. This example defines the custom element outside of the LWC component class.

```javascript
//myComponent.js
import { LightningElement } from "lwc";

// Define and register the element
customElements.define(
  "my-custom-element",
  class extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "closed" }).innerHTML = "<div>Custom Element Constructor</div>";
    }
  },
);

export default class MyComponent extends LightningElement {
  greeting = "World";
}
```

To work with the custom element's attributes and children, use `connectedCallback()` or `renderedCallback()` instead. For example, if you're creating elements and setting attributes on them, defer them to one of the lifecycle callbacks and use `attributeChangedCallback()` to define a callback when the attribute is changed. For more information, see the [custom element specification](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance).

## Use the Custom Element in LWC

Use the custom element in your LWC template with the `lwc:external` directive.

```html
<!-- myComponent.html -->
<template>
  <div class="slds-var-m-around_medium">Hello, {greeting}!</div>
  <my-custom-element lwc:external></my-custom-element>
</template>
```

## Import A Custom Element Within the Component Bundle

If you define and register a custom element in a separate JavaScript file within a component bundle, import the JavaScript file in your LWC JavaScript file. For example, define and register the custom element in a JavaScript file `myCustomElement.js` in the `myComponent` component bundle that follows this folder structure.

```ascii
main/default/lwc/myComponent
   ├──myComponent.html
   ├──myComponent.js
   ├──myComponent.js-meta.xml
   └──myCustomElement.js
```

In the `myCustomElement.js` file, define and register the custom element.

```javascript
// myCustomElement.js
class MyCustomElement extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "closed" }).innerHTML = "<div>Hello Custom Element</div>";
  }
}

// Registers the element
customElements.define("my-custom-element", MyCustomElement);
```

To import the JavaScript file from your Lightning web component, use the `import` syntax.

```javascript
// myComponent.js
import { LightningElement } from "lwc";
import "./myCustomElement";

export default class MyComponent extends LightningElement {}
```

In the HTML template file, create an instance of your custom element using `lwc:external`.

```html
<!-- myComponent.html -->
<template>
  <my-custom-element lwc:external></my-custom-element>
</template>
```

## Example: Create a Custom Element that Increments a Button Label

Here's an example to demonstrate the structure of a custom element. The example creates a button that increments the counter on its label when pressed.

```javascript
//myCounterButton.js
import { LightningElement } from "lwc";

class MyCounter extends HTMLElement {
  count = 0;
  handler = () => {
    this.count++;
    this._shadow.firstElementChild.innerHTML = this.count;
  };
  shadow = null;
  constructor() {
    super();
    this._shadow = this.attachShadow({ mode: "closed" });
    this._shadow.innerHTML = `Button:<button>${this.count}</button>`;
  }
  connectedCallback() {
    this._shadow.firstElementChild.addEventListener("click", this.handler);
  }
  disconnectedCallback() {
    this._shadow.firstElementChild.removeEventListener("click", this.handler);
  }
}
customElements.define("my-counter", MyCounter);
export default class MyCounterButton extends LightningElement {}
```

To use the custom element in LWC, add it to your template using the `lwc:external` directive.

```html
<!-- myCounterButton.html -->
<template>
  <my-counter lwc:external></my-counter>
</template>
```

The component renders in the DOM like this. The button label `${this.count}` is incremented each time it's clicked.

<!-- prettier-ignore -->
```html
<my-counter-button>
    <my-counter>
      #shadow-root (closed)
      |  "Button:"
      |  <button>0</button>
    </my-counter>
</my-counter-button>
```

## Example: Increment a Button with Attribute Change Callback

This example is similar to the previous example, but it watches the custom element's `count` attribute, using `attributeChangedCallback()` to define a callback when the attribute is changed.

```javascript
//myCounterWithCallback.js
import { LightningElement } from "lwc";

customElements.define(
  "my-counter",
  class MyCounter extends HTMLElement {
    constructor() {
      super();
      this._shadow = this.attachShadow({ mode: "closed" });
    }

    get count() {
      return this.getAttribute("count");
    }

    set count(val) {
      this.setAttribute("count", val);
    }

    connectedCallback() {
      this.renderButton();
      let btn = this._shadow.querySelector("#btn");
      btn.addEventListener("click", this.increment.bind(this));
    }

    static get observedAttributes() {
      return ["count"];
    }

    attributeChangedCallback(prop, oldVal, newValue) {
      if (prop === "count") {
        this.renderButton();
        let btn = this._shadow.querySelector("#btn");
        btn.addEventListener("click", this.increment.bind(this));
        // do something else
      }
    }

    increment() {
      this.count++;
    }

    renderButton() {
      this._shadow.innerHTML = `
        <button id="btn">${this.count}</button>
      `;
    }
  },
);

export default class extends LightningElement {}
```

Add the custom element tag to your LWC template.

```html
<!-- myCounterWithCallback.html -->
<template>
  <my-counter count="0" lwc:external></my-counter>
</template>
```

## Example: Generate a Square with Random Attributes

This example is adapted from the [MDN lifecycle callbacks article](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#lifecycle_callbacks). It uses a `<custom-square>` custom element that's defined and registered in a separate `customSquare.js` JavaScript file within the same `myCustomSquare` component bundle.

```ascii
main/default/lwc/myCustomSquare
   ├──myCustomSquare.html
   ├──myCustomSquare.js
   ├──myCustomSquare.js-meta.xml
   └──customSquare.js
```

The `customSquare.js` file creates a class for the custom element and registers it using `customElements.define("custom-square", Square);`. It also exports the `random` function, so that the `myCustomSquare` component can import and use it.

```javascript
// customSquare.js
class Square extends HTMLElement {
  // Specify observed attributes so that
  // attributeChangedCallback will work
  static get observedAttributes() {
    return ["color", "size"];
  }

  constructor() {
    // Always call super first in constructor
    super();

    this._shadow = this.attachShadow({ mode: "closed" });
    this._shadow.innerHTML = `<style></style><div></div>`;
  }

  connectedCallback() {
    console.log("Custom square element added to document.");
    this.updateStyle();
  }

  disconnectedCallback() {
    console.log("Custom square element removed from document.");
  }

  adoptedCallback() {
    console.log("Custom square element moved to new document.");
  }

  attributeChangedCallback(name, oldValue, newValue) {
    console.log("Custom square element attributes changed.");
    this.updateStyle();
  }

  updateStyle() {
    this._shadow.querySelector("style").textContent = `
      div {
        width: ${this.getAttribute("size")}px;
        height: ${this.getAttribute("size")}px;
        background-color: ${this.getAttribute("color")};
      }
    `;
  }
}

customElements.define("custom-square", Square);

function random(min, max) {
  return Math.floor(Math.random() * (max - min + 1) + min);
}

export { random };
```

The `myCustomSquare.js` file contains the button click handlers to add, update, and remove the custom square from the DOM. The JavaScript initializes the custom attributes and updates these attributes on the custom element. It also imports the `random` function from the `customSquare.js` file that defines and registers the custom element.

```javascript
// myCustomSquare.js
import { LightningElement, api } from "lwc";
import { random } from "./customSquare";

export default class MyCustomSquare extends LightningElement {
  // Initialize square attributes
  size = 100;
  color = "red";
  showSquare = false;

  // Initialize disabled property for buttons
  buttonDisabled = true;

  handleAdd() {
    // Add a custom square element to the DOM
    this.showSquare = true;

    // Enable the buttons for
    // interacting with the custom square
    this.buttonDisabled = false;
  }

  handleUpdate() {
    // Randomly update square's attributes
    this.size = random(50, 200);
    this.color = `rgb(${random(0, 255)}, ${random(0, 255)}, ${random(0, 255)})`;
  }

  handleRemove() {
    // Remove the square
    this.showSquare = false;
    this.buttonDisabled = true;
  }
}
```

**important:** We don’t recommend using JavaScript to manipulate the DOM. It's better to use [HTML directives](https://developer.salesforce.com/docs/platform/lwc/reference/reference-directives.md) to write declarative code. This example uses `lwc:if` to conditionally display the custom element instead of using `appendChild` and `removeChild`. Using the conditional directive also triggers the `disconnectedCallback` and `connectedCallback` lifecycle callbacks for the custom element.

Add the buttons to the `myCustomSquare` HTML template file.

<!-- prettier-ignore -->
```html
<template>
  <lightning-card title="ComponentJavaScriptFile" icon-name="custom:custom14">
    <div class="slds-var-m-around_medium">
      <lightning-button onclick={handleAdd} label="Add custom-square to DOM"></lightning-button>
      <lightning-button onclick={handleUpdate} disabled={buttonDisabled} label="Update attributes">
      </lightning-button>
      <lightning-button onclick={handleRemove} disabled={buttonDisabled} label="Remove custom-square from DOM">
      </lightning-button>
      <template lwc:if={showSquare}>
        <custom-square lwc:external 
          size={size}
          color={color}></custom-square>
      </template>
    </div>
  </lightning-card>
</template>
```

**See Also**

- [Custom Elements - Reusable Web Components](https://web.dev/custom-elements-v1)

<!-- document id=52a8ec09d3a62f2eab6c128059a8655ed793a9dd64c9e4affd881dd4c45696c5 url=/developer/current/en-us/lwc/lwc/guides/data/data-error-types.md -->

# Work with Errors

You can encounter different error types when working with Lightning Web Components (LWC). Learn about different error types, how the errors are propagated, and how you can handle the errors.

## Error Types

The most common errors you encounter with LWC are JavaScript errors, Lightning Data Service errors, and Apex errors.

### JavaScript Errors

LWC uses the standard [`Error` JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) for runtime errors, which returns error type names like `ReferenceError`, `SyntaxError`, and so on. Throw exceptions using `throw` and handle them using the try-catch block.

For example, you get a `ReferenceError` in this case.

```javascript
showErrors() {
  try {
      undefinedVariable.toString();
  } catch(e) {
      console.error('e.name => ' + e.name); // ReferenceError
      console.error('e.message => ' + e.message); //undefinedVariable is not defined
      console.error('e.stack => ' + e.stack); //ReferenceError: undefinedVariable is not defined at Proxy.showErrors
  }
}
```

JavaScript errors can be thrown in synchronous or asynchronous code. Synchronous code is run line by line like this.

```javascript
connectedCallback() {
  console.log('log something'); // success
  throw new Error('some error'); // success
  console.log('error thrown'); // fails
}
```

When an error is thrown, any code that follows the error fails to run.

### Lightning Data Service Errors

Lightning Data Service (LDS) manages data for you via wire adapters like those in the `lightning/ui*Api` modules. You're working with asynchronous code when you write code that calls wire service or JavaScript promises. See [Handle Errors in Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-error.md).

### Apex Errors

Retrieving data using Apex means you can encounter errors or exceptions from your Apex code. When your Apex code encounters an error, you can use a try-catch block and handle the error in Apex. Otherwise, the error becomes unhandled and gets thrown directly to the client. You can handle a built-in Apex exception or create your own custom exception. See [Handle Errors from Apex](https://developer.salesforce.com/docs/platform/lwc/apex/apex-error-handling.md).

## Error Lifecycle

When your code throws an error but don't handle it, the error gets thrown to the parent component. If the parent component doesn't handle the error either, the error is then thrown to the enclosing app such as Lightning Experience or the Experience Builder site. You'll see a popup titled "A Component Error has occurred!" or "Something went wrong" with the error message and stack trace. Alternatively, you can handle the error more elegantly using a try-catch block.

Errors from asynchronous code are handled slightly differently. If the component doesn't handle the error, it gets thrown to the parent component. If the parent component doesn't handle the error, it gets thrown directly to the browser in the console.

This example shows how errors are propagated when working with synchronous vs asynchronous code.

```javascript
import { LightningElement } from "lwc";

export default class ErrorLifecycleExample extends LightningElement {
  greeting = "Hello";

  handleChange(event) {
    // Synchronous code with error
    this.greeting = event.targets.value; // targets is an intentional typo that throws an error

    // Asynchronous code with error
    Promise.resolve().then(() => {
      this.greeting = event.targets.value; // targets is an intentional typo that throws an error
    });
  }
}
```

In the synchronous example, the error is thrown by the enclosing app in Lightning Experience or the Experience Builder site. In the asynchronous example, the error is thrown in the browser console.

## Display Errors

Depending on how you want to handle errors, you can choose to display the errors on the user interface. To help users rectify the errors effectively, include a helpful message that briefly explains a corrective action. You can usually surface a helpful message from LDS or Apex or provide your own. Displaying errors consistently across the app is also helpful so users can know what to expect.

**tip:** [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) is an app that displays errors consistently using the [errorPanel](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/errorPanel) component while processing different errors structures using the [ldsUtils](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/ldsUtils/) module.

## Propagating Errors

As discussed in the previous sections, unhandled errors are propagated to the enclosing app or the browser by default. You can throw a custom error, which can be propagated by using the `throw` keyword or using a custom event. You can also use [Lightning Message Service or the `pubsub` module](https://developer.salesforce.com/docs/platform/lwc/events/events-pubsub.md).

Generally, you want to propagate errors from child components and then handle errors in parent components.

### Throw a Custom Error with a Toast Notification

As discussed in [Display Errors](#display-errors), you can surface a helpful message from LDS or Apex or provide your own. A common way to display an error is to use a toast. This example displays a custom error on a toast notification using the `throw` keyword. It uses [the `ldsUtils` module](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/ldsUtils/ldsUtils.js) from the lwc-recipes repo to reduce the errors into a string of error messages.

```javascript
import { LightningElement, wire } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { reduceErrors } from "c/ldsUtils";

export default class CustomErrorExample extends LightningElement {
  handleSomething(event) {
    try {
      throw new Error("Something has gone wrong!");
    } catch (e) {
      this.dispatchEvent(
        new ShowToastEvent({
          title: "Check your input",
          message: reduceErrors(e).join(", "),
          variant: "error",
        }),
      );
    }
  }
}
```

Alternatively, you can display the error provided by LDS or Apex.

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo displays errors from LDS on a toast notification. Look for examples that start with `lds*`, such as [ldsCreateRecord](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/main/default/lwc/ldsCreateRecord).

### Use a Custom Event

Using a custom event is helpful when you're working with multiple child components that need to be handled by a parent component in a consistent way. A child component dispatches the custom event and a parent component handles it.

Let's say your child component has a `useCustomEvent()` function that dispatches a custom event.

```javascript
//child.js
useCustomEvent() {
  const condition = true; // your logic here
  if (condition) {
    const selectedEvent = new CustomEvent('error', {
      detail: 'Your custom error here'
    });
    this.dispatchEvent(selectedEvent);
  } else {
    // do something
  }
}
```

The custom event name is `error`. In the parent component, handle the custom error using the `onerror` event handler name.

<!-- prettier-ignore -->
```html
<!-- parent.html -->
<template>
  <c-child onerror={handleCustomError}></c-child>
</template>
```

THe parent component displays an alert with the error details.

```javascript
import { LightningElement } from "lwc";

export default class Parent extends LightningElement {
  handleCustomError(e) {
    alert("From child component: " + e.detail);
  }
}
```

**See Also**

- [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines.md)
- [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/events/events-create-dispatch.md)
- [_MDN web docs_: throw](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/throw)

<!-- document id=6a081b73bea7a02fdcab3d40748c3c286a3bb98d1902f4e647141e38b43a44be url=/developer/current/en-us/lwc/lwc/guides/base-components/base-components-overview.md -->

# Work with Lightning Base Components

Lightning base components are the building blocks that make up Lightning Experience, the Salesforce mobile app, and Experience Builder sites. They incorporate Salesforce Lightning Design System (SLDS) markup and classes, while providing optimal performance and accessibility support. Base components include visual components and API modules that speed up your app development. Use base components to build your own user interfaces and apps.

**note:** Base components in the `lightning` namespace are available for both LWC and Aura components. We recommend using LWC whenever possible. Components from both frameworks can coexist and interoperate on a page. This document uses "Lightning Base Components" and "base components" interchangeably.

Learn about the basics of base components. The content here compliments the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/).

- [Base Components Categories](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-all.md)
- [Base Components Minimum API Version](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-min-version.md)
- [Supported App Containers](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-containers.md)
- [Base Components Considerations](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-considerations.md)
- [Base Components Accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-accessibility.md)

This section also provides best practices and usage patterns when using base components.

- [Base Components Usage Patterns](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-patterns.md)
- [Global Attributes Support](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-patterns-global.md)
- [Handle Events on Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-events.md)
- [Base Component Composition](https://developer.salesforce.com/docs/platform/lwc/guide/base-components-compose.md)

<!-- document id=33860672f1bb3fb9ff21df7bce0c7764bbd7f02b67a7d086a6c6b1ec5873edd5 url=/developer/current/en-us/lwc/lwc/guides/data/data-get-user-input-intro.md -->

# Work with Records Using Base Components

To create forms that let users view, edit, and create Salesforce records, use the `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form` components. For more information, see [Compare Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input.md).

**note:** The `lightning-record*form` components are the easiest way to work with records. They provide a UI to view, create, and edit records—similar to the record detail page in Salesforce. To create a custom UI, or if you don’t need a metadata-driven UI, [use a wire adapter](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service.md).

When working with records using base components, you can:

- [Load a record](https://developer.salesforce.com/docs/platform/lwc/guide/data-load-record.md)
- [Edit a record](https://developer.salesforce.com/docs/platform/lwc/guide/data-edit-record.md)
- [Create a record](https://developer.salesforce.com/docs/platform/lwc/guide/data-create-record.md)
- [Build custom UI](https://developer.salesforce.com/docs/platform/lwc/guide/data-salesforce-write.md)
- [Display record data in a table](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-intro.md)

You can also display a record form based on a record type and handle a custom event on a form. See [Usage Considerations for Working with Records](https://developer.salesforce.com/docs/platform/lwc/guide/data-considerations.md).

<!-- document id=69bbfac8ef8574fa4e19909c656c35b246f7e4167171f6422c7965c7935fd4bf url=/developer/current/en-us/lwc/lwc/guides/data/data.md -->

# Work with Salesforce Data

Salesforce provides several ways for Lightning web components to work with data. Always start with the simplest solution and move to a solution that allows for more customization as needed.

To work with Salesforce data, LWC provides these features.

- [Lightning base components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro.md)
- [Lightning Data Service wire adapters and functions](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service.md)
- [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines.md#graphql-wire-adapter)
- [Apex](https://developer.salesforce.com/docs/platform/lwc/apex/apex.md)
- [RefreshView API](https://developer.salesforce.com/docs/platform/lwc/guide/refreshview/data-refreshview.md)

For more information, review the [data guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines.md).

<!-- document id=263eda21c38144da180679975e6580133b9e2e1f92cadf7ccaf502166a027dfa url=/developer/current/en-us/lwc/slds_linter/guides/use/use-work-with-linter-intro.md -->

# Work With SLDS Linter

Use SLDS Linter to [scan your code](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-scan-code.md) with the complete set of rules, or [use custom configuration files](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-custom-config-files.md) to enable or disable specific rules. Also, learn how to [automatically fix the identified issues](https://developer.salesforce.com/docs/platform/slds-linter/guide/use-autofix-code.md) in the code.

<!-- document id=ba255ead4c0b890d4f5136483194e526be974c7387a0f0348111b409523df069 url=/developer/current/en-us/lwc/slds-validator/guides/work-with.md -->

# Work with SLDS Validator

SLDS Validator scans your code, validates it against a database of guidelines, and offers suggestions on how to improve your code. SLDS Validator makes recommendations for Lightning Web Components and Aura.

- To extend your SLDS Validator implementation, read [Customize SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/guide/customize.md).
- To learn more about Lightning Web Components, check out the [developer guide](https://developer.salesforce.com/docs/platform/lwc/guide).
- To learn more about Aura components, check out the [developer documentation](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/intro_components.htm).

<!-- document id=ab8eef2b1056e7af5f81731e73f83bbd0b6d42835d1052f14794918e923dafaf url=/developer/current/en-us/lwc/lwc/guides/create/create-dom-intro.md -->

# Work with the DOM

The Document Object Model (DOM) represents the HTML page so that you can work with its content, structure, and style using JavaScript or the standard DOM APIs. For example, you can [access elements in a component](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.md) using standard DOM APIs like `querySelector()` or without a selector using template refs. Although we don't recommend manipulating the DOM, some third-party JavaScript libraries require taking over the DOM.

With LWC, you can create components in:

- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom.md)
- [Synthetic Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-dom-synthetic.md)
- [Light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.md)
- [Mixed Shadow Mode (Beta)](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.md)

For more information on the DOM, see [_MDN Web Docs_: Document Object Model (DOM)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model).

<!-- document id=9f28427c466287f93bae24f62a63799e13081df44d2ebe5fcecf9b69b397480f url=/developer/current/en-us/lwc/lightning-components-security/guides/lws/lws-test-workflow.md -->

# Workflow to Test Your Components with Lightning Web Security

To evaluate how your custom Lightning components run with Lightning Web Security (LWS) enabled, follow this workflow.

:::Important

You can’t disable LWS on individual components. If you refactor components to take advantage of [features only available with LWS enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md), ensure that you thoroughly test all your components in sandboxes before you push them to production orgs. See [Considerations Before Using LWS-Only Features](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-refactor.md).

:::

1.  Download and configure the ESLint rules as described in [Install ESLint Rules for Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-lint.md).
2.  Run the base rule set against your components as described in [Run Base Rules Against Your Project](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-tools-lint.md#run-base-rules-against-your-project).
3.  Fix any errors revealed by the base ESLint rules.
4.  As you fix the errors, try the revised code in the [Lightning Web Security Console](https://developer.salesforce.com/tools/lws-console) to see if it can run with LWS.
5.  If your code is affected by distortions, review the distortion descriptions in the [LWS Distortion Viewer](https://developer.salesforce.com/tools/lws-distortion-viewer) for help with understanding the issues.
6.  After you fix the linting errors, enable **Use Lightning Web Security for Lightning web components and Aura components** in a sandbox, as described in [Enable Lightning Web Security in an Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable.md).
7.  Deploy your components to the sandbox.
8.  Test your components manually and by running your automated tests.
9.  If you notice any abnormal behavior or test results, try running the `recommended` rule set on your component code to debug any additional issues. You can skip this step if you ran the code in Lightning Web Security Console. The tool runs both sets of ESLint rules.
10. If your component isn’t performing correctly with Lightning Web Security enabled, or you can’t fix the ESLint errors, you can discuss the issue in the [Lightning Components Development group](https://sfdc.co/NextGenWebSecurity) on Trailhead.

11. If wish to keep your components backwards compatible with [Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/locker/locker-intro.md), follow these additional steps. For backwards compatibility with Lightning Locker, your components can’t use [features only available with LWS enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/get-started/get-started-compare-lws-locker.md).
    1.  In the sandbox, Disable the **Use Lightning Web Security for Lightning web components and Aura components** setting.
    2.  To ensure that the correct files are loaded in the browser for Lightning Locker, clear the browser cache. If the results aren’t what you expect after clearing the cache, try the other cache-related solutions in [Delayed Enabling or Disabling of LWS](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-caching.md).
    3.  To evaluate whether your components still work with Lightning Locker, test the modified components in the sandbox org. Use the [Lightning Locker Console](https://developer.salesforce.com/tools/locker-service-console) and the [Locker API Viewer](https://developer.salesforce.com/tools/locker-service-viewer) tools.
12. If the modified components perform well and pass tests in the sandbox, deploy the changes to production.
13. Enable the **Use Lightning Web Security for Lightning web components and Aura components** setting in production.

**See Also**

- [Debug with Lightning Web Security Enabled](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-debug.md)
- [Troubleshoot Issues Related to Lightning Web Security](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-troubleshoot.md)
- [_Lightning Web Components Developer Guide_: Debug Lightning Web Components](/docs/platform/lwc/guide/debug-intro.html)
- [_Lightning Aura Components Developer Guide_: Debugging](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/debug_intro.htm)

<!-- document id=f8d8f00ac646a2ff7a5bfde3cae78b51f32324fa8a2b24c16d3e5bad848ab152 url=/developer/current/en-us/lwc/utam/guide/slots.md -->

# Working with slots

A slot is a placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together. See [MDN: slots documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).

## Slot in a Web Component

Let's look at an example of how to use slots in a page object. Here's a modal with account fields. We're using the Salesforce application as an example, but we could use any application that has an account object with certain fields.

![Inspected slot](https://developer.salesforce.com/docs/media/utam/slots_screenshot.jpg)

As you can see from the screenshot, the `<records-record-layout-item>` component has an element `<slot name="inputField"></slot>` that can contain other components like input, lookup, or picklist depending on the account field type.

For the field that we selected for inspection, the content of the slot is a `<records-record-layout-lookup slot="inputField">...</records-record-layout-lookup>` element that has other nested HTML elements.

## Slot in a UTAM page object

To test the content of the `<records-record-layout-item>` component, our page object needs an `"inputFieldContainer"` [container element](/docs/platform/utam/references/utam-grammar/page-object-elements.html) because the item can contain any component inside the slot depending on the setup:

```json
{
  "elements": [
    {
      "type": "container",
      "name": "inputFieldContainer",
      "public": true,
      "selector": {
        "css": "[slot='inputField']"
      }
    }
  ]
}
```

The first thing to notice is that the **content of the slot isn't inside the shadow root, only the slot itself is**.
If a web developer puts something inside a `<slot>`, it becomes the fallback or “default” content. The browser shows it if there’s no corresponding filler in light DOM. Even though our component has a shadow root, the container element isn't crossing the shadow boundary and isn't inside the `"shadow"` element.

## Locating slot and slot content

If a page object element points to a slot itself (for example with `"slot[name='inputField']"`), its internal elements can only be found using [assignedNodes()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes), which isn't supported in UI automation tools. All we can do with such an element is to call basic actions, such as checking its presence or getting its attributes and text.

To point to another component inside the slot, the selector of our container element (`"inputFieldContainer"`) **should point to the content of the slot, not to the slot itself**: `"[slot='inputField']"`.

## Locating content of default slots

To make a UI component more generic, a developer can sometimes add a default slot (a slot without a name).

```html
<div class="slots">
  <slot name="inputField"></slot>
  <!-- default slot after named slot -->
  <slot></slot>
</div>
```

At run time, the content of the slot can be anything, so the page object can handle it in one of the following ways:

### 1. If the slot is the first element of its parent, use the default container

If you try to access the content of the first slot inside its parent, use the default selector (do not add a `"selector"` property to the JSON).

For example for the given HTML:

```html
<template>
  <!-- first slot is default slot -->
  <slot></slot>
</template>
```

The following container element can access the content.

```json
{
  "elements": [
    {
      "type": "container",
      "name": "firstSlotContent",
      "public": true
      // default selector is ":scope > *:first-child"
    }
  ]
}
```

### 2. Add a custom element of the hardcoded type (not recommended)

This approach is not a good option because you would have to add a method for every possible element. However, it might be a better option than hardcoding a selector in every test.

```json
{
  "elements": [
    {
      "type": "my/component",
      "name": "myComponentInsideSlot",
      "public": true,
      "selector": {
        "css": "my-component"
      }
    }
  ]
}
```

### 3. Locate with hardcoded CSS parameter passed at run time (not recommended)

A parameter can expose a hardcoded selector to the test; for example: `field.getRuntimeContent(MyComponent, "my-component")`. This approach violates encapsulation, but sometimes it's the only option.

Because we do not know CSS selector to locate content, it has to be added as a parameter.

```json
{
  "elements": [
    {
      "type": "container",
      "name": "runtimeContent",
      "public": true,
      "selector": {
        "css": "%s",
        "args": {
          "name": "hardcodedSelector",
          "type": "string"
        }
      }
    }
  ]
}
```

This parameter exposes a hardcoded selector to a UI test (for our example test code would be: `field.getRuntimeContent(MyComponent, "my-component")`.
This approach violates encapsulation, but can be the only available option for a page object author.

## Using a slot in a UI test

For our example, the UI test uses `field`, which is an instance of our page object with a slot:

- Java

  ```java
  RecordLayoutLookup lookup = field.getInputFieldContainer(RecordLayoutLookup.class);
  lookup.doSomething();
  ```

- JavaScript

  ```js
  const lookup = await field.getInputFieldContainer(RecordLayoutLookup);
  await lookup.doSomething();
  ```

The test invokes the container method with the type of the content to be loaded (`"RecordLayoutLookup"`) and then interacts with the returned content.

## Summary

- A slot inside a web component translates into a container element inside the UTAM page object
- A container's selector should always point to the slot content, never to the slot itself
- A container element is outside the shadow root of its immediate parent

<!-- document id=b74744d3d4fd7902488fab5be93a778108902f3cf20dda15e9eb33a6403cfa70 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-jest-create-tests.md -->

# Write Jest Tests for Lightning Web Components

Write your component tests in local JavaScript files. Commit them to version control along with the component itself. Jest tests aren’t saved to Salesforce.

Jest tests are written, saved, and run differently than Jasmine or Mocha tests written for the Lightning Testing Service. Jest tests are local only, and are saved and run independently of Salesforce.

You can use the Salesforce CLI command [`sf force lightning lwc test create`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_lightning.htm#cli_reference_force_lightning) to create a test directory and a boilerplate test file within the directory. The following command creates a test directory and file for testing the `myButton` Lightning web component.

```bash
sf force lightning lwc test create -f force-app/main/default/lwc/myButton/myButton.js
```

## Component Folder Structure

After you use the Salesforce CLI `create` command, you see a folder named `__tests__` at the top level of your component’s bundle directory, such as `force-app/main/default/lwc/myButton/__tests__`. Otherwise, create the folder yourself. Save all tests for this component inside the `__tests__` folder. Share tests with other team members or systems by committing the `__tests__` folder to version control.

## Update .forceignore

To ensure that the `__tests__` folder and its contents are never saved to Salesforce, add this glob pattern to the `.forceignore` file for each of your projects. The Salesforce CLI command [`sf force lightning lwc test setup` does this task for you.](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_lightning.htm#cli_reference_force_lightning)

```ascii
**/__tests__/**
```

This pattern ensures that Salesforce DX commands that push, pull, or transform code and metadata ignore the `__tests__` folder and its contents.

## Test File Naming Conventions

Jest runs JavaScript files in the `__tests__` directory. Test files must have names that end in `.js`, and we recommend that tests end in `.test.js`. You can have a single test file with all of your component tests, or you can have multiple files to organize related tests. Test files can be placed in sub folders.

## Write a Basic Test

To become an accomplished tester, learn how to use Jest. In particular, learn the syntax of the many [matchers provided with Jest](https://jestjs.io/docs/using-matchers). We don’t cover general Jest usage here because [the Jest documentation](https://jestjs.io/docs/getting-started) is excellent. We focus on the specifics of using Jest with Lightning web components.

Jest tests for a Lightning web component should test the behavior of a single component in isolation, with minimal dependencies on external components or services.

Let’s look at `hello.test.js`, which is the test for the `hello` Lightning web component in the [`lwc-recipes`](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/hello) repo.

```javascript
// hello.test.js
import { createElement } from "lwc";
import Hello from "c/hello";

describe("c-hello", () => {
  afterEach(() => {
    // The jsdom instance is shared across test cases in a single file so reset the DOM
    while (document.body.firstChild) {
      document.body.removeChild(document.body.firstChild);
    }
  });

  it("displays greeting", () => {
    // Create element
    const element = createElement("c-hello", {
      is: Hello,
    });
    document.body.appendChild(element);

    // Verify displayed greeting
    const div = element.shadowRoot.querySelector("div");
    expect(div.textContent).toBe("Hello, World!");
  });
});
```

Let’s walk through the code and learn about each section of the test file. All tests must use this structure.

### Imports

First, the test imports the `createElement` method. This method is available only in tests. The code must also import the component to test, which in this case is `c/hello`. Use these imports later to create the component under test.

```javascript
import { createElement } from "lwc";
import Hello from "c/hello";
```

### `describe` block

A `describe` block defines a test suite. A test suite contains one or more tests that belong together from a functional point of view.

```javascript
describe('c-hello', () => {
  ...
});
```

We recommend having a top level `describe` block with a description matching the component name. Add more `describe` blocks that group functionality only if necessary.

For `hello.test.js`, a single `describe` is sufficient. For more complex components, it may make sense to have several `describe` blocks that group things into categories like error scenarios, empty input, wired data, regular data, and so on.

### Clean Up Between Tests

The Jest [`afterEach()`](https://jestjs.io/docs/api#aftereachfn-timeout) method resets the DOM at the end of the test.

Since a browser isn’t running when tests run, Jest uses `jsdom` to provide an environment that behaves much like a browser’s DOM or `document`. Jest has a dependency on `jsdom`, which is a Node.js project, so `jsdom` is downloaded during installation of the `sfdx-lwc-jest` project the same way Jest itself is.

Each test file shares a single instance of `jsdom`, and changes aren’t reset between tests inside the file. Therefore it’s a best practice to clean up between tests, so that a test’s output doesn’t affect any other test.

```javascript
afterEach(() => {
  // The jsdom instance is shared across test cases in a single file so reset the DOM
  while (document.body.firstChild) {
    document.body.removeChild(document.body.firstChild);
  }
});
```

Jest also has other methods that you can use to perform setup and cleanup tasks. See [`jestjs.io/docs/en/setup-teardown`](https://jestjs.io/docs/setup-teardown).

### `it` (or `test`) block

**note:** `it` is an alias for [`test`](https://jestjs.io/docs/api#testname-fn-timeout). Use whichever word allows you to describe the expected behavior accurately.

An `it` block describes a single test. A test represents a single functional unit that you want to test. Write the `it` to describe the expected behavior of that function. For example, the `hello` component displays “Hello, World!”, so the `it` block tests that the hello component displays a greeting.

```javascript
it('displays greeting', () => {
    ...
});
```

### Create Test Component

The test uses the imported `createElement` method to create an instance of the component to test, in this case, `c-hello`.

```javascript
const element = createElement("c-hello", {
  is: Hello,
});
```

### Add Test Component to the DOM

The test then calls `appendChild` to add the component to the test’s version of `document`.

The `appendChild()` call inserts the component into the DOM and the lifecycle hooks `connectedCallback()` and `renderedCallback()` are called.

```javascript
document.body.appendChild(element);
```

The next step is to use a standard DOM query method to search the DOM for the element. Use `element.shadowRoot` as the parent for the query. It's a test-only API that lets you peek across the shadow boundary to inspect a component’s shadow tree. It’s the test equivalent of `this.template`.

```javascript
const div = element.shadowRoot.querySelector("div");
```

### Use Asserts

Finally, the `expect` statement is an assertion of the success condition: that the text of the element is “Hello, World!”

```javascript
const div = element.shadowRoot.querySelector("div");
expect(div.textContent).toBe("Hello, World!");
```

Jest supports lots of matchers like `toBe` and `toMatchObject` that make it easy to check that a value meets a condition. See [`jestjs.io/docs/en/expect`](https://jestjs.io/docs/expect).

## Test the Navigation Service

To test a component that extends `NavigationMixin(LightningElement)`, create a mock navigation plugin. The `sfdx-lwc-jest` package includes a [`lightning/navigation` mock](https://github.com/salesforce/sfdx-lwc-jest/blob/master/src/lightning-stubs/navigation/navigation.js) by default. To use the mock, you must [provide a jest config](https://developer.salesforce.com/docs/platform/lwc/guide/unit-testing-using-jest-advanced.md).

Here's an example mock that's used by many navigation components in the lwc-recipes repo.

```
/**
 * For the original lightning/navigation mock that comes by default with
 * @salesforce/sfdx-lwc-jest, see:
 * https://github.com/salesforce/sfdx-lwc-jest/blob/master/src/lightning-stubs/navigation/navigation.js
 */

import { createTestWireAdapter } from '@salesforce/wire-service-jest-util';
export const CurrentPageReference = createTestWireAdapter(jest.fn());

const Navigate = Symbol('Navigate');
const GenerateUrl = Symbol('GenerateUrl');

// We need the mock to reset between tests, so we hold the state in jest.fn() objects.
// We use Jest's reflection methods to implement the two CalledWith helpers below so we don't need to update all the existing tests.
// A cleaner implementation would just export these two mocks directly for consumption by the test authors to verify the state.
export const mockNavigate = jest.fn();
export const mockGenerate = jest.fn();

export const NavigationMixin = (Base) => {
    return class extends Base {
        [Navigate](pageReference, replace) {
            mockNavigate({ pageReference, replace });
        }
        [GenerateUrl](pageReference) {
            mockGenerate({ pageReference });
            return new Promise((resolve) => resolve('https://www.example.com'));
        }
    };
};
NavigationMixin.Navigate = Navigate;
NavigationMixin.GenerateUrl = GenerateUrl;

/*
 * Tests do not have access to the internals of this mixin used by the
 * component under test so save a reference to the arguments the Navigate method is
 * invoked with and provide access with this function.
 */
export const getNavigateCalledWith = () => {
    // If the mock was never called, return the object with undefined properties.
    // This prevents exceptions when tests destructure this object, allowing them to
    // fail in more expected ways as the test verifies properties on the pageReference object.
    if (mockNavigate.mock.calls.length === 0) {
        return {
            pageReference: undefined,
            replace: undefined
        };
    }

    // The mock was called, so return the most recent last call.
    // Because the mock is called with a single object, it's at the zero index.
    return mockNavigate.mock.lastCall[0];
};

export const getGenerateUrlCalledWith = () => {
    // If the mock was never called, return the object with undefined properties.
    // This prevents exceptions when tests destructure this object, allowing them to
    // fail in more expected ways as the test verifies properties on the pageReference object.
    if (mockGenerate.mock.calls.length === 0) {
        return {
            pageReference: undefined
        };
    }

    // The mock was called, so return the most recent last call.
    // Because the mock is called with a single object, it's at the zero index.
    return mockGenerate.mock.lastCall[0];
};

```

Use the mock with a `jest.config.js` config file.

```
const { jestConfig } = require('@salesforce/sfdx-lwc-jest/config');
const setupFilesAfterEnv = jestConfig.setupFilesAfterEnv || [];
setupFilesAfterEnv.push('<rootDir>/jest-sa11y-setup.js');
module.exports = {
    ...jestConfig,
    moduleNameMapper: {
        // Jest mocks
        '^@salesforce/apex$': '<rootDir>/force-app/test/jest-mocks/apex',
        '^@salesforce/schema$': '<rootDir>/force-app/test/jest-mocks/schema',
        '^lightning/navigation$':
            '<rootDir>/force-app/test/jest-mocks/lightning/navigation',
        '^lightning/platformShowToastEvent$':
            '<rootDir>/force-app/test/jest-mocks/lightning/platformShowToastEvent',
        '^lightning/uiRecordApi$':
            '<rootDir>/force-app/test/jest-mocks/lightning/uiRecordApi',
        '^lightning/messageService$':
            '<rootDir>/force-app/test/jest-mocks/lightning/messageService',
        '^lightning/actions$':
            '<rootDir>/force-app/test/jest-mocks/lightning/actions',
        '^lightning/modal$':
            '<rootDir>/force-app/test/jest-mocks/lightning/modal',
        '^lightning/refresh$':
            '<rootDir>/force-app/test/jest-mocks/lightning/refresh',
        '^lightning/logger$':
            '<rootDir>/force-app/test/jest-mocks/lightning/logger'
    },
    setupFiles: ['jest-canvas-mock'],
    setupFilesAfterEnv,
    testTimeout: 10000
};

```

## Test Imperative Apex Methods

When you call Apex methods imperatively, the Apex code doesn't run in your Jest tests. You need to mock the Apex method to return test data.

To mock Apex methods, update your `jest.config.js` file to include a `moduleNameMapper` entry for `@salesforce/apex`. This entry tells Jest where to find your mock Apex methods.

```javascript
moduleNameMapper: {
  '^@salesforce/apex$': '<rootDir>/force-app/test/jest-mocks/apex'
}
```

### Test a Create Operation

Let's look at a component that creates a contact record by calling an Apex method imperatively.

```javascript
// contactCreator.js
import { LightningElement } from 'lwc';
import createContact from '@salesforce/apex/ContactController.createContact';

export default class ContactCreator extends LightningElement {
  async handleCreate() {
    const result = await createContact({ lastName: 'Smith' });
    this.contactId = result.id;
  }
}
```

Create a mock Apex controller in `force-app/test/jest-mocks/apex/ContactController.js`.

```javascript
// ContactController.js
export const createContact = jest.fn();
```

Here's the test for this component.

```javascript
// contactCreator.test.js
import { createElement } from 'lwc';
import ContactCreator from 'c/contactCreator';
import createContact from '@salesforce/apex/ContactController.createContact';

describe('c-contact-creator', () => {
  afterEach(() => {
    while (document.body.firstChild) {
      document.body.removeChild(document.body.firstChild);
    }
    jest.clearAllMocks();
  });

  it('creates contact', async () => {
    // Mock the Apex method to return an ID
    const mockContactId = '003000000000001';
    createContact.mockResolvedValue({ id: mockContactId });

    // Create a component and call the method
    const element = createElement('c-contact-creator', {
      is: ContactCreator
    });
    document.body.appendChild(element);
    element.handleCreate();

    // Wait for async operation
    await Promise.resolve();

    // Verify Apex was called and component state updated
    expect(createContact).toHaveBeenCalledWith({ lastName: 'Smith' });
    expect(element.contactId).toBe(mockContactId);
  });
});
```

### Test Update and Delete Operations

Update and delete operations follow the same pattern. The only difference is the mock return value.

**Update Operation**

```javascript
// In the ContactController.js mock file
export const updateContact = jest.fn();

// In the contactCreator.test.js test file
updateContact.mockResolvedValue({ success: true });
```

**Delete Operation**

```javascript
// In the ContactController.js mock file
export const deleteContact = jest.fn();

// In the contactCreator.test.js test file
deleteContact.mockResolvedValue();
```

## Test Asynchronous DOM Updates

When the state of a Lightning web component changes, the DOM updates asynchronously. To ensure that your test waits for updates to complete before evaluating the result, return a resolved Promise. Chain the rest of your test code to the resolved Promise. Jest waits for the Promise chain to complete before ending the test. If the Promise ends in the rejected state, Jest fails the test.

```javascript
test("element does not have slds-icon class when bare", () => {
  const element = createElement("one-primitive-icon", { is: PrimitiveIcon });
  document.body.appendChild(element);
  // Property value is assigned after the component is inserted into the DOM
  element.variant = "bare";

  // Use a promise to wait for asynchronous changes to the DOM
  return Promise.resolve().then(() => {
    expect(element.classList).not.toContain("slds-icon");
  });
});
```

The `appendChild()` call inserts the component into the DOM and the lifecycle hooks `connectedCallback()` and `renderedCallback()` are called. The example then sets the element value _after_ the `appendChild()` call, which resembles cases where properties are set by another method or user interaction after the component is inserted into the DOM. In these cases, use a promise to wait for the asynchronous DOM update. For more information on the component lifecycle and rendering, see [Lifecycle Flow](https://developer.salesforce.com/docs/platform/lwc/create/create-lifecycle-hooks.md).

In cases where the property is set before the `appendChild()` call, the component is rendered synchronously. When the property is set before the `appendChild()` call, you don’t need to wait for asynchronous updates or return a promise.

**See Also**

- [Salesforce Developers Blog: Unit Test Lightning Web Components with Jest](https://developer.salesforce.com/blogs/2019/03/unit-test-lightning-web-components-with-jest.html)
- [Jest: Get Started](https://jestjs.io/docs/en/getting-started.html)
- [Jest: Expect Reference](https://jestjs.io/docs/expect)
- [GitHub Repo: lwc-recipes](https://github.com/trailheadapps/lwc-recipes)
- [Shadow DOM](https://developer.salesforce.com/docs/platform/lwc/create/create-dom.md)
- [Jest Test Patterns and Mock Dependencies](https://developer.salesforce.com/docs/platform/lwc/guide/unit-testing-using-jest-patterns.md)
- [Call Apex Methods Imperatively](https://developer.salesforce.com/docs/platform/lwc/apex/apex-call-imperative.md)

<!-- document id=73da69fc3b788a4a27db7db8fbb185988cdc53f43c909d15ee098d7805c5c797 url=/developer/current/en-us/lwc/lwc/guides/testing/unit-testing-using-wire-utility.md -->

# Write Jest Tests for Lightning Web Components That Use the Wire Service

Components use the wire service to get data from Salesforce. To test how these components handle data and errors from the wire service, use the `@salesforce/sfdx-lwc-jest` test utility.

The input that your test consumes shouldn't depend on outside code or data—you must have full control over it. Import the test utility API from `sfdx-lwc-jest` to mock the data so your test isn’t dependent on unpredictable factors like remote invocation or server latency.

The `sfdx-lwc-jest` utility has three adapters for mocking wire service data: a generic wire adapter, a Lightning Data Service (LDS) wire adapter, and an Apex wire adapter.

- The generic adapter emits data on demand when you call the `emit()` API. It does not include any extra information about the data itself.
- The LDS adapter mimics Lightning Data Service behavior and includes information about the data’s properties.
- The Apex wire adapter mimics calls to an Apex method and includes any error status.

**note:** If you’re not using the `sfdx-lwc-jest` utility for working with Salesforce DX, you can import adapters using the `@salesforce/wire-service-jest-util` test utility. However, we recommend using `sfdx-lwc-jest` for an integrated development experience.

To control the test, instead of getting data from Salesforce, create a JSON file that defines the data that the component expects.

To use the wire service test utility, follow these high-level steps.

1.  In your component bundle, create a folder called `__tests__` and a JavaScript class called `componentName.test.js`. It’s a best practice to name the file after the component, followed by `.test.js`.
2.  In the `__tests__` folder, create a `data` folder, and a JSON file called `_wireAdapter_.json`.
    1.  In the JSON file, mock the data that the wire adapter emits.
    2.  If the wire adapter is an LDS wire adapter, grab a snapshot of data using a REST client that accesses the [UI API that the wire adapter is based on](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_overview.htm). This approach is more accurate than writing JSON by hand.
3.  In the `componentName.test.js` file:
    1.  Import the component under test and its wire adapter. The test must reference the same wire adapter as the component under test.
    2.  Import the mock data from the JSON file.
    3.  Emit the mock data.
    4.  Verify that the component received the mock data.

## Component Under Test

Our sample component is a product card component.

The product card component displays a product and its name.

<!-- prettier-ignore -->
```html
<!-- productCard.html -->
<template>
  <div class="content">
    <template lwc:if={product}>         
        <div class="name">         
          <div>Name:</div>
          <div>{name}</div>
        </div>
    </template>
  </div>
</template>
```

In the component's JavaScript file, the `@wire` decorator tells the wire service to use the `getRecord` wire adapter to provision record data. It decorates the `wiredRecord` function, which receives an object with error or data properties.

```javascript
// productCard.js
import { LightningElement, wire } from "lwc";

// Wire adapter to load records.
import { getRecord } from "lightning/uiRecordApi";

export default class ProductCard extends LightningElement {
  // Id of Product__c to display.
  recordId;

  // Product__c to display
  product;

  // Product__c field values to display
  name = "";

  @wire(getRecord, { recordId: "$recordId", fields: ["Product.Name"] })
  wiredRecord({ data }) {
    if (data) {
      this.product = data;
      this.name = data.fields.Name.value;
    }
  }
}
```

**tip:** The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc) repo has examples of several components using the wire service that include Jest tests.

## Mock the Data

In your `__tests__` folder, create a folder called `data`. Within the `data` folder, make a file called `getRecord.json`, the same name as the wire adapter. Define the data that the component expects from the server. You can author the JSON yourself, but that can get difficult and error prone. The best practice is to grab a snapshot of data using a REST client that accesses the [UI API](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_overview.htm). For example, this data is a response from `/ui-api/records/{recordId}`, which is the resource that backs the `getRecord` wire adapter.

Our mocked data defines only the `Name` field on the record. In a real test, mock all the data that your component expects.

```json
{
  "fields": {
    "Name": {
      "value": "DYNAMO X1"
    }
  }
}
```

## Create a JavaScript Test

The unit test checks that the product card displays the product name.

The test must import the wire adapter used in the component under test. Here, that's the `getRecord` wire adapter from the `lightning/uiRecordApi` module. The test must also import the mock data to send through the wire adapter.

The test creates the component and appends it to the DOM. The component receives updates about data only when the component is connected to the DOM. After the component connects, pass the mocked data to the `emit` function on the wire adapter.

After emitting the mocked data, if `product` or `name` change, the component rerenders. Resolve a promise to ensure that the test code runs after the DOM has been updated with the new data. The code verifies that the product name field from the mock data is properly output in the DOM.

```javascript
// productCard.test.js
import { createElement } from "lwc";
import ProductCard from "c/productCard";
import { getRecord } from "lightning/uiRecordApi";

// Import mock data to send through the wire adapter.
const mockGetRecord = require("./data/getRecord.json");

test("displays product name field", () => {
  const element = createElement("c-product_filter", { is: ProductCard });
  document.body.appendChild(element);

  // Emit mock record into the wired field
  getRecord.emit(mockGetRecord);

  // Resolve a promise to wait for a rerender of the new content.
  return Promise.resolve().then(() => {
    const content = element.shadowRoot.querySelector(".content");
    const nameField = mockGetRecord.fields.Name.value;
    expect(content.textContent).toBe(`Name:${nameField}`);
  });
});
```

**note:** In Spring ’21 and earlier releases, you had to register the wire adapter under test. That code still works, but it isn’t recommended.

**See Also**

- [GitHub Repo: salesforce/sfdx-lwc-jest](https://github.com/salesforce/sfdx-lwc-jest)
- [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/data/data-wire-service-about.md)
- [lightning/ui\*Api Wire Adapters and Functions](https://developer.salesforce.com/docs/platform/lwc/reference/reference-ui-api.md)
- [GitHub Repo: lwc-recipes](https://github.com/trailheadapps/lwc-recipes)

<!-- document id=479681a36eca658d6f24a200c09590ffece5a1b3b7eea07c5325cd307571512b url=/developer/current/en-us/lwc/lwc/guides/reference/nfcservice/reference-lightning-nfcservice-write.md -->

# `write(options)`

Write text to an NFC tag.

## Syntax

```javascript
import { getNFCService } from 'lightning/mobileCapabilities';
write(
  payloads: NFCRecord[],
  options?: NFCServiceOptions
): Promise<Object>;
```

## Parameters

- payloads–(Required) An array of `NFCRecord` objects containing the raw bytes to be written.
- options-An `NFCServiceOptions` object to configure the NFCService request.

## Returns

If successful, the OS returns a `Promise` object that resolves to null. If unsuccessful, the OS returns a `Promise` object that rejects to` NFCServiceFailure`.

## Usage

Use this function to write text to an NFC tag.

```javascript
myNFCService
  .write(payloads, options)
  .then(() => {
    console.log("Payload was written successfully!");
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- When the user cancels the operation, the promise is rejected with a `NFCServiceFailure.code` value of USER_DISMISSED.

**note:** The caller is responsible for ensuring that the payload of the `NFCRecord` object is correctly formatted, per NFC specifications. To help with this, we’ve provided two helper functions, `createTextRecord()` and `createUriRecord()`. By using these functions, you can convert your text or URI payload to an NFC record first, and then pass those records to the `write()` method to be written to the tag.

**See Also**

- [NFCService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-data-types.md)
- [createTextRecord()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-createtextrecord.md)
- [createUriRecord()](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice-createurirecord.md)

<!-- document id=2d7bd4749be516ee5dac15012ea2a626f8b5f0199b6e33ba3f3a7191783277e7 url=/developer/current/en-us/lwc/lwc/guides/reference/healthservice/reference-lightning-healthservice-writeweight.md -->

# `writeWeight(record)`

Writes a body-weight record to the device’s health store. If needed, presents a permissions prompt to the user to request access to health data first, and then writes the record.

## Syntax

```javascript
import { getHealthService } from 'lightning/mobileCapabilities';
writeWeight(record: WeightRecord): Promise<void>
```

## Parameters

- `record`—(Required) A [`WeightRecord`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md) object that represents the weight measurement to write. Provide a `value` greater than 0 and a valid `unit`.

## Returns

- A resolved promise returns no object.

- A rejected promise returns a [`HealthServiceFailure`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md) object containing details about the error.

## Usage

This function writes a single weight record to the device’s health store.

```javascript
const record = {
  value: 80.5,
  unit: 'kg',
  startTime: Date.now(),
  endTime: null
};
myHealthService
  .writeWeight(record)
  .then(() => {
    console.log("Weight record saved.");
  })
  .catch((error) => {
    console.error("Error code: " + error.code);
    console.error("Error message: " + error.message);
  });
```

- When the record is written, the promise resolves with no value. Handle success in a `then` clause.
- If an error occurs, the error is returned via a rejected promise. Handle errors in a `catch` clause.
- If the user denies permission to write health data, the promise is rejected with a `HealthServiceFailure.code` value of `USER_DENIED_PERMISSION`.
- Permission to write health data is granted separately from permission to read it.

**See Also**

- [HealthService Example](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/use_healthservice_example.htm)
- [HealthService Data Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-data-types.md)
- [`getWeight(options)`](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-healthservice-getweight.md)

<!-- document id=3bd53ea5f16c81f57f14bb1906560eb80945c51e78d062c4159af250f81a45bf url=/developer/current/en-us/lwc/lwc/guides/use/use-experience-cloud-xml-configuration.md -->

# XML Configuration

The `js-meta.xml` file of a custom property editor component must include the `lightning__PropertyEditor` target to indicate that this component is a property editor.

Here's how the `js-meta.xml` file for `alignmentCPE` looks when the `lightning__propertyEditor` target is set.

```xml
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata" fqn="alignmentCPE">
   <apiVersion>66.0</apiVersion>
   <isExposed>true</isExposed>
   <masterLabel>Alignment Editor Component</masterLabel>
   <targets>
     <target>lightning__PropertyEditor</target>
   </targets>
</LightningComponentBundle>
```

**See Also**

- [`lightning__PropertyEditor` Target](https://developer.salesforce.com/docs/platform/lwc/reference/targets/targets-lightning-property-editor.md)

<!-- document id=d33be85e630bad536c506a05b84f89ad9789458c4694cb78dd8beec9fa2f5f9b url=/developer/current/en-us/lwc/lwc/guides/reference/reference-configuration-tags.md -->

# XML Configuration File Elements

Each Lightning web component folder must include a configuration file named `componentName.js-meta.xml`. The configuration file defines the metadata values for the component, including targets and the design configuration for the builders like Lightning App Builder and Experience Builder.

**tip:** Want to check out sample configuration files? The [lwc-recipes](https://github.com/trailheadapps/lwc-recipes) repo contains components with configuration files, like [this one for the `eventSimple` example component](https://github.com/trailheadapps/lwc-recipes/blob/main/force-app/main/default/lwc/eventSimple/eventSimple.js-meta.xml). Look for `.js-meta.xml` configuration files in the component bundles in `force-app/main/default/lwc`.

Throughout this page, you can click on any subtag value name (like `lightning__AppPage` or `lightning__RecordPage`) to learn more about its specific properties and configuration options.

## `ai`

Defines an AI description for the component and its properties. The `ai` tag set is supported only for record pages in orgs that have Setup with Agentforce enabled. For more information, see [Setup with Agentforce](https://help.salesforce.com/s/articleView?id=xcloud.setup_agentforce_overview.htm&type=5).

Add the `ai` tag set at the top level of the `js-meta.xml` file. Specify the `ai` tag only once. The `ai` tag contains one `description` tag, and can contain multiple `property` tags.

### `description`

The AI-related description of the component. This description isn’t user-facing. Agentforce uses this description to analyze the component for inclusion in agent-generated Lightning pages. AI component descriptions can be up to 4,000 characters. See [Tips for Writing AI Component Descriptions](https://developer.salesforce.com/docs/platform/lwc/use/use-config-for-agentforce-tips.md).

### `property`

Each `property` tag in the `ai` tag set contains the AI-related description for a single component property. Provide a property tag for each component property that's annotated by @api.

This tag doesn’t replace the `property` tag in the `targetConfig` section, but enhances it by providing an AI description. Define the component properties using the `property` tag in the `targetConfig` tag set just like usual.

Use the `property` tag with these attributes.
| Attribute | Type | Description | Required |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `aiDescription` | String | The AI description for the property. This property description isn't user-facing. Agentforce uses it to help in its analysis of the component for inclusion in agent-created Lightning pages. | Yes |
| `name` | String | The attribute name. This value must match the property name in the component's JavaScript class. It must also match the `name` value defined for this property in the `targetConfig` tag set. | Yes |

## `apiVersion`

Salesforce API version `45.0` or higher. Regardless of `apiVersion`, the component always uses the latest version of Lightning Data Service and Lightning base components. The Lightning Locker version is set at the org level, and isn't related to the component `apiVersion`.

Beginning in Winter '24, LWC supports [versioning for custom components](https://developer.salesforce.com/docs/platform/lwc/create/create-version-components.md). Beginning in Spring ’25, all components **must** specify an API version. Unversioned components continue to work as before, but must have an `apiVersion` tag set to save changes back to Salesforce. To apply bug fixes and new functionality that are tied to a later API version, upgrade your component's API version.

## `capabilities`

A capability is something that a component can do, as opposed to a target, which defines where you can use a component.

Supports the `capability` subtag.

### `capability`

Valid values are:

| Value                                                                                                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`lightningCommunity__RelaxedCSP`](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_security_locker_csp.htm)       | Enables a component installed from a managed package to run in an Experience Builder site that has Lightning Locker disabled. This setting allows managed package developers to opt in to running their Lightning web components in a site with Lightning Locker disabled. Lightning web components in a managed package that don’t include the `lightningCommunity__RelaxedCSP` tag are disabled in the Components panel in Experience Builder for any site with Lightning Locker disabled. Nested components must also include this tag. |
| [`lightning__dynamicComponent`](https://developer.salesforce.com/docs/platform/lwc/js/js-dynamic-components.md)                                                                                                          | Enables a component to dynamically instantiate other components.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`lightning__ServerRenderable`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-hydration-experience-cloud.html)                                        | Enables server-side rendering (SSR) with islands architecture for a page. For Experience Builder sites that use Lightning Web Runtime only.                                                                                                                                                                                                                                                                                                                                                                                                |
| [`lightning__ServerRenderableWithHydration`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-hydration-experience-cloud.html)                           | Enables SSR with hydration for a custom component. For Experience Builder sites that use Lightning Web Runtime only.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [`lightning__ServiceCloudVoiceToolkitApi`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-service-cloud-voice-toolkit-api) | Enables a component to use the Service Cloud Voice Toolkit API. A component that uses the `lightning-service-cloud-voice-toolkit-api` component must specify the `lightning__ServiceCloudVoiceToolkitApi` capability.                                                                                                                                                                                                                                                                                                                      |

## `description`

A short description of the component, usually a single sentence. This user-facing description appears in list views, like the list of Lightning Components in Setup, and as a tooltip in the builders like Lightning App Builder and Experience Builder.

## `isExposed`

If `isExposed` is `false`, the component isn’t exposed in the builders.

To allow the component to be used in a builder, set `isExposed` to `true` and define at least one `<target>`, which is a type of Lightning page.

**note:** A custom Lightning web component can’t access a Lightning web component or module in a custom namespace. It can access Lightning web components and modules only in the `c` and `lightning` namespaces.

## `masterLabel`

The title of the component. Appears in list views, like the list of Lightning Components in Setup, and in the builders.

## `runtimeNamespace`

The namespace of the managed package of your Vlocity Lightning web components. See [_Salesforce Help_: Vlocity User Interaction Tools](https://help.salesforce.com/s/articleView?id=xcloud.os_req_lwc_compatible_Vlocity_lwc_vlocity.htm).

## `targets`

Specifies where the component can be added, such as on a type of Lightning Page or in Embedded Service Chat. If you want your component to appear in the builders, specify at least one Lightning page type.

Supports the `target` subtag.

### `target`

A page or container type. Valid values are:

**note:** Click on any target names (like `lightning__AppPage` or `lightning__RecordPage`) to learn more about its properties and configuration options, including support for `targetConfigs` tags and subtags.

| Value                                                                                                                                                                       | Description                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`analytics__Dashboard`](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_lwc_in_db.meta/bi_dev_guide_lwc_in_db/bi_lwc_in_db_reference.htm)                   | Enables a component to be used as a widget in a CRM Analytics dashboard.                                                                                                                                                                                                                               |
| [`lightningCommunity__Default`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-community-default.md)                                                                                             | Enables a component in Experience Builder to expose editable properties when the component is selected. Only properties defined for the `lightningCommunity__Page` or `lightningCommunity__Theme_Layout` targets are editable in Experience Builder.                                                   |
| [`lightningCommunity__Page`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-community-page.md)                                                                                                   | Enables a drag-and-drop component to be used on a page in Experience Builder. Components appear in the Components panel.                                                                                                                                                                               |
| [`lightningCommunity__Page_Layout`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-community-page-layout.md)                                                                                     | Enables a component to be used in Experience Builder as a page layout for an LWR site. Components appear in the Content Layout window.                                                                                                                                                                 |
| [`lightningCommunity__Theme_Layout`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-community-theme-layout.md)                                                                                   | Enables a component to be used in Experience Builder as a theme layout for an LWR site. Components appear in Settings in the Theme area.                                                                                                                                                               |
| [`lightningSnapin__ChatHeader`](https://developer.salesforce.com/docs/atlas.en-us.snapins_web_dev.meta/snapins_web_dev/embedded_services_web_lightning_web_components.htm)  | Enables a custom chat header component to be selected from Embedded Service Chat Setup. A component that imports the `lightningsnapin/baseChatHeader` module must specify that `lightningSnapin__ChatHeader` target.                                                                                   |
| [`lightningSnapin__ChatMessage`](https://developer.salesforce.com/docs/atlas.en-us.snapins_web_dev.meta/snapins_web_dev/embedded_services_web_lightning_web_components.htm) | Enables a custom chat message component to be selected from Embedded Service Chat Setup. A component that imports the `lightningsnapin/baseChatMessage` module must specify the `lightningSnapin__ChatMessage` target.                                                                                 |
| [`lightningSnapin__MessagingPreChat`](https://developer.salesforce.com/docs/service/messaging-web/guide/create-custom-pre-chat-form.html)                                   | Enables a custom pre-chat component to be selected from Embedded Service Deployments in Setup.                                                                                                                                                                                                         |
| [`lightningSnapin__MessagingHeader`](https://developer.salesforce.com/docs/service/messaging-web/guide/customize-header.html)                                               | Enables a custom component to be selected from Embedded Service Deployments in Setup.                                                                                                                                                                                                                  |
| [`lightningSnapin__Minimized`](https://developer.salesforce.com/docs/atlas.en-us.snapins_web_dev.meta/snapins_web_dev/embedded_services_web_lightning_web_components.htm)   | Enables a custom minimized component to be selected from Embedded Service Chat Setup. A component that imports the `lightningsnapin/minimized` module must specify the `lightningSnapin__Minimized` target.                                                                                            |
| [`lightningSnapin__PreChat`](https://developer.salesforce.com/docs/atlas.en-us.snapins_web_dev.meta/snapins_web_dev/embedded_services_web_lightning_web_components.htm)     | Enables a custom prechat component to be selected from Embedded Service Chat Setup. A component that imports the `lightningsnapin/basePrechat` module must specify the `lightningSnapin__PreChat` target.                                                                                              |
| [`lightningStatic__Email`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-static-email.md)                                                                                                       | Enables a component to be used in and Email Content Builder.                                                                                                                                                                                                                                           |
| [`lightning__AgentforceInput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-agentforce-input.md)                                                                                               | Enables a component to be used in agent actions for accepting user input.                                                                                                                                                                                                                              |
| [`lightning__AgentforceOutput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-agentforce-output.md)                                                                                             | Enables a component to be used in agent actions for displaying output data.                                                                                                                                                                                                                            |
| [`lightning__AppPage`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-app-page.md)                                                                                                               | Enables a component to be used on an App page in Lightning App Builder. Enables a component to be used in a Lightning app, such as in a Console app.                                                                                                                                                   |
| [`lightning__ECSFSApp`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-ECSFSApp.md)                                                                                                              | Enables a component to be used in Field Service Mobile App Builder.                                                                                                                                                                                                                                    |
| [`lightning__EnablementProgram`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-enablement-program.md)                                                                                           | Enables a component to be used in Program Builder as a [custom exercise type](https://help.salesforce.com/s/articleView?id=sales.enablement_custom_items_overview.htm) for an Enablement program. Components appear in the Custom Items section of the Components list in the Program Builder palette. |
| [`lightning__FlowScreen`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-flow-screen.md)                                                                                                         | Enables a component to be used on flow screens in Flow Builder.                                                                                                                                                                                                                                        |
| [`lightning__GlobalAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-global-action.md)                                                                                                     | Enables a component to be used as a global quick action. To specify the type of global quick action, define a [`targetConfig` for `lightning_GlobalAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-global-action.md#targetconfig) with an `actionType` attribute.                                                   |
| [`lightning__HomePage`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-home-page.md)                                                                                                             | Enables a component to be used on a Home page in Lightning App Builder.                                                                                                                                                                                                                                |
| [`lightning__Inbox`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-inbox.md)                                                                                                                    | Enables a component to be used in Lightning App Builder to add to email application panes for the Outlook and Gmail integrations.                                                                                                                                                                      |
| [`lightning__PropertyEditor`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-property-editor.md)                                                                                                 | Enables a component to be used as a custom property editor in Experience Builder. Reference it in a `LightningTypeBundle` or in an Experience Builder component's `js-meta.xml` file.                                                                                                                  |
| [`lightning__RecordAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-record-action.md)                                                                                                     | Enables a component to be used as a quick action on a record page. To specify the type of quick action, define a [`targetConfig` for `lightning_RecordAction`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-record-action.md#targetconfig) with an `actionType` attribute.                                                |
| [`lightning__RecordPage`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-record-page.md)                                                                                                         | Enables a component to be used on a record page in Lightning App Builder.                                                                                                                                                                                                                              |
| [`lightning__ServiceDocument`](https://developer.salesforce.com/docs/atlas.en-us.field_service_dev.meta/field_service_dev/fsl_dev_mobile_document_builder.htm)              | Enables a component to be used in Document Builder.                                                                                                                                                                                                                                                    |
| [`lightning__Tab`](https://developer.salesforce.com/docs/platform/lwc/use/use-config-custom-tab.md)                                                                                                                         | Enables a component to be used in a custom tab in Lightning Experience or the Salesforce mobile app.                                                                                                                                                                                                   |
| [`lightning__UrlAddressable`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-url-addressable.md)                                                                                                 | Enables you to directly navigate to a component using a specific URL.                                                                                                                                                                                                                                  |
| [`lightning__UtilityBar`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-utility-bar.md)                                                                                                         | Enables a component to be used as a utility item on the utility bar in the App Manager.                                                                                                                                                                                                                |
| [`lightning_VoiceExtension`](https://developer.salesforce.com/docs/platform/lwc/guide/targets/targets-lightning-voice-extension.md)                                                                                                  | Enables a component to be used on a Voice Extension page in Lightning App Builder.                                                                                                                                                                                                                     |

## `targetConfigs`

The configuration metadata for a specified target. Supports the `targetConfig` subtag. For more information, see the documentation for each [`target`](#target).

**See Also**

- [Component Configuration File](https://developer.salesforce.com/docs/platform/lwc/create/create-components-meta-file.md)
- [Configure Your Component for Different Form Factors](https://developer.salesforce.com/docs/platform/lwc/use/use-config-form-factors.md)
- [_Salesforce Help_: Understanding Packages](https://help.salesforce.com/articleView?id=sharing_apps.htm)
- [_Salesforce Help_: Guidelines for Assembling Enablement Program](https://help.salesforce.com/s/articleView?id=sales.enablement_programs_overview.htm)