# developer Lightning Component Reference (lightning-base-components) - Full Documentation

<!-- document id=10b1f0cb94ca9a310d84bf2f546f714e68c3bee4b1ac1cc72be224a4bb8dee85 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/accordion/lightning-accordion.md -->


# Accordion

**`lightning-accordion`**

A collection of vertically stacked sections with multiple content areas.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="accordion" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-accordion` component shows vertically stacked sections of content that you can expand and collapse. Click a section's header to expand its content. Users can control how much content is visible without scrolling as much to see the content of a page.

To create an accordion section, nest a [`lightning-accordion-section`](/docs/platform/lightning-component-reference/guide/lightning-accordion-section.html) component within `lightning-accordion`. Each `lightning-accordion-section` can contain HTML markup or Lightning components.

By default, you can open only one section at a time. Close a section by opening another section. You can configure the accordion to allow multiple sections to be open, and then click the section headers to open and close the section.

**note:** You can specify one or more active sections. Active sections are expanded when the component loads. This documentation uses the terms "active", "expanded", and "open" interchangeably.

`lightning-accordion` doesn't support lazy loading. The content you load in inactive sections also impact your page load time.

## Design

`lightning-accordion` implements the accordion blueprint in the Salesforce Lightning Design System (SLDS). The accordion adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Accordion](https://v1.lightningdesignsystem.com/components/accordion/)                                                               | [Accordion](https://www.lightningdesignsystem.com/components/accordion/)                                        |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Initialize the Accordion with an Active Section

The first accordion section is expanded by default. To change the default, provide a section name by using the `active-section-name` attribute. The section name is case-sensitive.

This example creates a basic accordion with three sections, where section B is expanded by default. Only one accordion section is expanded at a time.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-accordion active-section-name="B">
        <lightning-accordion-section name="A" label="Accordion Title A"
            >This is the content area for section A</lightning-accordion-section
        >
        <lightning-accordion-section name="B" label="Accordion Title B"
            >This is the content area for section B</lightning-accordion-section
        >
        <lightning-accordion-section name="C" label="Accordion Title C"
            >This is the content area for section C</lightning-accordion-section
        >
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

If two or more sections use the same name and that name is also specified as the `active-section-name`, the first section with that name is expanded by default.

**tip:** To view interactive examples, see the [Examples tab](/docs/platform/lightning-component-reference/guide/lightning-accordion.html?type=Example).

## Initialize the Accordion with Multiple Active Sections

To specify multiple expanded sections, include `allow-multiple-sections-open` in your markup and pass in an array of accordion section names to `active-section-name`.
If you don't pass in a section name, all sections are closed by default.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-accordion
        allow-multiple-sections-open
        active-section-name={activeSections}
    >
        <lightning-accordion-section name="A" label="Accordion Title A">
            <p>This is the content area for section A.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="B" label="Accordion Title B">
            <p>This is the content area for section B.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="C" label="Accordion Title C">
            <p>This is the content area for section C.</p>
        </lightning-accordion-section>
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

In your JavaScript code, define the sections you want to expand.

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

export default class LightningExampleAccordionMultiple extends LightningElement {
  activeSections = ["A", "C"];
}
```

## Handle the Section Toggle Event

When the open sections change, use the `onsectiontoggle` handler to find out which sections are active.

This example shows the name of the active section.

<!-- prettier-ignore-start -->
```html
<template>
    <p>{activeSectionsMessage}</p>

    <lightning-accordion
        allow-multiple-sections-open
        onsectiontoggle={handleSectionToggle}
        active-section-name="A"
    >
        <lightning-accordion-section name="A" label="Accordion Title A">
            <p>This is the content area for section A.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="B" label="Accordion Title B">
            <p>This is the content area for section B.</p>
        </lightning-accordion-section>

        <lightning-accordion-section name="C" label="Accordion Title C">
            <p>This is the content area for section C.</p>
        </lightning-accordion-section>
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

Use the `detail.openSections` property to return the active section names.

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

export default class DemoAccordionMultiple extends LightningElement {
  activeSectionsMessage = "";

  handleSectionToggle(event) {
    const openSections = event.detail.openSections;

    if (openSections.length === 0) {
      this.activeSectionsMessage = "All sections are closed";
    } else {
      this.activeSectionsMessage = "Open sections: " + openSections.join(", ");
    }
  }
}
```

The `openSections` event parameter returns a string or an array of strings depending on the `allow-multiple-sections-open` attribute.

- If you include the `allow-multiple-sections-open` attribute, `openSections` returns an array. For example: `['A']` for an open accordion section and `['A', 'B']` for multiple open accordion sections. An accordion section without a `name` value or a `name` value that contains an empty string is excluded from the `openSections` array. If only this accordion section is opened, `openSections` returns an empty array and `openSections.length` returns 0. If none of the accordion sections include a `name` value, `openSections` returns an empty array and `openSections.length` returns 0 when any number of accordion sections are opened.
- If you don't include the `allow-multiple-sections-open` attribute, `openSections` returns a string. For example: `A` for an open accordion section. In this case, only one section can be open at a time. If an accordion section without a `name` attribute or a `name` value that contains an empty string is opened, `openSections` returns undefined.

## Expand Sections Programmatically

To expand a section, pass in the section name by using `active-section-name`.

This example expands section B when the **Expand Section B** button is pressed.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button label="Expand Section B" onclick={handleClick}>
    </lightning-button>
    <lightning-accordion
        active-section-name={section}
        onsectiontoggle={handleSectionToggle}
    >
        <lightning-accordion-section name="A" label="A"
            >Content A</lightning-accordion-section
        >
        <lightning-accordion-section name="B" label="B"
            >Content B</lightning-accordion-section
        >
        <lightning-accordion-section name="C" label="C"
            >Content C</lightning-accordion-section
        >
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

The `onclick` handler on the button sets the active section name, which opens the section programmatically.

Set the value for the open section by using the `openSections` property in the `onsectiontoggle` handler.

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

export default class App extends LightningElement {
  section = "";

  handleClick(event) {
    this.section = "B";
  }

  handleSectionToggle(event) {
    this.section = event.detail.openSections;
  }
}
```

To expand multiple sections programmatically, include `allow-multiple-sections-open` in your markup and pass in an array of section names instead.

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

export default class App extends LightningElement {
  section = [];

  handleClick(event) {
    this.section = ["B", "C"];
  }

  handleSectionToggle(event) {
    this.section = event.detail.openSections;
  }
}
```

## Conditionally Show an Accordion Section

To toggle the visibility of an accordion section, use the [`if:true` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-conditional.html).

<!-- prettier-ignore -->
```html
<template>
  <lightning-button onclick={handleToggleSection} label="Toggle Section B"></lightning-button>

  <lightning-accordion class="example-accordion" active-section-name="A">
    <lightning-accordion-section name="A" label="Accordion Title A">
      <p>This is the content area for section A.</p>
    </lightning-accordion-section>

    <template if:true={isDVisible}>
      <lightning-accordion-section name="B" label="Accordion Title B">
        <p>This is the content area for section B.</p>
      </lightning-accordion-section>
    </template>
  </lightning-accordion>
</template>
```

## Component Styling

`lightning-accordion` adapts to [SLDS 1](https://v1.lightningdesignsystem.com/components/accordion/) and [SLDS 2](https://www.lightningdesignsystem.com/components/accordion/) styling.

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a border and gray background to the accordion content area by using SLDS classes.

<!-- prettier-ignore-start -->
```html
<lightning-accordion active-section-name="A">
    <lightning-accordion-section name="A" label="Accordion Title A">
        <div class="slds-box slds-theme_shade">
            <p>This is the content area for section A.</p>
        </div>
    </lightning-accordion-section>
    <!-- More accordion sections here -->
</lightning-accordion>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

You can't initialize an accordion with multiple sections by using only markup. Pass the array of section names using JavaScript, as described in [Initialize the Accordion with Multiple Active Sections](#initialize-the-accordion-with-multiple-active-sections).

Accordion sections aren’t lazy loaded. Content in sections that are collapsed initially are available on load in the DOM.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Accessibility

`lightning-accordion` implements the [SLDS accordion blueprint](https://v1.lightningdesignsystem.com/components/accordion), which follows the [WAI-ARIA Authoring Practices for the accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/). In addition to the keyboard interaction guidelines on the WAI-ARIA site, you can use the Left Arrow and Right Arrow key to move focus from an accordion header. The Home and End keys aren’t used for keyboard interaction on `lightning-accordion`.

`lightning-accordion` observes these roles, states, and properties.

- `lightning-accordion` has `role="list"`.
- When you set `active-section-name` to expand specific sections, the button on those section headers uses `aria-expanded` set to `true`.
- An accordion section sets `aria-hidden` to `true` if the section is collapsed, which hides the content from assistive technologies.

## Custom Events

**`sectiontoggle`**

The event that's fired when an accordion loads with at least one active section or when a section is toggled.

The `sectiontoggle` event returns this parameter.

| Parameter    | Type   | Description                                                                               |
| ------------ | ------ | ----------------------------------------------------------------------------------------- |
| openSections | object | The name of the active section. Returns an array of strings for the active section names. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event doesn’t bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event doesn’t propagate outside the template in which it was dispatched.                             |


:::::

:::::tab
::component-specification{component="accordion" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=13f8dcc88600e4dc93045d65c0db05dc49f8da3a58b1712c72a3abc95a8e343a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/accordionSection/lightning-accordion-section.md -->


# Accordion Section

**`lightning-accordion-section`**

A single section that is nested in an accordion component.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="accordionSection" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-accordion-section` component defines the content of an accordion section inside a [`lightning-accordion`](/docs/platform/lightning-component-reference/guide/lightning-accordion.html) component.
Each section can contain HTML markup or Lightning components.

This example creates a basic accordion with three sections, where section B is
expanded by specifying it with the `active-section-name` attribute in `lightning-accordion`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-accordion active-section-name="B">
        <lightning-accordion-section name="A" label="Accordion Title A"
            >This is the content area for section A</lightning-accordion-section
        >
        <lightning-accordion-section name="B" label="Accordion Title B"
            >This is the content area for section B</lightning-accordion-section
        >
        <lightning-accordion-section name="C" label="Accordion Title C"
            >This is the content area for section C</lightning-accordion-section
        >
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

Use the `label` attribute to provide optional header text for an accordion section. When the header text is too long to display in the viewport, the text is truncated and displayed with an ellipsis on desktop screens. Hover with the mouse to see the full text.

On mobile devices, long header text wraps to multiple lines because hover text isn't available.

To expand or collapse a section, click the toggle button or header text.

## Design

Use `lightning-accordion-section` within `lightning-accordion`, which implements the accordion blueprint in the Salesforce Lightning Design System (SLDS). The accordion adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Accordion](https://v1.lightningdesignsystem.com/components/accordion/)                                                               | [Accordion](https://www.lightningdesignsystem.com/components/accordion/)                                        |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Add an Action Menu

This example creates the same basic accordion with an added `lightning-button-menu` on
the first section. The button menu is assigned to the `actions` slot which makes it display on the section header.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-accordion active-section-name="B">
        <lightning-accordion-section name="A" label="Accordion Title A">
            <lightning-button-menu
                slot="actions"
                alternative-text="Show menu"
                menu-alignment="right"
            >
                <lightning-menu-item
                    value="New"
                    label="Menu Item One"
                ></lightning-menu-item>
                <lightning-menu-item
                    value="Edit"
                    label="Menu Item Two"
                ></lightning-menu-item>
            </lightning-button-menu>
            <p>This is the content area for section A.</p>
        </lightning-accordion-section>
        <lightning-accordion-section name="B" label="Accordion Title B"
            >This is the content area for section B</lightning-accordion-section
        >
        <lightning-accordion-section name="C" label="Accordion Title C"
            >This is the content area for section C</lightning-accordion-section
        >
    </lightning-accordion>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

For more information, see [`lightning-accordion`](/docs/platform/lightning-component-reference/guide/lightning-accordion.html).

## Usage Considerations

If two or more sections use the same name and that name is also specified as
the `active-section-name`, the first section using that name is expanded by default.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Accessibility

`lightning-accordion-section` renders the toggle button and title in a `<button>` element. When a section is expanded, the button
renders with `aria-expanded="true"`. When a section is collapsed, the button renders with `aria-expanded="false"`.

To expand or collapse a section using the keyboard, press the Tab key to set focus on the toggle button or header text and press Enter.

To set the `aria-level` value on the section header, pass in a number from 1 to 6 on the `heading-level` attribute.

`lightning-accordion-section` observes these roles, states, and properties.

- `lightning-accordion-section` has `role="listitem"`.
- The button on a section header displays the label you provide to the `label` attribute.
- The button on a section header assigns `aria-controls` to the ID of the element that contains the accordion section content. This attribute sets a relationship between the button and the element with the accordion section content. When the button is clicked, the element with the content specifies either `aria-hidden="true"` or `aria-hidden="false"` depending on whether the content is visible or not.


:::::

:::::tab
::component-specification{component="accordionSection" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=e1757b43d0ca353d5d1e5821bc4001accbfc38aab3b6bb93250b70c848281f1e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/actionOverride/aura-action-override.md -->

# Action Override

**`lightning:actionOverride`**

Enables a component to be used as an override for a standard action. You can override the View, New, Edit, and Tab standard actions on most standard and all custom components.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This interface is a **marker interface**. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

The `lightning:actionOverride` doesn’t add or require any attributes on components that implement it. Components that implement this interface don’t automatically override any action. You need to manually override relevant actions in Setup.

Only components that implement this interface appear in the _Lightning Component Bundle_ menu of an object action Override Properties panel.

## Example

This example shows the markup required to add the `lightning:actionOverride` interface to a Lightning component.

```html
<aura:component implements="lightning:actionOverride,force:hasRecordId,force:hasSObjectName">
  <lightning:card title="Expense Details">
    <aura:set attribute="actions">
      <lightning:button label="Edit" onclick="{!c.handleEdit}" />
    </aura:set>
    <p class="slds-p-horizontal_small">(expense details go here)</p>
  </lightning:card>
</aura:component>
```

In Lightning Experience, the standard Tab and View actions display as a page, while the standard New and Edit actions display in an overlay panel. When used as action overrides, Aura components that implement the `lightning:actionOverride` interface replace the standard behavior completely. A component used as an action override always displays as a page in Lightning Experience and displays in a popup window in Experience Cloud sites. Your component displays without controls, except for the main Lightning Experience navigation bar. Your component is expected to provide a complete user interface for the action, including navigation or actions beyond the navigation bar.

## See Also

[Override Standard Actions with Aura Components ](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_lex_s1_action_overrides.htm)


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=eaffc9ec5014f95b804da28a2a5922a70256a49b94b785abb5deb89e6ed200fc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/afterScriptsLoaded/ltng-after-scripts-loaded.md -->

# After Scripts Loaded

**`ltng:afterScriptsLoaded`**

Fired when [`ltng:require`](/docs/platform/lightning-component-reference/guide/ltng-require.html) has loaded all scripts listed in `ltng:require.scripts`.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

For more information, see the [`ltng:require` documentation](/docs/platform/lightning-component-reference/guide/ltng-require.html).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=28432ca1e20fb9928e8efaf59a47577fb6731919eca8b0662de8327cca1b2dcc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/accApi/lightning-acc-api.md -->

# Agentforce Conversation Client API

**`lightning/accApi`**

Manages the state of the Agentforce side panel. The `lightning/accApi` module requires API version 59.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/accApi` module includes methods to work with the Agentforce panel in Lightning Experience.

To use the Agentforce Conversation Client API in your component, import the module in your component's JavaScript file.

```js
import {
  open,
  close,
  execute
  ...
} from "lightning/accApi";
```

For this module's specification and examples, see the [Agentforce Conversation Client Developer Guide](https://developer.salesforce.com/docs/platform/accsdk/guide/).

:::::

:::::tab
::component-specification{component="accApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0c535dd7443539fd8713380ab126d761b44c7e67fceab061dbc0a3c19bda5743 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/alert/lightning-alert.md -->


# Alert

**`lightning/alert`**

Create an alert modal within your component that communicates a state that affects the entire system, not just a feature or page.

**For Use In**

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="alert" model="lwc" namespace="lightning"}


:::::

:::::tab

Use the `lightning/alert` module to create and open an alert modal from your component. Use `LightningAlert` on your components to communicate a state that affects the entire system, not just a feature or page.

Use `LightningAlert.open()` instead of the native `window.alert()` for a more consistent user experience. They have similar functions, but `LightningAlert.open()` works in cross-origin iframes, where the `.alert()` method is no longer supported in Chrome and Safari. Unlike `window.alert()`, `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 has closed.

Import `LightningAlert` from the `lightning/alert` module in the component that you use to open the alert modal, and call `LightningAlert.open()` with your attributes.

This example creates an alert modal with an error message and an **OK** button. The `.open()` function returns a promise that resolves when you click **OK**.

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

```javascript
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 has been closed
  }
}
```

## Design

This module implements the prompt blueprint in the Salesforce Lightning Design System (SLDS). The prompt adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                         | SLDS 2                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Prompt](https://v1.lightningdesignsystem.com/components/prompt/)                              | [Prompt](https://www.lightningdesignsystem.com/components/prompt/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of attributes to customize the alert modal style.

`LightningAlert` supports these attributes:

- `message`: Message text that displays in the alert.
- `label`: Header text, also used as the `aria-label`. Default string is `Alert`.
- `variant`: Two values, `header` and `headerless`. Default value is `header`.
- `theme`: Color theme for the header. The `theme` attribute supports these [options](https://v1.lightningdesignsystem.com/utilities/themes/#site-main-content) from SLDS:
  - `default`: white
  - `shade`: gray
  - `inverse`: dark blue
  - `alt-inverse`: darker blue
  - `success`: green
  - `info`: gray-ish blue
  - `warning`: yellow
  - `error`: red
  - `offline`: ​black

If an invalid value is provided, `LightningAlert` uses the `default` theme. `LightningAlert` ignores the `style` attribute.

**tip:** To view interactive examples, see the [Examples tab](/docs/platform/lightning-component-reference/guide/lightning-alert.html?type=Example).

## Test Your Alert Component

Test code that use `LightningAlert` by mocking the `LightningAlert.open()` method.

This example uses a button to open an alert dialog with text that changes when the alert opens.

<!-- prettier-ignore-start -->
```html
<button data-button onclick={handleClick}>Open Alert</button>
<template if:true={alertViewed}>
    <div data-text>Content Viewed</div>
</template>
<template if:false={alertViewed}>
    <div data-text>Click to View Content</div>
</template>
```
<!-- prettier-ignore-end -->

```javascript
import LightningAlert from 'lightning/alert';
jest.mock('lightning/alert');
​
test(() => {
    // Create and appendChild(element)
​
    const buttonEle = element.shadowRoot.querySelector('[data-button]');
    const textEle = element.shadowRoot.querySelector('[data-text]');
​
    // Mock .open()
    // No value passed since LightningAlert doesn't have a return value
    LightningAlert.open = jest.fn().mockResolvedValue();
    // Initial value
    expect(textEle.textContent).toBe('Click to View Content');
    // Click modal open button
    buttonEle.click();
​
    // Click handler render cycle
    await Promise.resolve();
    // Render cycle triggered by tracked value {result}
    await Promise.resolve();
​
    // Verify alertViewed has updated in template
    expect(textEle.textContent).toBe('Content Viewed');
    // Open triggered once
    expect(LightningAlert.open.mock.calls).toHaveLength(1);
})
```

## Accessibility

The `lightning/alert` module implements the SLDS [prompt blueprint](https://v1.lightningdesignsystem.com/components/prompt/#site-main-content), which follows the [WAI-ARIA Authoring Practices for the alert and message dialogs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/). Like modals, the alert dialog is a focus trap, but it specifies `role="alertdialog"` to indicate its severity.

Use the keyboard interaction guidelines on the SLDS site. When the dialog opens, focus moves to the header text on the dialog, which has `tabindex="-1"`.

To close the dialog, you can press the Esc key. Alternatively, you can tab to the OK button and press Enter.

`lightning/alert` observes these roles, states, and properties.

- The section element has `role="alertdialog"` with an `aria-description`, which uses the value you provide for the `message` attribute.
- The `aria-labelledby` value on the section is set to the ID of the header text. Provide a header text by using the `label` attribute.


:::::

:::::tab
::component-specification{component="alert" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=81c4fa3c8dfc5141288e1d3a7cc8bb44eb41d5461d5a9c9306f13de276f005e2 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/allowGuestAccess/ltng-allow-guest-access.md -->

# Allow Guest Access

**`ltng:allowGuestAccess`**

Allows guest user access on an application.

**For Use In**

Lightning Out (Beta)

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add the `ltng:allowGuestAccess` interface to your Lightning Out dependency app to make it available to users without requiring them to authenticate with Salesforce. This interface lets you build your app with Lightning components, and deploy it anywhere and to anyone.

A Lightning Out dependency app with the `ltng:allowGuestAccess` interface can be used with Lightning Components for Visualforce and with Lightning Out.

- Using Lightning Components for Visualforce, you can add your Lightning 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, you can deploy your Lightning app anywhere Lightning Out is supported—which is almost anywhere!

The `ltng:allowGuestAccess` interface is only usable in orgs that have Digital Experiences enabled, and your Lightning Out app is associated with all Experience Cloud site endpoints that you’ve defined in your org. Experience Cloud sites include sites built using Experience Builder and Visualforce.

When you add the `ltng:allowGuestAccess` interface to a Lightning app, the app is open to guest users and is available through _every_ Experience Builder 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.

Be extremely 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 Experience Cloud site’s guest user profile. Lightning components don’t automatically enforce CRUD and FLS when you reference objects or retrieve the objects from an Apex controller. This means that the framework continues to display records and fields for which users don’t have CRUD access and FLS visibility. You must manually enforce CRUD and FLS in your Apex controllers. A mistake in code used in an app enabled for guest access can open your org’s data to the world.

## Usage

First, add the `ltng:allowGuestAccess` interface to your Lightning Out dependency app.

For example:

```xml
<aura:application access="GLOBAL" extends="ltng:outApp"
    implements="ltng:allowGuestAccess">
    <aura:dependency resource="c:storeLocatorMain"/>
</aura:application>
```

You can only add the `ltng:allowGuestAccess` interface to Lightning apps, not to individual components.

Next, add the Lightning Out JavaScript library to your page.

- With Lightning Components for Visualforce, simply add the `<apex:includeLightning />` tag anywhere on your page.
- With Lightning Out, add a `<script>` tag that references the library directly, using a Experience Cloud site endpoint URL. For example:

```xml
<script src="https://yourExperienceDomain/experienceURL/lightning/lightning.out.js"></script>
```

A sample URL for the JavaScript library is `https://universalcontainers.force.com/ourstores/lightning/lightning.out.js`

Finally, add the JavaScript code to load and activate your Lightning app. This code is standard Lightning Out, with the important addition that you must use one of your org’s Experience Cloud site URLs for the endpoint. The endpoint URL takes the form `https://yourExperienceDomain/experienceURL/`. The relevant line is emphasized in the following sample.

```html
<script>
  $Lightning.use(
    "c:locatorApp", // name of the Lightning 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/" // Experience Cloud site endpoint
  );
</script>
```

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/lightning_out.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=ec43268ef53f4a02fe3127495b33aa4821ceaaa3750b1ca255a7e15c8262fc50 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightningcommunity/allowInRelaxedCSP/lightningcommunity-allow-in-relaxed-csp.md -->

# Allow In Relaxed CSP

**`lightningcommunity:allowInRelaxedCSP​`**

Enables a component to be used in a Relaxed CSP Experience Builder site.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add the `lightningcommunity:allowInRelaxedCSP`​ interface to enable this component to run in an Aura-based Experience Builder site that has Lightning Locker disabled. If this interface is not implemented, and Lightning Locker is disabled, your component won't be rendered in runtime, and won't be available in design time.

This example shows the markup required to add the `lightningcommunity:allowInRelaxedCSP`​ interface.

```xml
<aura:component implements="lightningcommunity:allowInRelaxedCSP">
    <!-- Your component markup here -->
</aura:component>
```

For more information, see [Enable Third-Party Components to Run When Lightning Locker Is Off](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_security_locker_off_components.htm) in the _Experience Cloud Developer Guide_.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=12a3744bd414dde64d421a378ab62bb483652c0e8a82fa53d795529e01bb49a3 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/analyticsInteraction/forceCommunity-analytics-interaction.md -->

# Analytics Interaction

**`forceCommunity:analyticsInteraction`**

Tracks events that are triggered by custom components in Aura-based Experience Builder sites and sends the data to Google Analytics.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This example creates a custom button and includes the `forceCommunity:analyticsInteraction` event in the button's client-side controller. Clicking the button sends event data to Google Analytics.

```javascript
handleClick : function(cmp, event, helper) {
    var analyticsInteraction = $A.get("e.forceCommunity:analyticsInteraction");
    analyticsInteraction.setParams({
        hitType : 'event',
        eventCategory : 'Button',
        eventAction : 'click',
        eventLabel : 'Winter Campaign Button',
        eventValue: 200
    });
    analyticsInteraction.fire();
}
```

This event is supported in Aura-based Experience Builder sites only. To enable event tracking, add your Google Analytics tracking ID in Settings | Advanced in Experience Builder and publish the site. Google Analytics isn’t supported in sandbox environments.


:::::

:::::tab
## Attributes

| Name             | Description                                                                                              | Type    | Default | Required                                     |
| ---------------- | -------------------------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
| `eventAction`    | The type of action. Required for 'event' hitType.                                                        | string  |         |                                              |
| `eventCategory`  | The type or category of item that was interacted with. Required for 'event' hitType.                     | string  |         |                                              |
| `eventLabel`     | A label for providing additional event information.                                                      | string  |         |                                              |
| `eventValue`     | A positive numeric value associated with the event.                                                      | integer |         |                                              |
| `exDescription`  | A description of the exception.                                                                          | string  |         |                                              |
| `exFatal`        | True if the exception was fatal.                                                                         | boolean |         |                                              |
| `hitType`        | The type of hit. Supported types: 'event', 'social', 'exception', 'timing'.                              | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `socialAction`   | The type of action that happens. Required for 'social' hitType.                                          | string  |         |                                              |
| `socialNetwork`  | The network on which the action occurs. Required for 'social' hitType.                                   | string  |         |                                              |
| `socialTarget`   | Specifies the target of a social interaction. Required for 'social' hitType.                             | string  |         |                                              |
| `timingCategory` | A string for categorizing all user timing variables into logical groups. Required for 'timing' hitType.  | string  |         |                                              |
| `timingLabel`    | A string that can be used to add flexibility in visualizing user timings in the reports.                 | string  |         |                                              |
| `timingValue`    | The number of milliseconds in elapsed time to report to Google Analytics. Required for 'timing' hitType. | integer |         |                                              |
| `timingVar`      | A string to identify the variable being recorded. Required for 'timing' hitType.                         | string  |         |                                              |

:::::

::::::

<!-- document id=0834d308c2f0f937eb33aa2c92e66a35ab6fdd04fc9bc7079cb40985a7170b55 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/analyticsInteractionGtag/forceCommunity-analytics-interaction-gtag.md -->

# Analytics Interaction Gtag

**`forceCommunity:analyticsInteractionGtag`**

Tracks events that are triggered by custom components in Aura-based Experience Builder sites and sends the data to Google Analytics.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This example creates a custom button and includes the `forceCommunity:analyticsInteractionGtag` event in the button's client-side controller. Clicking the button sends event data to Google Analytics.

```javascript
handleClick : function(cmp, event, helper) {
            var analyticsInteraction = $A.get("e.forceCommunity:analyticsInteractionGtag");
            analyticsInteraction.setParams({
                event : 'click',
                event_category : 'Button',
                event_label : 'Winter Campaign Button',
                value: 200
            });
            analyticsInteraction.fire();
        }
```

This example sends a user timing event to Google Analytics indicating that it took 3549 milliseconds for the current web page to load all external JavaScript dependencies. (Credit to Google Analytics documentation.)

```javascript
handleClick : function(cmp, event, helper) {
            if (window.performance) {
              // Gets the number of milliseconds since page load
              // (and rounds the result since the value must be an integer).
              var timeSincePageLoad = Math.round(performance.now());

              var analyticsInteraction = $A.get("e.forceCommunity:analyticsInteractionGtag");
              analyticsInteraction.setParams({
                  event : 'timing_complete',
                  name : 'load',
                  value : 3549,
                  event_category: 'JS Dependencies',
                  event_label: 'Google CDN'
              });
              analyticsInteraction.fire();
            }
        }
```

This example sends an exception event to Google Analytics if the divisor y is zero. (Credit to Google Analytics documentation.)

```
handleClick : function(cmp, event, helper) {
            var x = component.get("v.x");
            var y = component.get("v.y");

            try {
                var r = divide(x, y);
            } catch(err) {
                var analyticsInteraction = $A.get("e.forceCommunity:analyticsInteractionGtag");
                analyticsInteraction.setParams({
                    event : 'exception',
                    description : err,
                    fatal : false
                });
                analyticsInteraction.fire();
            }
        }
```

This event is supported in Aura-based Experience Builder sites only. To enable event tracking, add your Google Analytics tracking ID in Settings | Advanced in Experience Builder and publish the site.


:::::

:::::tab
## Attributes

| Name             | Description                                                                                                                                                                        | Type    | Default | Required                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
| `description`    | A description of the error.                                                                                                                                                        | string  |         |                                              |
| `event`          | The string that will appear as the event action in Google Analytics Event reports.                                                                                                 | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `event_category` | An event category is a name that you supply as a way to group objects that you want to analyze. Also, a string for categorizing all user timing variables into logical groups.     | string  |         |                                              |
| `event_label`    | Provides additional information for events that you want to analyze. Also, a string that can be used to add flexibility in visualizing user timings in the reports.                | string  |         |                                              |
| `fatal`          | True if the error was fatal.                                                                                                                                                       | boolean |         |                                              |
| `name`           | A string to identify the variable being recorded. Required for 'timing_complete' event.                                                                                            | string  |         |                                              |
| `value`          | An integer used to assign a numerical value to a page object. Also, he number of milliseconds in elapsed time to report to Google Analytics. Required for 'timing_complete' event. | integer |         |                                              |

:::::

::::::

<!-- document id=002bb0e03598ba75471301906bcbb92667c571813b983e573fd885e2a226699f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/api.md -->

# API Modules

Access Salesforce data, platform features, and specialized APIs with wire adapters and functions.

## Record Data

Access record data, object metadata, and list information using these UI API modules.

- [GraphQL API](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-module.html)
- [UI Apps API](/docs/platform/lightning-component-reference/guide/lightning-ui-apps-api.html)
- [UI Layout API](/docs/platform/lightning-component-reference/guide/lightning-ui-layout-api.html)
- [UI Lists API](/docs/platform/lightning-component-reference/guide/lightning-ui-lists-api.html)
- [UI Record API](/docs/platform/lightning-component-reference/guide/lightning-ui-record-api.html)
- [UI Object Info API](/docs/platform/lightning-component-reference/guide/lightning-ui-object-info-api.html)
- [UI Related List API](/docs/platform/lightning-component-reference/guide/lightning-ui-related-list-api.html)

## Commerce API

Manage carts, register guest buyers, and retrieve pricing and product details for a webstore using these Commerce API modules.

- [Commerce Cart API](/docs/platform/lightning-component-reference/guide/lightning-commerce-cart-api.html)
- [Commerce Register Guest Buyer API](/docs/platform/lightning-component-reference/guide/lightning-commerce-register-guest-buyer-api.html)
- [Commerce Repricing API](/docs/platform/lightning-component-reference/guide/lightning-commerce-repricing-api.html)

## Lightning Console API

Build enhanced console apps with workspace, utility bar, and messaging features using these Console API modules.

- [Conversation Toolkit API](/docs/platform/lightning-component-reference/guide/lightning-conversation-toolkit-api.html)
- [Navigation Item API](/docs/platform/lightning-component-reference/guide/lightning-platform-navigation-item-api.html)
- [Platform Utility Bar API](/docs/platform/lightning-component-reference/guide/lightning-platform-utility-bar-api.html)
- [Platform Workspace API](/docs/platform/lightning-component-reference/guide/lightning-platform-workspace-api.html)

## More Salesforce APIs

Integrate Agentforce, CRM Analytics, CMS content, and other data sources using these API modules.

- [Agentforce Conversation Client API](/docs/platform/lightning-component-reference/guide/lightning-acc-api.html)
- [Analytics Wave API](/docs/platform/lightning-component-reference/guide/lightning-analytics-wave-api.html)
- [CMS Delivery API](/docs/platform/lightning-component-reference/guide/lightning-cms-delivery-api.html)
- [CMS Editor API](/docs/platform/lightning-component-reference/guide/lightning-cms-editor-api.html)
- [Emp API](/docs/platform/lightning-component-reference/guide/lightning-emp-api.html)
- [Industries Education Public API](/docs/platform/lightning-component-reference/guide/lightning-industries-education-public-api.html)
- [Service Cloud Voice Toolkit API](/docs/platform/lightning-component-reference/guide/lightning-service-cloud-voice-toolkit-api.html)
- [Service Knowledge API](/docs/platform/lightning-component-reference/guide/lightning-service-knowledge-api.html)
- [UI Learning Platform API](/docs/platform/lightning-component-reference/guide/lightning-ui-learning-platform-api.html)

<!-- document id=fb9340d3fece019d332455edc04e006df0486079f14f773afc8d7c12a4ad2782 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/appHomeTemplate/aura-app-home-template.md -->

# App Home Template

**`lightning:appHomeTemplate`**

Indicates the component can be used as a flexipage page template for the APP_PAGE page type.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:appHomeTemplate` interface to enable your component to be used as a custom Lightning page template for pages of type App Page. This interface has no effect except when used within Lightning Experience and the Salesforce app.

Components that implement this interface appear in the Custom Templates section of the Lightning App Builder new page wizard for app pages.

Each template component should implement only one template interface. Template components shouldn’t implement any other type of interface, such as `flexipage:availableForAllPageTypes` or `force:hasRecordId`. A template component can’t multi-task as a regular Lightning component. It’s either a template, or it’s not.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=b7604639308d5081ac373fa3f8e3a29fc1713e8f5dc8fd1f78e4b1f8f351fcdd url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/appHostable/force-app-hostable.md -->

# App Hostable

**`force:appHostable`**

Enables an Aura component to be used as a custom tab.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add the `force:appHostable` interface to an Aura component to allow it to be used as a custom tab in Lightning Experience or the Salesforce mobile app. Components that implement this interface can be used to create tabs in both Lightning Experience and the Salesforce mobile app.

This interface is a marker interface. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

## Example

```xml
<!--simpleTab.cmp-->
<aura:component implements="force:appHostable">

    <!-- Simple tab content -->
    <h1>My Tab</h1>

</aura:component>
```

The `force:appHostable` interface makes the component available for use as a custom tab.

For more information, see [Add Lightning Components as Custom Tabs in a Lightning App](https://help.salesforce.com/s/articleView?id=platform.aura_add_cmp_lex.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=d8387b10814ef0dddb51d15a66cb27d58dc1f6fff2ef35651af8acf31a575c39 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/applicationEvent/aura-application-event.md -->

# Application Event

**`aura:applicationEvent`**

The root event of the event hierarchy for all events of `type="APPLICATION"`.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

An application event is a form of communication between Aura components anywhere in the application, even if they aren't in the same parent-child containment hierarchy. It follows a traditional publish-subscribe model.

For more information, see [Application Events](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/events_application.htm) in the _Lightning Aura Components Developer Guide_.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=49c7ba4ce1a016414f4b3983e4eb328ee8112285de835f16a8d37f04b0501d5d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/assetLoaded/wave-asset-loaded.md -->

# Asset Loaded

**`wave:assetLoaded`**

Indicates that an Analytics asset has finished loading.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:assetLoaded` event is sent when an Analytics asset has finished loading.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name   | Description                                         | Type   | Default | Required                                     |
| ------ | --------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `id`   | The identifier of the Analytics asset which loaded. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type` | The type of the Analytics asset which loaded.       | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=4e89c5a0e2d8cc0f119b40f57f520d92f36ad1f8d2ce40e0b71615491611bdca url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura-components.md -->

# Aura Components

**note:** Use Lightning Web Components (LWC) where possible for new development. For more information, see [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-introduction.html).

Salesforce provides prebuilt components that use the Aura programming model.

Components in the [`lightning`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-lightning.md) namespace are known as Lightning base components, which implement Salesforce Lightning Design System (SLDS) component designs and blueprints. Lightning base components include the Aura components listed in this section and Lightning web components listed in the [Components](https://developer.salesforce.com/docs/platform/components.md) section.

Aura components are available in these namespaces.

- [`lightning`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-lightning.md)
- [`aura`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/aura-namespace.md)
- [`force`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/force/aura-force.md)
- [`forceChatter`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/forceChatter/aura-forceChatter-namespace.md)
- [`forceCommunity`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/forceCommunity/aura-forceCommunity-namespace.md)
- [`lightningcommunity`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightningcommunity/aura-lightningcommunity-namespace.md)
- [`ltng`](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/ltng/aura-ltng-namespace.md)
- [`ui` (deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-ui.md)

## See Also

[Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/)

<!-- document id=f7ee54e2770d7f3fc1e1c7fe968a8cd258dc9bbab6130f1a2d5ba3cae3604b71 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/events.md -->

# Aura Events

**note:** Use Lightning Web Components (LWC) where possible for new development. For more information, see [Migrate Events](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-events.html).

Aura events enable communication between components. Handle these events in your custom component to respond to changes in Lightning Experience, Salesforce mobile app, and Aura-based Experience Builder sites.

## Aura Framework Events

Customize component behavior using these events.

- [Application Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/applicationEvent/aura-application-event.md)
- [Component Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/componentEvent/aura-component-event.md)
- [Done Rendering](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/doneRendering/aura-done-rendering.md) (Deprecated)
- [Done Waiting](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/doneWaiting/aura-done-waiting.md) (Deprecated)
- [Location Change](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/locationChange/aura-location-change.md)
- [Method Call](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/methodCall/aura-method-call.md)
- [No Access](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/noAccess/aura-no-access.md)
- [System Error](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/systemError/aura-system-error.md)
- [Value Change](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/valueChange/aura-value-change.md)
- [Value Destroy](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/valueDestroy/aura-value-destroy.md)
- [Value Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/valueEvent/aura-value-event.md)
- [Value Init](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/valueInit/aura-value-init.md)
- [Value Render](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/valueRender/aura-value-render.md)
- [Waiting](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/waiting/aura-waiting.md)

## Component Events

Customize UI component behavior with these events.

- [Clear Error](/docs/platform/lightning-component-reference/guide/ui-clear-errors.html)
- [Collapse](/docs/platform/lightning-component-reference/guide/ui-collapse.html)
- [Expand](/docs/platform/lightning-component-reference/guide/ui-expand.html)
- [Menu Focus Change](/docs/platform/lightning-component-reference/guide/ui-menu-focus-change.html) (Deprecated)
- [Menu Select](/docs/platform/lightning-component-reference/guide/ui-menu-select.html) (Deprecated)
- [Menu Trigger Press](/docs/platform/lightning-component-reference/guide/ui-menu-trigger-press.html) (Deprecated)
- [Validation Error](/docs/platform/lightning-component-reference/guide/ui-validation-error.html) (Deprecated)

## Chatter Events

Customize Chatter feed behavior using these events.

- [Custom Open File](/docs/platform/lightning-component-reference/guide/forceChatter-custom-open-file.html)
- [Post Created](/docs/platform/lightning-component-reference/guide/forceChatter-post-created.html)

## Console Chat Events

Customize chat behavior in console apps using these events.

- [Conversation Agent Send](/docs/platform/lightning-component-reference/guide/aura-conversation-agent-send.html)
- [Conversation Chat Ended](/docs/platform/lightning-component-reference/guide/aura-conversation-chat-ended.html)
- [Conversation Custom Event](/docs/platform/lightning-component-reference/guide/aura-conversation-custom-event.html)
- [Conversation New Message](/docs/platform/lightning-component-reference/guide/aura-conversation-new-message.html)

## Console Omni-Channel Events

Customize Omni-Channel behavior in console apps using these events.

- [Omni-Channel Connection Error](/docs/platform/lightning-component-reference/guide/aura-omni-channel-connection-error.html)
- [Omni-Channel Login Success](/docs/platform/lightning-component-reference/guide/aura-omni-channel-login-success.html)
- [Omni-Channel Logout](/docs/platform/lightning-component-reference/guide/aura-omni-channel-logout.html)
- [Omni-Channel Status Changed](/docs/platform/lightning-component-reference/guide/aura-omni-channel-status-changed.html)
- [Omni-Channel Work Accepted](/docs/platform/lightning-component-reference/guide/aura-omni-channel-work-accepted.html)
- [Omni-Channel Work Assigned](/docs/platform/lightning-component-reference/guide/aura-omni-channel-work-assigned.html)
- [Omni-Channel Work Closed](/docs/platform/lightning-component-reference/guide/aura-omni-channel-work-closed.html)
- [Omni-Channel Work Declined](/docs/platform/lightning-component-reference/guide/aura-omni-channel-work-declined.html)
- [Omni-Channel Work Flag Updated](/docs/platform/lightning-component-reference/guide/aura-omni-channel-work-flag-updated.html)
- [Omni-Channel Workload Changed](/docs/platform/lightning-component-reference/guide/aura-omni-channel-workload-changed.html)

## CRM Analytics Events

Customize CRM Analytics behavior using these events.

- [Asset Loaded](/docs/platform/lightning-component-reference/guide/wave-asset-loaded.html)
- [Discover](/docs/platform/lightning-component-reference/guide/wave-discover.html)
- [Discover Response](/docs/platform/lightning-component-reference/guide/wave-discover-response.html)
- [Page Change](/docs/platform/lightning-component-reference/guide/wave-page-change.html)
- [Selection Changed](/docs/platform/lightning-component-reference/guide/wave-selection-changed.html)
- [Update](/docs/platform/lightning-component-reference/guide/wave-update.html)

## Experience Builder Events

Customize Experience Builder site behavior using these events.

- [Analytics Interaction](/docs/platform/lightning-component-reference/guide/forceCommunity-analytics-interaction.html)
- [Analytics Interaction Gtag](/docs/platform/lightning-component-reference/guide/forceCommunity-analytics-interaction-gtag.html)
- [Deflection Signal](/docs/platform/lightning-component-reference/guide/lightningcommunity-deflection-signal.html)
- [Route Change](/docs/platform/lightning-component-reference/guide/forceCommunity-route-change.html)

## Navigation Events

Navigate from a custom component to another page in Lightning Experience, Aura-based Experience Builder sites, and Salesforce mobile app.

- [Navigate Home](/docs/platform/lightning-component-reference/guide/force-navigate-home.html) (Deprecated)
- [Navigate To Component](/docs/platform/lightning-component-reference/guide/force-navigate-to-component.html) (Deprecated)
- [Navigate To List](/docs/platform/lightning-component-reference/guide/force-navigate-to-list.html) (Beta)
- [Navigate To Object Home](/docs/platform/lightning-component-reference/guide/force-navigate-to-object-home.html)
- [Navigate To Related List](/docs/platform/lightning-component-reference/guide/force-navigate-to-related-list.html) (Beta)
- [Navigate To SObject](/docs/platform/lightning-component-reference/guide/force-navigate-to-sobject.html) (Beta)
- [Navigate To URL](/docs/platform/lightning-component-reference/guide/force-navigate-to-url.html)

## Page-Level Events

Customize page-level behavior using these events.

- [Close Quick Action](/docs/platform/lightning-component-reference/guide/force-close-quick-action.html)
- [Refresh View](/docs/platform/lightning-component-reference/guide/force-refresh-view.html)
- [Show Toast](/docs/platform/lightning-component-reference/guide/force-show-toast.html)

## Record Events

Work with records using these events.

- [Create Record](/docs/platform/lightning-component-reference/guide/force-create-record.html)
- [Edit Record](/docs/platform/lightning-component-reference/guide/force-edit-record.html)
- [Record Save](/docs/platform/lightning-component-reference/guide/force-record-save.html)
- [Record Save Success](/docs/platform/lightning-component-reference/guide/force-record-save-success.html)
- [Refresh View](/docs/platform/lightning-component-reference/guide/force-refresh-view.html) (Beta)

## See Also

- [Events for Chat](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_liveagent_events.htm)
- [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm)
- [Communicating with Events](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/events_intro.htm)

<!-- document id=de0aceed9837f51b1188f0b5403ad360fec2d5482c58abf421121d1871f0cdce url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/aura-events.md -->

# Aura Events in `aura` Namespace

The `aura` namespace provides framework-level events that you can handle to customize component behavior.

- [Application Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/applicationEvent/aura-application-event.md)
- [Component Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/componentEvent/aura-component-event.md)
- [Done Rendering (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/doneRendering/aura-done-rendering.md)
- [Done Waiting (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/doneWaiting/aura-done-waiting.md)
- [Location Change](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/locationChange/aura-location-change.md)
- [Method Call](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/methodCall/aura-method-call.md)
- [No Access](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/noAccess/aura-no-access.md)
- [System Error](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/systemError/aura-system-error.md)
- [Value Change](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/valueChange/aura-value-change.md)
- [Value Destroy](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/valueDestroy/aura-value-destroy.md)
- [Value Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/valueEvent/aura-value-event.md)
- [Value Init](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/valueInit/aura-value-init.md)
- [Value Render](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/valueRender/aura-value-render.md)
- [Waiting (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/waiting/aura-waiting.md)

<!-- document id=de95ed93b04e742e819b93fad2f591742a8ac11d816b4c94cddbce83bed04f88 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/force-events.md -->

# Aura Events in `force` Namespace

The `force` namespace provides several events that you can fire to work with records and page navigation.

- [Close Quick Action](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/closeQuickAction/force-close-quick-action.md)
- [Create Record](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/createRecord/force-create-record.md)
- [Edit Record](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/editRecord/force-edit-record.md)
- [Navigate Home (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateHome/force-navigate-home.md)
- [Navigate To Component (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToComponent/force-navigate-to-component.md)
- [Navigate To List (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToList/force-navigate-to-list.md)
- [Navigate To Object Home](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToObjectHome/force-navigate-to-object-home.md)
- [Navigate To Related List (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToRelatedList/force-navigate-to-related-list.md)
- [Navigate To SObject (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToSObject/force-navigate-to-sobject.md)
- [Navigate To URL](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/navigateToURL/force-navigate-to-url.md)
- [Record Save](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/recordSave/force-record-save.md)
- [Record Save Success](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/recordSaveSuccess/force-record-save-success.md)
- [Refresh View (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/refreshView/force-refresh-view.md)
- [Show Toast](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/showToast/force-show-toast.md)

<!-- document id=fded26811cbb813533d2bae4a545b87e2bb40cd6d3a4baa57a9a5c9b9fba950b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceChatter/forceChatter-events.md -->

# Aura Events in `forceChatter` Namespace

The `forceChatter` namespace provides several events.

- [Custom Open File](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/customOpenFile/forceChatter-custom-open-file.md)
- [Post Created](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/postCreated/forceChatter-post-created.md)

<!-- document id=ad7245e3668da15915e6acd927fc48d7a5164058e838a9f665b8587de8b48414 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/forceCommunity-events.md -->

# Aura Events in `forceCommunity` Namespace

The `forceCommunity` namespace provides several events.

- [Analytics Interaction](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/analyticsInteraction/forceCommunity-analytics-interaction.md)
- [Analytics Interaction Gtag](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/analyticsInteractionGtag/forceCommunity-analytics-interaction-gtag.md)
- [Route Change](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/routeChange/forceCommunity-route-change.md)

<!-- document id=464d5f305c656619f7b606d790419de4bf06803c123fbe52cd49996f78097f51 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/lightning-events.md -->

# Aura Events in `lightning` Namespace

The `lightning` namespace provides several Aura events to customize component behavior for Enhanced Messaging channels, Omni-Channel, and Lightning Console apps.

- [Conversation Agent Send](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/conversationAgentSend/aura-conversation-agent-send.md)
- [Conversation Chat Ended](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/conversationChatEnded/aura-conversation-chat-ended.md)
- [Conversation Custom Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/conversationCustomEvent/aura-conversation-custom-event.md)
- [Conversation New Message](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/conversationNewMessage/aura-conversation-new-message.md)
- [Omni Channel Connection Error](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelConnectionError/aura-omni-channel-connection-error.md)
- [Omni Channel Login Success](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelLoginSuccess/aura-omni-channel-login-success.md)
- [Omni Channel Logout](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelLogout/aura-omni-channel-logout.md)
- [Omni Channel Status Changed](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelStatusChanged/aura-omni-channel-status-changed.md)
- [Omni Channel Work Accepted](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkAccepted/aura-omni-channel-work-accepted.md)
- [Omni Channel Work Assigned](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkAssigned/aura-omni-channel-work-assigned.md)
- [Omni Channel Work Closed](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkClosed/aura-omni-channel-work-closed.md)
- [Omni Channel Work Declined](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkDeclined/aura-omni-channel-work-declined.md)
- [Omni Channel Work Flag Updated](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkFlagUpdated/aura-omni-channel-work-flag-updated.md)
- [Omni Channel Workload Changed](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/omniChannelWorkloadChanged/aura-omni-channel-workload-changed.md)
- [Open Files](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/openFiles/aura-open-files.md)
- [Send Chatter Extension Payload](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/sendChatterExtensionPayload/aura-send-chatter-extension-payload.md) (Beta)
- [Tab Closed](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabClosed/aura-tab-closed.md)
- [Tab Created](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabCreated/aura-tab-created.md)
- [Tab Focused](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabFocused/aura-tab-focused.md)
- [Tab Refreshed](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabRefreshed/aura-tab-refreshed.md)
- [Tab Replaced](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabReplaced/aura-tab-replaced.md)
- [Tab Updated](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/tabUpdated/aura-tab-updated.md)

<!-- document id=13b17c24900cace25eacff80b0283df83b676a1306861c0dbf1d66d6d9422dab url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightningcommunity/lightningcommunity-events.md -->

# Aura Events in `lightningcommunity` Namespace

The `lightningcommunity` namespace provides an event for working with Experience Builder Aura sites.

- [Deflection Signal](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/deflectionSignal/lightningcommunity-deflection-signal.md)

<!-- document id=4a4395e19922122efe8df8e6f0591242683bf79c9745cd472aeceee94b570372 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/ltng-events.md -->

# Aura Events in `ltng` Namespace

The `ltng` namespace provides several events.

- [After Scripts Loaded](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/afterScriptsLoaded/ltng-after-scripts-loaded.md)
- [Before Loading Resource](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/beforeLoadingResources/ltng-before-loading-resources.md)
- [Select SObject](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/selectSObject/ltng-select-sobject.md)
- [Send Message](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/sendMessage/ltng-send-message.md)

<!-- document id=bb915b9abb4716ab75e58e46ca5a70997ae689bc30d60403d354e89de2721e06 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/ui-events.md -->

# Aura Events in `ui` Namespace

The `ui` namespace provides several events that you can use with [Aura components in the `ui` namespace](https://developer.salesforce.com/docs/platform/lightning-component-reference/aura-ui.md).

- [Clear Error](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/clearErrors/ui-clear-errors.md)
- [Collapse](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/collapse/ui-collapse.md)
- [Expand](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/expand/ui-expand.md)
- [Menu Focus Change (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/menuFocusChange/ui-menu-focus-change.md)
- [Menu Select (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/menuSelect/ui-menu-select.md)
- [Menu Trigger Press (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/menuTriggerPress/ui-menu-trigger-press.md)
- [Validation Error (Deprecated)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/validationError/ui-validation-error.md)

<!-- document id=2552768bee914bf743c235481f4e9a545866e28d51767afebc07944f07ffb67b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/wave-events.md -->

# Aura Events in `wave` Namespace

The `wave` namespace provides several events that you can use with [Aura components in the `wave` namespace](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-wave-namespace.md).

- [assetLoaded](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/assetLoaded/wave-asset-loaded.md)
- [discover](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/discover/wave-discover.md)
- [discoverResponse](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/discoverResponse/wave-discover-response.md)
- [pageChange](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/pageChange/wave-page-change.md)
- [selectionChanged](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/selectionChanged/wave-selection-changed.md)
- [update](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/update/wave-update.md)

<!-- document id=6a9d8ea760184e17a09f922e3c8ce9402300d6f49484cb9ba7c82306a768577a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/interfaces.md -->

# Aura Interfaces

**note:** Use Lightning Web Components (LWC) where possible for new development. For more information, see [Migrate Interfaces](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-interfaces.html).

Aura Interfaces make your components available for use on record pages, flow screens, utility bars, and Aura-based Experience Builder sites. These interfaces enable you to integrate custom component logic with platform capabilities, allowing components to participate in declarative configuration and extend legacy Salesforce functionality.

## Marker Interfaces

Marker interfaces enable a component to be used in a specific page or app, such as in Lightning App Builder, Experience Builder, and more.

- [Action Override](/docs/platform/lightning-component-reference/guide/aura-action-override.html)
- [Available For All Page Types](/docs/platform/lightning-component-reference/guide/flexipage-available-for-all-page-types.html)
- [Available For Record Home](/docs/platform/lightning-component-reference/guide/flexipage-available-for-record-home.html)
- [App Hostable](/docs/platform/lightning-component-reference/guide/force-app-hostable.html)
- [Available for All Page Types](/docs/platform/lightning-component-reference/guide/forceCommunity-available-for-all-page-types.html)
- [Available For Chatter Extension Composer](/docs/platform/lightning-component-reference/guide/aura-available-for-chatter-extension-composer.html)
- [Available For Chatter Extension Renderer](/docs/platform/lightning-component-reference/guide/aura-available-for-chatter-extension-renderer.html)
- [Available For Flow Actions](/docs/platform/lightning-component-reference/guide/aura-available-for-flow-actions.html)
- [Available For Flow Screens](/docs/platform/lightning-component-reference/guide/aura-available-for-flow-screens.html)
- [Available For Forecasting Page](/docs/platform/lightning-component-reference/guide/aura-available-for-forecasting-page.html)
- [Available For Mail App App Page](/docs/platform/lightning-component-reference/guide/clients-available-for-mail-app-app-page.html)
- [Background Utility Item](/docs/platform/lightning-component-reference/guide/aura-background-utility-item.html)
- [Profile Menu Interface](/docs/platform/lightning-component-reference/guide/forceCommunity-profile-menu-interface.html)
- [Search Interface](/docs/platform/lightning-component-reference/guide/forceCommunity-search-interface.html)
- [Has Record Id](/docs/platform/lightning-component-reference/guide/force-has-record-id.html)
- [Has SObject Name](/docs/platform/lightning-component-reference/guide/force-has-sobject-name.html)
- [Lightning Quick Action](/docs/platform/lightning-component-reference/guide/force-lightning-quick-action.html)
- [Lightning Quick Action Without Header](/docs/platform/lightning-component-reference/guide/force-lightning-quick-action-without-header.html)
- [Utility Item](/docs/platform/lightning-component-reference/guide/aura-utility-item.html)


## Functional Interfaces

Functional interfaces provide additional functionality to a component, such as enabling the component to be addressable directly via a URL.

- [Allow In Relaxed CSP](/docs/platform/lightning-component-reference/guide/lightningcommunity-allow-in-relaxed-csp.html)
- [Has Page Reference](/docs/platform/lightning-component-reference/guide/aura-has-page-reference.html)
- [Is Url Addressable](/docs/platform/lightning-component-reference/guide/aura-is-url-addressable.html)
- [Has Event Context](/docs/platform/lightning-component-reference/guide/clients-has-event-context.html)
- [Has Item Context](/docs/platform/lightning-component-reference/guide/clients-has-item-context.html)

## Template Interfaces

Template interfaces enable a component to be used as custom Lightning page templates in Lightning App Builder or Experience Builder. Each component can implement only one template interface and cannot implement other interfaces.

- [App Home Template](/docs/platform/lightning-component-reference/guide/aura-app-home-template.html)
- [Forecasting Template](/docs/platform/lightning-component-reference/guide/aura-forecasting-template.html)
- [Home Template](/docs/platform/lightning-component-reference/guide/aura-home-template.html)
- [Record Home Template](/docs/platform/lightning-component-reference/guide/aura-record-home-template.html)
- [Layout](/docs/platform/lightning-component-reference/guide/forceCommunity-layout.html)
- [Theme Layout](/docs/platform/lightning-component-reference/guide/forceCommunity-theme-layout.html)

## See Also

[Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/)

<!-- document id=580be127bb1910abda844f53f17e62b59c7dbb1dfe93d4e4b26c9e6fedfeeedb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/clients/clients-interfaces.md -->

# Aura Interfaces in `clients` Namespace

The `clients` namespace provides these Aura interfaces.

- [Available For Mail App App Page](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForMailAppAppPage/clients-available-for-mail-app-app-page.md)
- [Has Event Context](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/hasEventContext/clients-has-event-context.md)
- [Has Item Context](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/hasItemContext/clients-has-item-context.md)

<!-- document id=47317ccfec6d420555ebface8ac435b09bc25acf5e8e5896886619d76c259fad url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/flexipage/flexipage-interfaces.md -->

# Aura Interfaces in `flexipage` Namespace

The `flexipage` namespace provides these Aura interfaces.

- [Available For All Page Types](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForAllPageTypes/flexipage-available-for-all-page-types.md)
- [Available For Record Home](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForRecordHome/flexipage-available-for-record-home.md)

<!-- document id=8737a4df1a116a2226f04d7f6e9019555dcfc3239f6cdc0fe0a332b57662d2d3 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/force-interfaces.md -->

# Aura Interfaces in `force` Namespace

The `force` namespace provides these Aura interfaces.

- [App Hostable](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/appHostable/force-app-hostable.md)
- [Has Record Id](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/hasRecordId/force-has-record-id.md)
- [Has SObject Name](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/hasSObjectName/force-has-sobject-name.md)
- [Lightning Quick Action](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightningQuickAction/force-lightning-quick-action.md)
- [Lightning Quick Action Without Header](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightningQuickActionWithoutHeader/force-lightning-quick-action-without-header.md)

<!-- document id=bbac4f8deb63a9af2276c039b3b522972c072e27e157e57535dd908dc44dac17 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/forceCommunity-interfaces.md -->

# Aura Interfaces in `forceCommunity` Namespace

The `forceCommunity` namespace provides these Aura interfaces.

- [Available For All Page Types](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForAllPageTypes/forceCommunity-available-for-all-page-types.md)
- [Layout](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/layout/forceCommunity-layout.md)
- [Profile Menu Interface](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/profileMenuInterface/forceCommunity-profile-menu-interface.md)
- [Search Interface](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/searchInterface/forceCommunity-search-interface.md)
- [Theme Layout](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/themeLayout/forceCommunity-theme-layout.md)

<!-- document id=33498d84a9d07fd08bc1e48c370a4d398604ec3f0f4484dd365aebb818804923 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/lightning-interfaces.md -->

# Aura Interfaces in `lightning` Namespace

The `lightning` namespace provides these Aura interfaces.

- [Action Override](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/actionOverride/aura-action-override.md)
- [App Home Template](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/appHomeTemplate/aura-app-home-template.md)
- [Available For Chatter Extension Composer](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForChatterExtensionComposer/aura-available-for-chatter-extension-composer.md)
- [Available For Chatter Extension Renderer](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForChatterExtensionRenderer/aura-available-for-chatter-extension-renderer.md)
- [Available For Flow Actions](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForFlowActions/aura-available-for-flow-actions.md)
- [Available For Flow Screens](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForFlowScreens/aura-available-for-flow-screens.md)
- [Available For Forecasting Page](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/availableForForecastingPage/aura-available-for-forecasting-page.md)
- [Background Utility Item](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/backgroundUtilityItem/aura-background-utility-item.md)
- [Forecasting Template](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/forecastingTemplate/aura-forecasting-template.md)
- [Has Page Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/hasPageReference/aura-has-page-reference.md)
- [Home Template](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/homeTemplate/aura-home-template.md)
- [Is Url Addressable](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/isUrlAddressable/aura-is-url-addressable.md)
- [Record Home Template](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/recordHomeTemplate/aura-record-home-template.md)
- [Utility Item](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/utilityItem/aura-utility-item.md)

<!-- document id=5b79818a90ebcb2de26d51e9890b99425e4e507103686460468ea7e5a6aadc3f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightningcommunity/lightningcommunity-interfaces.md -->

# Aura Interfaces in `lightningcommunity` Namespace

The `lightningcommunity` namespace provides this Aura interface.

- [Allow In Relaxed CSP](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/allowInRelaxedCSP/lightningcommunity-allow-in-relaxed-csp.md)

<!-- document id=ff27fd9aab0a904608a62702a6abf485920c7b7ef07aab4f9021bfa1a278ca11 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/ltng-interfaces.md -->

# Aura Interfaces in `ltng` Namespace

The `ltng` namespace provides this Aura interface.

- [Allow Guest Access](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/allowGuestAccess/ltng-allow-guest-access.md)

<!-- document id=8a071d826fb735a0446b36b961985b762f4bdc615d09282d6eab2995d9bf1f50 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/flexipage/availableForAllPageTypes/flexipage-available-for-all-page-types.md -->

# Available For All Page Types

The `flexipage:availableForAllPageTypes` interface enables a component to be used on a page via the Lightning App Builder.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To make your component available for record pages and any other type of page, implement the `flexipage:availableForAllPageTypes` interface.

If your component is designed for record pages only, use the [`flexipage:availableForRecordHome` interface](/docs/platform/lightning-component-reference/guide/flexipage-available-for-record-home.html) instead.

Here's an example of a component that can be used in Lightning App Builder for a page.

```xml
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
    <aura:attribute name="greeting" type="String" default="Hello" access="global" />
    <aura:attribute name="subject" type="String" default="World" access="global" />

    <div style="box">
      <span class="greeting">{!v.greeting}</span>, {!v.subject}!
    </div>
</aura:component>
```

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=c34f0f7b2e8d17600b61f7be791ca63d8d496e8578d899d04580a4d63748c039 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/availableForAllPageTypes/forceCommunity-available-for-all-page-types.md -->

# Available For All Page Types

**`forceCommunity:availableForAllPageTypes`**

Enables a component for drag and drop in the Lightning Components panel in Experience Builder.

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To appear in Experience Builder, a component must implement the `forceCommunity:availableForAllPageTypes` interface.

Here's the sample code for a simple "Hello World" component.

```xml
<aura:component implements="forceCommunity:availableForAllPageTypes" access="global">
    <aura:attribute name="greeting" type="String" default="Hello" access="global" />
    <aura:attribute name="subject" type="String" default="World" access="global" />

    <div style="box">
      <span class="greeting">{!v.greeting}</span>, {!v.subject}!
    </div>
</aura:component>
```

Mark your resources, such as a component, with `access="global"` to make the resource usable outside of your own org. For example, if you want a component to be usable in an installed package or by a Lightning App Builder user or an Experience Builder user in another org.

Next, add a design resource to your component bundle. A design resource describes the design-time behavior of an Aura component—information that visual tools need to allow adding the component to a page or app. It contains attributes that are available for administrators to edit in Experience Builder.

```xml
<design:component label="Hello World">
    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet" />
    <design:attribute name="greeting" label="Greeting" />
</design:component>
```

When you add custom components to your Experience Builder site, they can bypass the object- and field-level security (FLS) you set for the guest user profile. Aura components don’t automatically enforce CRUD and FLS when referencing objects or retrieving the objects from an Apex controller. This means that the framework continues to display records and fields for which users don’t have CRUD permissions and FLS visibility. You must manually enforce CRUD and FLS in your Apex controllers.

For more information, see [Using Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_intro.htm?search_text=forceCommunity:availableForAllPageTypes) in the Lightning Aura Components Developer Guide.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=79a3f4eb5d85542e13d021c8d6bf1d3cbc6eb862a326ef9ad283f3de9c66d0a5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/availableForChatterExtensionComposer/aura-available-for-chatter-extension-composer.md -->

# Available For Chatter Extension Composer

**`lightning:availableForChatterExtensionComposer`**

Enables a component to be used in the Chatter publisher.

**For Use In**

Experience Builder sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning:availableForChatterExtensionComposer` interface to integrate your custom apps into the Chatter publisher and place the custom app’s payload in the feed. This interface is available in Experience Builder sites.

The `lightning:availableForChatterExtensionComposer` interface works with the `lightning:availableForChatterExtensionRenderer` interface and the `lightning:sendChatterExtensionPayload` event to integrate your custom apps into the Chatter publisher and to render the app’s payload in the feed.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_integrate_customapps_to_publisher.htm).


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=6b788900e87f739d79622b990dc2d2cd00a285137c6b901398b33e9c5a8d1806 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/availableForChatterExtensionRenderer/aura-available-for-chatter-extension-renderer.md -->

# Available For Chatter Extension Renderer

**`lightning:availableForChatterExtensionRenderer`**

Enables a component to be used in the Chatter publisher.

**For Use In**

Experience Builder sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning:availableForChatterExtensionRenderer` interface to integrate your custom apps into the Chatter publisher and place the custom app’s payload in the feed. This interface is available in Experience Builder sites.

The `lightning:availableForChatterExtensionRenderer` interface works with the `lightning:availableForChatterExtensionComposer` interface and the `lightning:sendChatterExtensionPayload` event to integrate your custom apps into the Chatter publisher and to render the app’s payload in the feed.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_integrate_customapps_to_publisher.htm).


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=82312f1ef54fdd5287bf168c60a976bcb5fb68cc9cc9a3476050a7c91c441983 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/availableForFlowActions/aura-available-for-flow-actions.md -->

# Available For Flow Actions

**`lightning:availableForFlowActions`**

Enables a component's controller to be used as an action in a flow.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Add the `lightning:availableForFlowActions` interface to a Lightning component to make it available as a flow action. When a component is executed as a flow action, the flow calls the `invoke` method in the client-side controller. Flows that include Lightning components are supported only in Lightning runtime.

Lightning components that implement `lightning:availableForFlowActions` are available as Local Action elements in the Cloud Flow Designer. If an attribute is declared in the component's design resource, flow admins can pass values between that attribute and the flow when they configure the Local Action element.

To run your code asynchronously, for example because you're making an XML HTTP request (XHR), return a Promise.

When the method finishes or the Promise is settled, control is returned back to the flow.

- Asynchronous Code: When a Promise is fulfilled, the next element in the flow is executed. When a Promise is rejected or times out, the flow takes the Local Action element's fault connector and sets `$Flow.FaultMessage` to the error message. By default, the error message is "An error occurred when the flow tried to execute the c:myComponent component.". To customize the error message, return it as an error in the `reject()` call. When a Promise times out, it returns control to the flow, but it doesn't cancel the original request. For example, if the request fires a `force:showToast` event after a delay, the event still fires even after the promise times out. To abort a Promise, use the `cancelToken` attribute provided by the interface.

- Synchronous Code: When the method finishes, the next element in the flow is executed.

This example shows the markup required to add the `lightning:availableForFlowActions` interface to a Lightning component.

```html
<aura:component implements="lightning:availableForFlowActions">
  // declare attributes here
</aura:component>
```

Here's an example of an asynchronous client-side controller. The `invoke` method returns a Promise. When the method has done all it needs to do, it completes the call. If the request is successful, the method uses `resolve()` to execute the next element in the flow after this action. Otherwise, it uses `reject()` to take the Local Action element's fault connector and sets `$Flow.FaultMessage` to "My error message". If the request takes too long, it uses `cancelToken.promise.then` to abort the request.

```javascript
/** Asynchronous Client-Side Controller **/
({
    invoke : function(component, event, helper) {
       var cancelToken = event.getParam("arguments").cancelToken;

       return new Promise(function(resolve, reject) {
          var xhttp = new XMLHttpRequest();

          // Do something, like get data from
          // a database behind your firewall
          xhttp.onreadystatechange = $A.getCallback(function() {
              if (/* request was successful */) {
                // Complete the call and return to the flow
                resolve();
              } else {
                reject(new Error("My error message"));
              }
          });

          // Gracefully abort the Promise if it times out
          cancelToken.promise.then(function(error) {
              xhttp.abort();
              reject(error);
          });
       });
    }
})


```

Here's an example of a synchronous client-side controller. When the `invoke` method finishes, control returns to the flow.

```javascript
/** Synchronous Client-Side Controller **/
({
  invoke: function (component, event, helper) {
    // Do something, like open another browser tab
    // with a specified URL
  },
});
```

For more information, see [Create Flow Actions By Using Lightning Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_flow_actions.htm).

## Methods

This interface requires your component to implement the following method.

`invoke(component, event, helper)`: Called when a flow executes the component as a local action. To handle asynchronous calls, construct a Promise in this method.

- `cancelToken` (Object): A token that you can use to gracefully abort a Promise. When the Promise times out, `cancelToken.requested` is set to `true` and `cancelToken.promise` is resolved with a timeout Error object.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=24d4d698c6fdf6a180b8c0cb844f9bbab9cd52a44eaeedf83fd26473afabafa0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/availableForFlowScreens/aura-available-for-flow-screens.md -->

# Available For Flow Screens

**`lightning:availableForFlowScreens`**

Enables a component to be used in flow screens.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Add the `lightning:availableForFlowScreens` interface to a Lightning component to make it available for flow screens. This interface is supported only in Lightning runtime.

This example shows the markup required to add the `lightning:availableForFlowScreens` interface to a Lightning component.

```html
<aura:component implements="lightning:availableForFlowScreens">
  <!-- Your component markup here -->
</aura:component>
```

After making the component available to flow screens, you can add a resource bundle to enable attributes that admins can edit in the Cloud Flow Designer. You can also replace the whole flow screen with your own component.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_flow_screens_intro.htm).

## Custom Validation

Salesforce validates each flow screen when the user attempts to navigate to the next screen. If the flow screen is not valid, the user can’t progress. To validate the component with the flow screen, declare the `validate` attribute in the component. Set the `validate` attribute to a custom validation function that must return two parameters: `isValid` and `errorMessage`.

Here's example markup for a Lightning component with custom validation. The `validate` attribute is set by the component’s client-side controller later in this example.

```html
<aura:component implements="lightning:availableForFlowScreens" access="global">
  <!-- When the component renders, call the init handler. -->
  <aura:handler name="init" value="{!this}" action="{!c.init}" />
  <!-- Attribute to store the validation logic in. -->
  <aura:attribute
    name="validate"
    type="Aura.Action"
    description="Custom validation function to run when the flow is navigated to the next screen. The function must evaluate the component and return values for isValid and errorMessage."
  />
  <aura:attribute name="textAttribute" type="String" />
  <lightning:input
    id="nameinput"
    type="text"
    label="What is your name?"
    value="{!v.textAttribute}"
  />
</aura:component>
```

Here's the corresponding client-side controller. When the component renders, the `init` handler sets the component's `validate` attribute to a function that validates the component. When the user navigates to the next flow screen, the function in the validate attribute is run.

- If the component is valid, the function returns the `isValid` parameter as true and the user navigates to the next flow screen.
- Otherwise, the function returns the `isValid` parameter as false and a custom error message that displays under the Lightning component in the flow screen. The user can't navigate to the next screen until the function is successful.

```javascript
({
  init: function (cmp, event, helper) {
    // Set the validate attribute to a function that includes validation logic
    cmp.set("v.validate", function () {
      var userInput = cmp.get("v.textAttribute");
      if (userInput && userInput.length > 0) {
        // If the component is valid...
        return { isValid: true };
      } else {
        // If the component is invalid...
        return { isValid: false, errorMessage: "A value is required." };
      }
    });
  },
});
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=e9e39664c1fccf6a0f36cf232edbae86621942ad14c13f580e6a561cc0d9cd28 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/availableForForecastingPage/aura-available-for-forecasting-page.md -->

# Available For Forecasting Page

**`lightning:availableForForecastingPage`**

Enables a component to be used in a Lightning Forecasting page.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning:availableForForecastingPage` interface to make your component available for Lightning Forecasting pages only.

This example creates a "Hello World" component that's available only for Lightning Forecasting pages.

```
<aura:component implements="lightning:availableForForecastingPage" access="global">
    <aura:attribute name="greeting" type="String" default="Hello" access="global" />
    <aura:attribute name="subject" type="String" default="World" access="global" />

    <div style="box">
      <span class="greeting">{!v.greeting}</span>, {!v.subject}!
    </div>
</aura:component>
```

For more information, see [Configure Components for Lightning Pages and the Lightning App Builder](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder.htm) in the Lightning Aura Components Developer Guide.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=1dfe5c309040269db8a00823885de7179124af88c6640de4f125338a2756a50f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/clients/availableForMailAppAppPage/clients-available-for-mail-app-app-page.md -->

# Available For Mail App App Page

**`clients:availableForMailAppAppPage`**

Enables components to show up in the Lightning for Gmail or Lightning For Outlook Flexipages.

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To add a component to a Mail App Lightning page in the Lightning App Builder, or email application panes in Lightning for Outlook or Lightning for Gmail, implement the `clients:availableForMailAppAppPage` marker interface. This interface is used with `clients:hasItemContext` and `clients:hasEventContext`to implement record-specific and event-specific information.

To ensure that custom components appear correctly in Lightning for Outlook or Lightning for Gmail, enable them to adjust to variable widths.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_email_app_pane.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=803495a53413094daae8f8ed8f3744ece0b4bf3155d468634a5686ba98070795 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/flexipage/availableForRecordHome/flexipage-available-for-record-home.md -->

# Available For Record Home

The `flexipage:availableForRecordHome` interface enables a component to be used on a record home page via the Lightning App Builder.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To make your component available for record pages only, implement the `flexipage:availableForRecordHome` interface.

If your component is designed for record pages and any other type of page, use the `flexipage:availableForAllPageTypes` interface instead.

Here's an example of a component that can be used on a record page

```xml
<aura:component implements="flexipage:availableForRecordHome" access="global">
    <aura:attribute name="greeting" type="String" default="Hello" access="global" />
    <aura:attribute name="subject" type="String" default="World" access="global" />

    <div style="box">
      <span class="greeting">{!v.greeting}</span>, {!v.subject}!
    </div>
</aura:component>
```

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=189312df01d2059e6b7c36aaf177e9762f4be19d7dca2c5aa90c94f525a2fd03 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/avatar/lightning-avatar.md -->


# Avatar

**`lightning-avatar`**

A visual representation of an object.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="avatar" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-avatar` component is an image that represents an object, such as
an account or user. By default, the image renders in medium sizing with a
rounded rectangle, which is also known as the `square` variant.

Here’s a basic avatar example.

<!-- prettier-ignore-start -->
```html
<lightning-avatar src="/images/codey.jpg" alternative-text="Codey Bear">
</lightning-avatar>
```
<!-- prettier-ignore-end -->

To use an image in your org as an avatar, upload the image as a static resource in the Static Resources setup page. Import the image from the [`@salesforce/resourceUrl` module](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.html) and use it in the `src` attribute.

## Design

`lightning-avatar` implements the avatar blueprint in the Salesforce Lightning Design System (SLDS). The avatar adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Avatar](https://v1.lightningdesignsystem.com/components/avatar/)                                                                     | [Avatar](https://www.lightningdesignsystem.com/components/avatar/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Handle Invalid Image Paths

The `src` attribute resolves the relative path to an image, but sometimes the
image path doesn't resolve correctly because the user is offline or the image
has been deleted. To handle an invalid image path, you can provide fallback
initials by using the `initials` attribute or a fallback icon with the `fallback-icon-name`
attribute. These attributes work together if both are specified.

If initials and fallback icon name are provided, the initials are shown and the
background color of the fallback icon is used as the background color for the initials.
The fallback icon is shown only when the image path is invalid and initials aren’t provided.

This example shows the initials "Sa" if the image path is invalid. The fallback icon
"standard:account" provides the background color for the initials. The icon is one of the
[standard icons](https://v1.lightningdesignsystem.com/icons/#standard)
in SLDS.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-avatar
        src="/bad/image/url.jpg"
        initials="Sa"
        fallback-icon-name="standard:account"
        alternative-text="Salesforce"
    >
    </lightning-avatar>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

Use a combination of icons, variants, and utility classes to style your avatars.

### Icons

Although SLDS provides several categories of icons, only icons from the [standard](https://v1.lightningdesignsystem.com/icons/#standard) and [custom](https://v1.lightningdesignsystem.com/icons/#custom) categories can be used in `lightning-avatar`.

**note:** When applying SLDS classes or icons, check that they’re
available in the SLDS release tied to your org. The latest
SLDS resources become available only when the new release
is available in your org.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `square` is the default variant, displaying a rectangle avatar with rounded corners
- `circle` displays a round avatar

This example creates a round avatar.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-avatar
        variant="circle"
        src="https://v1.lightningdesignsystem.com/assets/images/avatar2.jpg"
        fallback-icon-name="standard:person_account"
        alternative-text="Amy Smith"
    ></lightning-avatar>
</template>
```
<!-- prettier-ignore-end -->

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin around the avatar using an SLDS class. The fallback icon is displayed if the image path is invalid.

<!-- prettier-ignore-start -->
```html
<lightning-avatar
    variant="circle"
    src="https://v1.lightningdesignsystem.com/assets/images/avatar2.jpg"
    fallback-icon-name="standard:person_account"
    alternative-text="Account Name"
    class="slds-m-around_small"
>
</lightning-avatar>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

Use the `alternative-text` attribute to describe the avatar, such as a user's initials or name. This description provides the value for the `alt` attribute in the `img` HTML tag.


:::::

:::::tab
::component-specification{component="avatar" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=4b1416942f96dd5e49a013ce2654c4a90633c723050b3588ac0f7b8fe234a7bf url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/backgroundUtilityItem/aura-background-utility-item.md -->

# Background Utility Item

**`lightning:backgroundUtilityItem`**

Enables a component to be used at the app level without rendering any UI.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:backgroundUtilityItem` interface to allow a component to be used as an app-level component that is created when the app loads, and runs code without rendering itself in the app UI.

Components that implement this interface are added to the app through the Select Utility Items milestone in Setup.

This example shows how to implement a background utility item that listens for `lightning:tabCreated` events when the app loads, and invokes `lightning:workspaceAPI` methods to prevent more than 10 tabs from opening.

```html
<aura:component implements="lightning:backgroundUtilityItem">
  <aura:handler event="lightning:tabCreated" action="{! c.onTabCreated }" />
  <lightning:workspaceAPI aura:id="workspace" />
</aura:component>
```

In your client-side controller, limit the number of tabs when a new tab is created.

```javascript
({
  onTabCreated: function (cmp) {
    var workspace = cmp.find("workspace");
    workspace.getAllTabInfo().then(function (tabInfo) {
      if (tabInfo.length > 10) {
        workspace.closeTab({
          tabId: tabInfo[0].tabId,
        });
      }
    });
  },
});
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=a0eaa434f763dce1b798b15573f5f64c50075429cc78f5aae7611927d45c5aa1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/badge/lightning-badge.md -->


# Badge

**`lightning-badge`**

Represents a label which holds a small amount of information, such as the number of unread notifications.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="badge" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-badge` component is a label that holds small amounts of information. A
badge can show the status of unread notifications, or provide a label for a block of
text. Badges don't work for navigation because they can't include a hyperlink.

You can create two types of badges.

- A text-only badge
- A badge with an icon that appears before or after the text

Here’s an example of a text-only badge.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-badge label="Account Name"> </lightning-badge>
</template>
```
<!-- prettier-ignore-end -->

To create a badge with an icon, set the `icon-name` to a Lightning Design System icon. The icon appears before the text by default.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-badge label="Account Name" icon-name="standard:account">
    </lightning-badge>
</template>
```
<!-- prettier-ignore-end -->

To place the icon after the text, set `icon-position="end"`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-badge
        label="Starred Accounts"
        icon-name="custom:custom11"
        icon-position="end"
    >
    </lightning-badge>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-badge` implements the badge blueprint in the Salesforce Lightning Design System (SLDS). The badge adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Badge](https://v1.lightningdesignsystem.com/components/badges/)                                                                      | [Badge](https://www.lightningdesignsystem.com/components/badges/)                                               |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of icons and utility classes to style your badges.

### Icons

See the [SLDS icons](https://v1.lightningdesignsystem.com/icons) for available icons.

**note:** When applying SLDS classes or icons, check that they’re available in the SLDS release tied to your org. The latest SLDS resources become available only when the new release is available in your org.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

Change the badge color by using an SLDS class.
See [colors](https://v1.lightningdesignsystem.com/components/badges/#Colors) for more information.

This example creates a green badge by using the `slds-theme_success` SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-badge label="Approved" class="slds-theme_success"> </lightning-badge>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

Badges with nested elements are not supported. To create a label that contains links, use [`lightning-pill`](/docs/platform/lightning-component-reference/guide/lightning-pill.html) instead.


:::::

:::::tab
::component-specification{component="badge" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0b3c77297e336284028b0ee7662524d4a1af11dcabc593150bfa789e3a3d3149 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/barcodeScanner/lightning-barcode-scanner.md -->

# Barcode Scanner

**`lightning-barcode-scanner`**

Scans barcodes on a mobile device.

**For Use In**

Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-barcode-scanner` component embeds a barcode scanning function displayed as an icon, which launches the barcode scanner when the user clicks it. For more information on the API this component uses, see [Use the BarcodeScanner API](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner.html) in the Lightning Web Components Developer Guide.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner> </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

To disable the barcode scanner, set the `disabled` attribute. The barcode scanner is enabled by default.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner disabled> </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

## Scanning Modes

Barcode scanning supports both single scan and continuous scan. A single scan component automatically closes after one successful scan, while a continuous scan component remains open. The `lightning-barcode-scanner` component is single scan by default.

To enable continuous scanning, set the `enable-continuous-scan` attribute.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner enable-continuous-scan>
  </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

## Scanner Options

The BarcodeScanner API for `lightning-barcode-scanner` supports various scanner options. For the list of barcode scanner option properties, see [BarcodeScannerOptions](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-barcodescanner-data-types) in the Lightning Web Components Developer Guide.

You can configure various scanner options for a scanning session. For example, if you want your component to support only a specific set of barcode types, specify the types as a list in the `barcodeTypes` property. If you want to modify the size of the scanner camera view, specify the size in the `scannerSize` property. In this example, the barcode scanner supports only the specified types `CODE_128`,`EAN_13`, and `QR`, and will ignore the other types, and the barcode scanner camera view is changed to `LARGE`.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner scanner-options={myScannerOptions}>
  </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

```javascript
const myScannerOptions = {
  barcodeTypes: ["CODE_128", "QR", "EAN_13"],
  scannerSize: "LARGE",
};
```

## Icons

To specify an icon size for the barcode scanner component, set the `icon-size` attribute. By default, the `icon-size` is medium.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner icon-size="large"> </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

To set custom assistive technology text for the component icon in its enabled and disabled state, set the `enabled-alternative-text` and `disabled-alternative-text` attributes.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner
    enabled-alternative-text="Alt text for the enabled icon"
    disabled-alternative-text="Alt text for the disabled icon"
  >
  </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

You can also create a custom icon for the component by specifying images and alternative texts to use in the component's enabled and disabled states.

To use a custom image for the barcode scanner icon, set the `enabled-icon-src` and `disabled-icon-src` attributes to image paths in the `staticResource` folder. This example uses custom image for the component's icon enabled and disabled states.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-barcode-scanner
    enabled-icon-src="path/to/staticResource/enabled_image"
    enabled-alternative-text="Alt text for the custom enabled icon"
    disabled-icon-src="path/to/staticResource/disabled_image"
    disabled-alternative-text="Alt text for the custom disabled icon"
  >
  </lightning-barcode-scanner>
</template>
```
<!-- prettier-ignore-end -->

## Custom Events

The `lightning-barcode-scanner` component supports two events, `scan` and `error`.

The `scan` event is triggered by a successful scan on a single scan component or by successfully closing the scanner window on a multiple scan component. It returns this parameter.

| Parameter       | Type | Description                           |
| --------------- | ---- | ------------------------------------- |
| scannedBarcodes | list | Returns an array of scanned barcodes. |

The `scan` event has these properties.

| Property   | Value | Description                                                                                                  |
| ---------- | ----- | ------------------------------------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                                                  |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event to prevent firing the click event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                               |

The `errors` event is triggered if there is an error during the scan. The event contains the error details. It returns this parameter.

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| error     | object | Returns the error details. |

The `errors` event has these properties.

| Property   | Value | Description                                                                                                  |
| ---------- | ----- | ------------------------------------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                                                  |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event to prevent firing the click event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                               |


:::::

:::::tab
::component-specification{component="barcodeScanner" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6c548cd1d2000de905d14b0dfc3e24a5a4f9b22754144b40f90b42d3886be69d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/beforeLoadingResources/ltng-before-loading-resources.md -->

# Before Loading Resources

**`ltng:beforeLoadingResources`**

Fired before [`ltng:require`](/docs/platform/lightning-component-reference/guide/ltng-require.html) attempts to load the requested resources.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

For more information, see the [`ltng:require` documentation](/docs/platform/lightning-component-reference/guide/ltng-require.html).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=4b3dee8d9685dd06ded1139afbfd792667fda579fd0cefb4334b994e24dc106e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/breadcrumb/lightning-breadcrumb.md -->

# Breadcrumb

**`lightning-breadcrumb`**

An item in the hierarchy path of the page the user is on.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A `lightning-breadcrumb` component shows the path of a page relative to a
parent page. Nest `lightning-breadcrumb` in a `lightning-breadcrumbs` component.
Each breadcrumb is actionable and separated by a greater-than sign. The order
the breadcrumbs appear depends on the order they’re listed in markup.

Here's an example.

<!-- prettier-ignore-start -->
```html
<template>
    <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>
</template>
```
<!-- prettier-ignore-end -->

## Design

Use `lightning-breadcrumb` within [`lightning-breadcrumbs`](/docs/platform/lightning-component-reference/guide/lightning-breadcrumbs.html), which implements the breadcrumbs blueprint in the Salesforce Lightning Design System (SLDS). The breadcrumbs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Breadcrumbs](https://v1.lightningdesignsystem.com/components/breadcrumbs/)                                                           | [Breadcrumbs](https://www.lightningdesignsystem.com/components/breadcrumb/)                                     |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Links Using Breadcrumbs

The behavior of a breadcrumb is similar to a link that's for navigation. If a link isn’t provided via the `href` attribute, the value defaults to `#`. Since a breadcrumb is for navigation, we don't recommend leaving out the `href` attribute because `#` links to the same page when middle-clicked or opened in a new tab.

To provide custom navigation, use an `onclick` handler with [`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html). If you provide a link in the `href` attribute, calling `event.preventDefault()` enables you to bypass the link and use your custom navigation instead.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-breadcrumbs>
        <lightning-breadcrumb
            label="Parent Account"
            href="path/to/place/1"
            onclick={handleNavigateToCustomPage1}
        >
        </lightning-breadcrumb>
        <lightning-breadcrumb
            label="Case"
            href="path/to/place/2"
            onclick={handleNavigateToCustomPage2}
        >
        </lightning-breadcrumb>
    </lightning-breadcrumbs>
</template>
```
<!-- prettier-ignore-end -->

Handle the `click` events in your JavaScript code.

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

export default class DemoBreadcrumbs extends LightningElement {

handleNavigateToCustomPage1(event) {
    event.preventDefault();
    //your custom navigation here
}
handleNavigateToCustomPage2(event) {
    event.preventDefault();
    //your custom navigation here
}
```

## Generate Breadcrumbs with Iteration

Iterate over a list of items by using `for:each` to generate breadcrumbs. If you don't provide a link with an `onclick` handler, `href` defaults to `#`.

For example, you can create an array of breadcrumbs with label and name values.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-breadcrumbs>
        <template for:each={myBreadcrumbs} for:item="crumbs">
            <lightning-breadcrumb
                key={crumbs.id}
                label={crumbs.label}
                name={crumbs.name}
                onclick={handleNavigateTo}
            >
            </lightning-breadcrumb>
        </template>
    </lightning-breadcrumbs>
</template>
```
<!-- prettier-ignore-end -->

Get the name of the breadcrumb that's clicked by using the `event.target` property.

```javascript
//mybreadcrumbs.js
import { LightningElement, track } from "lwc";

export default class MyComponentName extends LightningElement {
  @track
  myBreadcrumbs = [
    { label: "Account", name: "objectName", id: "account1" },
    { label: "Record Name", name: "record", id: "account2" },
  ];

  handleNavigateTo(event) {
    //get the name of the breadcrumb that's clicked
    const name = event.target.name;
    event.preventDefault();
    //your custom navigation here
  }
}
```

## Usage Considerations

A breadcrumb shows your location in an app's hierarchy, not your browsing history. Breadcrumbs are especially useful when you want to go to a parent page from another page in the app. They also help you situate yourself in the app.

Breadcrumbs are commonly used with a tree for navigating between nested pages. The full hierarchy path is listed on a second or third level page.

Creating breadcrumbs with an overflow menu using `lightning-breadcrumbs` isn't currently supported.

## See Also

[`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html)


:::::

:::::tab
::component-specification{component="breadcrumb" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=51cedd95341b1618ae70abc789fe7facbd90c9caf6b3ffdcd687b0240fb2b975 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/breadcrumbs/lightning-breadcrumbs.md -->


# Breadcrumbs

**`lightning-breadcrumbs`**

A hierarchy path of the page you're currently visiting within the website or app.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="breadcrumbs" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-breadcrumbs` component is an ordered list that shows the path of a page and helps you navigate back to the parent.
Each breadcrumb item is a `lightning-breadcrumb` component. Breadcrumbs are actionable and separated by a greater-than sign.

For more information, see the [`lightning-breadcrumb`](/docs/platform/lightning-component-reference/guide/lightning-breadcrumb.html) documentation.

## Design

`lightning-breadcrumbs` implements the breadcrumbs blueprint in the Salesforce Lightning Design System (SLDS). The breadcrumbs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Breadcrumbs](https://v1.lightningdesignsystem.com/components/breadcrumbs/)                                                           | [Breadcrumbs](https://www.lightningdesignsystem.com/components/breadcrumb/)                                     |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use utility classes to style your breadcrumbs.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin around the breadcrumbs using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-breadcrumbs class="slds-m-around_small">
    <lightning-breadcrumb
        label="Parent Account"
        href="http://example.com/parent"
    >
    </lightning-breadcrumb>
    <lightning-breadcrumb label="Case" href="http://example.com/case">
    </lightning-breadcrumb>
</lightning-breadcrumbs>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

`lightning-breadcrumbs` renders with `role="navigation"`, which is a landmark role that enables screen readers to provide keyboard navigation to the links on the breadcrumbs.
The `aria-label="Breadcrumbs"` property is rendered automatically to inform screen readers the navigation type. Screen readers read both the role and the label description.

If your page includes another navigation landmark besides the breadcrumbs, you can use a different label for the other navigation landmark. Updating the `aria-label` property on `lightning-breadcrumbs` is currently not supported.

The last breadcrumb item usually corresponds to the current page that a user is viewing.
This breadcrumb item renders with `aria-current="page"`, which is announced by the screen reader as the current page within a set of navigation links.


:::::

:::::tab
::component-specification{component="breadcrumbs" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=69093a877abd965492d3b14a69b6a242d261c16b8713ae691d37296d7ca3a49f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/button/lightning-button.md -->


# Button

**`lightning-button`**

A clickable element used to perform an action.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="button" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button` component represents a button element that runs an
action. Use `lightning-button` to:

- Submit or reset a form
- Begin a new task
- Trigger a new UI element to appear on the page
- Specify a new or next step in a process

Use the `type` attribute to specify `button`, `submit`, or `reset`. The default type is `button`.

The `submit` and `reset` types create buttons for submitting and resetting form data.
Use these button types in `lightning-record-edit-form` and the HTML `form` element. The `reset` type button only deletes the values in the form fields without interacting with the database. For information about resetting the form fields to their initial values, see
[`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html).

For the default button, clicking the button triggers the `click` event. Use an `onclick` handler to perform the button's action.

You can create a button with a label only, or add the `icon-name` attribute
for a button with a label and icon. To create an icon-only
button, use the `lightning-button-icon` component instead.

Here's an example that creates a button with the `brand` variant, and shows
`label` text on the button. The `title` attribute provides tooltip text for the button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button
        variant="brand"
        label="Start"
        title="Begins the task"
        onclick={handleClick}
    >
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Here's another example that creates a button with the `brand` variant, with a label
and icon. The button places the icon to the left
of the label by default, so the example uses `icon-position` to place the icon on the right.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button
        variant="brand"
        label="Download"
        icon-name="utility:download"
        icon-position="right"
        onclick={handleClick}
    >
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

You can retrieve the label of the button that's clicked by using `event.target`. For
example, to retrieve the label on the button, use `event.target.label`.

You can also use the `stretch` attribute to expand the button to the full available width. In this example, the button stretches horizontally to fit the full `<div>` container.

<!-- prettier-ignore-start -->
```html
<div>
    <lightning-button
        variant="brand"
        label="Get Started"
        title="Get Started"
        stretch
    ></lightning-button>
</div>
```
<!-- prettier-ignore-end -->

## Design

`lightning-button` implements the buttons blueprint in the Salesforce Lightning Design System (SLDS). The buttons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Buttons](https://v1.lightningdesignsystem.com/components/buttons/)                                                                   | [Buttons](https://www.lightningdesignsystem.com/components/buttons/)                                            |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of icons, variants, and utility classes to customize your button styles.

### Icons

Use the `icon-name` attribute to add a utility icon to the button.

The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) provides nearly 200 utility
icons that can be used in `lightning-button` along with label text. Although
SLDS provides several categories of icons, only the utility category can be used in `lightning-button`.

### Variants

Use the `variant` attribute with one of these values to apply styling and animation.

- `base` is a button without a border, which gives it the look of a plain text link.
- `neutral` is the default variant, a plain uncolored button.
- `brand` is a blue button, used to draw attention to the primary action on a page.
- `brand-outline` is similar to `brand` but the color is used for the label and border only, not the button color.
- `destructive` is a red button used to warn users that its action has a negative effect.
- `destructive-text` is similar to `destructive` but only the label and border are red.
- `inverse` uses the background color and light text, useful for dark backgrounds.
- `success` is a green button used to indicate a successful action.

### Animation

Buttons are animated by default. For the `base` variant, an underline is drawn when you mouse over the button. For the other variants, a ripple of contrasting color appears when you click the button.

When a button is disabled, the animation is disabled as well.

If your browser or operating system is set to reduce animation, the button animations don't appear.

To prevent animation for a button, use the `disable-animation` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button
        variant="brand"
        label="Start"
        title="Begins the task"
        disable-animation
        onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

We recommend setting this attribute only when you place `lightning-button` near other
buttons that aren't animated, for consistency.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin to the left of the second button by using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-button label="Cancel" title="Cancel"></lightning-button>
<lightning-button
    variant="brand"
    label="Brand"
    title="Primary action"
    class="slds-m-left_x-small"
></lightning-button>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-button` supports these component styling hooks.

| CSS Custom Property                  | `lightning-button` Variants                      |
| ------------------------------------ | ------------------------------------------------ |
| `--slds-c-button-*`                  | all                                              |
| `--slds-c-button-color-*`            | `base`                                           |
| `--slds-c-button-text-color-*`       | `neutral` (default), `base`, and `brand-outline` |
| `--slds-c-button-neutral-*`          | `neutral` (default)                              |
| `--slds-c-button-brand-*`            | `brand`                                          |
| `--slds-c-button-outline-brand-*`    | `brand-outline`                                  |
| `--slds-c-button-destructive-*`      | `destructive`                                    |
| `--slds-c-button-text-destructive-*` | `destructive-text`                               |
| `--slds-c-button-inverse-*`          | `inverse`                                        |
| `--slds-c-button-success-*`          | `success`                                        |

## Usage Considerations

To create an icon-only button, use the `lightning-button-icon` component instead. Creating an icon-only button by using `lightning-button` results in additional spacing next to the icon. To create a button that triggers a menu, use `lightning-button-menu`.

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.

If you're creating forms to interact with Salesforce records, consider `lightning-record-form` or `lightning-record-edit-form` instead of creating your own.

On mobile screens, we recommend setting the button size to
44x44 px. If you have more than one target on a screen that performs the same action, only one of the targets needs to meet the target size of 44x44 px. For more information, see [Follow Accessible Mobile Design Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/mobile-a11y).

## Accessibility

Buttons must have an accessible name for assistive technology to announce the button's purpose. Provide this name by using the `label` attribute and make it a clear call to action, for example, "Edit record".

If you create an icon-only button with `lightning-button`, provide an accessible name by using the `aria-label` or `aria-labelledby` attribute. We recommend that you use one of the attributes but not both.

To provide a text label that's not visible on the screen, use `aria-label`.

<!-- prettier-ignore-start -->
```html
<lightning-button
    aria-label="Download"
    icon-name="utility:download"
    variant="base"></lightning-button>
```
<!-- prettier-ignore-end -->

To associate the button with text from another element, use `aria-labelledby`.

<!-- prettier-ignore-start -->
```html
<h2 id="downloadLabel">Download Files</h2>
<h3 id="downloadDesc">View and make changes to your files</h3>
<lightning-button
    aria-labelledby="downloadLabel downloadDesc"
    icon-name="utility:download"
    variant="base"></lightning-button>
```
<!-- prettier-ignore-end -->

To use `aria-label` with additional descriptive text, use `aria-describedby`.

<!-- prettier-ignore-start -->
```html
<lightning-button
    aria-label="Close"
    aria-describedby="descriptionClose"
    icon-name="utility:close"
    variant="base"></lightning-button>


<div id="descriptionClose">Closing this window resets the form and
returns you back to the main page.</div>
```
<!-- prettier-ignore-end -->

`lightning-button` provides many variants that add color to a button, which convey different meaning on a button. Use the variants together with clear text on the button to match the meaning you’re trying to convey via color. For example, if you use the destructive button to point out a potential warning, make sure that the text communicates the same message.

To inform screen readers that a button is disabled, include the `disabled` attribute.

Use these accessibility and `aria` attributes on `lightning-button`.

| Attribute        | Type              | Description                                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accesskey        | string            | A shortcut key to activate or place focus on the button.                                                                                                                                                                                                                                                                                                  |
| aria-atomic      | boolean           | Specifies whether the screen reader should always present the live region as a whole, even if only part of the region changes. The default is `false`.                                                                                                                                                                                                    |
| aria-controls    | ID reference list | An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.                                                                                                                                                                                                                                            |
| aria-describedby | ID reference list | An element ID or a space-separated list of element IDs that provide a descriptive label or description for the button.                                                                                                                                                                                                                                    |
| aria-expanded    | boolean           | Indicates whether a collapsible element that's controlled by the button is expanded or collapsed. To reference the controlled element, use `aria-controls`.                                                                                                                                                                                               |
| aria-haspopup    | token             | Indicates that the button has an interactive popup element. Valid values are 'true', 'dialog', 'menu', 'listbox', 'tree', and 'grid'.                                                                                                                                                                                                                     |
| aria-label       | string            | Provides an assistive label where a visible label can’t be used.                                                                                                                                                                                                                                                                                          |
| aria-labelledby  | ID reference list | Specifies the ID or list of IDs of the element or elements that contain visible descriptive text to describe the button.                                                                                                                                                                                                                                  |
| aria-live        | token             | Indicates that the button can dynamically update without a page reload, and specifies how the change is announced by assistive technologies. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`. |
| tabindex         | integer           | Specifies whether the button is focusable during tab navigation. Set the tab index to -1 to prevent focus on the button during tab navigation. The default value is 0, which makes the button focusable during tab navigation. For more information, see [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex).        |

For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).


:::::

:::::tab
::component-specification{component="button" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=014d8c2576a1bd71a37bb7a23f48e6b7b5a91bad92550d758f52eaa0e75710aa url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonGroup/lightning-button-group.md -->


# Button Group

**`lightning-button-group`**

Represents a group of buttons.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonGroup" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button-group` component represents a set of buttons that appear together to create a navigational bar. The body of the component can contain one or more of these components:

- [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html)
- [`lightning-button-icon`](/docs/platform/lightning-component-reference/guide/lightning-button-icon.html)
- [`lightning-button-icon-stateful`](/docs/platform/lightning-component-reference/guide/lightning-button-icon-stateful.html)
- [`lightning-button-menu`](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html)
- [`lightning-button-stateful`](/docs/platform/lightning-component-reference/guide/lightning-button-stateful.html)

To create navigational tabs, use [`lightning-tabset`](/docs/platform/lightning-component-reference/guide/lightning-tabset.html) instead of `lightning-button-group`.

When you use `lightning-button-menu`, set `variant="border-filled"` on the button menu for a white button background. Otherwise, the `lightning-button-menu` background is transparent by default.

To create buttons, use the `lightning-button` component as shown in this example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-group>
        <lightning-button label="Alpha"></lightning-button>
        <lightning-button label="Beta"></lightning-button>
        <lightning-button label="Gamma"></lightning-button>
    </lightning-button-group>
</template>
```
<!-- prettier-ignore-end -->

Handle clicks by using the `onclick` handler.

<!-- prettier-ignore-start -->
```html
<lightning-button-group>
    <lightning-button label="Edit" onclick={handleClick}></lightning-button>
    <lightning-button label="View" onclick={handleClick}></lightning-button>
</lightning-button-group>
```
<!-- prettier-ignore-end -->

In your JavaScript code, use the `event.target` property to retrieve the label of the clicked button.

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

export default class DemoApp extends LightningElement {
  handleClick(event) {
    const buttonLabel = event.target.label;
    //  Handle clicks
  }
}
```

To handle navigation within Lightning Experience and the Salesforce app, use the [`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html) component.

## Design

`lightning-button-group` implements the button groups blueprint in the Salesforce Lightning Design System (SLDS). The button groups adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Button Groups](https://v1.lightningdesignsystem.com/components/button-groups/)                                                       | [Button Groups](https://www.lightningdesignsystem.com/components/button-groups/)                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

To apply additional styling, use SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

You can customize the `lightning-button-*` base components you use within `lightning-button-group` by using SLDS styling hooks. For more information, see the corresponding base component documentation.

## See Also

[lightning-navigation](/docs/platform/lightning-component-reference/guide/lightning-navigation.html)

[Navigate to Pages](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate)


:::::

:::::tab
::component-specification{component="buttonGroup" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=3e46c007c43fca14cd339792e2a44efe282c28a084ca4694935e0fec58f2f65b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonIcon/lightning-button-icon.md -->


# Button Icon

**`lightning-button-icon`**

A button that contains only an icon.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonIcon" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button-icon` component represents an icon-only button element that
runs an action. Clicking the button triggers the JavaScript
method set for `onclick`.

Here’s an example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-icon
        icon-name="utility:close"
        variant="bare"
        onclick={handleClick}
        alternative-text="Close window"
    >
    </lightning-button-icon>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-button-icon` implements the button icons blueprint in the Salesforce Lightning Design System (SLDS). The button icons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Button Icons](https://v1.lightningdesignsystem.com/components/button-icons/)                                                         | [Button Icons](https://www.lightningdesignsystem.com/components/button-icons/)                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of the `icon-class`, `size`, `variant`, and `class`
attributes to customize the button and icon styles.

To customize styling on the icon element, use the
`icon-class` attribute. This example creates an icon-only button with bare
variant and icon styling. `icon-class` supports SLDS utility classes only.

<!-- prettier-ignore-start -->
```html
<lightning-button-icon
    icon-name="utility:settings"
    variant="bare"
    alternative-text="Settings"
    icon-class="slds-m-around_medium"
>
</lightning-button-icon>
```
<!-- prettier-ignore-end -->

### Icons

Use the `icon-name` attribute to add a utility icon to the button.

The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) offers nearly 200 utility
icons for use with `lightning-button-icon`. You can use only the utility category with `lightning-button-icon`.

**note:** When applying SLDS classes or icons, check that they’re
available in the SLDS release tied to your org. The latest
SLDS resources become available only when the new release
is available in your org.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `bare` shows an icon without a container or border
- `bare-inverse` shows an icon in white color without a container or border, useful for dark backgrounds
- `border` is the default variant, an icon in a transparent container with a border
- `border-filled` shows an icon in a filled container with a border
- `border-inverse` shows an icon in a transparent container with a border, useful for dark backgrounds
- `brand` shows an icon in white color in a blue container with a blue border
- `container` shows an icon in a transparent container without a border

For the `bare` and `bare-inverse` variants, the `size` class applies to the icon itself. For all other variants, the `size` class applies to the button.

Add the `disabled` attribute to prevent interaction with the button icon.

### Sizes

Adjust the button and icon sizes by using the `size` attribute with one of these values.

For `bare` and `bare-inverse` variants:

- `medium` is the default size, which creates a 14px by 14px icon
- `small` creates a 12px by 12px icon
- `x-small` creates a 8px by 8px icon
- `large` creates a 24px by 24px icon

For other variants:

- `medium` is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
- `small` creates a 24px by 24px button enclosing a 14px by 14px icon
- `x-small` creates a 20px by 20px button enclosing a 12px by 12px icon
- `xx-small` creates a 16px by 16px button enclosing a 8px by 8px icon

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin to the left of the second button by using the `slds-m-left_xx-small` class.

<!-- prettier-ignore-start -->
```html
<lightning-button-icon
    icon-name="utility:zoomin"
    alternative-text="Zoom in"
    title="Zoom in"
></lightning-button-icon>
<lightning-button-icon
    icon-name="utility:zoomout"
    alternative-text="Zoom out"
    title="Zoom out"
    class="slds-m-left_xx-small"
></lightning-button-icon>
```
<!-- prettier-ignore-end -->

To apply custom styling, use the `:host` selector or define a custom class by using the `class` attribute.

<!-- prettier-ignore-start -->
```html
<lightning-button-icon
    icon-name="utility:zoomin"
    alternative-text="Zoom in"
    title="Zoom in"
    class="my-round-button"
></lightning-button-icon>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-button-icon` contains the same customizable elements as `lightning-button`, which supports `--slds-c-button-*` custom properties. Custom properties for button icons work only with specific `lightning-button-icon` variants.

| CSS Custom Property                | `lightning-button-icon` Variants                             |
| ---------------------------------- | ------------------------------------------------------------ |
| `--slds-c-button-color-background` | `border` (default), `bare`, `bare-inverse`, and `container`  |
| `--slds-c-button-color-border`     | `bare`, `bare-inverse`, and `container`                      |
| `--slds-c-button-text-color`       | N/A                                                          |
| `--slds-c-button-text-color-*`     | `border` (default), `bare`, `container`, and `border-filled` |
| `--slds-c-button-radius-border`    | all                                                          |
| `--slds-c-button-sizing-border`    | `bare`, `bare-inverse`, `border-inverse`, and `container`    |

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) in the Lightning Web Components Developer Guide.

## Usage Considerations

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.

## Accessibility

`lightning-button-icon` contains an informational icon, which conveys information that surrounding text doesn't.
For each icon, provide assistive text that describes the button's action.

Use the `alternative-text` attribute to describe the icon. The description indicates what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.

The description you provide to `alternative-text` is available to users in two ways.

- As hover text when you hover over the button
- As hidden text for assistive technologies

To override the hover text provided by `alternative-text`, use the `title` attribute, which corresponds to the native browser tooltip.
The description you provide to `title` appears when you hover over the button. To support touch-only devices, keyboard navigation, and assistive technologies, use `title` together with `label` or `alternative-text`.

To show a contextual popup on the button, use the `tooltip` attribute.
The popup becomes visible when you hover over the button, or after the button receives keyboard focus. Showing the popup on hover or on keyboard focus makes sure that all users can access it, even if they aren’t using a mouse. The button is rendered with `aria-describedby`, linking it to the ID of the popup, which helps assistive technology read the popup content.

If you use both `title` and `tooltip` attributes, they’re both visible when you hover over the button. Some screen readers don’t support the `title` attribute and many of them don’t read the `title` attribute by default.

<!-- prettier-ignore-start -->
```html
<lightning-button-icon
    icon-name="utility:settings"
    title="Settings"
    tooltip="Display your account settings"
    alternative-text="Hidden text for assistive technology"
>
</lightning-button-icon>
```
<!-- prettier-ignore-end -->

For sighted users, make sure your description on `title` and `tooltip` aren’t repetitive. We recommend providing detailed information to `tooltip` and make `title` more concise if you use both.

Buttons that show an icon instead of text don’t have an accessible name. To provide an accessible name in `lightning-button-icon`, use the `aria-label` attribute. If there’s visible text for the element, use `aria-labelled-by` instead.

To inform screen readers that a button is disabled, set the `disabled` attribute to true.

Use these accessibility and `aria` attributes on `lightning-button-icon`.

| Attribute        | Type              | Description                                                                                                                                                                                                                                                                                                                                               |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accesskey        | string            | A shortcut key to activate or place focus on the button.                                                                                                                                                                                                                                                                                                  |
| aria-atomic      | boolean           | Specifies whether the screen reader always presents the live region as a whole, even if only part of the region changes. The default is `false`.                                                                                                                                                                                                          |
| aria-controls    | ID reference list | An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.                                                                                                                                                                                                                                            |
| aria-describedby | ID reference list | An element ID or a space-separated list of element IDs that provide descriptive labels for the button.                                                                                                                                                                                                                                                    |
| aria-expanded    | boolean           | Indicates whether a collapsible element that's controlled by the button is expanded or collapsed. To reference the controlled element, use `aria-controls`.                                                                                                                                                                                               |
| aria-haspopup    | token             | Indicates that the button has an interactive popup element. Valid values are 'true', 'dialog', 'menu', 'listbox', 'tree', and 'grid'. To create a button that displays a list of menu items when clicked, use `lightning-button-menu` instead.                                                                                                            |
| aria-label       | string            | Provides an assistive label where a visible label can’t be used.                                                                                                                                                                                                                                                                                          |
| aria-live        | token             | Indicates that the button can dynamically update without a page reload, and specifies how the change is announced by assistive technologies. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`. |
| tabindex         | integer           | Specifies whether the button is focusable during tab navigation. Set the tab index to -1 to prevent focus on the button during tab navigation. The default value is 0, which makes the button focusable during tab navigation. For more information, see [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex).        |

For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).


:::::

:::::tab
::component-specification{component="buttonIcon" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=89bb43e37984ace55a83c431d5dc5090071ae99a14605e3f469a93914de269c1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonIconStateful/lightning-button-icon-stateful.md -->


# Button Icon Stateful

**`lightning-button-icon-stateful`**

An icon-only button that retains state.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonIconStateful" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button-icon-stateful` component represents an icon-only button
element that toggles between two states. For example, you can use this
component for capturing a customer's feedback on a blog post (like or
dislike). Clicking the button triggers the handler set for `onclick`.
You can change the state of the icon by using the `selected` attribute.

This example creates a Like button that toggles between two states. The Like button is selected by default. The button's state is stored in the `selected` attribute.

Selecting the Dislike button also toggles the state on the Like button and deselects it.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-icon-stateful
        icon-name="utility:like"
        selected={liked}
        alternative-text="Like"
        onclick={handleToggle}
    >
    </lightning-button-icon-stateful>
</template>
```
<!-- prettier-ignore-end -->

Handle the `click` event in your JavaScript code.

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

export default class MyComponentName extends LightningElement {
  liked = true;

  handleToggle() {
    this.liked = !this.liked;
  }
}
```

## Design

`lightning-button-icon-stateful` implements the button icons blueprint in the Salesforce Lightning Design System (SLDS). The button icons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Button Icons (Stateful)](https://v1.lightningdesignsystem.com/components/button-icons/#Stateful)                                     | [Button Icons](https://www.lightningdesignsystem.com/components/button-icons/#Stateful)                         |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of `icon-name`, `variant`, `size`, and `class` attributes to
customize the button and icon styles.

### Icons

Use the `icon-name` attribute to add a utility icon to the button.

The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) offers nearly 200 utility
icons that can be used in `lightning-button-icon-stateful`. Although the
SLDS provides several categories of icons, only the utility
category can be used with this component.

**note:** When applying SLDS classes or icons, check that they are
available in the SLDS release tied to your org. The latest
SLDS resources become available only when the new release is available in your org.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `border` is the default variant, an icon in a transparent container with a border
- `border-filled` shows an icon in a filled container with a border
- `border-inverse` shows an icon in a transparent container with a border, useful for dark backgrounds

### Sizes

Adjust the button and icon sizes by using the `size` attribute with one of these values.

- `medium` is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
- `small` creates a 24px by 24px button enclosing a 14px by 14px icon
- `x-small` creates a 20px by 20px button enclosing a 12px by 12px icon
- `xx-small` creates a 16px by 16px button enclosing a 8px by 8px icon

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin to the left of the second button by using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-button-icon-stateful
    icon-name="utility:like"
    selected={likeState}
    onclick={handleLikeButtonClick}
    alternative-text="Like"
></lightning-button-icon-stateful>
<lightning-button-icon-stateful
    icon-name="utility:answer"
    selected={answerState}
    onclick={handleAnswerButtonClick}
    alternative-text="Answer"
    class="slds-m-left_xx-small"
></lightning-button-icon-stateful>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


CSS custom properties for stateful button icons work only with specific `lightning-button-icon-stateful` variants.

| CSS Custom Property                | `lightning-button-icon-stateful` Variants |
| ---------------------------------- | ----------------------------------------- |
| `--slds-c-button-color-background` | `border` (default) and `border-inverse`   |
| `--slds-c-button-color-border`     | N/A                                       |
| `--slds-c-button-text-color`       | N/A                                       |
| `--slds-c-button-text-color-*`     | `border` (default) and `border-filled`    |
| `--slds-c-button-radius-border`    | all                                       |
| `--slds-c-button-sizing-border`    | N/A                                       |

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) in the Lightning Web Components Developer Guide.

## Usage Considerations

Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.

## Accessibility

`lightning-button-icon-stateful` contains an informational icon, which conveys information that surrounding text doesn't. Each icon should be accompanied by either assistive text.
When selected, the button renders with `aria-pressed="true"`. When not selected, the button renders with `aria-pressed="false"`.
The `aria-pressed` attribute enables screen readers to announce whether a button is pressed or not.

Use the `alternative-text` attribute to describe the icon.
The description should indicate what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.

The text is available to users in two ways.

- On the tooltip when you hover over the button
- As text for assistive technologies

Buttons that only show an icon to represent do not have an accessible name. For `lightning-button-icon-stateful`, provide the accessible name using the `aria-label` attribute.

Use the following accessibility and `aria` attributes on `lightning-button-icon-stateful`.

| Attribute        | Type              | Description                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accesskey        | string            | A shortcut key to activate or place focus on the button                                                                                                                                                                                                                                                                         |
| aria-atomic      | boolean           | Specifies whether the screen reader should always present the live region as a whole, even if only part of the region changes. The default is `false`.                                                                                                                                                                          |
| aria-controls    | ID reference list | An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.                                                                                                                                                                                                                  |
| aria-describedby | ID reference list | An element ID or a space-separated list of element IDs that provide a descriptive label or description for the button.                                                                                                                                                                                                          |
| aria-expanded    | boolean           | Indicates whether the state of an element, controlled by the button, is expanded or collapsed. To reference the controlled element, use `aria-controls`.                                                                                                                                                                        |
| aria-label       | string            | Provides an assistive label where a visible label cannot be used.                                                                                                                                                                                                                                                               |
| aria-live        | string            | Indicates whether the button will be updated, and describes the types of updates assistive technologies will make. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`. |

For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).


:::::

:::::tab
::component-specification{component="buttonIconStateful" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=e15643c7d5462baa3af6266cc4e523fe45c8522246b36ef628b4b415754cb430 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonMenu/lightning-button-menu.md -->


# Button Menu

**`lightning-button-menu`**

Represents a dropdown menu with a list of actions or functions.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonMenu" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button-menu` component represents a button that shows a
dropdown menu of actions or functions when you click it.

The menu closes when you click away from it. When you select a menu item,
the menu also closes and puts the focus back on the button.

Use [`lightning-menu-item`](/docs/platform/lightning-component-reference/guide/lightning-menu-item.html) components nested in `lightning-button-menu` to specify the menu items for the button menu.

This example shows how to create a dropdown button menu with three items. To add a text label to the button before the icon, use the `label` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu alternative-text="Settings">
        <lightning-menu-item label="Font" value="font"> </lightning-menu-item>
        <lightning-menu-item label="Size" value="size"> </lightning-menu-item>
        <lightning-menu-item label="Format" value="format">
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-button-menu` implements the menus blueprint in the Salesforce Lightning Design System (SLDS). The menus adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Menus](https://v1.lightningdesignsystem.com/components/menus/)                                                                       | [Menus](https://www.lightningdesignsystem.com/components/menus/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

The `lightning-button-menu` component supports several variants that change the look of the button. You can use a combination of the `variant`, `icon-name`, and `icon-size` attributes to customize the button and icon styles.

For more information, see the [Component Styling](#component-styling) section.

## Checked Menu Items

To create menu items that appear with a checkmark, use the `checked`
attribute in the `lightning-menu-item` component, toggling it as needed.

<!-- prettier-ignore -->
```html
<lightning-button-menu
  alternative-text="Formatting options"
  onselect={handleSelect}
>
  <lightning-menu-item
    value="bold"
    label="Bold"
    checked={isBold}
  ></lightning-menu-item>
  <lightning-menu-item
    value="italic"
    label="Italic"
    checked={isItalic}
  ></lightning-menu-item>
</lightning-button-menu>
```

To enable toggling of a menu item, you must set an initial value on the `checked`
attribute, specifying either `true` or `false`.

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

export default class ButtonMenuCheckedExample extends LightningElement {
  isBold = true; // initial value must be true/false
  isItalic = false;

  handleSelect(event) {
    const { value } = event.detail;
    if (value === "bold") this.isBold = !this.isBold;
    if (value === "italic") this.isItalic = !this.isItalic;
  }
}
```

## Create Dividers and Subheadings

Use the [`lightning-menu-divider`](/docs/platform/lightning-component-reference/guide/lightning-menu-divider.html) component to create a dividing line after a menu item.

Use the [`lightning-menu-subheader`](/docs/platform/lightning-component-reference/guide/lightning-menu-subheader.html) component to create subheadings in the list of menu items.

## Generate Menu Items

This example creates a button menu with several items during initialization. When working with an iterator, include a unique `key` value on `lightning-menu-item`. For more information, see [Render Lists](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.html) in the _Lightning Web Components Developer Guide_.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        alternative-text="Action"
        onselect={handleMenuSelect}
    >
        <template for:each={items} for:item="action">
            <lightning-menu-item
                label={action.label}
                value={action.value}
                key={action.label}
            >
            </lightning-menu-item>
        </template>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

The `items` array definition uses the `@track` decorator to track mutations in the array. If the value of `items` changes, the component's template rerenders.
Define `items` and handle the `select` event in your JavaScript code.

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

export default class DemoButtonMenu extends LightningElement {
  @track
  items = [
    {
      label: "Alpha",
      value: "alpha",
    },
    {
      label: "Beta",
      value: "beta",
    },
    {
      label: "Gamma",
      value: "gamma",
    },
  ];

  handleMenuSelect(event) {
    // retrieve the selected item's value
    const selectedItemValue = event.detail.value;

    // INSERT YOUR CODE HERE
  }
}
```

## Show the Loading State of a Menu

The `is-loading` attribute enables you to show an activity indicator while the menu is loading. You can
use this attribute, for example, to inform users that the menu is working while generating a large list of menu items.
When `is-loading` is `true`, the menu shows a spinner.

Use `loading-state-alternative-text` along with `is-loading` to specify explanatory text such as "Loading menu..." or
"Please wait while items load".

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        is-loading
        loading-state-alternative-text="Loading menu items"
    >
        <lightning-menu-item value="one" label="One"></lightning-menu-item>
        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Draft Indicators

Use the `is-draft` and `draft-alternative-text` attributes together to indicate that the button menu is in an unsaved state.
The draft indicator, an asterisk, is shown for the button menu when `is-draft` is `true`. Use the draft indicator with
the `draft-alternative-text` attribute to provide text describing the reason the menu is in a draft state.
Use the button menu's draft state to show there’s unsaved state or unsaved data, for example, if a user changes a customizable menu.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        is-draft
        draft-alternative-text="Menu has unsaved changes"
    >
        <lightning-menu-item value="one" label="One"></lightning-menu-item>
        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

Use a combination of the `icon-name`, `icon-size`, `variant`, and `class` attributes to customize the button and icon styles.

### Icons

By default, the button shows a utility:down icon to indicate the dropdown function.
Use the `icon-name` attribute to place an optional [utility icon](https://v1.lightningdesignsystem.com/icons/#utility)
in front of the utility:down icon. Use the `icon-size` attribute to change the icon size from the default size of `medium`.

When applying SLDS classes or icons, check that they’re
available in the SLDS release tied to your org. The Lightning
Design System site shows the latest SLDS resources, which
become available only when the new release is available in your org.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `border` - The default variant, which shows a gray border around the button's down arrow symbol. The area inside the border is transparent and clickable.
- `border-inverse` - Same as the `border` variant except the down arrow is white so it's visible on dark backgrounds.
- `border-filled` - Same as the `border` variant, except the area inside the border is white.
- `container` - Shows only the down arrow, without a visible border. The clickable area surrounding the down arrow is the same size as the default `border` variant and is transparent.
- `bare` - Same as the `container` variant, except the clickable area surrounding the down arrow is smaller than the default.
- `bare-inverse` - Same as the `bare` variant except the down arrow is white so it's visible on dark backgrounds.

### Sizes

Adjust the button and icon sizes by using the `size` attribute with one of these values.

For `bare` and `bare-inverse` variants:

- `medium` is the default size, which creates a 14px by 14px icon
- `small` creates a 12px by 12px icon
- `x-small` creates a 8px by 8px icon
- `large` creates a 24px by 24px icon

For other variants:

- `medium` is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
- `small` creates a 24px by 24px button enclosing a 14px by 14px icon
- `x-small` creates a 20px by 20px button enclosing a 12px by 12px icon
- `xx-small` creates a 16px by 16px button enclosing a 8px by 8px icon

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding around the button menu by using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-button-menu
    class="slds-p-around_medium"
    alternative-text="Show menu"
>
    <lightning-menu-item value="Edit" label="Edit"></lightning-menu-item>
    <lightning-menu-item value="Save" label="Save"></lightning-menu-item>
</lightning-button-menu>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-button-menu` supports these component styling hooks.

| CSS Custom Property                | `lightning-button-menu` Variants                                                                            |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--slds-c-button-color-background` | `border` (default), `bare`, `bare-inverse`, and `container`                                                 |
| `--slds-c-button-color-border`     | `bare`, `bare-inverse`, and `container`                                                                     |
| `--slds-c-button-text-color`       | `border` (default), `bare`, `bare-inverse`,`container`, and `border-filled`; use with the `label` attribute |
| `--slds-c-button-text-color-*`     | `border` (default), `bare`, `container`, and `border-filled`                                                |
| `--slds-c-button-radius-border`    | all                                                                                                         |
| `--slds-c-button-sizing-border`    | `bare`, `bare-inverse`, `border-inverse`, and `container`                                                   |

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) in the Lightning Web Components Developer Guide.

## Usage Considerations

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.

This component's menu items are created only if the button is
triggered. You can't reference the menu items during initialization
or if the button isn't triggered yet.

In Lightning Experience, a button menu that's in an open state overlays the record edit page or modal, the global header, and the record form footer when scrolling.

You can customize the alignment of the dropdown menu relative to the button by using `menu-alignment`.
If you’re using `lightning-button-menu` in a container that specifies the `overflow:hidden` CSS property,
setting `menu-alignment="auto"` makes sure that the dropdown menu isn’t hidden from view when the menu is toggled. For mobile devices, set `menu-alignment="auto"` to ensure proper display of the menu.

When using this component within `lightning-button-group`, set `variant="border-filled"` on `lightning-button-menu` for a white button background. Otherwise, the `lightning-button-menu` background is transparent by default.

## Accessibility

To inform screen readers that a button menu is disabled, set the `disabled`
attribute to `true`.

Buttons must have an accessible name to enable assistive technology to describe the button's purpose. Provide this name using the `alternative-text` or `label` attribute. Make it a clear action, such as "Show menu". To make the name available to assistive technology but hidden from view, use `alternative-text`.

`lightning-button-menu` is rendered with `aria-haspopup="true"` to indicate that the button opens a menu. The component also indicates whether the menu is currently expanded or collapsed using `aria-expanded="true"` or `aria-expanded="false"`.

For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).

To display a contextual popup over the button menu, use the `tooltip` attribute.
The popup becomes visible when you hover over the button, or after the button receives keyboard focus. Showing the popup on hover or on keyboard focus ensures that all users can access it, even if they aren’t using a mouse.

If you use both `title` and `tooltip` attributes, they are both visible when you hover over the button. Some screen readers don’t support the `title` attribute and many of them don’t read the `title` attribute by default.

<!-- prettier-ignore-start -->
```html
<lightning-button-menu
    icon-name="utility:settings"
    title="Settings"
    tooltip="Choose a settings category"
    alternative-text="Hidden text for assistive technology"
>
</lightning-button-menu>
```
<!-- prettier-ignore-end -->

For sighted users, make sure your descriptions for `title` and `tooltip` are not repetitive. We recommend providing detailed information to `tooltip` and making `title` more concise if you use both.

If you use the `is-loading` indicator, use `loading-state-alternative-text` to provide a description for users of assistive devices.

If you use the `is-draft` indicator, use `draft-alternative-text` to provide a description for users of assistive devices.

## Custom Events

**`select`**

The event fired when the menu is selected.

The `select` event returns the following parameter.

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| value     | string | The value of the selected option. |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

**`open`**

The event fired when you open the dropdown menu in one of the following ways.

- Tab to the button and press the Enter key
- Click the button that toggles the dropdown menu

The `open` event doesn’t return any parameters.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can’t call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

**`close`**

The event fired when you close the dropdown menu in one of the following ways.

- Select or unselect a dropdown menu item
- Click the button that toggles the dropdown menu
- Remove focus from the dropdown menu, such as by clicking outside of the dropdown menu or tabbing to another element on the page

The `close` event does not return any parameters.

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                         |


:::::

:::::tab
::component-specification{component="buttonMenu" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9ae56b9dadde860ec64284b2093947bf117c07a390c72ddbeaadd8bd4c91692d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonStateful/lightning-button-stateful.md -->


# Button Stateful

**`lightning-button-stateful`**

A button that toggles between states.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonStateful" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-button-stateful` component represents a button that toggles
between states, similar to a Like button on social media. Stateful buttons can
show a different label and icon based on their `selected` states.

To handle the state change when the button is clicked, use the `onclick` event
handler. This example enables you to toggle the button between states,
showing the "Follow" label by default, and replacing it with "Following"
when the button is selected. Selecting the button toggles the `selected` state to true,
and deselecting it toggles `selected` state to false. When the `selected` state is true, the
button shows "Unfollow" when you mouse over it or when it receives focus.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-stateful
        label-when-off="Follow"
        label-when-on="Following"
        label-when-hover="Unfollow"
        icon-name-when-off="utility:add"
        icon-name-when-on="utility:check"
        icon-name-when-hover="utility:close"
        selected={isSelected}
        onclick={handleClick}
    >
    </lightning-button-stateful>
</template>
```
<!-- prettier-ignore-end -->

The `handleClick()` function toggles the state via the `isSelected` attribute.

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

export default class MyComponentName extends LightningElement {
  isSelected = false;

  handleClick() {
    this.isSelected = !this.isSelected;
  }
}
```

`lightning-button-stateful` doesn't retrieve the button label from `event.target.label`. To work with the button labels, use the `labelWhenOff`,
`labelWhenOn`, and `labelWhenHover` attributes.

## Design

`lightning-button-stateful` implements the buttons blueprint in the Salesforce Lightning Design System (SLDS). The buttons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Buttons (Stateful)](https://v1.lightningdesignsystem.com/components/buttons/#flavor-stateful)                                        | [Buttons (Stateful)](https://www.lightningdesignsystem.com/components/buttons/#flavor-stateful)                 |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of icon names, variants, and utility classes to style your stateful buttons.

### Icons

Use the `icon-name` attribute to add a utility icon to the button.

The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) provides nearly 200 utility
icons that can be used in `lightning-button-stateful` along with a text label. Although SLDS provides several categories of icons, only the utility category can be used with this component.

When applying SLDS classes or icons, check that they are
available in the SLDS release tied to your org. The latest
SLDS resources become available only when the new release
is available in your org.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `neutral` is the default variant, a plain uncolored button.
- `brand` is a blue button, used to draw attention to the primary action on a page.
- `destructive` is a red button used to warn users that its action has a negative effect.
- `inverse` uses the background color and light text, useful for dark backgrounds.
- `success` is a green button used to indicate a successful action.
- `text` is a button without a border, which gives it the look of a plain text link.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on the button using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-button-stateful
    label-when-off="Follow"
    label-when-on="Following"
    label-when-hover="Unfollow"
    icon-name-when-off="utility:add"
    icon-name-when-on="utility:check"
    icon-name-when-hover="utility:close"
    selected={isSelected}
    onclick={handleClick}
    class="slds-p-around_medium"
>
</lightning-button-stateful>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-button-stateful` contains the same customizable elements as `lightning-button`, which supports `--slds-c-button-*` custom properties. CSS custom properties for stateful buttons work only with particular `lightning-button-stateful` variants.

| CSS Custom Property             | `lightning-button-stateful` Variants |
| ------------------------------- | ------------------------------------ |
| `--slds-c-button-*`             | all                                  |
| `--slds-c-button-color-*`       | `base`                               |
| `--slds-c-button-text-color-*`  | `neutral` (default) and `text`       |
| `--slds-c-button-neutral-*`     | `neutral` (default)                  |
| `--slds-c-button-brand-*`       | `brand`                              |
| `--slds-c-button-destructive-*` | `destructive`                        |
| `--slds-c-button-inverse-*`     | `inverse`                            |
| `--slds-c-button-success-*`     | `success`                            |

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) in the Lightning Web Components Developer Guide.

## Usage Considerations

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Accessibility

This component uses `aria-live="polite"`, which means the button label is read after the current user task or content.

To inform screen readers that a button is disabled, set the `disabled` attribute to true.


:::::

:::::tab
::component-specification{component="buttonStateful" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=83e5d6e87afe84f31e88c9f19c83378eae0349321663ec478320b7f1e8e4aa3d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/card/lightning-card.md -->


# Card

**`lightning-card`**

Cards apply a container around a related grouping of information.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="card" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-card` groups related information in a stylized container. The information can be a single item or a group of items such as a related list.

A `lightning-card` can contain a title, body, actions, and a footer. The title, actions, and footer are optional. You can also provide an icon in the header in front of the title.

Use the `actions` slot to pass content such as `lightning-button-icon` or `lightning-button` to perform an action when clicked. An action menu is shown on the top corner of the card opposite the title.

Here's an example that passes in the title, actions, and footer as slots, and includes an icon.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-card variant="narrow" icon-name="standard:opportunity">
        <h1 slot="title">This is a title</h1>
        <h1>This is the body</h1>
        <div slot="actions">
            <lightning-button-icon
                icon-name="utility:down"
            ></lightning-button-icon>
        </div>
        <div slot="footer">
            <h6>This is the footer</h6>
        </div>
    </lightning-card>
</template>
```
<!-- prettier-ignore-end -->

`title` is available as an attribute or a slot. Pass in the title as a slot if you want to pass in markup, such as making the title bold.

Use the `title` attribute if your title doesn't need extra formatting. Setting the `title` attribute overwrites the `title` slot. For more information, see [Use Slots as Placeholders](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-slots).

## Design

`lightning-card` implements the cards blueprint in the Salesforce Lightning Design System (SLDS). The cards adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Cards](https://v1.lightningdesignsystem.com/components/cards/)                                                                       | [Cards](https://www.lightningdesignsystem.com/components/cards/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Add an Action to the Footer Slot

The card footer is optional and can contain an action to link to another page.
If using the card footer, we recommend using a View All link that takes a user to the object list view.

This example adds the View All link to the footer slot,
specifying the `slds-card__footer-action` class on the &lt;a&gt; tag. This class makes the footer's click
target span the entire width of the card so you can click anywhere in the footer. The class isn't required.

For a View All link, set the href value of the tag to a URL to take the user to the object list view.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-card title="Hello">
        <lightning-button label="New" slot="actions"></lightning-button>
        <lightning-button label="Old" slot="actions"></lightning-button>
        <p class="slds-p-horizontal_small">Card Body (custom component)</p>
        <div slot="footer">
            <a class="slds-card__footer-action" href="#"
                >View All
                <span class="slds-assistive-text">Accounts</span>
            </a>
        </div>
    </lightning-card>
</template>
```
<!-- prettier-ignore-end -->

To navigate to records, list views, and objects in Lightning Experience, Experience Builder sites, and the Salesforce mobile app, use the navigation service, [`lightning/navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html). For more information, see [Basic Navigation](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-basic).

## Card with Illustration

A card can present an illustration in the card body when there's no data to show. To maintain a consistent experience, use the [`lightning-illustration` component](/docs/platform/lightning-component-reference/guide/lightning-illustration.html).

```html
 <lightning-card title="Tasks" icon-name="standard:task">
      <lightning-empty-state illustration-name="noresults:unknown" title="No new tasks">
        <p slot="description">Nothing needs your attention right now. Check back later.
        </p>
      </lightning-empty-state>
    </lightning-card>
```

## Card with Loading Indicator

When you expect content to load with a noticeable delay, a loading indicator is helpful to notify a user of the delay. Use the [`lightning-spinner` component](/docs/platform/lightning-component-reference/guide/lightning-spinner.html) to show a spinner on the card before the content loads.

```html
 <lightning-card title="Tasks" icon-name="standard:task">
      <lightning-spinner alternative-text="Loading" size="medium"></lightning-spinner>
      <p slot="description">
        Loading tasks...
        </p>
    </lightning-card>
```

## Card with a Data Table

A card is useful for showing a list of related records or contacts. By placing a [`lightning-datatable` component](/docs/platform/lightning-component-reference/guide/lightning-datatable.html) inside the card, you can present tabular information within a card.

```html
 <lightning-card title="Contacts" icon-name="standard:contact">
      <lightning-button label="New" slot="actions"></lightning-button>

        <lightning-datatable
                key-field="id"
                data={data}
                columns={columns}>
        </lightning-datatable>
    </lightning-card>
```

## Card with Tiles

A card can show records by using tiles. To nest record data in a tile, use the [`lightning-tile` component](/docs/platform/lightning-component-reference/guide/lightning-tile.html). Within a tile, show an icon by using the `media` slot. To make your content responsive, consider using the [`lightning-layout` component] and the SLDS grid system.

```html
<lightning-card title="Contacts" icon-name="standard:contact">
    <lightning-button label="New" slot="actions" onclick={handleNew}></lightning-button>
        <div class="slds-grid slds-wrap slds-var-m-around_medium">
            <div class="slds-col slds-size_1-of-1 slds-medium-size_6-of-12">
                <lightning-tile label="Astro Nomical" href="/path/to/somewhere" actions={actions}
                onactiontriggered={handleAction} type="media" class="slds-var-m-around_medium">
                    <lightning-icon slot="media" icon-name="standard:contact"></lightning-icon>
                    <lightning-layout>
                        <lightning-layout-item flexibility="auto" padding="around-small">
                            <p class="slds-truncate" title="Company">Company:</p>
                            <p class="slds-truncate" title="Email">Email:</p>
                        </lightning-layout-item>
                        <lightning-layout-item flexibility="auto" padding="around-small">
                            <p class="slds-truncate" title="Salesforce">Salesforce</p>
                            <p class="slds-truncate" title="astro@nomical.com">astro@nomical.com</p>
                        </lightning-layout-item>
                    </lightning-layout>
                </lightning-tile>
            </div>
            <div class="slds-col slds-size_1-of-1 slds-medium-size_6-of-12">
            <!-- More tiles here -->
            </div>
        </div>
    <p slot="footer">View All</p>
</lightning-card>
```

## Nested Cards

A nested card groups data within an object, such as account details with sections for contact info and recent activity.

```html
<lightning-card title="Outer Card Header" icon-name="standard:account">
      <lightning-button label="New" slot="actions"></lightning-button>
      <lightning-card title="Card Header" icon-name="standard:contact">
        <p class="slds-var-m-around_medium">This is a nested card with no styling (default)</p>
      </lightning-card>
      <p slot="footer">View All</p>
    </lightning-card>
```

## Component Styling

Use a combination of icons and utility classes to customize the card style.

### Icons

`lightning-card` displays an SLDS icon if you pass an icon name with the `icon-name` attribute. The icon is rendered using `lightning-icon`.

When applying SLDS classes or icons, check that they are available in the SLDS release tied to your org. The latest SLDS resources become available only when the new release is available in your org.

Visit [icons](https://v1.lightningdesignsystem.com/icons/) to view available icons.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute, as shown in the [Add an Action to the Footer Slot](#add-an-action-to-the-footer-slot) section.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-card` also includes [`lightning-icon`](/docs/platform/lightning-component-reference/guide/lightning-icon.html) and [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html) components that you can customize by using SLDS styling hooks.

## Usage Considerations

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.


:::::

:::::tab
::component-specification{component="card" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=8be957f6fbbc89ec9965e0b9fe887f002bb324827ce7a1ea0b28498a5d02271d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/carousel/lightning-carousel.md -->


# Carousel

**`lightning-carousel`**

A collection of images that are displayed one at a time.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="carousel" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-carousel` component shows a series of images in a single
container, with image indicators and a control button
below the image panel. Only images passed in `lightning-carousel-image`
components are supported.

Use [`lightning-carousel-image`](/docs/platform/lightning-component-reference/guide/lightning-carousel-image.html)
components nested in `lightning-carousel` to specify
up to six images. For each image, optionally provide a header and descriptive text
that the carousel displays below the image. You can also hyperlink the images.

If you specify more than six images, the carousel shows the first six and ignores the rest.

The images are shown in the order that you list them in the `lightning-carousel` component.

The carousel shows one image at a time, and you can select particular
images by clicking the indicators. The carousel can display up to six indicators only.
On mobile devices, you can also swipe an image to scroll to the next image.

By default, the carousel auto scrolls and loops through the images repeatedly.
Each image is visible for 5 seconds before the carousel scrolls to the next image.
The control button enables you to pause and restart the automatic scrolling.

## Design

`lightning-carousel` implements the carousel blueprint in the Salesforce Lightning Design System (SLDS). The carousel adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Carousel](https://v1.lightningdesignsystem.com/components/carousel/)                                                 | [Cards](https://www.lightningdesignsystem.com/components/carousel/)                                             |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Customize Carousel Behavior

Disable auto scrolling and remove the control button by including the
`disable-auto-scroll` attribute in the `lightning-carousel` tag. The user
must then use the indicator buttons to display each image.

Disable continuous looping by including the `disable-auto-refresh` attribute. The
images scroll one time through and stop at the last image if you include `disable-auto-refresh`
but not `disable-auto-scroll`.

Change the number of seconds each image is visible for by using the `scroll-duration` attribute.

For example, you can create three images for the carousel and disable automatic scrolling.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-carousel disable-auto-scroll>
        <lightning-carousel-image
            src="path/to/carousel-01.jpg"
            header="First card"
            description="First card description"
            alternative-text="This is a card"
            href="https://www.example.com"
        >
        </lightning-carousel-image>
        <lightning-carousel-image
            src="path/to/carousel-02.jpg"
            header="Second card"
            description="Second card description"
            alternative-text="This is a card"
            href="https://www.example.com"
        >
        </lightning-carousel-image>
        <lightning-carousel-image
            src="path/to/carousel-03.jpg"
            header="Third card"
            description="Third card description"
            alternative-text="This is a card"
            href="https://www.example.com"
        >
        </lightning-carousel-image>
    </lightning-carousel>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

To implement additional styling for the `lightning-carousel` component, use the Lightning Design
System [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment/).

## Accessibility

`lightning-carousel` implements the [SLDS carousel blueprint](https://v1.lightningdesignsystem.com/components/carousel/), which follows the [WAI-ARIA Authoring Practices Guide for the carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/). Use the Tab key to move focus to the carousel, then tab again to focus on the indicator buttons. Use right and left arrow keys to scroll to the next or previous image.

`lightning-carousel` observes these roles, states, and properties.

- The indicator buttons use a `ul` element with `role="tablist"`.
- Each indicator button uses an `li` element with `role="presentation"`.
- Each list item wraps an anchor tag with `role="tab"`.
- Each anchor tag has `aria-selected="false"` when it's not selected.


:::::

:::::tab
::component-specification{component="carousel" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f93e8a24d1f3fa4f7f495f2b70c747ed3a4996241e726b298fd858a643d4878f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/carouselImage/lightning-carousel-image.md -->


# Carousel Image

**`lightning-carousel-image`**

Specifies an image that's used in `lightning-carousel`, including description and title

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="carouselImage" model="lwc" namespace="lightning"}


:::::

:::::tab

Use the `lightning-carousel-image` component to specify images for the
[`lightning-carousel`](/docs/platform/lightning-component-reference/guide/lightning-carousel.html) component.
You can specify up to six images, which then appear in the order that you
list them in the `lightning-carousel` component.

For each image, use the `src` attribute to specify the path to the image.
Optionally use `header` and `description` attributes to provide a header
and descriptive text that the carousel shows below the image.
You can also hyperlink the images with the `href` attribute.

Use the `alternative-text` attribute to supply assistive text for each image.

```html
<lightning-carousel-image
        src = "https://v1.lightningdesignsystem.com/assets/images/carousel/carousel-01.jpg"
        header = "First Card"
        description = "First card description."
        alternative-text = "First card accessible description."
        href = "https://www.example.com">
    </lightning-carousel-image>
```

## Design

Use `lightning-carousel-image` within `lightning-carousel`, which implements the carousel blueprint in the Salesforce Lightning Design System (SLDS). The carousel adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Carousel](https://v1.lightningdesignsystem.com/components/carousel/)                                                 | [Carousel](https://www.lightningdesignsystem.com/components/carousel/)                                          |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Use Images in Your Org

To use images in your org, upload them as static resources in the Static Resources
page in Setup. To reference a resource in `lightning-carousel-image`, use `{property}`
syntax in your `src` attribute.

If the image path is invalid or the image doesn’t load because the user is
offline or another reason, the description and alternative text replace the image.

This example uses static resources uploaded as a single image, and images uploaded in a zip file.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="slds-size_1-of-4">
        <lightning-carousel>
            <lightning-carousel-image
                src={companyLogoUrl}
                header="Company logo"
                description="Company logo uploaded to a static resource"
                alternative-text="Company logo"
            >
            </lightning-carousel-image>
            <lightning-carousel-image
                src={product1Url}
                header="Fantastic product 1"
                description="Fantastic product image in a zip file"
                alternative-text="Fantastic product 1"
            >
            </lightning-carousel-image>
            <lightning-carousel-image
                src={product2Url}
                header="Fantastic product 2"
                description="Fantastic product image in a zip file"
                alternative-text="Fantastic product 2"
            >
            </lightning-carousel-image>
        </lightning-carousel>
    </div>
</template>
```
<!-- prettier-ignore-end -->

The company logo was uploaded as a single image to a static resource named `company_logo` and imported as `companyLogo`. The Product1 and Product2 images were uploaded in a zip file to a static resource named `company_products` and imported as `companyProducts`.

```js
import { LightningElement } from "lwc";
import companyLogo from "@salesforce/resourceUrl/company_logo";
import companyProducts from "@salesforce/resourceUrl/company_products";

export default class CarouselStaticResources extends LightningElement {
  // Expose the static resource URL for use in the template
  companyLogoUrl = companyLogo;

  // Expose URL of assets included inside an archive file
  product1Url = companyProducts + "/product1.png";
  product2Url = companyProducts + "/product2.png";
}
```

## Accessibility

`lightning-carousel-image` includes accessibility features provided by `lightning-carousel`. A carousel image appears with header text and a description. Use the `alternative-text` attribute to specify assistive text for each image.

`lightning-carousel-image` observes these roles, states, and properties.

- The indicator button (tab's anchor) of a selected image has `aria-selected="true"`, and all other tabs have `aria-selected="false"`.
- The tab's anchor of a selected image has `tabindex="0"`, and all other tabs have `tabindex="-1"`.
- Each image container (tab panel) contains an element with `role="tabpanel"`.
- Each tab panel has an `aria-labelledby` attribute whose value is the ID of its associated indicator button.
- Each tab panel has an `aria-hidden` attribute whose value is toggled based on whether the panel is visible.


:::::

:::::tab
::component-specification{component="carouselImage" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6edcef518011d2a661c853f0ec05b6d3d7dc3b5f04b0781285ddedd6e07b9d7c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkbox/lightning-checkbox.md -->


# Checkbox

**`lightning-input`**
_type="checkbox"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="checkbox" model="lwc" namespace="lightning"}


:::::

:::::tab

Checkboxes present one or more options for selection. `lightning-input type="checkbox"` is useful for creating single checkboxes. If you are working
with a group of checkboxes, consider using [`lightning-checkbox-group`](/docs/platform/lightning-component-reference/guide/lightning-checkbox-group.html) instead.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="checkbox" label="Red" checked> </lightning-input>
    <lightning-input type="checkbox"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

A checkbox that's disabled is grayed out and you can't interact with it. A disabled checkbox isn't focusable and isn't submitted with the form. Similarly, you can't interact with a read-only checkbox.

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                | SLDS 2                                                                 |
| ---------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| checkbox   | [Checkbox](https://v1.lightningdesignsystem.com/components/checkbox/) | [Checkbox](https://www.lightningdesignsystem.com/components/checkbox/) |

## Read-Only Checkbox

Unlike the native `<input type="checkbox">` element, a read-only checkbox that you create using `lightning-input` with `type="checkbox"` and `read-only` attributes isn't focusable. You can't interact with a read-only checkbox and it isn't submitted with the form.

A read-only checkbox has these characteristics.

- Displays a checkmark icon without an enclosing border when the `checked` attribute is used.
- Displays a dotted square icon when the `checked` attribute isn't used.

If the checkbox also has `read-only` specified, adding the `required` attribute to a checkbox has no effect.

## Indeterminate Checkbox

An indeterminate checkbox shows a dash indicator instead of a checkbox. Use an indeterminate checkbox when you want to show a "Select All" checkbox for a group of checkbox. The indeterminate checkbox shows a dash indicator when only some items in a group are selected. Clicking the checkbox clears the indeterminate state. An indeterminate checkbox with a dash indicator has a `checked` value of `false`.

This example shows a "Select All" checkbox and a group of checkboxes. The "select all" checkbox either selects or deselects all the checkboxes in the group. When all the checkboxes are selected and you deselect one of the checkboxes in the group, the "Select All" checkbox becomes an indeterminate checkbox that shows a dash indicator.

<!-- prettier-ignore -->
```html
<template>
    <lightning-input
        type="checkbox"
        label="Select All"
        checked={allSelected}
        indeterminate={someSelected}
        onchange={handleSelectAllChange}
    >
    </lightning-input>

    <!-- A group of checkboxes -->
    <div class="slds-var-m-top_small slds-var-p-left_large">
        <template for:each={checkboxItems} for:item="item">
            <lightning-input
                key={item.id}
                type="checkbox"
                label={item.label}
                checked={item.checked}
                data-id={item.id}
                onchange={handleItemChange}
            >
            </lightning-input>
        </template>
    </div>

    <p class="slds-var-m-top_small">
        Selected: {selectedCount} of {totalCount}
    </p>
</template>
```

The checkbox specifies `true` for the `indeterminate` boolean when the selected number of checkboxes
is at least 1 but fewer than the total number of checkboxes in the group. In this scenario, only some checkboxes in the group are selected.

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

export default class BaseComponents extends LightningElement {
  checkboxItems = [
    { id: "red", label: "Red", checked: false },
    { id: "green", label: "Green", checked: true },
    { id: "blue", label: "Blue", checked: false },
  ];

  get selectedCount() {
    return this.checkboxItems.filter((item) => item.checked).length;
  }

  get totalCount() {
    return this.checkboxItems.length;
  }

  get allSelected() {
    return this.totalCount > 0 && this.selectedCount === this.totalCount;
  }

  get someSelected() {
    return this.selectedCount > 0 && this.selectedCount < this.totalCount;
  }

  handleSelectAllChange(event) {
    const isChecked = event.target.checked;
    this.checkboxItems = this.checkboxItems.map((item) => ({
      ...item,
      checked: isChecked,
    }));
  }

  handleItemChange(event) {
    const selectedId = event.target.dataset.id;
    const isChecked = event.target.checked;
    this.checkboxItems = this.checkboxItems.map((item) =>
      item.id === selectedId ? { ...item, checked: isChecked } : item,
    );
  }
}
```

## Handle Selections

When working with checkboxes and toggle
switches, use `this.template.querySelectorAll` to retrieve the array of components. You can
use `.filter` to determine which elements are checked or unchecked. The next
example displays the values of the selected checkboxes.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox"
        label="Red"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox"
        label="Blue"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox"
        label="Green"
        onchange={handleCheckboxChange}
    >
    </lightning-input>

    <p>Checked items: {selection}</p>
</template>
```
<!-- prettier-ignore-end -->

When you select a checkbox, the `handleCheckboxChange` function updates the `selection` property to display a list of selected checkboxes.

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

export default class CheckboxExample extends LightningElement {
  selection;

  handleCheckboxChange() {
    // Query the DOM
    const checked = Array.from(this.template.querySelectorAll("lightning-input"))
      // Filter down to checked items
      .filter((element) => element.checked)
      // Map checked items to their labels
      .map((element) => element.label);
    this.selection = checked.join(", ");
  }
}
```

To programmatically set a checkbox or checkbox button to `checked`, query the element using a custom data attribute. You can't query the internal elements of a Lightning web component. This example uses a custom attribute `data-element` to query the element. The checkbox is selected by clicking a button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox"
        data-element="subscribe-checkbox"
        label="Subscribe"
    >
    </lightning-input>
    <lightning-button
        label="Subscribe"
        onclick={handleSubscribe}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Set the element's `checked` property to `true`.

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

export default class CheckboxExample extends LightningElement {
  handleSubscribe(event) {
    this.template.querySelectorAll('[data-element="subscribe-checkbox"]').forEach((element) => {
      element.checked = true;
    });
  }
}
```

## Input Validation

To ensure the checkbox is selected before form submission, use the `required` attribute. You can programmatically check the checkbox's `checked` property in your validation logic.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="checkbox"
    label="I agree to the terms and conditions"
    required
    lwc:ref="termsCheckbox"
    message-when-value-missing="Please accept the terms and conditions"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the checkbox, check its validity using the `checkValidity()` method or access the `checked` property. If the value isn't valid, the `reportValidity()` method shows the error message below the checkbox.

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

export default class CheckboxValidation extends LightningElement {
  handleSubmit() {
    const checkbox = this.refs.termsCheckbox;
    console.log(checkbox.validity.valid); // Returns true or false
    if (!checkbox.checkValidity()) {
      checkbox.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `checkbox` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `valueMissing` - Indicates that an empty value is provided when the `required` attribute is set for any input type
- `valid` - True if none of the preceding properties are true

## Add Field-Level Help

To provide contextual help content, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying the specified help text.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox"
        label="Subscribe to newsletter"
        field-level-help="You will receive weekly updates about new features and promotions"
    >
    </lightning-input>
    <lightning-input
        type="checkbox"
        label="Enable notifications"
        field-level-help="Push notifications will be sent to your device when important events occur"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

Use a combination of variants and utility classes to customize your checkboxes.

### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the checkbox.

- `standard` is the default, which displays the label above the checkbox.
- `label-hidden` hides the label but make it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still displayed.
- `label-inline` aligns the label and field horizontally.
- `label-stacked` places the label above the field.

In most contexts, a stacked label (`standard` or `label-stacked` variant) results in better readability and clarity. Use horizontal labels (`label-inline` variant) when you want to conserve vertical space and have fewer than 10 fields.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the checkbox.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the checkbox and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the checkbox and the help tooltip.

If the checkbox fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns this `event.target` parameter.

| Parameter | Type    | Description                                                                                                                          |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| checked   | boolean | The value of the `checked` attribute. See [Handle Selections](#handle-selections) for an example of working with an array of inputs. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=2710662a851695f39b0815259c18de68bb0a3dbaaf3c0a12c904b9c7c01b73f7 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkboxButton/lightning-checkbox-button.md -->


# Checkbox Button

**`lightning-input`**
_type="checkbox-button"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="checkboxButton" model="lwc" namespace="lightning"}


:::::

:::::tab

Checkbox buttons present one or more options with an alternative visual
design.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        label="Add pepperoni"
        checked
        value="pepperoni"
    >
    </lightning-input>
    <lightning-input type="checkbox-button" label="Add salami" value="salami">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type      | SLDS 1                                                                              | SLDS 2                                                                               |
| --------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| checkbox-button | [Checkbox Button](https://v1.lightningdesignsystem.com/components/checkbox-button/) | [Checkbox Button](https://www.lightningdesignsystem.com/components/checkbox-button/) |

## Handle Selections

When working with checkboxes and toggle
switches, use `this.template.querySelectorAll` to retrieve the array of components. You can
use `.filter` to determine which elements are checked or unchecked. The following
example displays the values of the selected checkboxes.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        label="Red"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox-button"
        label="Blue"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox-button"
        label="Green"
        onchange={handleCheckboxChange}
    >
    </lightning-input>

    <p>Checked items: {selection}</p>
</template>
```
<!-- prettier-ignore-end -->

When you select a checkbox, the `handleCheckboxChange` function updates the `selection` property
to display a list of selected checkboxes.

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

export default class CheckboxExample extends LightningElement {
  selection;

  handleCheckboxChange() {
    // Query the DOM
    const checked = Array.from(this.template.querySelectorAll("lightning-input"))
      // Filter down to checked items
      .filter((element) => element.checked)
      // Map checked items to their labels
      .map((element) => element.label);
    this.selection = checked.join(", ");
  }
}
```

To programmatically set a checkbox or checkbox button to `checked`, query the element using a custom data attribute. You can't query the internal elements of a Lightning web component. This example uses a custom attribute `data-element` to query the element. The checkbox is selected by clicking a button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        data-element="subscribe-checkbox"
        label="Subscribe"
    >
    </lightning-input>
    <lightning-button
        label="Subscribe"
        onclick={handleSubscribe}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Set the element's `checked` property to `true`.

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

export default class CheckboxExample extends LightningElement {
  handleSubscribe(event) {
    this.template.querySelectorAll('[data-element="subscribe-checkbox"]').forEach((element) => {
      element.checked = true;
    });
  }
}
```

## Input Validation

To ensure the checkbox button is selected before form submission, use the `required` attribute.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="checkbox-button"
    label="Agree to Terms and Conditions"
    required
    lwc:ref="termsCheckbox"
    message-when-value-missing="Please accept the terms and conditions"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the checkbox button, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the checkbox button.

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

export default class CheckboxButtonValidation extends LightningElement {
  handleSubmit() {
    const checkboxButton = this.refs.termsCheckbox;
    console.log(checkboxButton.validity.valid); // Returns true or false
    if (!checkboxButton.checkValidity()) {
      checkboxButton.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `checkbox-button` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `valueMissing` - Indicates that an empty value is provided when the `required` attribute is set for any input type
- `valid` - True if none of the preceding properties are true

## Usage Considerations

The `label` is always hidden from view and available as assistive text for screen readers. Using the `variant` attribute with the checkbox button has no impact on label display or layout.

Field-level help text isn't supported for the checkbox button.

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the checkbox button.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the checkbox button and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the checkbox button and the help tooltip.

If the checkbox button fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns this `event.target` parameter.

| Parameter | Type    | Description                                                                                                                      |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| checked   | boolean | The value of `checked` attribute. See [Handle Selections](#handle-selections) for an example of working with an array of inputs. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=22aefd6c57f11582a41a170b947fe24540633ed5ccb6c668f7fe70ae69c46182 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkboxGroup/lightning-checkbox-group.md -->


# Checkbox Group

**`lightning-checkbox-group`**

A checkbox group that enables selection of single or multiple options.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="checkboxGroup" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-checkbox-group` component represents a checkbox group that enables
selection of single or multiple options.

If you specify the `required` attribute, at least one checkbox must be
selected. When a user interacts with the checkbox group and doesn't make a
selection, an error message appears. You can provide a custom error
message by using the `message-when-value-missing` attribute.

If you specify the `disabled` attribute, checkbox selections can't be
changed.

This example creates a checkbox group with two options and `option1` is
selected by default. At least one checkbox must be selected because the `required`
attribute is specified.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-checkbox-group
        name="checkboxGroup"
        label="Checkbox Group"
        options={options}
        value={value}
        onchange={handleChange}
        required
    >
    </lightning-checkbox-group>
</template>
```
<!-- prettier-ignore-end -->

The `value` attribute contains an array of checkboxes. To select a checkbox, pass in its value to the `value` attribute.
In this example, only `option1` is selected.

```javascript
//mycomponentname.js

import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  options = [
    { label: "One", value: "option1" },
    { label: "Two", value: "option2" },
  ];

  // Select option1 by default
  value = ["option1"];

  handleChange(event) {
    const changeValue = event.detail.value;
    alert(changeValue);
  }
}
```

To retrieve the values when a checkbox is selected or deselected, use `event.detail.value` in the `change` event handler.

## Design

`lightning-checkbox-group` implements the checkbox blueprint in the Salesforce Lightning Design System (SLDS). The checkbox adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Checkbox (Group)](https://v1.lightningdesignsystem.com/components/checkbox/#Group/)                                                  | [Checkbox (Group)](https://www.lightningdesignsystem.com/components/checkbox/#Group/)                           |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Checkboxes

To create checkboxes, pass in the following properties to the `options` attribute.

| Property | Type   | Description                                                    |
| -------- | ------ | -------------------------------------------------------------- |
| label    | string | The text that appears next to a checkbox.                      |
| value    | string | The string that's used to identify which checkbox is selected. |

## Input Validation

Client-side input validation is available for this component. For example, an error message is displayed when the checkbox group is marked required and no option is selected. A disabled checkbox group is always valid.

The validation occurs for the checkbox group, not for an individual checkbox. To override the default message "Complete this field" that appears when a selection on a checkbox group is required and no option is selected, use the `message-when-value-missing` attribute. This message appears when you remove focus from the checkbox group.

The `validity` attribute returns the ValidityState object, with the following supported properties.

- `valid`: Returns true if the checkbox group meets all its validation constraints.
- `valueMissing`: Returns true if a selection in the checkbox group is required but no checkbox is selected.

Other properties such as `badInput` are not supported.

This example creates a checkbox group that requires a selection and a button that checks validity when clicked.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-checkbox-group
        label="Select a color"
        options={options}
        value={value}
        required
    ></lightning-checkbox-group>
    <lightning-button
        label="Check validity"
        onclick={handleValidity}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

For checkbox groups that are required, the `checkValidity()` method returns true if at least one checkbox is selected, or false if none is selected. Calling `checkValidity()` is equivalent to returning `validity.valid` on the checkbox group.

To programmatically show error messages on an invalid checkbox group, use the `reportValidity()` method.

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

export default class CheckboxGroupRequiredValidity extends LightningElement {
  value = [];
  message = "";

  get options() {
    return [
      { label: "Red", value: "red" },
      { label: "Green", value: "green" },
      { label: "Blue", value: "blue" },
    ];
  }
  handleValidity(e) {
    var checkboxGroup = this.template.querySelector("lightning-checkbox-group");
    if (checkboxGroup.checkValidity()) {
      this.message = "That's a great selection!";
    } else {
      // Shows the error immediately without user interaction
      checkboxGroup.reportValidity();
      this.message = "Select your favorite color and try again.";
    }
  }
}
```

For custom validity error messages, specify the message by using `setCustomValidity()` and `reportValidity()`. `setCustomValidity()` overrides the error message that you provide with the `message-when-value-missing` attribute. For more information, see the [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Component Styling

You can use a combination of the `variant` and `class` attributes to customize the checkbox group.

### Variants

Use the `variant` attribute with one of these values to apply different label positioning.

- `label-hidden` hides the checkbox group label but make it available to assistive technology. This variant doesn’t hide the option labels.
- `label-inline` horizontally aligns the checkbox group label and options.
- `label-stacked` places the checkbox group label above the options.
- `standard` is the default value, which shows the checkbox group label above the options.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a box theme around the checkbox group by using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-checkbox-group
    class="slds-box"
    label="Select a color"
    options={options}
    value={value}
>
</lightning-checkbox-group>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-checkbox-group` is useful for grouping a set of checkboxes. If you
have a single checkbox, use `lightning-input type="checkbox"` instead.

## Accessibility

The checkbox group is nested in a `fieldset` element that contains a `legend`
element. The legend contains the `label` value. The `fieldset` element enables
grouping of related checkboxes to facilitate tabbing navigation and speech
navigation for accessibility purposes. Similarly, the `legend` element
improves accessibility by enabling a caption to be assigned to the `fieldset`.


:::::

:::::tab
::component-specification{component="checkboxGroup" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=342cb0112e2ab4b3d498dcb6b960ad13f92c9c875f8526d05942cb19095c3e1e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkboxToggle/lightning-checkbox-toggle.md -->


# Checkbox Toggle

**`lightning-input`**
_type="toggle"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="checkboxToggle" model="lwc" namespace="lightning"}


:::::

:::::tab

A checkbox toggle presents two values for single selection. Use the
`message-toggle-active` and `message-toggle-inactive` attributes to specify labels displayed under the toggle for each state. By default, the labels are Active and Inactive. To omit labels, set these attributes to empty strings.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="toggle" label="Toggle value" checked>
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

A toggle is similar to a checkbox; it presents a binary choice. However, a toggle is self-contained and is designed to be used in a form with only one field. When you switch a toggle on or off, the change for that item should save immediately.

By default, the toggle component expands to 100% of the available width. To limit the size of the toggle component, wrap it with an element that specifies the appropriate width.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="width:fit-content">
        <lightning-input type="toggle" label="Toggle value" checked>
        </lightning-input>
    </div>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                             | SLDS 2                                                                              |
| ---------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| toggle     | [Checkbox Toggle](https://v1.lightningdesignsystem.com/components/checkbox-toggle) | [Checkbox Toggle](https://www.lightningdesignsystem.com/components/checkbox-toggle) |

## Handle Selections

Track the state of each toggle individually using the `onchange` event. The following example displays the values of the enabled toggles.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="toggle"
        label="Email Notifications"
        checked={isEmailEnabled}
        onchange={handleEmailChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>
    <lightning-input
        type="toggle"
        label="SMS Notifications"
        checked={isSmsEnabled}
        onchange={handleSmsChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>
    <lightning-input
        type="toggle"
        label="Push Notifications"
        checked={isPushEnabled}
        onchange={handlePushChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>

    <p>Enabled notifications: {enabledNotifications}</p>
</template>
```
<!-- prettier-ignore-end -->

Track each toggle state and update the display when any toggle changes.

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

export default class ToggleExample extends LightningElement {
  isEmailEnabled = false;
  isSmsEnabled = false;
  isPushEnabled = false;

  handleEmailChange(event) {
    this.isEmailEnabled = event.target.checked;
  }

  handleSmsChange(event) {
    this.isSmsEnabled = event.target.checked;
  }

  handlePushChange(event) {
    this.isPushEnabled = event.target.checked;
  }

  get enabledNotifications() {
    const enabled = [];
    if (this.isEmailEnabled) enabled.push("Email");
    if (this.isSmsEnabled) enabled.push("SMS");
    if (this.isPushEnabled) enabled.push("Push");
    return enabled.length > 0 ? enabled.join(", ") : "None";
  }
}
```

## Input Validation

To ensure the toggle is enabled before form submission, use the `required` attribute. When `required` is used, the toggle must be enabled to pass validation.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="toggle"
    label="Accept terms"
    message-toggle-active="Accepted"
    message-toggle-inactive="Not accepted"
    required
    lwc:ref="termsToggle"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the toggle, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the toggle.

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

export default class ToggleValidation extends LightningElement {
  handleSubmit() {
    const toggle = this.refs.termsToggle;
    console.log(toggle.validity.valid); // Returns true or false
    if (!toggle.checkValidity()) {
      toggle.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `toggle` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `valueMissing` - Indicates that an empty value is provided when the `required` attribute is set for any input type
- `valid` - True if none of the preceding properties are true

## Component Styling

Use a combination of variants and utility classes to customize your checkbox toggle.

### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the fields.

- `standard` is the default, which displays the label next to the field.
- `label-hidden` hides the label but make it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still displayed.
- `label-inline` aligns the label and field horizontally.

**note:** The `label-stacked` variant isn't supported for the checkbox toggle.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the toggle.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the toggle and the label.

If the toggle fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns this `event.target` parameter.

| Parameter | Type    | Description                                                                                                                      |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| checked   | boolean | The value of `checked` attribute. See [Handle Selections](#handle-selections) for an example of working with an array of inputs. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=ff4724ae0eaee84aef9399588a9d79241988fcf1256c8faf5aa430e63f2d594c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/clearErrors/ui-clear-errors.md -->

# Clear Errors

**`ui:clearErrors`**

Indicates that validation errors are cleared.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

This event is fired when validation errors on an input field are cleared. To set a handler for the `ui:clearErrors` event, use the `onClearErrors` attribute on a component that extends `ui:input`, such as `ui:inputText` and `ui:inputNumber`.

The following `ui:inputNumber` component displays an error message when the number entered is less than 10. It displays an alert when the error message is cleared.

```xml
<aura:component>
  <aura:attribute name="myNumber" type="integer" default="10" />
  <ui:inputNumber
    aura:id="number"
    label="Enter a number: "
    value="{!v.myNumber}"
    onClearErrors="{!c.handleClearErrors}"
  />
  <ui:button label="Validate" press="{!c.handleValidate}" />
</aura:component>
```

Here's the client-side controller that handles the input validation and clearing of the error message.

```javascript
({
  handleValidate: function (cmp, evt, helper) {
    var num = cmp.find("number");
    var val = num.get("v.value");
    if (val < 10) {
      num.set("v.errors", [{ message: "Enter a number more than 10" }]);
    } else {
      num.set("v.errors", null);
    }
  },

  handleClearErrors: function (cmp, evt, helper) {
    alert("Error has been cleared");
  },
});
```

If you're using this event with a component other than those that extend `ui:input`, register the event first.

```xml
<aura:registerEvent
  name="onClearErrors"
  type="ui:clearErrors"
  description="The event fired when validation errors are cleared."
/>
```

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_validate_fields.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=5cbff9819961a75a2050c87c93d33118cedffaee4a31d57475d319ca07978286 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/clickToDial/lightning-click-to-dial.md -->


# Click To Dial

**`lightning-click-to-dial`**

Renders a formatted phone number as click-to-dial enabled or disabled for Open CTI and Voice.

**For Use In**

Lightning Experience

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="clickToDial" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-click-to-dial` component respects any existing click-to-dial
commands for computer-telephony integrations (CTI) with Salesforce, such as
Open CTI and Voice.

To dial phone numbers in the component, you must first enable the phone
system. After the phone system is enabled, when a user clicks on a phone
number the component notifies the phone system that the number was clicked.
Then, the component passes along any information that's required by the phone
system to make an outbound call.

Here's an example of how you can use a `lightning-click-to-dial` component. The
first phone number doesn't have a recordId or any parameters. The second phone
number has a recordId. The third phone number has a recordId and parameters.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-click-to-dial value="14155555551"> </lightning-click-to-dial>
    <lightning-click-to-dial value="14155555552" record-id="5003000000D9duF">
    </lightning-click-to-dial>
    <lightning-click-to-dial
        value="14155555553"
        record-id="5003000000D8cuI"
        params="accountSid=xxx, sourceId=xxx, apiVersion=123"
    >
    </lightning-click-to-dial>
</template>
```
<!-- prettier-ignore-end -->

## Open CTI Usage Considerations

The `lightning-click-to-dial` component works in conjunction with the Open CTI
for Lightning Experience API methods, `enableClickToDial`,
`disableClickToDial`, and `onClickToDial`. For more information, see the
[Open CTI Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_cti.meta/api_cti/).
The component doesn't support iFrames, which means
that it can't be used in utilities, such as a phone utility, or Lightning Out
apps that are hosted on iFrames.

To dial phone numbers using `lightning-click-to-dial`, first enable the phone
system with the Open CTI method `enableClickToDial`. To disable the phone
system, use the Open CTI method `disableClickToDial`.

When a phone number is clicked, the `onClickToDial` listener that's registered
with the Open CTI method `onClickToDial` is invoked.

`lightning-click-to-dial` can contain a `record-id` attribute. If you pass this
attribute, the payload that's passed to the Open CTI method `onClickToDial`
contains the record information associated with this record ID. For example,
record name and object type. If the `record-id` isn't passed, no record
information is provided to the `onClickToDial` handler.

A formatted phone number follows the North American format of 123 456 7890.


:::::

:::::tab
::component-specification{component="clickToDial" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=57fde7fe1ff2534a2a43f593b7953ada482bfc831496ebf57d3a6db0993b04ff url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/closeQuickAction/force-close-quick-action.md -->

# Close Quick Action

**`force:closeQuickAction`**

Closes a quick action panel. Only one quick action panel can be open in the app at a time.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To close a quick action panel, usually in response to completing or canceling the action, run `$A.get("e.force:closeQuickAction").fire();`.

This example closes the quick action panel after processing the input from the panel’s user interface and displaying a “toast” message with the processing results. While the processing and the toast are unrelated to closing the quick action, the sequence is important. Firing `force:closeQuickAction` should be the last thing your quick action handler does.

```javascript
/*quickAddController.js*/
({
  clickAdd: function (component, event, helper) {
    // Get the values from the form
    var n1 = component.find("num1").get("v.value");
    var n2 = component.find("num2").get("v.value");

    // Display the total in a "toast" status message
    var resultsToast = $A.get("e.force:showToast");
    resultsToast.setParams({
      title: "Quick Add: " + n1 + " + " + n2,
      message: "The total is: " + (n1 + n2) + ".",
    });
    resultsToast.fire();

    // Close the action panel
    var dismissActionPanel = $A.get("e.force:closeQuickAction");
    dismissActionPanel.fire();
  },
});
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience and the Salesforce mobile app only.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=027623620f9f63f9b56983b15c4f533844d9af0ccc0ad103596f912a57b06a01 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/cmsDeliveryApi/lightning-cms-delivery-api.md -->

# CMS Delivery API (Beta)

**`lightning/cmsDeliveryApi`**

Get published content from Salesforce CMS using the `lightning/cmsDeliveryApi` module. The `lightning/cmsDeliveryApi` module requires API version 52.0 or later.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
**note:** `lightning/cmsDeliveryApi` 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.

The `lightning/cmsDeliveryApi` (Beta) module provides wire adapters to work with content versions for an Experience Cloud site.

To use the CMS Delivery API in your component, import the functions in your component's JavaScript file.

```js
import { listContent } from "lightning/cmsDeliveryApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-cms-delivery-api-list-content).

:::::

:::::tab
::component-specification{component="cmsDeliveryApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2c0eca9425cf4315fd8e8e8fd9ada5096836f395958a575b5c7277d24fd67c01 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/collapse/ui-collapse.md -->

# Collapse

**`ui:collapse`**

Indicates that the `ui:menuList` component is collapsed.

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

This event is fired when you collapse the [`ui:menuList` component](/docs/platform/lightning-component-reference/guide/ui-menu-list.html). To set a handler for the `ui:collapse` event, use the `menuCollapse` attribute on `ui:menuList`.

The following example adds or remove a CSS class to the `ui:menuList` component when it's collapsed or expanded.

```xml
<aura:component>
  <ui:menu>
    <ui:menuTriggerLink aura:id="trigger" label="Contacts" />
    <ui:menuList
      class="actionMenu"
      aura:id="actionMenu"
      menuCollapse="{!c.addMyClass}"
      menuExpand="{!c.removeMyClass}"
    >
      <ui:actionMenuItem aura:id="item1" label="All Contacts" click="{!c.doSomething}" />
      <ui:actionMenuItem aura:id="item2" label="All Primary" click="{!c.doSomething}" />
    </ui:menuList>
  </ui:menu>
</aura:component>
```

Here's the client-side controller that handles the adding and removing of the CSS classes.

```javascript
({
  addMyClass: function (component, event, helper) {
    var trigger = component.find("trigger");
    $A.util.addClass(trigger, "myClass");
  },
  removeMyClass: function (component, event, helper) {
    var trigger = component.find("trigger");
    $A.util.removeClass(trigger, "myClass");
  },
});
```

If you're using this event with a component other than `ui:menuList`, register the event first.

```xml
<aura:registerEvent
  name="menuCollapse"
  type="ui:collapse"
  description="The event fired when the menu list collapses."
/>
```


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=16f9aaa20163e0ab33d19828b6c361a068c5537d2857b2142986a31f4263bbde url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/color/lightning-color.md -->


# Color Picker

**`lightning-input`**
_type="color"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="color" model="lwc" namespace="lightning"}


:::::

:::::tab

A color picker enables you to specify a color using a color picker or by
entering the color into a text field.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="color" label="Color" value="#EEEEEE">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                        | SLDS 2                                                                         |
| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| color      | [Color Picker](https://v1.lightningdesignsystem.com/components/color-picker/) | [Color Picker](https://www.lightningdesignsystem.com/components/color-picker/) |

## Input Validation

To ensure a color is selected, use the `required` attribute. The color value must be in hexadecimal format `#RRGGBB`. You can also use the `pattern` attribute to enforce specific color format requirements.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="color"
    label="Brand Color"
    value="#007bff"
    required
    lwc:ref="brandColor"
    message-when-value-missing="Please select a brand color"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the color input, use the `checkValidity()` method and access the `value` property to verify the color format. If the value isn't valid, the `reportValidity()` method shows the error message below the input field.

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

export default class ColorValidation extends LightningElement {
  handleSubmit() {
    const colorInput = this.refs.brandColor;
    console.log(colorInput.validity.valid); // Returns true or false
    if (!colorInput.checkValidity()) {
      colorInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const selectedColor = colorInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `color` type, these attributes apply:

- `badInput` - Indicates that the value is a valid hexadecimal color format
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `patternMismatch` - Indicates that the value doesn't match the specified pattern attribute
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

## Add Field-Level Help and Placeholder Text

To provide contextual help content, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

To provide sample input in the field, use the `placeholder` attribute. For example, in a `color` type field, show an example hexadecimal value.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="color"
        label="Primary Brand Color"
        placeholder="#0070D2"
        field-level-help="Select the primary color for your brand theme. This color will be used across all branded materials."
    >
    </lightning-input>
    <lightning-input
        type="color"
        label="Accent Color"
        placeholder="#FF9E2C"
        field-level-help="Choose a complementary accent color. Use hexadecimal format (#RRGGBB)."
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Event Handling

Use the `change` event for immediate updates as the user types or select a color. Alternatively, use the `commit` event to handle changes only when the user presses Enter or moves focus away from the input field. See [Custom Events](#custom-events).

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="color"
        label="Live Preview Color"
        value={liveColor}
        onchange={handleColorChange}
    >
    </lightning-input>
    
    <lightning-input
        type="color"
        label="Confirmed Color"
        value={confirmedColor}
        oncommit={handleColorCommit}
    >
    </lightning-input>
    
    <p>Live preview updates continuously: {liveColor}</p>
    <p>Confirmed color updates on Enter or blur: {confirmedColor}</p>
</template>
```
<!-- prettier-ignore-end -->

The `onchange` event provides real-time feedback, while `oncommit` waits for user confirmation.

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

export default class ColorEventExample extends LightningElement {
  liveColor = "#0070D2";
  confirmedColor = "#0070D2";

  handleColorChange(event) {
    // Updates continuously as user picks colors
    this.liveColor = event.detail.value;
  }

  handleColorCommit(event) {
    // Updates only when user presses Enter or input loses focus
    this.confirmedColor = event.target.value;
  }
}
```

## Component Styling

Use a combination of variants and utility classes to customize your color picker.

### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the color picker.

- `standard` is the default, which displays the label above the color picker.
- `label-hidden` hides the label but make it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still displayed.
- `label-inline` aligns the label and color picker horizontally.
- `label-stacked` places the label above the color picker.

In most contexts, a stacked label (`standard` or `label-stacked` variant) results in better readability and clarity. Use horizontal labels (`label-inline` variant) when you want to conserve vertical space and have fewer than 10 fields.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the color field.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the color field and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the color field and the help tooltip.

If the color field fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns this `event.detail` parameter.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

**`commit`**

The event fired when you press Enter after interacting with the input, or move away from the input so it loses focus.

Use `event.target.value` to access the input value.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=85ed87133fe86603a21ce4fa16cf1cd76ec31fcd3e9189543e7427f30e33ca57 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/combobox/lightning-combobox.md -->


# Combobox

**`lightning-combobox`**

A widget that provides an input field that is readonly, accompanied by a dropdown list of selectable options.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="combobox" model="lwc" namespace="lightning"}


:::::

:::::tab

`lightning-combobox` is an input element that enables single selection from a
list of options. The result of the selection corresponds to the value of the
input. Multiple selection is not supported. To support multiple selection, use [`lightning-dual-listbox`](/docs/platform/lightning-component-reference/guide/lightning-dual-listbox.html) instead.

This example creates a list of options with a default selection that's specified with the `value` attribute.
The `options` attribute specifies the name of an array of items for the dropdown list.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-combobox
        name="status"
        label="Status"
        placeholder="Choose Status"
        value={value}
        onchange={handleChange}
        options={statusOptions}
    >
    </lightning-combobox>
    <p>Selected option: {value}</p>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-combobox` implements the combobox blueprint in the Salesforce Lightning Design System (SLDS). The combobox adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Combobox](https://v1.lightningdesignsystem.com/components/combobox/)                                                                 | [Combobox](https://www.lightningdesignsystem.com/components/combobox/)                                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create a Combobox

In your JavaScript, define an array of options. Each option corresponds to a list item on the
dropdown list. Define the content of each option by specifying a `value` property and
a `label` property. The dropdown list shows the label that you provide by using the `label` value.
Select an item updates its corresponding `value` property.

Define an optional `description` property to add a line of descriptive text for each option. The
descriptive text appears below the label of the list item.
When adding descriptions, specify a description for each item in a list.
If some items are missing descriptions, the alignment of the items can appear incorrect.

```javascript
import { LightningElement } from "lwc";
export default class ComboboxExample extends LightningElement {
  statusOptions = [
    { value: "new", label: "New", description: "A new item" },
    {
      value: "in-progress",
      label: "In Progress",
      description: "Currently working on this item",
    },
    {
      value: "finished",
      label: "Finished",
      description: "Done working on this item",
    },
  ];

  value = "new";

  handleChange(event) {
    // Get the string of the "value" attribute on the selected option
    this.value = event.detail.value;
  }
}
```

Selecting an option triggers the `change` event, which calls the
`handleChange` function. To check which option is clicked,
use `event.detail.value`.

## Append an SLDS Icon

By default, the combobox options don't include an icon. To include an SLDS icon on the options, use the `button` variant. This variant supports options with and without icons. Consider these icon behaviors:

- The icon is placed before the option label
- The icon size is `xx-small` (14 px)
- Each option can have a unique SLDS icon

Visit [icons](https://v1.lightningdesignsystem.com/icons) to view the available icons.

To create a combobox with a unique SLDS icon on each option, use the `button` variant with the `iconName` property on the options.

<!-- prettier-ignore -->
```html
<lightning-combobox
  label="Filter"
  variant="button"
  value={filterValue}
  options={filterOptions}
  onchange={handleFilterChange}
>
</lightning-combobox>
```

When you select an option from the list, the icon and label are shown on the button.

```javascript
import { LightningElement } from "lwc";
export default class ComboboxExample extends LightningElement {
  filterValue = "all";
  get filterOptions() {
    return [
      { label: "All Items", value: "all", iconName: "utility:filter" },
      { label: "Active Only", value: "active", iconName: "utility:check" },
      { label: "Archived", value: "archived", iconName: "utility:archive" },
      { label: "Pending", value: "pending", iconName: "utility:clock" },
    ];
  }
  handleFilterChange(event) {
    this.filterValue = event.detail.value;
  }
}
```

To create a combobox that appears pill-like without an icon, use the `button` variant without specifying `iconName` on the options.

## Input Validation

Client-side input validation is available for this component. You can require
the selection by adding the `required` attribute. An error message is
automatically shown when an item isn’t selected on a required element.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` attributes. See [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html) for more information.

You can override the default message by providing your own value for
`message-when-value-missing`.

## Component Styling

Use a combination of variants and utility classes to customize your combobox styles.

### Variants

Use the `variant` attribute with one of these values to apply styling.

- `label-hidden` hides the label but make it available to assistive technology
- `label-inline` horizontally aligns the label and combobox
- `label-stacked` to place the label above the combobox
- `button` presents a pill-shaped combobox with icon support. See [Append an SLDS Icon](#append-an-slds-icon).

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute,

## Usage Considerations

Special characters like `"` must be escaped. For example, you want to display
`"New"`.

```javascript
const options = [
  { value: '"new"', label: '"New"' },
  { value: "expired", label: "Expired" },
];
```

When you use single quotes in the value, escape the quote with a double slash
instead of a single slash.

`lightning-combobox` doesn't currently support autocomplete or typeahead. The `autocomplete` attribute is reserved for internal use.

In Lightning Experience, a `lightning-combobox` dropdown list that's opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

On mobile devices, `lightning-combobox` has these limitations.

- The dropdown menu doesn't scroll correctly when there's limited space to show the complete list of options.
- The mobile viewport doesn't display the dropdown menu correctly, especially if you place the component near the bottom of the page.

We recommend that you use the HTML `<select>` element on mobile instead.

To enable record lookup in a combobox, use the [`lightning-record-picker` component](/docs/platform/lightning-component-reference/guide/lightning-record-picker.html) instead.

## Accessibility

Provide a text label for accessibility to make the information
available to assistive technology. The `label` attribute creates an HTML label
element for your component. To hide a label from view and make it
available to assistive technology, use the `label-hidden` variant.

This component uses `button` elements for select-only comboboxes to comply with the [Lightning Design System combobox blueprint](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup).

When an option label is too long to fit in a single line, the label wraps and continues in a new line. If a long word in an option label isn't fully visible, scroll horizontally on the dropdown list to reveal the whole word.

When a validation error appears, `lightning-combobox` links the input to the error message using the `aria-describedby` attribute. The error message is wrapped in an element with `role="status"`, which announces it through a polite, non-interruptive live region. `lightning-combobox` doesn't use `role="alert"` or `aria-live="assertive"` for validation errors as these roles interrupt the user immediately. A validation error doesn't need immediate interruption as the component already blocks form submission until the error is corrected.

Some browser and screen reader combinations, such as Chrome with JAWS or NVDA on Windows, announce the error message twice when a user leaves the invalid field. However, this behavior ensures that the user is notified of the error, regardless of which browser or screen reader they use. For more information, see [_LinkedIn_:Balancing UX and Accessibility with Screen Readers and Error Messages](https://www.linkedin.com/pulse/balancing-ux-accessibility-screen-readers-error-zmdte/).

## Custom Events

**`change`**

The event fired when an item is selected in the combobox.

The `change` event returns this parameter.

| Parameter     | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| selectedValue | string | The value of the selected option. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

**`open`**

The event fired when the dropdown is opened.

The `open` event doesn’t return any parameters.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can’t call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |


:::::

:::::tab
::component-specification{component="combobox" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=78aa5af7530c9e13d134861337919c9afaf2b7cceeb18a04275913418308e249 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/commerceCartApi/lightning-commerce-cart-api.md -->

# Commerce Cart API

**`lightning/commerceCartApi`**

Create and delete carts for buyers in a webstore using the `lightning/commerceCartApi` module. The `lightning/commerceCartApi` module requires API version 62.0 or later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/commerceCartApi` module includes methods to create and delete carts for buyers in a webstore.

To use the Commerce Cart API in your component, import the functions in your component's JavaScript file.

```js
import { createCart, deleteCart } from "lightning/commerceCartApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-cart-api.html).

:::::

:::::tab
::component-specification{component="commerceCartApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=e380007959712aa2c7d5a8169df0eedbda94d75731023ff5a5143957e32d1ae5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/commerceRegisterGuestBuyerApi/lightning-commerce-register-guest-buyer-api.md -->

# Commerce Register Guest Buyer API

**`lightning/commerceRegisterGuestBuyerApi`**

Register a guest buyer account against a webstore using the `lightning/commerceRegisterGuestBuyerApi` module. The `lightning/commerceRegisterGuestBuyerApi` module requires API version 62.0 or later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/commerceRegisterGuestBuyerApi` module includes a method to register a guest buyer account against a webstore.

To use the Commerce Register Guest Buyer API in your component, import the function in your component's JavaScript file.

```js
import { registerGuestBuyer } from "lightning/commerceRegisterGuestBuyerApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-register-guest-buyer-api.html).

:::::

:::::tab
::component-specification{component="commerceRegisterGuestBuyerApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a5aad955634df0c283a17fc7b8f85aedd86f57fb3a2f65f6fcbca12cd3480c3f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/commerceRepricingApi/lightning-commerce-repricing-api.md -->

# Commerce Repricing API

**`lightning/commerceRepricingApi`**

Retrieve pricing and product details for Order Management repricing scenarios using the `lightning/commerceRepricingApi` module. The `lightning/commerceRepricingApi` module requires API version 62.0 or later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/commerceRepricingApi` module includes wire adapters to retrieve pricing and product details for Order Management repricing scenarios.

To use the Commerce Repricing API in your component, import the wire adapters in your component's JavaScript file.

```js
import { productDetails, searchProducts } from "lightning/commerceRepricingApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-commerce-repricing-api.html).

:::::

:::::tab
::component-specification{component="commerceRepricingApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a1c8cbc663a3ae6e44f56db054e04b2b32c5019f6f6e410bf9900457d84ea1ae url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/componentEvent/aura-component-event.md -->

# Component Event

**`aura:componentEvent`**

The root event of the event hierarchy for all events of `type="COMPONENT"`.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A component event is the primary method for communication up the component hierarchy, typically from a child component to its direct parent.

For more information, see [Component Events](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/events_component.htm) in the _Lightning Aura Components Developer Guide_.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=556904da83a0f3c5bc1cb78a64cb9015c5863848dbe1722e8fff1fa09a350743 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/components.md -->

# Components

Salesforce provides prebuilt components that use the Lightning Web Components (LWC) programming model.

Components in the `lightning` namespace are known as Lightning base components. They implement Salesforce Lightning Design System (SLDS) component designs and blueprints. Lightning base components include the components listed here, and the Aura components listed in [Aura Components in `lightning` Namespace](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/components/aura-lightning.md) section.

Use these functional categories to help choose the right base component for your use case.

## Actions and Menus

Action and menu components trigger an action when you click them.

- [Button](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/button/lightning-button.md)
- [Button Group](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/buttonGroup/lightning-button-group.md)
- [Button Icon](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/buttonIcon/lightning-button-icon.md)
- [Button Icon Stateful](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/buttonIconStateful/lightning-button-icon-stateful.md)
- [Button Menu](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/buttonMenu/lightning-button-menu.md)
  - [Menu Divider](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/menuDivider/lightning-menu-divider.md)
  - [Menu Item](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/menuItem/lightning-menu-item.md)
  - [Menu Subheader](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/menuSubheader/lightning-menu-subheader.md)
- [Button Stateful](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/buttonStateful/lightning-button-stateful.md)
- [Click To Dial](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/clickToDial/lightning-click-to-dial.md)
- [Flow](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/flow/lightning-flow.md)

## Containers

Container components group related content together.

- [Accordion](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/accordion/lightning-accordion.md)
  - [Accordion Section](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/accordionSection/lightning-accordion-section.md)
- [Card](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/card/lightning-card.md)
- [Carousel](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/carousel/lightning-carousel.md)
  - [Carousel Image](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/carouselImage/lightning-carousel-image.md)
- [Layout](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/layout/lightning-layout.md)
  - [Layout Item](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/layoutItem/lightning-layout-item.md)
- [Modal](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/modal/lightning-modal.md)
  - [Modal Body](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/modalBody/lightning-modal-body.md)
  - [Modal Footer](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/modalFooter/lightning-modal-footer.md)
  - [Modal Header](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/modalHeader/lightning-modal-header.md)
- [Quick Action Panel](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/quickActionPanel/lightning-quick-action-panel.md)
- [Tab Set](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/tabset/lightning-tabset.md)
  - [Tab](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/tab/lightning-tab.md)
- [Tile](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/tile/lightning-tile.md)

## Images (Visuals)

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

- [Avatar](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/avatar/lightning-avatar.md)
- [Badge](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/badge/lightning-badge.md)
- [Dynamic Icon](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/dynamicIcon/lightning-dynamic-icon.md)
- [Empty State (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/emptyState/lightning-empty-state.md)
- [Helptext](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/helptext/lightning-helptext.md)
- [Icon](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/icon/lightning-icon.md)
- [Illustration (Beta)](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/illustration/lightning-illustration.md)
- [Map](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/map/lightning-map.md)
- [Pill](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/pill/lightning-pill.md)
- [Pill Container](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/pillContainer/lightning-pill-container.md)

## Input

Input components let users enter data and can validate the input.

- [Checkbox Group](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/checkboxGroup/lightning-checkbox-group.md)
- [Combobox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/combobox/lightning-combobox.md)
- [Dual Listbox](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/dualListbox/lightning-dual-listbox.md)
- [File Upload](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/fileUpload/lightning-file-upload.md)
- [Input](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/input/lightning-input.md)
- [Input Rich Text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/inputRichText/lightning-input-rich-text.md)
  - [Rich Text Toolbar Button](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/richTextToolbarButton/lightning-rich-text-toolbar-button.md)
  - [Rich Text Toolbar Button Group](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/richTextToolbarButtonGroup/lightning-rich-text-toolbar-button-group.md)
- [Radio Group](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/radioGroup/lightning-radio-group.md)
- [Record Picker](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/recordPicker/lightning-record-picker.md)
- [Select](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/select/lightning-select.md)
- [Slider](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/slider/lightning-slider.md)
- [Text Area](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/textarea/lightning-textarea.md)

## Forms

Form components help users create, edit, and view records.

- [Record Form](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/recordForm/lightning-record-form.md)
- [Record Edit Form](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/recordEditForm/lightning-record-edit-form.md)
  - [Input Field](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/inputField/lightning-input-field.md)
- [Record View Form](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/recordViewForm/lightning-record-view-form.md)
  - [Output Field](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/outputField/lightning-output-field.md)

## Navigation

Navigation components help users move between pages.

- [Breadcrumbs](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/breadcrumbs/lightning-breadcrumbs.md)
  - [Breadcrumb](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/breadcrumb/lightning-breadcrumb.md)
- [Vertical Navigation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/verticalNavigation/lightning-vertical-navigation.md)
  - [Vertical Navigation Item](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/verticalNavigationItem/lightning-vertical-navigation-item.md)
  - [Vertical Navigation Item Badge](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/verticalNavigationItemBadge/lightning-vertical-navigation-item-badge.md)
  - [Vertical Navigation Item Icon](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/verticalNavigationItemIcon/lightning-vertical-navigation-item-icon.md)

## Notifications

Status and notification components deliver information and insights.

- [Alert](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/alert/lightning-alert.md)
- [Confirm](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/confirm/lightning-confirm.md)
- [Platform Show Toast Event](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/platformShowToastEvent/lightning-platform-show-toast-event.md)
- [Prompt](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/prompt/lightning-prompt.md)
- [Toast](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/toast/lightning-toast.md)
- [Toast Container](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/toastContainer/lightning-toast-container.md)

## Output

Output components display data that's formatted for the user's locale and language. Use them wherever you want to display data.

- [Formatted Address](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedAddress/lightning-formatted-address.md)
- [Formatted Date Time](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedDateTime/lightning-formatted-date-time.md)
- [Formatted Email](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedEmail/lightning-formatted-email.md)
- [Formatted Location](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedLocation/lightning-formatted-location.md)
- [Formatted Name](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedName/lightning-formatted-name.md)
- [Formatted Number](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedNumber/lightning-formatted-number.md)
- [Formatted Phone](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedPhone/lightning-formatted-phone.md)
- [Formatted Rich Text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedRichText/lightning-formatted-rich-text.md)
- [Formatted Text](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedText/lightning-formatted-text.md)
- [Formatted Time](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedTime/lightning-formatted-time.md)
- [Formatted URL](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/formattedUrl/lightning-formatted-url.md)
- [Relative Date Time](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/relativeDateTime/lightning-relative-date-time.md)

## Progress

Progress components convey the progress of a process.

- [Progress Bar](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/progressBar/lightning-progress-bar.md)
- [Progress Indicator](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/progressIndicator/lightning-progress-indicator.md)
- [Progress Ring](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/progressRing/lightning-progress-ring.md)
- [Progress Step](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/progressStep/lightning-progress-step.md)
- [Spinner](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/spinner/lightning-spinner.md)

## Tables and Trees

Table and tree components can display a large amount of formatted record data. Tree components can show hierarchy with
rows that you can expand and collapse.

- [Datatable](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/datatable/lightning-datatable.md)
- [Tree](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/tree/lightning-tree.md)
- [Tree Grid](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/treeGrid/lightning-tree-grid.md)

## Third-Party UI

Embed your web apps directly in a Salesforce page.

- [UI Embedding](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/lightning/uiEmbedding/lightning-ui-embedding.md)

<!-- document id=fe49fbb46d32a70f44e8200f193c36fe20ff121f36c2b5e7bf27bd799eaa6120 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/confirm/lightning-confirm.md -->


# Confirm

**`lightning/confirm`**

Create a confirm modal within your component that asks the user to respond before they continue.

**For Use In**

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="confirm" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning/confirm` module creates a confirm modal within your component. Use `LightningConfirm` on your component to ask the user to respond before they continue.

Use `LightningConfirm.open()` instead of the native `window.confirm()` for a more consistent user experience. They have similar functions, but `LightningConfirm.open()` works in cross-origin iframes, where the `.confirm()` method is no longer supported in Chrome and Safari. Unlike `window.confirm()`, `LightningConfirm.open()` doesn't halt execution on the page, it returns a Promise. Use `async`/`await` or `.then()` for any code you want to run after the confirm has closed.

Import `LightningConfirm` from the `lightning/confirm` module in the component that opens the confirm modal, and call `LightningConfirm.open()` with your attributes.

This example creates a headerless confirm modal with two buttons, **OK** and **Cancel**. The `.open()` function returns a promise that resolves to true when you click **OK** and false when you click **Cancel**.

<!-- prettier-ignore-start -->
```html
<!-- c/myApp.html -->
<template>
    <lightning-button onclick={handleConfirmClick} label="Open Confirm Modal">
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

```javascript
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 prompt message",
      variant: "headerless",
      label: "this is the aria-label value",
      // setting theme would have no effect
    });
    //Confirm has been closed
    //result is true if OK was clicked
    //and false if cancel was clicked
  }
}
```

## Design

This module implements the prompt blueprint in the Salesforce Lightning Design System (SLDS). The prompt adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                         | SLDS 2                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Prompt](https://v1.lightningdesignsystem.com/components/prompt/)                              | [Prompt](https://www.lightningdesignsystem.com/components/prompt/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of attributes to customize the confirm modal style.

`LightningConfirm` supports these attributes:

- `message`: Message text that displays in the confirm.
- `label`: Header text, also used as the `aria-label`. Default string is `Confirm`.
- `variant`: Two values, `header` and `headerless`. Default value is `header`.
- `theme`: Color theme for the header. The `theme` attribute supports the following [options](https://v1.lightningdesignsystem.com/utilities/themes/#site-main-content) from SLDS:
  - `default`: white
  - `shade`: gray
  - `inverse`: dark blue
  - `alt-inverse`: darker blue
  - `success`: green
  - `info`: gray-ish blue
  - `warning`: yellow
  - `error`: red
  - `offline`: ​black​

If an invalid value is provided, `LightningConfirm` uses the `default` theme. `LightningConfirm` ignores the `style` attribute.

**tip:** To view interactive examples, see the [Examples tab](/docs/platform/lightning-component-reference/guide/lightning-confirm.html?type=Example).

## Test Your Component's Confirm Modal

Code using `LightningConfirm` can be tested by mocking the `LightningConfirm.open()` method.

The example below uses a button to open a confirm dialog and sets the result in a template.

<!-- prettier-ignore-start -->
```html
<button data-button onclick={handleClick}>Open Confirm</button>
<div data-result>{result}</div>
```
<!-- prettier-ignore-end -->

```js
import LightningConfirm from 'lightning/confirm';
jest.mock('lightning/confirm');
​
test(() => {
    // Create and appendChild(element)
​
    const buttonEle = element.shadowRoot.querySelector('[data-button]');
    const resultEle = element.shadowRoot.querySelector('[data-result]');
​
    // Mock .open()
    // Pass true if testing when user clicks "OK"
    // Pass false if testing when user clicks "Cancel"
    LightningConfirm.open = jest.fn().mockResolvedValue(true);
    // Initial value
    expect(resultEle.textContent).toBe('unknown');
    // Click modal open button
    buttonEle.click();
​
    // Click handler render cycle
    await Promise.resolve();
    // Render cycle triggered by tracked value {result}
    await Promise.resolve();
​
    // Verify result is set in the template
    expect(resultEle.textContent).toBe('true');
    // Open triggered once
    expect(LightningConfirm.open.mock.calls).toHaveLength(1);
})
```


:::::

:::::tab
::component-specification{component="confirm" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=d40850a3a122bfdc157b813437c6c3355711311fe15e59add8f74d5a62ed0370 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/conversationAgentSend/aura-conversation-agent-send.md -->

# Conversation Agent Send

**`lightning:conversationAgentSend`**

Indicates an agent sent a message.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning:conversationAgentSend` event is triggered when an agent sends a message through the Salesforce console. This event is also triggered when using Enhanced Messaging channels. To work with Enhanced Messaging channels, the session must be active and the Enhanced Conversation Component must be visible on the page.

For more information, see [Events for Chat](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_liveagent_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name        | Description                                                                                | Type   | Default | Required                                     |
| ----------- | ------------------------------------------------------------------------------------------ | ------ | ------- | -------------------------------------------- |
| `content`   | The text of a message in the chat log.                                                     | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `name`      | The name of the agent who is attempting to send the message as it appears in the chat log. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `recordId`  | Record ID of the conversation.                                                             | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `timestamp` | The date and time the agent attempted to send the chat message.                            | date   |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type`      | The type of message that was received—for example, agent.                                  | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=74a11c9b657031a848422905dd53c161c5bb85dfc192e5da508afd3ec4ed98bc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/conversationChatEnded/aura-conversation-chat-ended.md -->

# Conversation Chat Ended

**`lightning:conversationChatEnded`**

Indicates a conversation has ended.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning:conversationChatEnded` event is triggered when an active chat ends or an agent leaves a chat conference. This event is also triggered when using Enhanced Messaging channels. To work with Enhanced Messaging channels, the session must be active and the Enhanced Conversation Component must be visible on the page.

For more information, see [Events for Chat](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_liveagent_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name       | Description                    | Type   | Default | Required                                     |
| ---------- | ------------------------------ | ------ | ------- | -------------------------------------------- |
| `recordId` | Record ID of the conversation. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=ca069106ea6d2713db74118bf62249bf9a91ec5f52d1bdfeb5cb34e066520d82 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/conversationCustomEvent/aura-conversation-custom-event.md -->

# Conversation Custom Event

**`lightning:conversationCustomEvent`**

Indicates receipt of a custom event on a conversation.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning:conversationCustomEvent` event is triggered when a custom event occurs during a chat.

For more information, see [Events for Chat](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_liveagent_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name       | Description                        | Type   | Default | Required                                     |
| ---------- | ---------------------------------- | ------ | ------- | -------------------------------------------- |
| `data`     | Data attached to the custom event. | string |         |                                              |
| `recordId` | Record ID of the conversation.     | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type`     | Name of the custom event.          | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=0d0da3d4275e393b8969a531b50e9e274f10f2eaed340b631d224ef33069cef5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/conversationNewMessage/aura-conversation-new-message.md -->

# Conversation New Message

**`lightning:conversationNewMessage`**

Indicates that a new message was sent by the customer.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning:conversationNewMessage` event is triggered when the customer sends a new message. This event is also triggered when using Enhanced Messaging channels. To work with Enhanced Messaging channels, the session must be active and the Enhanced Conversation Component must be visible on the page.

For more information, see [Events for Chat](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_liveagent_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name        | Description                                                                                                  | Type   | Default | Required                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------ | ------ | ------- | -------------------------------------------- |
| `content`   | The message that was sent by the customer.                                                                   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `name`      | The name of the user who sent the message. This name matches the username displayed in the conversation log. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `recordId`  | Record ID of the conversation.                                                                               | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `timestamp` | The date and time that the message was received.                                                             | date   |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type`      | The type of message that was received—for example, agent.                                                    | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=5d9722ff28a28b467f2fd878f89dccd67739c5fbc3679335769ca99d9b492d57 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/conversationToolkitApi/lightning-conversation-toolkit-api.md -->

# Conversation Toolkit API

**`lightning/conversationToolkitApi`**

Conversation Toolkit API is a collection of front-end API methods for interacting with the MIAW or Enhanced Messaging product using the `lightning/conversationToolkitApi` module. The `lightning/conversationToolkitApi` module requires API version 60.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

All the methods in the `lightning/conversationToolkitApi` module return a promise. Required method parameters are explicitly passed as individual arguments. Optional parameters are passed into an object as the last argument of the method.

To use the Conversation Toolkit API in your component, import the functions in your component's JavaScript file.

```js
import {
  endConversation,
  getConversationLog,
  setAgentInput,
  sendTextMessage,
  setMessagingComponent,
  sendMessagingComponent,
  inactivateConversation,
} from "lightning/conversationToolkitApi";
```

**note:** Using Conversation Toolkit API in markup via the `lightning-conversation-toolkit-api` component is deprecated. Use the imported functions instead. Some functions are available only by import.

For this module's documentation, see [LWC Methods for Enhanced Messaging in Lightning Experience](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_enhanced_lightning_conversationtoolkitapi_lwc.htm) in the Console Developer Guide.


:::::

:::::tab
::component-specification{component="conversationToolkitApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a5384fb81f0d31a4cfb7bcf5e0e132ac6bac594576740524defac22cd24a8240 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/createRecord/force-create-record.md -->

# Create Record

`force:createRecord`

Displays the Full Record Create panel.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event opens a page to create a record for the specified `entityApiName`, for example, "Account", or "myNamespace**MyObject**c".

**note:** We recommend implementing `lightning:pageReferenceUtils` instead and creating the object using `lightning:navigation` with the `standard__object` page type. This launches a record create page with fields prepopulated with default values.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm).

To display the record create page for an object, set the object name on the `entityApiName` attribute and fire the event. `recordTypeId` is optional and, if provided, specifies the record type for the created object. Provide `recordTypeId` as a separate field, not as part of `defaultFieldValues`. `defaultFieldValues` is optional and, if provided, specifies values to use to prepopulate the create record form.

This example displays the record create panel for contacts.

```javascript
createRecord : function (component, event, helper) {
    var createRecordEvent = $A.get("e.force:createRecord");
    createRecordEvent.setParams({
        "entityApiName": "Contact"
    });
    createRecordEvent.fire();
}
```

This event is handled by the one.app container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites. This event presents a standard page to create a record. That is, it doesn’t respect overrides on the object’s create action.

The following objects are not supported by `force:createRecord`:

- `ContractLineItem`
- `EventRelation`
- `OpportunityLineItem`
- `OrderItem`
- `QuoteLineItem`
- `TaskRelation`
- `WorkOrderLineItem`

## Prepopulating Field Values

The `defaultFieldValues` attribute lets you prepopulate the create record form with default or calculated field values. Prepopulated values can accelerate data entry, improve data consistency, and otherwise make the process of creating a record easier. Specify default field values as name-value pairs in a JavaScript object.

This example displays the record create panel for a contact with two fields prepopulated.

```
var createAcountContactEvent = $A.get("e.force:createRecord");
createAcountContactEvent.setParams({
    "entityApiName": "Contact",
    "defaultFieldValues": {
        'Phone' : '415-240-6590',
        'AccountId' : '001xxxxxxxxxxxxxxx'
    }
});
createAcountContactEvent.fire();
```

You can specify values for fields even if they’re not available in the create record form.

- If the field is hidden because it’s not on the page layout, the value specified in `defaultFieldValues` is saved with the new record.
- If the current user doesn’t have create access to the field, due to field-level security, attempts to save the new record result in an error.

Error messages can’t reference fields the current user doesn’t have access to. This constraint means the user won’t know why the error occurred or how to resolve the issue. Firing the `force:createRecord` event tells the app to use the standard create record page. You can’t catch errors that occur there, or alter the create page interface or behavior, for example, to show an improved error message. For this reason, it’s essential to perform access checks in your own code, before firing the event.

You can’t prepopulate system-maintained fields, such as Id or record modification time stamps. Default values for these fields are silently ignored.

Prepopulating rich text fields is unsupported. It might work for simple values, but the internal format of rich text fields is undocumented, so setting complex values that include formatting is problematic. Use at your own risk.

Default values on dependent picklists are available on accounts, opportunities, cases, contacts, leads, and custom objects.

Date and time field values must use the ISO 8601 format. For example:

- Date: 2017-07-18
- Datetime: 2017-07-18T03:00:00Z

While the create record panel presents datetime values in the user’s local time, you must convert datetime values to UTC to prepopulate the field.


:::::

:::::tab
## Attributes

| Name                 | Description                                                                                                                                                                                                                                                                                            | Type   | Default | Required |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | -------- |
| `defaultFieldValues` | Prepopulates fields on a record create panel, including fields not displayed on the panel. ID fields and rich text fields can't be prepopulated. Users must have create access to prepopulated fields. Errors during saving that are caused by field access limitations do not display error messages. | map    |         |          |
| `entityApiName`      | Required. The API name of the custom or standard object, such as "Account", "Case", "Contact", "Lead", "Opportunity", or "namespace\_\_objectName\_\_c".                                                                                                                                               | string |         |          |
| `recordTypeId`       | Non-null if recordTypes are enabled. Null means Master RecordType.                                                                                                                                                                                                                                     | string |         |          |

:::::

::::::

<!-- document id=18c678bb41d82656bfc163ba76fbf283003f220fb3e06b8e89b8a0237b747177 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/analyticsWaveApi/lightning-analytics-wave-api.md -->

# CRM Analytics API

**`lightning/analyticsWaveApi`**

Get data and metadata for CRM Analytics assets, execute queries, and schedule data syncs for recipes, dataflows, and data connectors using the `lightning/analyticsWaveApi` module. CRM Analytics was previously known as Wave Analytics. The `lightning/analyticsWaveApi` module requires API version 52.0 or later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/analyticsWaveApi` module includes wire adapters and methods to work with CRM Analytics.

To use the CRM Analytics API in your component, import the functions in your component's JavaScript file.

```js
import {
  createDataConnector,
  createDataflowJob,
  createDatasetVersion,
  createDataset,
  createReplicatedDataset,
  ...
} from "lightning/analyticsWaveApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-analytics-wave-api).

:::::

:::::tab
::component-specification{component="analyticsWaveApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=22bcdf7c6d0537d6579120aa93602899605482426eff9a6546e72507c2046b35 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceChatter/customOpenFile/forceChatter-custom-open-file.md -->

# Custom Open File

**`forceChatter:customOpenFile`**

Adds custom logic for file open/tap action for Communities on mobile and tablet devices.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Specifications"]'}

:::::tab

## Attributes

| Name       | Description                | Type   | Default | Required                                     |
| ---------- | -------------------------- | ------ | ------- | -------------------------------------------- |
| `recordId` | The ID of the file record. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |


:::::

::::::

<!-- document id=f076e05bb05453a59488cb34040505d0273ae60ae9413099c50a6c3ad4ea599f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/datatable/lightning-datatable.md -->


# Datatable

**`lightning-datatable`**

A table that displays rows and columns of data.

**For Use In**

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="datatable" model="lwc" namespace="lightning"}


:::::

:::::tab

`lightning-datatable` presents tabular data where each column renders the content based on the data type.
For example, an email address is shown as a hyperlink with the `mailto:` URL scheme by specifying the
`email` type. The default data type on a column is `text`.

`lightning-datatable` isn't supported on mobile devices. Supported features
include:

- Formatting of columns with appropriate data types
- Infinite scrolling of rows
- Inline editing for some data types
- Header actions
- Header wrapping
- Row-level actions
- Resizing of columns
- Selecting of rows
- Sorting of columns by ascending and descending order
- Text wrapping and clipping
- Row numbering column
- Cell content alignment
- Appending an SLDS icon to column data
- Hiding the table header
- Hiding the table borders

Initialize the table by using the `data`, `columns`, and `key-field` attributes.
The `key-field` attribute is required for correct table behavior.
It associates each row with a unique identifier. The value you use for `key-field` is
case-sensitive and must match what's in your `data` array.
If you use `key-field="Id"`, make sure the Id that you provide in the `data` array
uses `Id` and not `id`.

## Design

`lightning-datatable` implements the data tables blueprint in the Salesforce Lightning Design System (SLDS). The data tables adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                         | SLDS 2                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Data Tables](https://v1.lightningdesignsystem.com/components/data-tables/)                    | [Data Tables](https://www.lightningdesignsystem.com/components/data-tables/)                                    |
| **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create a Data Table

This example creates a table whose first column shows a checkbox for row selection.
This column is visible by default, and you can hide it by adding `hide-checkbox-column` in your markup.
Selecting the checkbox selects the entire row of data and triggers the `onrowselection` event handler.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-datatable
        data={data}
        columns={columns}
        key-field="Id"
        onrowselection={getSelectedName}
    >
    </lightning-datatable>
</template>
```
<!-- prettier-ignore-end -->

Here's the JavaScript that creates selectable rows and the
`columns` object to their corresponding column data. The Probability column
shows percentages with an icon that denotes the increasing or decreasing
confidence trend.

This example defines five columns by setting properties and attributes for the `columns` object. The
Probability column shows percentages and an icon that denotes the increasing
or decreasing confidence trend. The icon is specified with the `cellAttributes`
property. See [Column Properties](#column-properties) for more information about the
properties for columns.

The JavaScript also loads two rows of data in the table. The ID for each
table row is used as the `key-field`.

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

const columns = [
  { label: "Opportunity name", fieldName: "OpportunityName", type: "text" },
  {
    label: "Probability",
    fieldName: "Probability",
    type: "percent",
    cellAttributes: {
      iconName: { fieldName: "TrendIcon" },
      iconPosition: "right",
    },
  },
  {
    label: "Amount",
    fieldName: "Amount",
    type: "currency",
    typeAttributes: { currencyCode: "EUR", step: "0.001" },
  },
  { label: "Contact Email", fieldName: "Contact", type: "email" },
  { label: "Contact Phone", fieldName: "Phone", type: "phone" },
];

const data = [
  {
    Id: "a",
    OpportunityName: "Cloudhub",
    Probability: 0.2,
    Amount: 25000,
    Contact: "jrogers@cloudhub.com",
    Phone: "2352235235",
    TrendIcon: "utility:down",
  },
  {
    Id: "b",
    OpportunityName: "Quip",
    Probability: 0.78,
    Amount: 740000,
    Contact: "quipy@quip.com",
    Phone: "2352235235",
    TrendIcon: "utility:up",
  },
];

export default class DatatableExample extends LightningElement {
  data = data;
  columns = columns;

  getSelectedName(event) {
    const selectedRows = event.detail.selectedRows;
    // Get that fieldName of the selected rows
    for (let i = 0; i < selectedRows.length; i++) {
      alert("You selected: " + selectedRows[i].OpportunityName);
    }
  }
}
```

When the data table is rendered, each row has a checkbox in the first
column. The first row shows columns with the data: Cloudhub, 20%,
\$25,000.00, jrogers@cloudhub.com, and (235) 223-5235. The last two columns use hyperlinks to represent an email address and telephone number.

## Select Rows

Selecting any number of rows via checkboxes or a radio button in the selection column emits the `onrowselection` event. The `event.detail.selectedRows` property contains a list of all selected rows after any checkbox or radio button interaction. Alternatively, the `event.detail.config.value` contains a single `id` value of the row that was toggled.

This JavaScript function returns the email addresses of all rows as they're selected.

```js
getSelectedEmail(event) {
    // Get the Contact of the selected rows
    event.detail.selectedRows.forEach((selectedRow) => {
        alert('Selected email addresses: ' + selectedRow.Contact);
    });
}
```

Use the `event.detail.config.action` property to keep a running list of rows that have been selected or deselected. `event.detail.config.action` has four possible values:

- `selectAllRows`: all rows are selected via the checkbox in the column header
- `deselectAllRows`: all rows are deselected via the checkbox in the column header
- `rowSelect`: single row is selected via the row checkbox
- `rowDeselect`: single row is deselected via the row checkbox

This JavaScript example keeps two running lists of row objects: a list of rows that have ever been selected and a list of row objects that are currently selected.

```js
selectedData = [];
currentlySelectedData = [];

handleRowSelection(event) {
    switch (event.detail.config.action) {
        case 'selectAllRows':
            for (let i = 0; i < event.detail.selectedRows.length; i++) {
                selectedData.push(event.detail.selectedRows[i]);
                currentlySelectedData.push(event.detail.selectedRows[i]);
            }
            break;
        case 'deselectAllRows':
            currentlySelectedData = [];
            break;
        case 'rowSelect':
            selectedData.push(event.detail.config.value);
            break;
        case 'rowDeselect':
            index = currentlySelectedData.indexOf(event.detail.config.value);
            if (index !== -1) {
                array.splice(index, 1);
            }
            break;
        default:
            break;
    }
}
```

To return the data in each selected row, use the `getSelectedRows()` method. This example returns the data of the selected row(s) in a paragraph.

<!-- prettier-ignore-start -->
```html
 <lightning-datatable
    lwc:ref="dt"
    key-field="id"
    data={data}
    columns={columns}></lightning-datatable>
<lightning-button
    label="Get Selected Row"
    onclick={handleGetSelected}></lightning-button>
<p>{selectedStr}</p>
```
<!-- prettier-ignore-end -->

To query your datatable, use the `lwc:ref` directive. This example uses `lwc:ref="dt"` where `dt` is the unique reference. Call the reference using `this.refs.dt`.

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

// Define columns (COLS) here
// Define or retrieve data (DATA) here

export default class DatatableExample extends LightningElement {
  data = DATA;
  columns = COLS;
  selected;

  handleGetSelected() {
    this.selected = this.refs.dt.getSelectedRows();
  }

  get selectedStr() {
    return this.selected ? JSON.stringify(this.selected) : "";
  }
}
```

For example, if two rows are selected and you click the **Get Selected Row** button, the paragraph shows:

```json
[
  {
    "name": "Name (0)",
    "website": "www.salesforce.com",
    "amount": 80,
    "phone": "7352970211",
    "closeAt": "2025-01-16T06:37:06.606Z"
  },
  {
    "name": "Name (1)",
    "website": "www.salesforce.com",
    "amount": 81,
    "phone": "3746646998",
    "closeAt": "2025-02-01T06:37:06.606Z"
  }
]
```

## Work with Data

To return a simple list of records, use the `getListUi` wire adapter. To select certain accounts using SOQL, use an Apex method. See [Call Apex Methods](https://developer.salesforce.com/docs/platform/lwc/guide/apex).

This example loads the first 10 contacts in the datatable using a SOQL query.

```java
public with sharing class ContactController {

    @AuraEnabled(cacheable=true)
    public static List<Contact> getContactList() {
        return [SELECT Id, FirstName, LastName, Title, Phone, Email FROM Contact LIMIT 10];
    }
}
```

The template wires up the datatable to the contact records using the `id` field.

<!-- prettier-ignore-start -->
```html
<template>
<lightning-datatable
    key-field="Id"
    data={contacts.data}
    columns={columns}>
</template>
```
<!-- prettier-ignore-end -->

Load the columns using JavaScript. This example wires the `getContactList` Apex method to the `contacts` property.

```javascript
import { LightningElement, wire } from "lwc";
import getContactList from "@salesforce/apex/ContactController.getContactList";

const columns = [
  { 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" },
];
export default class ApexDatatableExample extends LightningElement {
  error;
  columns = columns;

  @wire(getContactList)
  contacts;
}
```

## Column Properties

Use the following column properties to customize the behavior and visual
aspects of your columns.

| Property           | Type    | Description                                                                                                                                                                                                                                                                                                    |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| actions            | object  | Appends a dropdown menu of actions to a column. You must pass in a list of label-name pairs.                                                                                                                                                                                                                   |
| cellAttributes     | object  | Provides additional customization using `alignment` and `class` properties, in addition to `icon*` properties such as for appending an icon to the output. For more information, see [Append an Icon to Column Data](#append-an-icon-to-column-data).                                                          |
| editable           | boolean | Specifies whether a column supports inline editing. The default is false.                                                                                                                                                                                                                                      |
| fieldName          | string  | Required. The name that binds the columns attributes to the associated data. Each columns attribute must correspond to an item in the data array.                                                                                                                                                              |
| fixedWidth         | integer | Specifies the width of a column in pixels and makes the column non-resizable. If both `fixedWidth` and `initialWidth` values are provided, `initialWidth` is ignored.                                                                                                                                          |
| hideDefaultActions | boolean | Specifies whether to hide the default header actions on a column. The default is false. For more information, see [Create Header Actions](#create-header-actions).                                                                                                                                             |
| hideLabel          | boolean | Specifies whether to hide the label on a column. The default is false. For more information, see [Show an Icon Instead of a Column Label](#show-an-icon-instead-of-a-column-label).                                                                                                                            |
| iconName           | string  | The Lightning Design System name of the icon. Names are written in the format standard:opportunity. The icon is appended to the left of the header label. If `hideLabel` is provided, only the icon is visible in the column header.                                                                           |
| imgSrc             | string  | The URI for a custom icon. The icon is appended to the left of the header label. If `hideLabel` is provided, only the icon is visible in the column header. If there's an error loading the URI, `iconName` is used as a fallback.                                                                             |
| initialWidth       | integer | The width of the column when it's initialized, which must be within the `min-column-width` and`max-column-width` values, or within 50px and 1000px if they are not provided.                                                                                                                                   |
| label              | string  | Required. The text label in the column header. If `hideLabel` and `iconName` are set, the label is used as hover text for the icon and as the value of `aria-label`.                                                                                                                                           |
| sortable           | boolean | Specifies whether the column can be sorted. The default is false.                                                                                                                                                                                                                                              |
| type               | string  | Required. The data type to be used for data formatting. For more information, see [Data Types](#data-types).                                                                                                                                                                                                   |
| typeAttributes     | object  | Provides custom formatting with component attributes for the data type. For example, currency-code for the currency type. For more information, see [Data Types](#data-types).                                                                                                                                 |
| wrapText           | boolean | Specifies whether text in a column is wrapped when the table renders. Wrapped text vertically expands a row to reveal its full content. Use with `wrap-text-max-lines` to limit a number of lines before hiding the rest. For more information, see [Text Wrapping and Clipping](#text-wrapping-and-clipping). |

## Data Types

The data table formats the data cells of a column based on the type you specify for the column. To get correct formatting, specify a type that matches the field type you pass in to a column.

The default data type for a column is `text`. Object values passed into a text type column are shown as an empty string.

For number and string values like percent, currency, date, email, and phone numbers, the text type column shows the unformatted value of the string. For example, specify `type: 'date'` in the column definition if you're passing in a date to the column. The date is then formatted according to the user's Salesforce locale. If you don't specify the date type, the retrieved date string is formatted as text.

Additionally, specify `type: 'boolean'` if you're passing in a boolean value to a column to show a checkmark for a `true` value. Passing in a boolean value to a column of `text` type shows the value as `true` or `false`.

Each data type is associated with a base Lightning component. For example, the `text` type renders the associated data using a `lightning-formatted-text` component. The `phone` type renders the associated data using a `lightning-formatted-phone` component, and the phone number is formatted for the user's locale.

To customize your output, pass in the attributes of the base component via the `typeAttributes` property. Not all attributes on a base component are supported. For more information, see the table on supported type attributes below.

The properties you pass with `typeAttributes` must be specified by using the format shown here, not the format that's used for Lightning web component attributes in your HTML template. For example, although `lightning-formatted-number` recognizes a `currency-code` attribute, you must specify it as `currencyCode` with the `typeAttributes` property. For supported attribute values, refer to the component's documentation.

Valid data types and their supported attributes include:

| Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Supported Type Attributes                                                                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action      | Shows a dropdown menu using [lightning-button-menu](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html) with actions as menu items. The default dropdown menu alignment, denoted by `menuAlignment`, is `right`. Valid options for `menuAlignment` are `right`, `left`, `auto`, `center`, `bottom-left`, `bottom-center`, and `bottom-right`. Use `alternativeText` to set the accessible name of the row action trigger button. The accessible name defaults to "Show actions" and can reference a row field name to provide a record-specific accessible name. See [Create Static Row-Level Actions](#create-static-row-level-actions). | rowActions (required), menuAlignment (defaults to right), alternativeText (defaults to "Show actions")                                                        |
| boolean     | Shows the icon utility:check if the value is true, and a blank value otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | N/A                                                                                                                                                           |
| button      | Shows a button using [lightning-button](/docs/platform/lightning-component-reference/guide/lightning-button.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | disabled, iconName, iconPosition, label, name, title, variant                                                                                                 |
| button-icon | Shows a button icon using [lightning-button-icon](/docs/platform/lightning-component-reference/guide/lightning-button-icon.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | alternativeText, class, disabled, iconClass, iconName, name, title, variant                                                                                   |
| currency    | Shows a currency using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html). See [ Currency and Percentages](#currency-and-percentages).                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | currencyCode, currencyDisplayAs, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, step |
| date        | Shows a date and time based on the locale using [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html). See [Date and Time](#date-and-time).                                                                                                                                                                                                                                                                                                                                                                                                                                                         | day, era, hour, hour12, minute, month, second, timeZone, timeZoneName, weekday, year                                                                          |
| date-local  | Shows a date that is formatted based on the locale using [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html). To include a time value, use the `date` type instead. The value passed is assumed to be in the browser local time zone and there is no time zone transformation. See [Date and Time](#date-and-time).                                                                                                                                                                                                                                                                               | day, month, year                                                                                                                                              |
| email       | Shows an email address using [lightning-formatted-email](/docs/platform/lightning-component-reference/guide/lightning-formatted-email.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                           |
| location    | Shows a latitude and longitude of a location using [lightning-formatted-location](/docs/platform/lightning-component-reference/guide/lightning-formatted-location.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | latitude, longitude                                                                                                                                           |
| number      | Shows a number using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits                                        |
| percent     | Shows a percentage using [lightning-formatted-number](/docs/platform/lightning-component-reference/guide/lightning-formatted-number.html). See [Currency and Percentages](#currency-and-percentages).                                                                                                                                                                                                                                                                                                                                                                                                                                                                | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, step                                  |
| phone       | Shows a phone number using [lightning-formatted-phone](/docs/platform/lightning-component-reference/guide/lightning-formatted-phone.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A                                                                                                                                                           |
| text        | Shows text using [lightning-formatted-text](/docs/platform/lightning-component-reference/guide/lightning-formatted-text.html). This is the default data type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | linkify                                                                                                                                                       |
| url         | Shows a URL using [lightning-formatted-url](/docs/platform/lightning-component-reference/guide/lightning-formatted-url.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | label, target, tooltip                                                                                                                                        |

In some situations, multiple columns reference the same `fieldName` but have different `fieldApiNames` and different ways of working with the field information. To give a column a unique ID when using the same field name for two columns, use the attribute `columnKey` instead of `fieldName` on one of the column definitions.

```javascript
get columns() {
    return [
        // Column using 'fieldName' as identifier
        {
            label: 'Lead',
            fieldName: 'leadId',
            ...
        },
        // Column using 'columnKey' as identifier
        {
            label: 'Company',
            columnKey: 'leadCompany',
            fieldName: 'leadId',
            ...
        }
    ]
}
```

## Custom Formatting

To customize the formatting based on the data type, pass in the attributes for
the corresponding base Lightning component. For example, to show the URL value as a tooltip on a URL, pass in the `tooltip` value.

```javascript
const columns = [
  {
    label: "Company Website",
    fieldName: "website",
    type: "url",
    typeAttributes: { tooltip: { fieldName: "website" } },
  },
  // other column data
];
```

For more information on attributes and their supported values, see the
corresponding base component documentation.

For more information on creating your own data types, see [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types).

### Currency and Percentages

Currency type displays a value based on the org currency and your Salesforce locale by default.

To override the default currency code, pass in a custom `currencyCode` value.

```javascript
const columns = [
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    typeAttributes: { currencyCode: "EUR" },
  },
  // other column data
];
```

To specify the granularity on a currency or percentage for inline editing, pass in the `step` attribute. For example, specify `step: 0.01` to allow numbers with two decimal places, or `step: 0.001` permits three decimal places. Specify `step: 1` to require whole numbers. The default is `0.01`. You can preserve the number of fraction digits for display using `minimumFractionDigits` and `maximumFractionDigits`.

```javascript
const columns = [
  {
    label: "Probability",
    fieldName: "probability",
    type: "percent",
    typeAttributes: {
      step: "0.00001",
      minimumFractionDigits: "2",
      maximumFractionDigits: "3",
    },
    editable: true,
  },
  //other column data
];
```

For example, if you pass in `probability: 0.21234` in your column data, the display value is `21.234%`. When you inline edit, the `step` value is used to determine if your input is valid. If you pass in `probability: 0.78`, the display value is `78.00%` because `minimumFractionDigits` is set to `2`.

### Date and Time

The locale set in the Salesforce user preferences determines the default formatting for date and time types.

The data table supports the date object and dates provided as ISO8601 formatted strings. Timestamps are not supported.
These date formats can be displayed differently in a column. The default format is `September 26, 2020`,
which corresponds to `type: "date"` or `type: "date-local"` and an empty `typeAttributes` property.

While the `date` type can be used to display date and time, the `date-local` type displays only the date. Here's how you can show Salesforce date and time data types in `lightning-datatable`.
Salesforce Data Type|Datatable Data Type|Description
-----|-----|-----
DateTime|date|Expects date and time as input, and formats it according to the user's locale.
Date|date-local|Expects date as input, and formats it according to the user's locale. Does not include time conversion.

Here are several ways to show date and time in a column.

09/26/2018

```javascript
    {
        label: "Date",
        fieldName: "DueDate",
        type: "date-local",
        typeAttributes:{
            month: "2-digit",
            day: "2-digit"
        }
    }
```

Wednesday, September 26, 2018

```javascript
    {
        label: "Closed Date",
        fieldName: "ClosedDate",
        type: "date",
        typeAttributes:{
            weekday: "long",
            year: "numeric",
            month: "long",
            day: "2-digit"
        }
    }
```

September 26, 2018, 12:00 PM

```javascript
    {
        label: "Arrival Time",
        fieldName: "ArrivalTime",
        type: "date",
        typeAttributes:{
            year: "numeric",
            month: "long",
            day: "2-digit",
            hour: "2-digit",
            minute: "2-digit"
        }
    }
```

Wednesday, September 26, 2018, 12:00 PM

```javascript
    {
        label: "Event Time",
        fieldName: "EventTime",
        type: "date",
        typeAttributes:{
            weekday: "long",
            year: "numeric",
            month: "long",
            day: "2-digit",
            hour: "2-digit",
            minute: "2-digit"
        }
    }
```

The locale set in your Salesforce preferences determines the formatting.
For more information, see the [lightning-formatted-date-time](/docs/platform/lightning-component-reference/guide/lightning-formatted-date-time.html) documentation.

## Align Content in A Column

To horizontally align content in a column, use the `cellAttributes` property to pass in the `alignment` attribute and its setting, which can be `left`, `right`, or `center`.

```javascript
const columns = [
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    cellAttributes: { alignment: "left" },
  },
  // other column data
];
```

By default, number types align to the right. Number types include the `currency`, `number`, `percent` types.

The `action` type aligns to the center and cannot be overridden by the `alignment` attribute. All other types align to the left.

To override the alignment of the `action` type, consider using custom types and provide your own markup. See [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types).

## Show an Icon Instead of a Column Label

To show an icon instead of a label in the column header, specify the properties `iconName` and `hideLabel` in the column definition. Specify `iconName` as a [utility icon](https://v1.lightningdesignsystem.com/icons/#utility).

To display a custom image in the column header, use the `imgSrc` property to specify a link to an image. To use an image in your org, upload the image as a static resource in the Static Resources setup page and then import the image from the [`@salesforce/resourceUrl` module](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.html).

When both `iconName` and `imgSrc` are provided, `iconName` is used as a fallback if there is an error when attempting to load the image provided by `imgSrc`.

```javascript
const columns = [
  {
    label: "Ordering",
    fieldName: "id",
    type: "orderingButtons",
    fixedWidth: 90,
    iconName: "utility:trending",
    imgSrc: "https://www.lightningdesignsystem.com/assets/images/product2.jpg",
    hideLabel: true,
  },
  // other column data
];
```

To support assistive technologies, set the `label` property for the column even though the label is hidden. Use standard header text that you'd use without an icon. The label text is used to set values for the icon's `title` and `alternativeText` attributes. The text is shown as hover text. If the column has header controls the label text is used in `aria-label` for the header.

## Append an Icon to Column Data

To append an icon to your data output, use `cellAttributes` and pass in these
attributes.

| Attribute           | Description                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| iconName            | Required. The Lightning Design System name of the icon, for example, utility:down.                                      |
| iconLabel           | The label for the icon to be displayed on the right of the icon.                                                        |
| iconPosition        | The position of the icon relative to the data. Valid options include `left` and `right`. This value defaults to `left`. |
| iconAlternativeText | Descriptive text for the icon.                                                                                          |

You can add an icon with or without a label. This example defines two columns with icons.
The first column specifies the `utility:event` icon for all rows using the `iconName` cell attribute, and the icon appears to the left of the data without a label.
The second column uses computed values for the `iconName` and `iconLabel` and shows the icon to the right of the data.

```javascript
const columns = [
  // simple icon
  {
    label: "Close date",
    fieldName: "closeDate",
    type: "date",
    sortable: true,
    cellAttributes: {
      iconName: "utility:event",
      iconAlternativeText: "Close Date",
    },
  },
  // icon appended with a label
  {
    label: "Probability",
    fieldName: "probability",
    type: "percent",
    cellAttributes: {
      iconName: { fieldName: "confidenceDeltaIcon" },
      iconLabel: { fieldName: "confidenceDelta" },
      iconPosition: "right",
      iconAlternativeText: "Percentage Probability",
    },
  },
  // other column data
];
```

## Add Styles To Columns

Pass Lightning Design System (SLDS) classes to the `class` cell attribute when using standard data types. The classes you add are applied to all rows in a column.

```javascript
const columns = [
  {
    label: "Account Name",
    fieldName: "Name",
    cellAttributes: {
      class: "slds-text-color_success slds-text-title_caps",
    },
  }, // other column data
];
```

Custom classes are currently not supported. To apply custom styling on your datatable cells, create a custom data type and then apply your custom CSS classes. See [Custom Data Type Layout and Styles](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-styling).

## Show Indicators for Read-Only Fields

You can show a lock icon on read-only fields to specify they're not editable. To specify that a column's field as read-only, set the column attribute `editable` to `false` and the column attribute `displayReadOnlyIcon` to `true` in the associated column definition. This example shows a lock icon on each field in a column called "Website."

```javascript
const columns = [
    {
        label: 'Website',
        fieldName: 'website',
        type: 'url',
        editable: false,
        displayReadOnlyIcon: true,
    }
```

## Infinite Scrolling

Infinite scrolling enables you to load a subset of data and then shows more
when users scroll to the end of the table. To enable infinite scrolling, specify
`enable-infinite-loading` and provide an event handler using
`onloadmore`. By default, data loading is triggered when you scroll down to
20px from the bottom of the table, but the offset can be changed using the
`load-more-offset` attribute. Place the table in a container with a defined height
to establish the bottom of the table. This limit enables the datatable to calculate
when to load more and prevents infinite looping.

This example places the datatable in a container with a height of 500px. The table
loads 50 more rows from the database when you reach the end of the table until
there are no more data to load.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="height: 500px">
        <lightning-datatable
            columns={columns}
            data={data}
            key-field="Id"
            enable-infinite-loading
            onloadmore={loadMoreData}
        >
        </lightning-datatable>
    </div>
    {loadMoreStatus}
</template>
```
<!-- prettier-ignore-end -->

The `onloadmore` event handler retrieves more data when you scroll to the
bottom of the table until there are no more data to load. To show a spinner
while data is being loaded, set the `isLoading` property to `true`.

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

export default class DatatableExample extends LightningElement {
  data = [];
  columns = columnsDefs;
  loadMoreStatus;
  @api totalNumberOfRows;

  loadMoreData(event) {
    //Show a spinner to signal that data is being loaded
    event.target.isLoading = true;
    //Show "Loading" when more data is being loaded
    this.loadMoreStatus = "Loading";
    fetchData(50).then((data) => {
      if (data.length >= this.totalNumberOfRows) {
        event.target.enableInfiniteLoading = false;
        this.loadMoreStatus = "No more data to load";
      } else {
        const currentData = this.data;
        //Appends new data to the end of the table
        const newData = currentData.concat(data);
        this.data = newData;
        this.loadMoreStatus = "";
      }
      event.target.isLoading = false;
    });
  }
}
```

While this example uses a fixed number to denote the total number of rows, you
can also use the SOQL SELECT syntax with the `COUNT()` function to return the
number of rows in the object in your Apex controller. Then, set the result on
the `totalNumberOfRows` attribute during initialization.

```
    SELECT COUNT(Id) FROM Contact
```

## Scroll Back to the Top

Scrolling to the top of the datatable programmatically is useful if there are more rows than can fit the datatable's height. To quickly return to the first row, use the `scrollToTop()` method.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="height: 500px;">
        <lightning-datatable
                key-field="id"
                data={data}
                columns={columns}
                lwc:ref="datatable">
        </lightning-datatable>
    </div>
    <lightning-button label="Scroll to Top" onclick={handleScroll}></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

To call the `scrollToTop()` method, use [the `lwc:ref` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.html#refs). This example uses `lwc:ref="datatable"` where `datatable` is the unique reference. Call the reference using `this.refs.datatable`.

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

const columns = [
  // column data here
];

export default class DatatableScrollExample extends LightningElement {
  data = [];
  columns = columns;

  handleScroll() {
    this.refs.datatable.scrollToTop();
  }
}
```

The `scrollToTop()` method applies to the datatable's scrollbar only. It doesn't apply to the browser's scrollbar or an outer container scrollbar.

When you nest the datatable in a `div` container that specifies a height, the datatable header stays fixed at the top when you scroll through the rows. When the datatable is not nested in a `div` container with a height, the datatable header isn't fixed and can scroll. In the latter case, `scrollToTop()` doesn't scroll back to the top.

## Create Header Actions

Header actions refer to tasks you can perform on a column of data, such
as showing only rows that meet a criteria provided by the column. You can
perform actions on a column and handle them using the `onheaderaction` event
handler.

Header actions are available in the dropdown menu in the column header. The default header actions available on each column are as follows. For more information, see [Text Wrapping and Clipping](#text-wrapping-and-clipping).

| Action Name | Description                                                                                                                                                                              |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Wrap text   | Expands the row vertically to reveal more content if content is wider than the column width. Use `wrap-text-max-lines` to determine the number of lines to show when content is wrapped. |
| Clip text   | Truncates content to a single line with an ellipsis if content is wider than the column width. Content is clipped by default.                                                            |

To hide the dropdown menu with the default header actions on a column, pass in the `hideDefaultActions` property.

```javascript
const columns = [
  { label: "Opportunity name", fieldName: "opportunityName", type: "text" },
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    typeAttributes: { currencyCode: "EUR" },
    hideDefaultActions: true,
  },
  //other column data
];
```

If `hideDefaultActions` is set to `true` on a column that has custom header actions, the "Clip text" and "Wrap text" actions are removed from the actions dropdown menu,
and the content is clipped by default. To wrap text when the default actions are hidden, set `wrapText: true` in the column definition.

To create a custom header action, use the attributes as follows.

| Attribute | Description                                                                                                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label     | Required. The label for the action.                                                                                                                                                                              |
| name      | Required. The name of the action, which identifies the selected action.                                                                                                                                          |
| checked   | Specifies whether a check mark is shown to the left of the action label. If true, a check mark is shown to the left of the menu item. If false, a check mark is not shown but there is space to accommodate one. |
| disabled  | Specifies whether the action can be selected. If true, the action item is shown as disabled. This value defaults to false.                                                                                       |
| iconName  | The name of the icon that appears to the right of the action item.                                                                                                                                               |

For example, suppose you want to create a filter that shows only rows where the
Publishing State column matches either the Published or Unpublished state.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-datatable
        columns={mycolumns}
        data={mydata}
        key-field="Id"
        onheaderaction={handleHeaderAction}
    >
    </lightning-datatable>
</template>
```
<!-- prettier-ignore-end -->

Bind the header actions to the `actions` column attribute, which can be done
during initialization.

```javascript
const columns = [
  // other column data
  {
    label: "Publishing State",
    fieldName: "published",
    type: "text",
    actions: [
      { label: "All", checked: true, name: "all" },
      { label: "Published", checked: false, name: "show_published" },
      { label: "Unpublished", checked: false, name: "show_unpublished" },
    ],
  },
];
```

```javascript
handleHeaderAction: (event) {
    // Retrieves the name of the selected filter
    const actionName = event.detail.action.name;
    // Retrieves the current column definition
    // based on the selected filter
    const colDef = event.detail.columnDefinition;
    const columns = this.columns;
    const activeFilter = this.activeFilter;

    if (actionName !== activeFilter) {
        var idx = columns.indexOf(colDef);
        // Update the column definition with the updated actions data
        var actions = columns[idx].actions;
        actions.forEach((action) => {
            action.checked = action.name === actionName;
        });
        this.activeFilter = actionName;
        this.updateBooks();
        this.columns = columns;
    }
}
```

Finally, return the rows to match the selected filter, which is performed by
`this.updateBooks()`.

```javascript
updateBooks(cmp) {
    const rows = this.rawData;
    const activeFilter = this.activeFilter;
    const filteredRows = rows;
    if (activeFilter !== 'all') {
        filteredRows = rows.filter(function (row) {
            return (activeFilter === 'show_published' ||
              (activeFilter === 'show_unpublished');
        });
    }
    this.data = filteredRows;
}
```

## Create Static Row-Level Actions

Row-level actions refer to tasks you can perform on a row of data, such as
updating or deleting the row. Static actions apply to all rows on the table.
You can perform actions on each row and handle them using the `onrowaction`
event handler.

Supported attributes for the row actions are as follows.

| Attribute | Description                                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |
| label     | Required. The label for the action.                                                                                        |
| name      | Required. The name of the action, which identifies the selected action.                                                    |
| disabled  | Specifies whether the action can be selected. If true, the action item is shown as disabled. This value defaults to false. |
| iconName  | The name of the icon that appears to the right of the action item.                                                         |

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-datatable
        columns={mycolumns}
        data={mydata}
        key-field="Id"
        onrowaction={handleRowAction}
    >
    </lightning-datatable>
</template>
```
<!-- prettier-ignore-end -->

You must provide a list of actions to the columns data, which can be done
during initialization. This JavaScript initializes the actions
column and handles the actions on each row, showing the row details and
deleting the row when the action is clicked.

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

const actions = [
    { label: 'Show details', name: 'show_details' },
    { label: 'Delete', name: 'delete' }
];

const columns = [
    // Other column data here
    { type: 'action', typeAttributes: { rowActions: actions, menuAlignment: 'left' } }
];

export default class DatatableExample extends LightningElement {
    data = [];
    columns = columns;

    handleRowAction(event) {
            const action = event.detail.action;
            const row = event.detail.row;
            switch (action.name) {
                case 'show_details':
                    alert('Showing Details: ' + JSON.stringify(row));
                    break;
                case 'delete':
                    const rows = this.data;
                    const rowIndex = rows.indexOf(row);
                    rows.splice(rowIndex, 1);
                    this.data = rows;
                    break;
     }
}
```

By default, screen readers announce the row action trigger button as "Show actions" on every row. To give the button a more descriptive, record-specific accessible name, use `alternativeText`. Bind it to a row field name so each row gets a distinct accessible name.

```javascript
const columns = [
  // Other column data here
  {
    type: "action",
    typeAttributes: {
      rowActions: actions,
      // Announces, for example, "Show actions for Acme Corp"
      alternativeText: { fieldName: "showActionsLabel" },
    },
  },
];
```

## Create Dynamic Row-Level Actions

Dynamic actions are created based on the content of each row. When you click
the dropdown menu, an asynchronous call is made to determine which actions to
return for the particular row. The logic that determines which action to
return can be created on initialization. In this example, the action and its
label is evaluated when the dropdown menu is activated. Assume that we have an
`active` column that shows the status of a contact (Active or Inactive),
which determines which action to show (Deactivate or Activate).

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

const actions = [
    { label: 'Show details', name: 'show_details' },
    { label: 'Delete', name: 'delete' }
];

const columns = [
    // Your column data
];

export default class DatatableExample extends LightningElement {
    data = [];
    columns = columns;

    constructor() {
        super();
        this.columns = [
            // Other column data here
            { type: 'action', typeAttributes: { rowActions: this.getRowActions } },
        ]
    }

    getRowActions(row, doneCallback) {
        const actions = [];
            if (row['isActive']) {
                actions.push({
                    'label': 'Deactivate',
                    'iconName': 'utility:block_visitor',
                    'name': 'deactivate'
                });
            } else {
                actions.push({
                    'label': 'Activate',
                    'iconName': 'utility:adduser',
                    'name': 'activate'
                });
            }
            // simulate a trip to the server
            setTimeout(() => {
                doneCallback(actions);
            }), 200);
    }
}
```

The previous example illustrates how to create and handle dynamic actions on
the client-side only. You can make server calls and persist your record data
changes via an Apex controller.

## Resize Tables and Columns

The width and height of the datatable is determined by the container element.
A scroller is appended to the table body if there are more rows to show.
For example, you can restrict the height to 300px by applying CSS styling to
the container element.

<!-- prettier-ignore-start -->
```html
<div style="height: 300px;">
    <!-- lightning-datatable goes here -->
</div>
```
<!-- prettier-ignore-end -->

By default, columns are resizable. Users can resize the column width to a
minimum of 50px and a maximum of 1000px. Users can also resize the column width using the keyboard. For more information, see the [Accessibility](#accessibility) section.

### Work with Column Widths

You can customize the column widths in many ways. To specify your own width and disable resizing for a specific column, pass in `fixedWidth` to the column property. To specify an initial width and enable resizing for a specific column, pass in `initialWidth` to the column property.

```javascript
const columns = [
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    initialWidth: 80,
  },
  // other column data
];
```

Columns have a default minimum width of 50px and maximum width of 1000px. To change the minimum and maximum width of columns, use the
`min-column-width` and `max-column-width` attributes. For example, if you want a user to be able to resize a column to a minimum of 80px, set `min-column-width="80"`.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    key-field="Id"
    data={data}
    columns={columns}
    min-column-width="80"
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

To prevent users from resizing columns, specify `resize-column-disabled` in your markup. The table can still adjust its column widths when you resize the browser window or the width of the parent container changes. The `resize-column-disabled` attribute allows the table to resize columns when `column-widths-mode` is set to `auto`. See the next section for more information.

Resizing a column fires the `resize` event. For more information, See the [Custom Events](#custom-events) section.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    key-field="Id"
    data={data}
    columns={columns}
    onresize={handleResize}
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

To return the column widths, use the `event.detail` property on the `onresize` event handler.

```javascript
handleResize(event) {
    const sizes = event.detail.columnWidths;
}
```

### Manage Column Width Resize

The `column-widths-mode` attribute accepts values of `fixed` (default) or `auto`. To provide granular control on your column widths, use this attribute with the `fixedWidth` and `initialWidth` column properties. See [Use Fixed Width Mode](#use-fixed-width-mode) and [Use Auto Width Mode](#use-auto-width-mode) for more information.

Widths for the following columns are fixed and cannot be changed.

- Row Number column
- Selection (checkbox) column
- Action column

### Use Fixed Width Mode

Render columns with equal widths using `column-widths-mode="fixed"`, which is the default setting. Any content that's too long to be shown is clipped and appears with a trailing ellipsis. The column width is calculated by taking total available width and dividing equally among the columns.

You can specify your own widths using `fixedWidth` or `initialWidth`. The widths of the remaining columns without a specified `fixedWidth` or `initialWidth` value are equal.

Setting new data on the columns doesn't trigger resizing for columns, unless the new column definition specifies a change in `fixedWidth` or `initialWidth` values. In `fixed` mode, the columns automatically resizes and maintain equal widths when:

- The browser window is resized
- The parent container width for the datatable is changed
- The `row-number-offset` value is changed
- More or less data is passed in

When you manually resize a column to a larger width, the other columns maintain their widths, showing a scrollbar to enable scrolling to the end of the table columns. When you manually resize to a smaller width, the other columns also maintain their widths.

You can resize manually using a mouse or a keyboard. On a keyboard, press enter in the header cell, tab to reach the resizer (column divider), and press the left or right arrow keys. On a touchscreen device, tap on the desired column resizer area, move to the desired width, and then release.

### Use Auto Width Mode

To trigger resizing of columns according to the length or size of data in a column, set `column-widths-mode="auto"`. In `auto` width mode, the columns automatically resize when:

- Data changes in at least one row and the number of rows stays the same
- The column definition changes, such as a change in a column property or the number of columns

Pass a new reference of columns with changes for resize to take effect. The columns don't resize if there's only a change in the number of records in the data.

Column widths are calculated based on the width of the content in the column and the total width of the table. Specify your own widths for particular columns using the `fixedWidth` or `initialWidth` properties. The widths of the columns without these properties are calculated based on the width of the content in the column and the remaining table width. If the columns definition is passed but no data is set yet, the columns are rendered based on the width of the column labels.

A column's width is limited by the `max-column-width` value, or 1000px by default. If a column width is calculated to be wider than the `max-column-width` value, the content is truncated and shown with an ellipsis. If the column also specifies `wrapText: true`, the column results in a narrower width than if the column has clipped text.

A column's width is also limited by the `min-column-width` value, or 50px by default. If a column width is calculated to be narrower than the `min-column-width` value, the width is set to minimum column width and may have extra white space.

When you manually resize a column, the other columns maintain their widths. This behavior also occurs when a column is manually resized in `fixed` mode.

The columns keep their width ratios while adjusting the column widths when:

- The browser window is resized
- The parent container width for the datatable is changed
- The `rowNumberOffset` value is changed

Auto width mode is supported for containers with block display, which corresponds to the `display: block` CSS property.
`lightning-datatable` doesn't fully support containers with `display:inline-block` or flex properties.

## Specify Maximum Number of Selected Rows

You can specify how many rows can be selected. When the maximum number of rows have been selected, the datatable disables the checkboxes that aren't selected. You can select another checkbox only after you deselect one of the selected checkboxes.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    key-field="Id"
    data={data}
    columns={columns}
    max-row-selection="5"
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

## Enable Single Row Selection

To enable single row selection, set `max-row-selection="1"`. For single row selection, the datatable use a radio button by default. Selecting the radio button selects the entire row of data and triggers the `onrowselection` event handler.

To render a checkbox for single row selection, set `single-row-selection-mode="checkbox"`.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    key-field="Id"
    data={data}
    columns={columns}
    max-row-selection="1"
    single-row-selection-mode="checkbox"
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

## Select Rows Programmatically

The `selected-rows` attribute enables you to preselect rows.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    columns={columns}
    data={data}
    key-field="Id"
    selected-rows={selectedRows}
>
</lightning-datatable>
<lightning-button label="Select" onclick={handleSelect}> </lightning-button>
```
<!-- prettier-ignore-end -->

To select a row programmatically, pass in the row `key-field` value.

```javascript
    // Load data via init handler first
    // then handle programmatic selection
    handleSelect() {
        const rows = ['a'];
        this.selectedRows = rows;
    }
```

If `max-row-selection` is set to a value less than the number of selected rows,
only the specified number of rows is selected. For example, if you set
`max-row-selection` to 2 and pass in `['a', 'b', 'c']` to `selected-rows`, only
rows a and b are selected.

## Disable Rows Programmatically

Use the `disabled-rows` attribute to prevent users from changing the selection status of specified rows. Pass row identifiers into `disabled-rows` to prevent the rows from being selected. Pass row identifiers into both `disabled-rows` and `selected-rows` to prevent the rows from being deselected.

<!-- prettier-ignore -->
```html
<template>
  <lightning-datatable
    key-field="id"
    columns={columns}
    data={data}
    disabled-rows={disabledRows}
  >
  </lightning-datatable>
</template>
```

To disable a row programmatically, pass in the row `key-field` value to the `disabled-rows` attribute.
For example, `disabledRows = ['a', 'b'];` where `a` and `b` correspond to the `id` values of the rows to be disabled.
Rows that are both disabled and selected count towards the `max-row-selection`.
For example, if you set `max-row-selection` to 2, and pass in `['a', 'b']` to both
`disabled-rows` and `selected-rows`, the user can't select additional rows.

## Sort Data By Column

To enable sorting of row data by a column label, set `sortable` to `true` for
the column on which you want to enable sorting. Clicking a column header sorts rows by ascending order, and clicking it subsequently reverses the order. Handle the `onsort` event to update the table with the new column index and sort direction.

Here's an example of an `onsort` event handler.

```javascript
data = data;
columns = columns;
sortDirection = 'asc';
sortedBy;
// The method onsort event handler
handleSort(event) {
    const { fieldName: sortedByField, sortDirection } = event.detail;
    const cloneData = [...this.data];

    cloneData.sort(this.sortBy(sortedByField, sortDirection === 'asc' ? 1 : -1));
    this.data = cloneData;
    this.sortDirection = sortDirection;
    this.sortedBy = sortedByField;
}
```

The handler assigns `fieldName` to `sortedByField`, which stores the name of the field that is currently being sorted. It also retrieves `sortDirection` from the `sort` event. On first sort, `sortDirection` is `asc`.

To keep the original data intact, `cloneData` creates a shallow copy of the `data` array. The handler passes in the comparison function `sortBy` and pass it to the [array sort() method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). Then it updates the `data` property with the sorted data, `sortDirection` with the new sort direction, and `sortedBy` with the sorted column.

For more information, see the Sortable Column example in the Example tab.

## Inline Editing

When you make a column editable, a pencil icon appears when you hover over the
cells in that column. Clicking the icon or pressing the Enter key triggers
inline editing. Inline editing is not supported for date and location fields.

Make a column editable by setting `editable` to true when you are defining
your columns.

```javascript
    {label: 'Amount', fieldName: 'amount', type: 'currency', typeAttributes: { currencyCode: 'EUR'}, editable : 'true'},
    {label: 'Contact Email', fieldName: 'contact', type: 'email', editable : 'true'}
```

You can handle the `oncancel`, `oncellchange`, and `onsave` actions when the
cell value changes or is saved. When the `onsave` action is used, the
**Cancel** and **Save** button appears after a value cell changes and you
press the Enter or Tab key, or move away from the cell.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-datatable
        key-field="Id"
        data={data}
        columns={columns}
        onsave={handleSave}
    >
    </lightning-datatable>
</template>
```
<!-- prettier-ignore-end -->

Retrieve the new value using `event.detail.draftValues`.

```javascript
handleSave(event) {
    this.saveDraftValues = event.detail.draftValues;
}
```

You can also program an external element, such as a button, to open an inline edit panel on the currently active cell or next editable cell in the datatable. Invoke the `openInlineEdit()` method in the external element that should direct a user to the first editable cell in your datatable component.

This example opens a datatable cell for inline edit when the user clicks an "Edit" button.

```javascript
import { LightningElement } from "lwc";
export default class DatatableWithInlineEdit extends LightningElement {
  data = [];
  columns = columns;
  rowOffset = 0;

  handleClick() {
    const dt = this.template.querySelector("lightning-datatable");
    dt.openInlineEdit();
  }
}
```

For more information, see [Display Data in a Table with Inline Editing](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-inline-edit).

## Handle Errors

When invalid data is entered, `lightning-datatable` can show client-side validation error messages at the row level and the table level.

To show errors for a column, you must make the column editable. When there's an editable column, `lightning-datatable` sets the `show-row-number-column` attribute to true to show the row errors in the number column. You can't override this setting.

For cells with standard types, the datatable uses the `lightning-input` component to handle editing of the cell content, and also to aid in handling error messages. To show error messages with custom data types, you can use `lightning-input` with the attribute `data-inputable` in your edit template. Then use the same techniques described here for showing errors.

To show error messages for any editable columns, specify the `errors` attribute in your `lightning-datatable` component.

The `errors` attribute represents an object that specifies a `rows` property to provide information for the rows that contain errors and a `table` property to provide error information to show for the table.

The `errors` attribute represents an object that accepts one or both of these properties.

- `rows`-Provides information to show errors at the row level.
- `table`-Provides information to show errors at the bottom of the table. See [Show Errors for the Table](#show-errors-for-the-table).

The `rows` object keys are the datatable’s `key-field` values, which provide a unique identifier for each row. Using this `key-field` value, you can provide custom errors on specific rows.

Customize the error messages using these properties in the `rows` object.

- `title`-Title for the error tooltip.
- `messages`-Text of error messages, listed in an array.
- `fieldNames`-Fields that triggered errors. Order the field names in a simple array to match the messages in the `messages` array.
- `rowTitle`-Optional string for the error icon's assistive text, which is used in place of the row's scope cell value.

**note:** Set `rowTitle` when the scope cell value isn't a string, such as when the custom cell type outputs an object. Screen readers then announce a meaningful row label instead of `[object Object]`. If you don't set `rowTitle` and the scope cell value isn't a usable string, the assistive text falls back to `Row Number {N}`, where `{N}` is the row's 1-based index, so screen readers always announce a meaningful identifier.

To show custom messages under the fields with errors, you can specify `fieldNames` as an object instead of a simple array. See [Show Custom Error Messages for Cells](#show-custom-error-messages-for-cells).

When an error is triggered, the datatable highlights in red the cell that corresponds to the specified `fieldName` value, and shows an error icon in the row number column. When you click the icon, a tooltip shows the text that's specified in `title` and `messages`.

For all types of error display, you must add the `errors` attribute to your component. This attribute's values can be modified in events that handle error conditions.

Your `lightning-datatable` component looks something like this.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-datatable
        key-field="Id"
        data={data}
        columns={columns}
        errors={errors}
    >
    </lightning-datatable>
    <lightning-button label="Trigger error" onclick={triggerError}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

In this example, you can click a button to show the errors.

## Show Errors on a Row

For row-level errors, define the error messages and field names in the `errors` object. To map the messages to `fieldNames`, specify an array of field names in the same order in which you specify the messages. In the example, when the error is triggered, the borders for the `amount` and `contact` cells in the row with the `key-field` 1 turn red to represent the error state. The messages are shown in the tooltip in the number column, not on the cells themselves.

```javascript
    triggerError(event) {
           this.errors = {
                rows: {
                    1: {
                        title: 'We found 2 errors.',
                        messages: [
                            'Enter a valid amount.',
                            'Verify the email address and try again.'
                        ],
                        fieldNames: ['amount', 'contact']
                    }
                },
            };
        }
```

## Show Custom Error Messages for Cells

To show custom error messages under each field that has an error, you can specify the `fieldNames` property as an object of key-value pairs specifying the field name and the message like this:

```javascript
    triggerError(event) {
           this.errors = {
                rows: {
                    1: {
                        title: 'We found 2 errors.',
                        messages: [
                            'Enter a valid amount.',
                            'Verify the email address and try again.'
                        ],
                        fieldNames: {
                            'amount': "Enter an amount greater than 100"
                            'contact': "Specify a valid domain name"
                        }

                    }
                },
            };
        }
```

If a cell is in the error state, the error message appears below the field when you click the edit icon to correct the entry. If you want to show the error icon and tooltip in the number column in addition to the field level message, also include the `title` and `messages` properties.

## Show Errors for the Table

To show error messages at the bottom of the table, use the `table` property in the `error` object like this:

```javascript
  triggerError(event) {
           this.errors = {
                table: {
                    title: 'Your entry cannot be saved. Fix the errors and try again.',
                    messages: [
                        'Row 1 amount must be number',
                        'Row 1 email is invalid'
                    ]
                }
            };
        }
```

When you use the `table` property, if an error occurs in an edited cell, the datatable shows an error icon in the bottom bar next to the Cancel and Save buttons. Click the icon to show a tooltip with the values of the `title` and `messages` properties that are set for the `table` property. The table-level errors require the table bottom bar to be present. Don’t include the attribute `suppress-bottom-bar` in the `lightning-datatable` component.

To show errors on rows and at the bottom of the table, declare both the `rows` and `table` properties in the `errors` object.

```javascript
    triggerError(event) {
           this.errors = {
                rows: {
                    1: {
                        title: 'We found 2 errors.',
                        messages: [
                            'Enter a valid amount.',
                            'Verify the email address and try again.'
                        ],
                        fieldNames: {
                            'amount': "Enter an amount greater than 100"
                            'contact': "Specify a valid domain name"
                        }
                    }
                },
               table: {
                    title: 'Your entry cannot be saved. Fix the errors and try again.',
                    messages: [
                        'Row 1 amount must be number',
                        'Row 1 email is invalid'
                    ]
                }
                    }
                },
            };
        }
```

## Text Wrapping and Clipping

You can wrap or clip text within columns. Text wrapping expands the rows vertically to reveal more content. Text clipping truncates the content to a single line within the column.

To toggle between the two views, select **Wrap text** or **Clip text** from
the dropdown menu on the column header.

If the number of characters is more than what the column width can hold,
content is clipped by default.

Text wrapping and clipping are not supported for row number columns and the following data types:

- action
- boolean
- button
- button-icon
- date-local

For `text` data type, text clipping converts newline characters to spaces and condenses multiple spaces or tabs to one space. Text clipping suppresses line breaks, truncates content to fit a single line in the column, and adds a trailing ellipsis. Text wrapping breaks lines and hyphenates words as needed to fit the column.

To enable text wrapping by default, set `wrapText` to true on the `columns` property.

```javascript
const columns = [
  {
    label: "Description",
    fieldName: "description",
    type: "text",
    wrapText: true,
  },
  //other column data
];
```

To show a number of lines of text in the column and hide the remaining lines, use `wrap-text-max-lines`.
This example shows three lines of text and hides the rest; the text on line 3 is truncated and shown with an ellipsis.

<!-- prettier-ignore-start -->
```html
<lightning-datatable
    data={data}
    columns={columns}
    key-field="Id"
    wrap-text-max-lines="3"
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

Handle the selection of **Wrap text** or **Clip text** on the column header using the `onheaderaction` handler.
To return the name of the action, use the `event.target.action.name` property.

### Text Wrapping in Column Headers

You can also wrap or clip the text in the column header with the `wrap-table-header` attribute. The property has three possible values:

- none (default)
- all
- by-column

`none` causes clipping on all column headers and `all` causes wrapping on all column headers. `by-column` wraps the header for columns that have the **Wrap text** setting enabled and clips the header for columns that have the **Clip text** setting enabled.

## Accessibility

`lightning-datatable` renders with a `grid` role and a polite live region that announces whether the table is in navigation mode or action mode. To toggle action mode, tab into the table and then press the Enter key or Space Bar. To toggle back to navigation mode, press the Esc key to return focus to the cell. For more information about the different modes, see [Toggle Between Navigation and Action Modes](#toggle-between-navigation-and-action-modes).

Each row header renders with an `aria-label` attribute with the labels you provide for the column definition. By default, the row number column renders with `aria-label="Row Number"` and cannot be changed. When row selection is enabled, each row renders with `aria-selected` set to true or false depending on whether the row is selected. Each cell renders with a `gridcell` role.

Use the following `aria` attributes on `lightning-datatable` to provide a caption or description on your table for assistive technologies. These attributes are rendered on the `<table>` element.

| Attribute        | Type              | Description                                                                                                                                        |
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| aria-label       | string            | Provides an assistive label to identify a table from other tables on a page.                                                                       |
| aria-describedby | ID reference list | Specifies the ID or space-separated list of IDs that describes the current element.                                                                |
| aria-labelledby  | ID reference list | Specifies the ID or space-separated list of IDs of the element or elements that contain visible descriptive text to caption or describe the table. |

When using `aria-label`, consider using `aria-describedby` to provide supplemental information. We don't recommend using `aria-label` together with `aria-labelledby`. When there's visible text that labels an element, consider using `aria-labelledby` instead of `aria-label`.

If you use `aria-describedby`, the element that provides the description doesn't need to be visible. For more information, see [MDN web docs: aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby).

### Provide an Accessible Label for the Table

Use the `aria-label` attribute to provide a more descriptive label for the datatable for assistive technology. The `aria-label` attribute and its value are passed down to the rendered `table` element.
On pages with multiple tables, `aria-label` helps users identify which table
they're accessing.

Set the attribute in `lightning-datatable` in your template.

<!-- prettier-ignore-start -->
```html
<lightning-datatable aria-label="Account Details by Year for EMEA Region">
</lightning-datatable>
```
<!-- prettier-ignore-end -->

Change the ARIA label dynamically using the `ariaLabel` property.

```javascript
const myLightningDataTableElement = this.template.querySelector("lightning-datatable");
myLightningDataTableElement.ariaLabel = "Account Details by Revenue for EMEA Region";
```

The `aria-label` attribute doesn't support empty strings. If you set `aria-label=""` in the HTML or `.ariaLabel = ""` in JavaScript, the table's `aria-label`
attribute is hidden, not rendered with an empty string. An empty label string can confuse screen readers.

### Provide an Accessible Caption for the Table

If you have descriptions on an element or on multiple elements for the table, set the `aria-labelledby` value with the ID or list of IDs of the elements.

<!-- prettier-ignore-start -->
```html
<h2 id="table-desc1">Account Details by Year</h2>
<h3 id="table-desc2">EMEA Region</h3>
<lightning-datatable
    aria-labelledby="table-desc1 table-desc2"
    key-field="Id"
    data={data}
    columns={columns}
>
</lightning-datatable>
```
<!-- prettier-ignore-end -->

`lightning-datatable` generates a unique string for the element and `aria-labelledby` value to prevent any naming conflicts with other `<table>` elements on the page. Always verify that your rendered table correctly matches the IDs of the descriptive text in the DOM with a screen reader like JAWS or VoiceOver.

### Toggle Between Navigation and Action Modes

You can use data tables in navigation mode and action mode using the keyboard.
To enter navigation mode, tab into the data table, which triggers focus on the
first data cell in the table body on initial load. Use the arrow keys to move around the table. If you use the arrow key to 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.

To enter action mode, press Enter or the Spacebar. You can navigate to each actionable element in the table using the Tab key.

When focus is on a cell that contains a link, press Enter to activate the link. If the link is a URL, the browser directs you to the website. If the link is a phone number or email, your browser prompts you to open the appropriate app for the link.

When using custom types, add additional attributes to make all elements of the component accessible. To make elements focusable, pass `tabindex={internalTabIndex}` all the way down to every component or element in the custom type. All focusable elements also must include `data-navigation="enable"`. If you don't want the element to be focusable, use `tabindex=-1`. For more information, see [Datatable Accessibility](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.html) in the Lightning Web Components Developer Guide.

### Resize Columns Using Arrow Keys

Columns can be resized in action mode. The component announces the column width during a resize. First, navigate to the column header using the arrow keys. Then, press the Tab key to activate the column divider to resize a column. You can resize a column by increasing or decreasing its width using one of the following key combinations.

- Right and Left Arrow keys
- Up and Down Arrow keys
- Page Up and Page Down keys

When you resize a column, the new column width is announced by assistive technology. To finish resizing the column and return to navigation mode, press the Esc key.

### Resize Columns Using Your Mouse

There are several ways to resize a column using your mouse.

- Click and drag: To resize a column, click the column header divider and drag your mouse to the width that you want.
- Click to activate resize mode: To resize a column, click the column header divider, move your mouse to the width that you want, and click again to commit the resize. To exit resize mode without committing the resize, press the Esc key or tab to remove focus from the column edge.

### Apply Focus on an Active Cell

To programmatically apply focus to the active cell, use the `focus()` method. For example, you can click a button to move focus back to the last active cell on the datatable.

<!-- prettier-ignore-start -->
```html
 <lightning-datatable
    lwc:ref="dt"
    key-field="id"
    data={data}
    columns={columns}></lightning-datatable>
<lightning-button
    label="Focus"
    onclick={handleFocus}></lightning-button>
```
<!-- prettier-ignore-end -->

To query your datatable, use the `lwc:ref` directive. This example uses `lwc:ref="dt"` where `dt` is the unique reference. Call the reference using `this.refs.dt`.

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

// Define columns (COLS) here
// Define or retrieve data (DATA) here

export default class DatatableExample extends LightningElement {
  data = DATA;
  columns = COLS;
  selected;

  handleFocus() {
    this.refs.dt.focus();
  }
}
```

## Usage Considerations

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`cancel`**

The event fired when the cancel button is pressed during inline editing.

The `cancel` event does not return any parameter.

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

**`headeraction`**

The event fired when a header action is selected, such as text wrapping, text clipping, or a custom header action.

The `headeraction` event returns the following parameters.

| Parameter        | Type   | Description                                                                                                                                                                                                  |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| action           | object | The action definition described in [Create Header Actions](#create-header-actions).                                                                                                                          |
| columnDefinition | object | The column definition specified in the `columns` property, for example, the key-value pairs for `label`, `fieldName`, `type`, `typeAttributes`, and `wrapText`. See [Column Properties](#column-properties). |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

**`loadmore`**

The event fired when you scroll to the bottom of the table to load more data, until there are no more data to load.

The `loadmore` event returns the following parameters.

| Parameter             | Type    | Description                                                                                                              |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| enableInfiniteLoading | boolean | Specifies whether infite loading is available on the table.                                                              |
| isLoading             | boolean | Specifies that data is loading and shows a spinner on the table.                                                         |
| loadMoreOffset        | integer | The number of pixels between the bottom of the table and the current scroll position, used to trigger more data loading. |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

**`resize`**

The event fired when the a table column is resized, which depends on which width mode you're using.

In the default `fixed` width mode, the `resize` event is fired when:

- The table renders initially
- You manually resize a column
- The number of columns changes on a subsequent rerender

In `auto` width mode, the event is fired only when you manually resize a column. See [Use Fixed Width Mode](#use-fixed-width-mode) and [Use Auto Width Mode](#use-auto-width-mode) for more information.

The `resize` event is _not_ fired in the following cases.

- You resize the browser or viewport, causing adjustments in the column widths
- You change the column definition, but not the number of columns, causing adjustments in the column widths.

The `resize` event returns the following parameters.

| Parameter       | Type    | Description                                                                                                                                         |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| columnWidths    | object  | The width of all columns, in pixels. For example, a table with 5 columns of 205px width each at initial render returns `[205, 205, 205, 205, 205]`. |
| isUserTriggered | boolean | Specifies whether the column resize is caused by a user action.                                                                                     |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

**`rowselection`**

The event fired when the row is selected.

The `rowselection` event returns the following parameter.

| Parameter     | Type   | Description                                                                                                            |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| selectedRows  | object | The data in the rows that are selected.                                                                                |
| config.action | string | The type of selection event. Valid options include 'selectAllRows', 'deselectAllRows', 'rowSelect', and 'rowDeselect'. |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

**`save`**

The event fired when data is saved during inline editing.

The `save` event returns the following parameter.

| Parameter   | Type   | Description                                              |
| ----------- | ------ | -------------------------------------------------------- |
| draftValues | object | The current value that's provided during inline editing. |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

**`sort`**

The event fired when a column is sorted.

The `sort` event returns the following parameters.

| Parameter         | Type    | Description                                                    |
| ----------------- | ------- | -------------------------------------------------------------- |
| fieldName         | string  | The fieldName that controls the sorting.                       |
| isMultiColumnSort | boolean | Reserved for internal use. Defaults to false.                  |
| sortDirection     | string  | The sorting direction. Valid options include 'asc' and 'desc'. |

The event properties are as follows.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                             |

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-datatable`, see the `c-datatable-*` components in the LWC Recipes repo.


:::::

:::::tab
::component-specification{component="datatable" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=ec2eead83868c56952d40a30e76f47ad4ce31614871d5e25e4570fbfd80ba01a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/date/lightning-date.md -->


# Date Picker

**`lightning-input`**
_type="date"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="date" model="lwc" namespace="lightning"}


:::::

:::::tab

A date input field includes a text input to type a date and a datepicker
to select a date.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="date" label="Birthday"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                      | SLDS 2                                                                       |
| ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| date       | [Datepickers](https://v1.lightningdesignsystem.com/components/datepickers/) | [Datepickers](https://www.lightningdesignsystem.com/components/datepickers/) |

## Usage

On mobile devices, this component uses the native datepicker, which ignores the `date-style` attribute. The native datepicker uses the user's device settings for names of months and weekdays, the input date format, and the calendar type.

On desktop, this component uses a datepicker styled with the Lightning Design System. This picker uses the user's Salesforce language setting for names of months and weekdays, and the user's Salesforce locale setting for the date format. The entered date is validated against the user's Salesforce locale format during the `blur` event.

## Date Style

The component uses `date-style="medium"` by default to display the date
in a medium-length style, such as Jan 7, 2020 in the en-US locale.
To display a short style such as 1/7/2020, set `date-style="short"` in the component. To display a long style such as January 7, 2020, set `date-style="long"`.

When the field receives focus, a message appears under the field with the date format based on the user locale and `date-style` value.
For example, if your user locale is en-US and the `date-style` is `medium`, the message displays "Format: Dec 31, 2024".

The date entered must be valid for the user's Salesforce locale, and match one of the short, medium, or long styles. If the date entered is valid, the component accepts the input and reformats it to the specified `date-style` during the `blur` event.
For example, if the component specifies `date-style="long"` and you enter 1/7/2020 in the en-US locale, the component reformats it to January 7, 2020.

The component accepts a month value of `13` to accommodate conditions that sometimes require a 13th month in a year. For most locales, if you enter `13` for the month, the component converts the date to the first month of the following year during the `blur` event.

Use the `value` attribute to supply an initial value for the date as an ISO8601 formatted date string,
such as `2020-11-03`.

## Date Range

Set `min` and `max` to ISO8601 formatted date strings to constrain the allowed date values.

- If you set a `min` value, the datepicker calendar displays the month specified in the `min` value, and the previous month button is disabled. For example, if you specify `min="2025-1-1"`, the calendar displays January 2025 and the previous month button is disabled.
- If you set a `max` value, the datepicker calendar displays the month specified in the `max` value, and the next month button is disabled. For example, if you specify `max="2025-12-31"`, the calendar displays December 2025 and the next month button is disabled.

The datepicker shows dates outside the min and max range in gray as a visual cue. Although users can select a date outside the range,
the `blur` event triggers the field to display a validation error message.

## Add Field-Level Help and Placeholder Text

To provide a hint for entering information in the field, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

To provide sample input in the field, use the `placeholder` attribute. For example, in a `date` input, show the date in the expected format.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="date"
        label="Event Date"
        placeholder="mm/dd/yy"
        field-level-help="The event date must be in the future"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

To ensure a date is provided, use the `required` attribute. Use `min` and `max` attributes to constrain the allowed date range. The component automatically validates the date format based on the user's Salesforce locale.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="date"
    label="Event Date"
    required
    min="2026-01-01"
    max="2030-12-31"
    lwc:ref="eventDate"
    message-when-value-missing="Event date is required"
    message-when-range-underflow="Event date must be after January 1, 2025"
    message-when-range-overflow="Event date must be before December 31, 2030"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

An error icon is displayed on an invalid date field, except on desktop browsers.

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the date input, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the date field.

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

export default class DateValidation extends LightningElement {
  handleSubmit() {
    const dateInput = this.refs.eventDate;
    console.log(dateInput.validity.valid); // Returns true or false
    if (!dateInput.checkValidity()) {
      dateInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const selectedDate = dateInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `date` type, these attributes apply:

- `badInput` - Indicates that the value is invalid or doesn't match the allowed format for the user's locale
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `patternMismatch` - Indicates that the value doesn't match the allowed pattern
- `rangeOverflow` - Indicates that the date is greater than the specified `max` attribute
- `rangeUnderflow` - Indicates that the date is less than the specified `min` attribute
- `typeMismatch` - Indicates that an invalid format was entered
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

The `badInput` validity error for `date` and `datetime` fields displays a default message that varies by locale. For example, "Your entry does not match the allowed format Dec 31, 2024" is displayed for en-US locale, but a different date format is shown for a different locale.

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format Dec 31, 2024"

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format MMM d, yyyy"

## Usage Considerations

You can guide users with a `field-level-help` tooltip and a `placeholder` prompt in the text field, as described in [Add Field-Level Help and Placeholder Text](#add-field-level-help-and-placeholder-text).

On desktop, the datepicker calendar clips behind other components on the page if the parent container of `lightning-input` has a smaller width or height than the calendar. To prevent clipping, give the parent container a minimum width of 285px and minimum height of 310px.

By default, the datepicker calendar renders above all modals and the main Salesforce header.

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the date field.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the date field and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the date field and the help tooltip.

If the date field fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=284f64efd875960f246979f4ffc0abf71f33e16a93e186f2c538f902d5edae60 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/datetime/lightning-datetime.md -->


# Datetime Picker

**`lightning-input`**
_type="datetime"_ or _type="datetime-local"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="datetime" model="lwc" namespace="lightning"}


:::::

:::::tab

A datetime field includes a text input to type a date and a datepicker
to select a date, and similar fields for typing or picking a time.

```html
<template>
  <lightning-input type="datetime" label="Created date"> </lightning-input>
</template>
```

There is no behavioral difference between the `datetime` and `datetime-local` types.

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                              | SLDS 2                                                                               |
| ---------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| datetime   | [Datetime Picker](https://v1.lightningdesignsystem.com/components/datetime-picker/) | [Datetime Picker](https://www.lightningdesignsystem.com/components/datetime-picker/) |

## Usage

The timepicker displays a dropdown menu with time options in 15-minute intervals, starting from 12:00 AM. To specify custom time intervals (in minutes) for the dropdown options, use the `time-step-minutes` attribute. You can pass in an interval of 5 or more minutes.

<!-- prettier-ignore -->
```html
<lightning-input
  type="datetime"
  label="Event Start"
  time-step-minutes="10"
></lightning-input>
```

On mobile devices, this component uses the native datetime picker, which ignores the `date-style` and `time-style` attributes. The native datetime picker uses the user's device settings for names of months and weekdays, the input datetime format, and the calendar type.

When the field receives focus, a message appears under the field with the date format based on the user locale and `date-style` value.
For example, if your user locale is en-US and the `date-style` is `medium`, the message displays "Format: Dec 31, 2024".

On desktop, `lightning-input` provides its own date/time picker that's styled with the Lightning Design System. Your Salesforce locale setting determines the acceptable date and time formats you can type in the fields and the format displayed in the fields after you pick a date and time. Your Salesforce language setting determines the names of months and weekdays displayed in the datepicker calendar, and the labels of the date and time fields.

The date and time you enter are automatically validated against your Salesforce locale format during the `blur` event. The date and time displayed reflect your Salesforce time zone setting. Use the `timezone` attribute to specify a different time zone in IANA time zone database format. For example, specify `timezone="America/New_York"` for US Eastern Time or `timezone="GMT"` for Greenwich Mean Time.

## Date Style

The component uses `date-style="medium"` by default to display the date
in a medium-length style, such as Jan 7, 2020 in the en-US locale.
To display a short style such as 1/7/2020, set `date-style="short"` in the component. To display a long style such as January 7, 2020, set `date-style="long"`.

The date entered must be valid for the user's Salesforce locale, and match one of the short, medium, or long styles. If the date entered is valid, the component accepts the input and reformats it to the specified `date-style` during the `blur` event.
For example, if the component specifies `date-style="long"` and a user enters 1/7/2020 in the en-US locale, the component reformats it to January 7, 2020.

The component accepts a month value of `13` to accommodate conditions that sometimes require a 13th month in a year. For most locales, if you enter `13` for the month, the component converts the date to the first month of the following year during the `blur` event.

The component uses `time-style="short"` by default to display the time without seconds, such as 6:53 PM in the en-US locale. To display time including seconds,
set `time-style="medium"` or `time-style="long"`. The medium and long styles currently have the same formatting.

Your Salesforce locale setting determines the time format you can type in the field or select in the timepicker, either 12-hr time with AM/PM or 24-hr time format.

Use the `value` attribute to optionally supply an initial value for the date and time as an ISO8601 formatted datetime string such as `2020-11-03T18:13:41Z`.

## Date Range

Set `min` and `max` to ISO8601 formatted datetime strings to constrain the allowed date and time values.

- If you set a `min` value, the datepicker calendar displays the month specified in the `min` value, and the previous month button is disabled. For example, if you specify `min="2025-1-1"`, the calendar displays January 2025 and the previous month button is disabled.
- If you set a `max` value, the datepicker calendar displays the month specified in the `max` value, and the next month button is disabled. For example, if you specify `max="2025-12-31"`, the calendar displays December 2025 and the next month button is disabled.

The datepicker shows dates outside the min and max range in gray as a visual cue. Users can still select a date and time outside the range,
but the `blur` event triggers the field to display a validation error message.

## Add Field-Level Help and Placeholder Text

To provide a hint for entering information in the field, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

Adding a `placeholder` value shows the placeholder text in both the date and time fields.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="datetime"
        label="Event Date and Time"
        field-level-help="The event date must be in the future"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

To validate a datetime input, use the `required` attribute to ensure a date and time are provided. Use `min` and `max` attributes to constrain the allowed datetime range. The component automatically validates the date and time format based on the user's Salesforce locale.

<!--prettier-ignore-->
```html
<template>
  <lightning-input
    type="datetime"
    label="Meeting Start"
    required
    min="2026-01-01T09:00:00Z"
    max="2030-12-31T17:00:00Z"
    lwc:ref="meetingStart"
    message-when-value-missing="Meeting start time is required"
    message-when-range-underflow="Meeting must start after January 1, 2026 at 9:00 AM"
    message-when-range-overflow="Meeting must start before December 31, 2030 at 5:00 PM"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

An error icon is displayed on an invalid date and time field, except on desktop browsers.

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the datetime input in JavaScript, use the `checkValidity()` method. If one of the fields isn't valid, the `reportValidity()` method shows the error message below the first invalid field.

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

export default class DatetimeValidation extends LightningElement {
  handleSubmit() {
    const datetimeInput = this.refs.meetingStart;
    console.log(datetimeInput.validity.valid); // Returns true or false
    if (!datetimeInput.checkValidity()) {
      datetimeInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const selectedDatetime = datetimeInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `datetime` type, these attributes apply:

- `badInput` - Indicates that the value is invalid or doesn't match the allowed format for the user's locale
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `patternMismatch` - Indicates that the value doesn't match the allowed pattern
- `rangeOverflow` - Indicates that the date is greater than the specified `max` attribute
- `rangeUnderflow` - Indicates that the date is less than the specified `min` attribute
- `typeMismatch` - Indicates that an invalid format was entered
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

The `badInput` validity error for `date` and `datetime` fields displays a default message that varies by locale. For example, "Your entry does not match the allowed format Dec 31, 2024" is displayed for en-US locale, but a different date format is shown for a different locale.

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format Dec 31, 2024"

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format MMM d, yyyy"

## Usage Considerations

You can guide users with a `field-level-help` tooltip, as described in [Add Field-Level Help and Placeholder Text](#add-field-level-help-and-placeholder-text).

On desktop, the datepicker calendar clips behind other components on the page if the parent container of `lightning-input` has a smaller width or height than the calendar. To prevent clipping, give the parent container a minimum width of 285px and minimum height of 310px.

In Lightning Experience, a datepicker calendar that's opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

## Time Zone Differences

Set the same time zone on your mobile device and in Salesforce to avoid confusion and potential validation issues. For example, suppose the current time is 4:00 PM ET. Your mobile device is set to the America/New_York time zone and you're interacting with Salesforce while it's set to the America/Los_Angeles time zone. When you tap an empty date/time field
on the mobile device, the native date/time picker automatically selects the current device time, 4:00 PM.

Since the current time is 1:00 PM in Salesforce, this input time is in the future. If there's a validation rule stating that the value must be earlier than the current time, for example, the value is invalid. This occurs only because of the time zone discrepancy, and only on mobile devices when the date/time field is initially empty.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="datetime" label="Created date"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` elements and uses a standard `for` attribute to link the label elements to the date and time fields.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the date and time fields with the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the date and time fields with the help tooltip.

If the date or time field fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=d7e32c376e0e7d6d3c0403186fefef166bd4d5a14b4dc3789fc79de87e7a0afa url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightningcommunity/deflectionSignal/lightningcommunity-deflection-signal.md -->

# Deflection Signal

**`lightningcommunity:deflectionSignal`**

Indicates that a Experience Builder site user interacts with a deflection item (an item determined to be responsible for a case deflection). Reports can then be created on supported signal types.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightningcommunity:deflectionSignal` event is fired whenever a site user interacts with a deflection item. Reports can then be created on supported signal types.

Custom Aura components can listen to this system event and handle it as required, for example, to kickstart another process if the user did not find an article helpful.

```xml
<aura:component implements="forceCommunity:availableForAllPageTypes">
    <aura:attribute name="message" type="String" required="false"/>
    <aura:handler event="lightningcommunity:deflectionSignal" action="{!c.handleSignal}"/>
    <lightning:formattedText value="{!v.message}"/>
</aura:component>
```

This client-side controller example handles the system event and checks for an interaction where the user did not find the deflection item helpful.

```javascript
/** Client-Side Controller **/
({
  handleSignal: function (component, event, helper) {
    var signal = event.getParams() || {},
      sourceType = signal.sourceType,
      payload = signal.payload;
    // Process case create deflection signals
    if (sourceType && sourceType === "caseCreateDeflectionModal") {
      if (payload && payload.deflectionAnswer === "NO") {
        component.set("v.message", "Sorry you didn't find that helpful.");
      }
      if (payload && payload.caseCreated === true) {
        component.set(
          "v.message",
          "We apologize for the inconvenience. We'll get in touch with you shortly about your case."
        );
      }
    }
  },
});
```

## Usage Considerations

A `lightningcommunity:deflectionSignal` event is fired when a user is going through a process to solve an issue, and then interacts with a deflection item that could potentially resolve their issue early. For example, a `lightningcommunity:deflectionSignal` event is fired by the Case Deflection component with information about the user’s interaction with a helpful Article.

Generally, a deflection has two parts:

- the source: some process or record the user starts on, such as the case create form
- the destination: a deflection item that the user then interacts with, such as a useful article
  The `sourceType` determines how the event gets processed. Only events with a supported `sourceType` are processed for Custom Report Types. Currently, the only supported value for `sourceType` is `caseCreateDeflectionModal`.

The content of the `payload` attribute depends on the type of signal used.

This event is handled by the one.app container. It’s supported in Aura-based Experience Builder sites.

For more information about this event, see the [Experience Cloud Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_using_deflection_framework.htm).


:::::

:::::tab
## Attributes

| Name                            | Description                                                                                                                                                                                                                                                                       | Type    | Default | Required                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
| `callback`                      | Callback function invoked after signal is received and processed. Only called if `shouldSubmitSourceTypeSignals=true`.                                                                                                                                                            | object  |         |                                              |
| `destination`                   | The ID of the deflection item.                                                                                                                                                                                                                                                    | string  |         |                                              |
| `destinationType`               | Object type of the deflection item.                                                                                                                                                                                                                                               | string  |         |                                              |
| `payload`                       | Additional information about the deflection signal. The content of the payload depends on the sourceType.                                                                                                                                                                         | object  |         |                                              |
| `shouldSubmitSourceTypeSignals` | Once an event is fired with `shouldSubmitSourceTypeSignals=true`, all signals of that `sourceType` are submitted to the server in a single batch to be processed. This should always be true unless signals are logically dependent on each other and must be processed together. | boolean | true    |                                              |
| `source`                        | The unique identifier of how the user arrived at the deflection item                                                                                                                                                                                                              | string  |         |                                              |
| `sourceType`                    | Descriptor of where deflection occured. Only signals with supported types will get processed. `sourceType` is synonymous with signalAgent.                                                                                                                                        | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=57ffbd60c0a485bcc139255b795955dd011ade5a342a0d7d8fe8d42f860ea0de url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/discover/wave-discover.md -->

# Discover

**`wave:discover`**

Analytics event that a [`wave:waveDashboard`](/docs/platform/lightning-component-reference/guide/wave-wave-dashboard.html) listens and responds to with a [`wave:discoverResponse`](/docs/platform/lightning-component-reference/guide/wave-discover-response.html) event.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:discover` event sends a global request to listening Analytics dashboard assets to respond with their identifying information (via the `wave:discoverResponse` event). You can include your own parameter in the response.

The `wave:discover` and `wave:discoverResponse` events are particularly useful for discovering when a dashboard is being added dynamically to the page, or whether the page has multiple dashboards.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name  | Description                                                     | Type   | Default | Required                                     |
| ----- | --------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `UID` | Optional identifier that will be included in the response data. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=6787593f5b909810143570bc1296eaddb7297da0a38db05baf047de662cecedf url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/discoverResponse/wave-discover-response.md -->

# Discover Response

**`wave:discoverResponse`**

Response event to a [`wave:discover`](/docs/platform/lightning-component-reference/guide/wave-discover.html) event.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:discoverResponse` event provides the response following a request for Analytics dashboards to identify their assets.

The `wave:discover` and `wave:discoverResponse` events are particularly useful for discovering when a dashboard is being added dynamically to the page, or whether the page has multiple dashboards.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name       | Description                                                                        | Type    | Default | Required                                     |
| ---------- | ---------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
| `UID`      | Optional identifier that will be included in the request data.                     | string  |         |                                              |
| `id`       | The identifier for the Analytics asset, in the form of a standard 18-character ID. | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `isLoaded` | A flag to determine whether the asset is loaded or still loading.                  | boolean |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `title`    | The title of the asset.                                                            | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type`     | The type of the Analytics asset. Currently, only dashboard is supported.           | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=3e8ee5937ad9c5e6b9cc6b488b2cfa29c89334e1613d5b2aed5c7b1cd9eb4493 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/distributedMarketing/lightning-distributed-marketing.md -->

# Distributed Marketing

**`lightning/distributedMarketing`**

Open the Distributed Marketing Launcher modal from your component.

**For Use In**

Lightning Experience

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

The `lightning/distributedMarketing` module opens the Distributed Marketing
Launcher modal from your component. Import the `openDistributedMarketing`
function from the `lightning/distributedMarketing` module and call it to launch
the modal.

```javascript
import { openDistributedMarketing } from "lightning/distributedMarketing";
```

For this module's documentation, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-distributed-marketing-api.html).


:::::

:::::tab

::component-specification{component="distributedMarketing" model="lwc" namespace="lightning"}


:::::

::::::

<!-- document id=aa49064509252772a99012a1acddb4a7f1c9be675c899327b80a22d4b0f96cc5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/doneRendering/aura-done-rendering.md -->

# Done Rendering (Deprecated)

**`aura:doneRendering`**

Indicates that the initial rendering of the root application or root component has completed.

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab

The `aura:doneRendering` event is deprecated. Use the [render event](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_render_handler.htm) instead. Unless your component is running in complete isolation in a standalone app and not included in complex apps, such as Lightning Experience or the Salesforce mobile app, the container app may trigger your event handler multiple times. This behavior makes it difficult to handle each event appropriately.

This event is automatically fired if no more components need to be rendered or rerendered due to any attribute value changes.

Handle the `aura:doneRendering` event in a client-side controller. A component can have only one `<aura:handler>` tag to handle this event.

```xml
<aura:handler event="aura:doneRendering" action="{!c.doneRendering}" />
```

For example, you want to customize the behavior of your app after it’s finished rendering the first time but not after subsequent rerenderings. Create an attribute to determine if it’s the first rendering.

```xml
<aura:component>
  <aura:handler event="aura:doneRendering" action="{!c.doneRendering}" />
  <aura:attribute name="isDoneRendering" type="Boolean" default="false" />
  <!-- Other component markup here -->
  <p>My component</p>
</aura:component>
```

This client-side controller checks that the `aura:doneRendering` event has been fired only once.

```javascript
({
  doneRendering: function (cmp, event, helper) {
    if (!cmp.get("v.isDoneRendering")) {
      cmp.set("v.isDoneRendering", true);
      //do something after component is first rendered
    }
  },
});
```


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=8c3dacae036128d7fbd1e6e78ac9e10bd0a915e003baf287588ce45537cc8f3c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/doneWaiting/aura-done-waiting.md -->

# Done Waiting

**`aura:doneWaiting`**

Indicates that the client-side framework is done waiting for a response to a server request, which is always preceded by an `aura:waiting` event.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `aura:doneWaiting` event is deprecated. To determine when an action is complete, use the response status in an action's callback instead. The `aura:doneWaiting` application event is fired for every server response, even for responses from other components in your app. Unless your component is running in complete isolation in a standalone app and not included in Lightning Experience or the Salesforce mobile app, the container app may trigger your event handler multiple times. This behavior makes it difficult to handle each event appropriately.

This event is automatically fired if no more response from the server is expected.

Handle the `aura:doneWaiting` event in a client-side controller. A component can have only one `<aura:handler>` tag to handle this event.

```xml
<aura:handler event="aura:doneWaiting" action="{!c.hideSpinner}" />
```

This example hides a spinner when `aura:doneWaiting` is fired.

```xml
<aura:component>
  <aura:handler event="aura:doneWaiting" action="{!c.hideSpinner}" />
  <!-- Other component markup here -->
  <center><ui:spinner aura:id="spinner" /></center>
</aura:component>
```

This client-side controller fires an event that hides the spinner.

```javascript
({
  hideSpinner: function (component, event, helper) {
    var spinner = component.find("spinner");
    var evt = spinner.get("e.toggle");
    evt.setParams({ isVisible: false });
    evt.fire();
  },
});
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=9c9b2014170b7b53c99c0245c21e7c448a1356a65922880c0125571e0fcf056c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/dualListbox/lightning-dual-listbox.md -->


# Dual Listbox

**`lightning-dual-listbox`**

A pair of listboxes that enables multiple options to be selected and reordered.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="dualListbox" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-dual-listbox` component represents two side-by-side listboxes.
Select one or more options in the list on the left. Move the selected options to
the list on the right. The order of the selected options persists and you
can reorder options.

Here's an example that creates a simple dual listbox with 8 options. Options
7, 2 and 3 are selected under the second listbox. Options 2 and 7
are required options.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-dual-listbox
        id="selectOptions"
        name="Select Options"
        label="Select Options"
        source-label="Available Options"
        selected-label="Selected Options"
        options={listOptions}
        value={defaultOptions}
        required-options={requiredOptions}
        onchange={handleChange}
    >
    </lightning-dual-listbox>
</template>
```
<!-- prettier-ignore-end -->

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  listOptions = [
    { value: "1", label: "Option 1" },
    { value: "2", label: "Option 2" },
    { value: "3", label: "Option 3" },
    { value: "4", label: "Option 4" },
    { value: "5", label: "Option 5" },
    { value: "6", label: "Option 6" },
    { value: "7", label: "Option 7" },
    { value: "8", label: "Option 8" },
  ];

  defaultOptions = ["7", "2", "3"];

  requiredOptions = ["2", "7"];

  handleChange(event) {
    // Get the list of the "value" attribute on all the selected options
    const selectedOptionsList = event.detail.value;
    alert(`Options selected: ${selectedOptionsList}`);
  }
}
```

To specify the number of options users can select, use the `min` and `max`
attributes. For example, if you set `min` to 3 and `max` to 8, users must
select at least 3 options and at most 8 options.

## Design

`lightning-dual-listbox` implements the dueling picklist blueprint in the Salesforce Lightning Design System (SLDS). The dueling picklist adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Dueling Picklist](https://v1.lightningdesignsystem.com/components/dueling-picklist/)                                                 | [Data Tables](https://www.lightningdesignsystem.com/components/dueling-picklist/)                               |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Input Validation

Client-side input validation is available for this component. Disabled fields are always valid.

To check the validity states of the input, use the `validity` attribute to return an object with read-only `boolean` attributes.

- `rangeOverflow`
- `rangeUnderflow`
- `valueMissing`
- `valid`
  For more information on the `validity` attribute, see [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html).

## Error Messages

When an input validation fails, the following messages are shown by default.

- `rangeOverflow`: Select at most [max] options
- `rangeUnderflow`: At least [min] options must be selected
- `valueMissing`: An option must be selected

[max] and [min] refer to the numerical values for the `max` and `min` attributes you provide.

You can override the default messages by providing your own values for these attributes: `message-when-range-overflow`, `message-when-range-underflow`, and `message-when-value-missing`.

## Custom Validity Error Messages

To programmatically show error messages on invalid fields, use the `reportValidity()` method. For custom error messages, return the message by using `setCustomValidity()` and `reportValidity()`. For more information, see [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html).

## Component Styling

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the picklist field.

- `standard` is the default
- `label-hidden` hides the label visually but makes it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still shown.
- `label-inline` aligns the label next to the picklist field
- `label-stacked` places the label above the picklist field

### Customize Component Styling

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

To customize the SLDS styles on the "Move selection to Selected" or "Move selection up" buttons, use SLDS 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) in the Lightning Web Components Developer Guide.

## Usage Considerations

To return the selected values, use the `onchange` handler.

```javascript
handleChange(event) {
    // Get an array of the selected options
    const selectedOptionsList = event.detail.value;
    alert(`Options selected: ${selectedOptionsList}`);
}
```

The `onchange` handler is triggered when you click the left and right buttons to
move options from one list to another or when you change the order of options
in the selected options list.

For optimal performance, limit each list to 50 options or fewer. Moving more than
50 options at once can be resource-intensive and can result in noticeable delays for users.

## Accessibility

Use these keyboard shortcuts to work with dual listboxes.

- Click - Select a single option.
- Cmd+Click - Select multiple options or deselect selected options.
- Shift+Click - Select all options between the current and last clicked option.

To work with options, move focus to an option and use these shortcuts.

- Up Arrow - Move selection to previous option.
- Down Arrow - Move selection to next option.
- Ctrl+Up Arrow (Windows) or Cmd+Up Arrow (Mac) - Move focus to the previous option.
- Ctrl+Down Arrow (Windows) or Cmd+Down Arrow (Mac) - Move focus to the next option.
- Ctrl+Space - Toggle selection of focused option.
- Ctrl+Right Arrow (Windows) or Cmd+Right Arrow (Mac) - Move selected options to the right listbox.
- Ctrl+Left Arrow (Windows) or Cmd+Left Arrow (Mac) - Move selected options to the left listbox.
- Tab - Move focus to the buttons or between boxes.

When focus is on an option, type a character to move focus to the next option with a name that starts with the typed character. The first typed character is matched with the first character of the label in the order that the options occur. To select the focused option, press Ctrl+Space. This type-ahead feature isn't currently supported for multibyte characters such as Chinese and Japanese.

For example, if you have multiple options that start with the letter "E" and focus is on an option that starts with "A", type "E" to move focus to the first option that starts with "E".
Typing "E" again moves focus to the next option that starts with "E".

The component presents two buttons to move an option to the selected list and back to the source list.

- The first button's assistive text is "Move selection to Selected", where Selected is the label of the second list.
- The second button's assistive text is "Move selection to Source", where Source is the label of the first list.

When focus is on a button:

- Move selection to Selected - Select an option from the first (source) list, then press Enter on the button to move the option to the selected list.
- Move selection to Source - Select an option from the second (selected) list, then press Enter on the button to move the option back to the source list.

If no items are selected or available, the move buttons and reorder buttons are disabled.

To accommodate high magnification when zoom is greater than 200%, the list boxes stack vertically, separated by up and down arrow icons instead of right and left arrow buttons.

## Custom Events

**`change`**

The event fired when an item is selected in the combobox.

The `change` event returns this parameter.

| Parameter | Type   | Description                               |
| --------- | ------ | ----------------------------------------- |
| value     | string | A comma-separated list of selected items. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |


:::::

:::::tab
::component-specification{component="dualListbox" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c52ec5537319084e985281cbd809fb081e2baa2ec10ec21269d1ea73d6bfe14d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/dynamicIcon/lightning-dynamic-icon.md -->


# Dynamic Icon

**`lightning-dynamic-icon`**

Represents various animated icons with different states.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="dynamicIcon" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-dynamic-icon` component visually indicates an event that's in
progress, such as a graph that's loading.

Here's an example of an ellie icon with alternative text.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-dynamic-icon
        type="ellie"
        alternative-text="Your calculation is running."
    >
    </lightning-dynamic-icon>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-dynamic-icon` implements the dynamic icons blueprint in the Salesforce Lightning Design System (SLDS). The dynamic icons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Dynamic Icons](https://v1.lightningdesignsystem.com/components/dynamic-icons/)                                                       | [Dynamic Icons](https://www.lightningdesignsystem.com/components/dynamic-icons/)                                |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage Considerations

These `type` options are available.

- `type="ellie"` shows a pulsing blue circle, which pulses and stops after one animation cycle. This icon is great for field calculations or a process that's running in the background.
- `type="eq"` shows an animated graph with three bars that rise and fall randomly. This icon is great for a graph that's refreshing.
- `type="score"` shows a green filled circle or a red unfilled circle. This icon is great for showing positive and negative indicators.
- `type="strength"` shows three animated horizontal circles that are colored green or red. This icon is great for Einstein calculations or indicating password strengths.
- `type="trend"` shows animated arrows that point up, down, or straight. This icon is great for showing the movement of a value from one range to another, like a forecast score.
- `type="waffle"` shows a square made up of a 3x3 grid of circles. This icon animates on hover. This icon is great for app-related items, like the App Launcher in Lightning Experience.

## Accessibility

Optionally, you can use the `alternative-text` attribute to describe the
`lightning-dynamic-icon`.

Sometimes a `lightning-dynamic-icon` is decorative and doesn't need a description.
However, on smaller screens and windows the `lightning-dynamic-icon` can also be
informational. In this case, include `alternative-text`. If you don't include
`alternative-text`, check smaller screens and windows to ensure that the
`lightning-dynamic-icon` is only decorative on all formats.


:::::

:::::tab
::component-specification{component="dynamicIcon" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6e6e3ac32dde313699bb006019e0ba799a3c0855c4f64a0614685ef397f8b894 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/dynamicListContainer/lightning-dynamic-list-container.md -->


# Dynamic List Container (Developer Preview)

**`lightning-dynamic-list-container`**

Represents a list that renders using virtualization, presenting only a portion of the list at a time. This component requires API version 67.0 or later. To use this component, select the Dev channel in [Salesforce Release Manager](https://help.salesforce.com/s/articleView?id=xcloud.release_manager.htm).

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="dynamicListContainer" model="lwc" namespace="lightning"}


:::::

:::::tab

**note:** Working with dynamic lists 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 in production with these commands or tools.

The `lightning-dynamic-list-container` component renders a portion of a list at a time by using intelligent virtualization. This component is useful for large datasets where you don't want to render the entire list all at once in the DOM. It can improve browser performance, reduce memory usage, and speed up user interactions in large lists.

Use `lightning-dynamic-list-container` with the [`lightning-dynamic-list-item` component]().

## Usage

**important:** To use dynamic lists, opt in to the Dev channel in [Salesforce Release Manager](https://help.salesforce.com/s/articleView?id=xcloud.release_manager.htm).

To implement your list using `lightning-dynamic-list-container`, consider the roles of these key wrapper components:

1. `lightning-dynamic-list-container`: the parent wrapper responsible for managing overall list rendering and slicing data based on the user's scroll position.
2. `lightning-dynamic-list-item`: the child wrapper representing each individual row, dynamically positioned by the container based on the current scroll position.

Both wrappers use `<slot>`, allowing them to wrap various list implementations and row types.

To create a dynamic list:

- Enclose all rows with `lightning-dynamic-list-container`.
- Enclose each row with `lightning-dynamic-list-item`, passing a unique identifier using the `item-id` attribute.
- Place both `lightning-dynamic-list-container` and `lightning-dynamic-list-item` in the same LWC template.
- Pass the full list data to `lightning-dynamic-list-container` using the `list-items` attribute.

<!-- prettier-ignore -->
```html
<template>
    <!--
        Scrollable behavior is managed by dynamicListContainer.
        Don't add scrollable classes, such as slds-scrollable_y.
    -->
    <div class="list-container">
        <lightning-dynamic-list-container
            lwc:ref="dynamicListContainer"
            list-items={listItems}
            onrenderlistitems={handleRenderListItems}
        >
            <template for:each={listItemsToRender} for:item="item">
                <lightning-dynamic-list-item key={item.id} item-id={item.id}>
                    <div>Your Custom Row Content</div>
                </lightning-dynamic-list-item>
            </template>
            <footer slot="footer">
                <div>Your Custom List Footer</div>
            </footer>
        </lightning-dynamic-list-container>
    </div>
</template>
```

Make sure that there are no components or elements between adjacent `lightning-dynamic-list-item` components, or between the container and the first `lightning-dynamic-list-item`. You don't need to configure custom scrolling such as `overflow: scroll` or similar styles from your list container. Scrolling is handled by `lightning-dynamic-list-container`.

To manage rendering of lists as you scroll, handle the `renderlistitems` event from `lightning-dynamic-list-container`. Extract `listItemsToRender` from the event detail to get the subset of list data to render in the DOM. The component automatically positions each row.

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

export default class MyDynamicList extends LightningElement {
  _listItemsToRender = [];

  // The full list data
  @api listItems;

  get listItemsToRender() {
    return this._listItemsToRender;
  }

  handleRenderListItems(event) {
    // The component tells you which items to render
    this._listItemsToRender = event.detail.listItemsToRender;
  }
}
```

`lightning-dynamic-list-container` requires a bounded height for the list. Make sure that at least one ancestor of `lightning-dynamic-list-container` has an explicit height in pixels, percentage, or viewport units. The scrollable viewport expands to fill the height of its nearest ancestor with a defined height.

```css
.list-container {
  height: 400px; /* fixed and bounded  */
}

.list-container {
  max-height: 80vh; /* bounded by the viewport height */
}
```

When building your lists, avoid padding on elements between `lightning-dynamic-list-container` and `lightning-dynamic-list-item`. Use margin on rows wrapped by `lightning-dynamic-list-item` for spacing between rows and between rows and container.

## Virtualization

The `lightning-dynamic-list-container` component implements intelligent virtualization with these behaviors.

- **Renders only visible items**: Only the rows currently visible in the viewport with a small buffer are rendered in the DOM. The component adds rows and removes them from the DOM as you scroll.
- **Supports variable row heights**: Rows can have different heights, and the component automatically recalculates positions as needed.
- **Maintains smooth scrolling**: Uses scroll anchoring to ensure a smooth scrolling experience during virtualization.
- **Handles dynamic list changes efficiently:**
  - Rows can be resized individually or collectively.
  - Rows can be added or removed at any position in the list.
  - The list container itself can be resized.

## Load More Rows

To load more rows when the user scrolls to the end of the list, you can either add a `load more` button using the `footer` slot or listen for the `loadmore` event dispatched by the `lightning-dynamic-list-container`. If you append new list items to the existing list, reassign the list to trigger reactivity.

<!-- prettier-ignore -->
```html
<template>
    <div class="list-container">
        <!--
            Display the spinner above the DynamicList.
            Don't remove or re-create DynamicListContainer when loading more rows.
        -->
        <template if:true={isLoading}>
            <lightning-spinner></lightning-spinner>
        </template>
        <lightning-dynamic-list-container
            lwc:ref="dynamicListContainer"
            list-items={listItems}
            onrenderlistitems={handleRenderListItems}
            onloadmore={handleLoadMore}
        >
            <template for:each={listItemsToRender} for:item="item">
                <lightning-dynamic-list-item key={item.id} item-id={item.id}>
                    <div>Your Custom Row Content</div>
                </lightning-dynamic-list-item>
            </template>
        </lightning-dynamic-list-container>
    </div>
</template>
```

The example uses static content for the list items. For an example that loads record data from your org, see the [`lightning-dynamic-list-item` documentation](/docs/platform/lightning-component-reference/guide/lightning-dynamic-list-item.html).

To add a loading screen while loading more rows, such as with `lightning-spinner`, display the spinner above the `lightning-dynamic-list-container` rather than replacing it. Don't remove or re-create the `lightning-dynamic-list-container` when loading more rows.

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

export default class MyDynamicList extends LightningElement {
  _listItems = [];
  _listItemsToRender = [];
  _isLoading = false;

  get listItemsToRender() {
    return this._listItemsToRender;
  }

  get isLoading() {
    return this._isLoading;
  }

  handleRenderListItems(event) {
    this._listItemsToRender = event.detail.listItemsToRender;
  }

  handleLoadMore(event) {
    const startOffset = event.detail.startOffset;
    this._generateListItems();
    // Make sure to reassign to listItems for reactivity
    this._listItems = [...this._listItems];
  }

  connectedCallback() {
    this._generateListItems();
  }

  _generateListItems() {
    this._isLoading = true;
    for (let i = 0; i < 500; i++) {
      this._listItems.push({
        id: this._listItems.length,
      });
    }
    this._isLoading = false;
  }
}
```

**note:** This example uses a mock list. For an example that uses record data, see the [`lightning-dynamic-list-item` documentation](/docs/platform/lightning-component-reference/guide/lightning-dynamic-list-item.html).

Make sure that the component defines an explicit height.

```css
.list-container {
  height: 400px; /* or any bounded value */
  position: relative; /* ensure spinner is positioned correctly */
}
```

## List Filtering and Search

If the list is filtered, such as after a search, call the `reset()` method on `lightning-dynamic-list-container` before updating the list data. This ensures the internal cache is cleared and new rows are rendered from the beginning.

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

export default class MyDynamicList extends LightningElement {
  _listData;
  _filteredListData = [];
  _listItemsToRender = [];

  @api
  get listData() {
    return this._filteredListData;
  }

  set listData(value) {
    if (Array.isArray(value)) {
      this._listData = value;
      this._filteredListData = value;
    }
  }

  get listItemsToRender() {
    return this._listItemsToRender;
  }

  handleRenderListItems(event) {
    this._listItemsToRender = event.detail.listItemsToRender;
  }

  handleSearch(event) {
    // Call the reset method before setting the new list data
    this.refs.dynamicListContainer.reset();
    this._filteredListData = this._listData.filter((data) => {
      // Custom filter logic
    });
  }
}
```

## Scroll a Row Into View

To scroll a specific row into view, use the `scrollRowIntoView()` method on `lightning-dynamic-list-container`. Pass the target row index as the first argument and an optional config object as the second. By default, scrolling is instant and focus remains unchanged. To enable smooth scrolling and move focus to the row, set `behavior: 'smooth'` and `focus: true` in the config.

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

export default class MyDynamicList extends LightningElement {
  _listItemsToRender = [];

  // The full list data
  @api listItems;

  get listItemsToRender() {
    return this._listItemsToRender;
  }

  handleRenderListItems(event) {
    this._listItemsToRender = event.detail.listItemsToRender;
  }

  handleScrollRowIntoView(targetRowIndex) {
    this.refs.dynamicListContainer.scrollRowIntoView(targetRowIndex, {
      behavior: "smooth",
      focus: true,
    });
  }
}
```

## Configure ARIA Role Assignment

By default, `lightning-dynamic-list-container` follows standard list semantics to ensure accessibility for screen readers. When `disableAutoListSemantics` is `false` (default), the component automatically assigns these roles:

- Container Level: The viewport or main container is assigned `role="list"`.
- Item Level: Each list item is assigned `role="listitem"`.

To change the role to `presentation`, set `disableAutoListSemantics` to `true`. This configuration is useful when the `lightning-dynamic-list-container` component is nested inside other components that already provide their own ARIA context, preventing redundant or conflicting screen reader announcements.

## Configure Keyboard Navigation Support

By default, `lightning-dynamic-list-container` handles keydown events. To disable keyboard support, set `disableKeyboardSupport = true`. When `disableKeyboardSupport = true`, these features are deactivated:

- Arrow Key Navigation: Users can't move focus between list items using the Up Arrow and Down Arrow keys.
- Home and End Keys: Shortcuts to jump to the first or last item in the list are disabled.
- Page Up and Down Keys: The ability to scroll through the list in "pages" via the keyboard is removed.
- Focus Tracking: The internal keyboard state doesn't update the index for focused item based on user key presses.

When `disableKeyboardSupport` is `true`, screen reader users can still navigate the list using their standard virtual cursor when `disableAutoListSemantics` remains `false`. This property only affects the active keyboard event listeners managed by the component. This configuration is useful in these use cases:

- Custom Key Handlers: If your application requires specific, non-standard keyboard interactions that conflict with the default list navigation, you can disable the internal support and implement your own listener on a wrapper element.
- Read-Only Lists: In scenarios where the list is decorative or informational and doesn't contain interactive elements, disabling keyboard support can prevent accidental focus traps.
- Nested Interactivity: If the list items themselves contain complex widgets that manage their own internal focus and key events, you can disable the container-level support to avoid "bubbling" conflicts.

## Focus Tracking and Preservation

Unlike other virtualization frameworks, `lightning-dynamic-list-container` ensures that system focus is always preserved, even if the row with system focus is no longer visible in the viewport. This critical feature provides:

- **Focus Tracking**: Keeps track of which row has focus even when it's not rendered.
- **Focus Restoration**: Ensures the row with focus is rendered in the DOM after a repaint, and programmatically restores focus to the row.

## Usage Considerations

1. If a user focuses on any element within a row—other than the first focusable element—then scrolls the row out of view and later scrolls back, the component restores focus to the first focusable element in that row, not the originally focused element. The same behavior occurs if the user presses the Tab or Shift+Tab keys while the focused row is out of view.
2. When a user scrolls quickly, multiple scroll events are fired in rapid succession. To improve performance, `lightning-dynamic-list` processes only the last event captured. This can result in a temporary blank screen during fast scrolling, with content appearing only after scrolling stops.

## Accessibility

`lightning-dynamic-list-container` provides comprehensive accessibility and keyboard navigation support out of the box.

- **Arrow Key Navigation**: Use the Up Arrow and Down Arrow keys to navigate between rows, even if the focused row isn't currently visible.
- **Home/End Key Navigation**: Jump to the first or last row in the list, even if those rows are not currently visible.
- **Semantic List Support**: Automatically adds appropriate ARIA roles (`list`, `listitem`, `presentation`) to maintain semantic structure and provides `aria-setsize` and `aria-posinset` attributes for proper list item positioning information.
- **Browse Mode Detection**: Detects when users navigate using screen reader browse mode (where system focus and cursor aren't synchronized) and provides live announcements to suggest switching to focus mode.
- **Screen Reader Support**: Supports JAWS, NVDA, and VoiceOver screen readers.

## Custom Events

**`loadmore`**

The event that's fired when the user scrolls to the end of the list.

The `loadmore` event returns this parameter.

| Parameter   | Type   | Description                                                              |
| ----------- | ------ | ------------------------------------------------------------------------ |
| startOffset | number | The index in the list where the next batch of data should begin loading. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event doesn’t bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event doesn’t propagate outside the template in which it was dispatched.                             |

**`renderlistitems`**

The event that's fired when the component determines which items should be rendered.

The `renderlistitems` event returns this parameter.

| Parameter         | Type  | Description                                                                  |
| ----------------- | ----- | ---------------------------------------------------------------------------- |
| listItemsToRender | array | The list items to be rendered, which are the only items rendered in the DOM. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event doesn’t bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event doesn’t propagate outside the template in which it was dispatched.                             |


:::::

:::::tab
::component-specification{component="dynamicListContainer" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2f3596eaab3be05dba21b81ffe60a6bd83cb8bfcc3dd254f04fe46a8734fedfb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/dynamicListItem/lightning-dynamic-list-item.md -->

# Dynamic List Item (Developer Preview)

**`lightning-dynamic-list-item`**

Represents a row in a `lightning-dynamic-list-container` component. Each row is dynamically positioned by the container based on the current scroll position. This component requires API version 67.0 or later. To use this component, select the Dev channel in [Salesforce Release Manager](https://help.salesforce.com/s/articleView?id=xcloud.release_manager.htm).

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

**note:** Working with dynamic lists 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 in production with these commands or tools.

`lightning-dynamic-list-item` represents a row in the [`lightning-dynamic-list-container` component](/docs/platform/lightning-component-reference/guide/lightning-dynamic-list-container.html).

## Usage

**important:** To use dynamic lists, opt in to the Dev channel in [Salesforce Release Manager](https://help.salesforce.com/s/articleView?id=xcloud.release_manager.htm).

`lightning-dynamic-list-container` and `lightning-dynamic-list-item` must be part of the same LWC component to share the same shadow DOM. Use `lightning-dynamic-list-item` within `lightning-dynamic-list-container` and place them in the same LWC template.

When building your lists, avoid padding on elements between `lightning-dynamic-list-container` and `lightning-dynamic-list-item`. Use margin on rows wrapped by `lightning-dynamic-list-item` for spacing between rows and between rows and container.

`lightning-dynamic-list-item` doesn't provide any styling. You can use custom or SLDS utility classes to create a visual container for your list items.

<!-- prettier-ignore -->
```html
<lightning-card title="Dynamic Lists - Contacts" icon-name="standard:contact">
  <div class="slds-card__body slds-p-around_medium">
    <lightning-dynamic-list-container
      list-items={listItems}
      onrenderlistitems={handleRenderListItems}
    >
      <template for:each={listItemsToRender} for:item="item">
        <lightning-dynamic-list-item key={item.id} item-id={item.id}>
          <div class="contact-tile slds-p-around_small">
            <p>{item.name}</p>
            <p>{item.email}</p>
          </div>
        </lightning-dynamic-list-item>
      </template>
    </lightning-dynamic-list-container>
  </div>
</lightning-card>
```

Include a height for `lightning-dynamic-list-container`. The height doesn't have to be fixed but it must be bounded to ensure proper rendering and scroll behavior.

```css
/* Required: bounded height for lightning-dynamic-list-container */
.list-container {
  height: 400px;
}

.contact-tile {
  border: 1px solid #c2c8d4;
  margin: 0.5rem;
}
```

## Load Data

Here's how you can load record data by using the [`lightning/graphql` module](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.html). For example, you can request 1000 contact records and each subset renders in the DOM as you scroll.

```javascript
import { LightningElement, wire } from "lwc";
import { gql, graphql } from "lightning/graphql";

export default class BaseComponents extends LightningElement {
  // The full list of items from GraphQL
  _listItems = [];

  // The subset of items for rendering by lightning-dynamic-list-container
  _listItemsToRender = [];

  // Expose a list reference for lightning-dynamic-list-container
  get listItems() {
    return this._listItems;
  }

  // Populate data once from GraphQL wire
  // Avoids repeated new array creation
  @wire(graphql, {
    query: gql`
      query getContacts {
        uiapi {
          query {
            Contact(first: 1000, orderBy: { Name: { order: ASC } }) {
              edges {
                node {
                  Id
                  Name {
                    value
                  }
                  Email {
                    value
                  }
                }
              }
            }
          }
        }
      }
    `,
  })
  wiredContacts({ errors, data }) {
    if (data) {
      this._listItems = data.uiapi.query.Contact.edges.map((edge) => ({
        id: edge.node.Id,
        name: edge.node.Name?.value || "Unknown",
        email: edge.node.Email?.value || "N/A",
      }));
    } else if (errors) {
      this._listItems = [];
      // Handle the errors
    }
  }

  get listItemsToRender() {
    return this._listItemsToRender;
  }

  handleRenderListItems(event) {
    this._listItemsToRender = event.detail.listItemsToRender;
  }
}
```

## See Also

[`lightning-dynamic-list-container`](/docs/platform/lightning-component-reference/guide/lightning-dynamic-list-container.html)

[Lightning Web Components Developer Guide: Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines.html)

[GraphQL API Developer Guide](https://developer.salesforce.com/docs/platform/graphql/guide/)


:::::

:::::tab
::component-specification{component="dynamicListItem" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=319866e55de8358fc865d81e8663c77086c900b09810eef2e579a8284aef7993 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/editRecord/force-edit-record.md -->

# Edit Record

**`force:editRecord`**

Displays the record edit screen for a given record.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event opens a page to edit the record specified by `recordId`.

To display the record edit page for an object, set the object name on the `recordId` attribute and fire the event. This example displays the record edit page for a contact that’s specified by `recordId`.

This example displays the record create panel for contacts.

```javascript
editRecord : function(component, event, helper) {
    var editRecordEvent = $A.get("e.force:editRecord");
    editRecordEvent.setParams({
         "recordId": component.get("v.contact.Id")
   });
    editRecordEvent.fire();
}
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name       | Description                       | Type   | Default | Required                                     |
| ---------- | --------------------------------- | ------ | ------- | -------------------------------------------- |
| `recordId` | The ID of the record to be edited | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=a42c78fd4e8689e71dee625e6dba6edbb276b0cbf03560cc5211d739cc56abf6 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/empApi/lightning-emp-api.md -->

# Emp API

**`lightning/empApi`**

Work with the EmpJs Streaming API library using the `lightning/empApi` module, which subscribes to a streaming channel and listens to event messages using a shared CometD connection for a single user session. The `lightning/empApi` module is supported only in desktop browsers and requires API version 44.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/empApi` module provides access to methods for subscribing to a streaming channel and listening to event messages. All streaming channels are supported, including channels for platform events, PushTopic events, generic events, and Change Data Capture events.

The `lightning/empApi` module uses a shared CometD connection, enabling you to run multiple streaming apps in a single browser session. The connection isn’t shared across user sessions in other browsers. The `lightning/empApi` module only supports one user per browser. Multiple user sessions aren't supported in one browser.

To use the CRM Analytics API in your component, import the functions in your component's JavaScript file.

```javascript
import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled } from "lightning/empApi";
```

## `subscribe`

Subscribes to a given channel and returns a promise that holds a subscription object, which you use to unsubscribe later.

| Parameter         | Type     | Description                                                                                                                                                                                                                             |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channel           | string   | The channel name to subscribe to.                                                                                                                                                                                                       |
| replayId          | number   | Indicates what point in the stream to replay events from. Specify -1 to get new events from the tip of the stream, -2 to replay from the last saved event, or a specific event replay ID to get all saved and new events after that ID. |
| onMessageCallback | function | A callback function that's invoked for every event received.                                                                                                                                                                            |

## `unsubscribe`

Unsubscribes from the channel using the given subscription object and returns a promise. The result of this operation is passed in to the callback function. The result object holds the successful boolean field which indicates whether the `unsubscribe` operation was successful. The result fields are based on the CometD protocol for the unsubscribe operation. See [CometD Reference Doc](https://docs.cometd.org/current3/reference/#_bayeux_meta_unsubscribe).

| Parameter    | Type     | Description                                                                        |
| ------------ | -------- | ---------------------------------------------------------------------------------- |
| subscription | object   | Subscription object that the subscribe call returned.                              |
| callback     | function | A callback function that's called with a server response for the unsubscribe call. |

## `onError`

Registers a listener to errors that the server returns.

| Parameter | Type     | Description                                                                                                                                            |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| callback  | function | A callback function that's called when an error response is received from the server for handshake, connect, subscribe, and unsubscribe meta channels. |

## `setDebugFlag`

Set to true or false to turn console logging on or off respectively.

| Parameter | Type    | Description                                                          |
| --------- | ------- | -------------------------------------------------------------------- |
| flag      | boolean | Set to true or false to turn console logging on or off respectively. |

## `isEmpEnabled`

Returns a promise that holds a Boolean value. The value is true if the EmpJs Streaming API library can be used in this context; otherwise false.

## Usage

This example subscribes to a streaming channel when you click the Subscribe button. It logs received event messages to the JavaScript console in your browser. The Unsubscribe button lets you stop the subscription and stop receiving event messages. This example uses the default streaming channel of `/event/Test__e` and assumes that the `Test__e` platform event is defined. Replace the default value with the desired channel name.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-card title="EmpApi Example" icon-name="custom:custom14">
        <div class="slds-m-around_medium">
            <p>
                Use the buttons below to subscribe and unsubscribe to a
                streaming channel!
            </p>
            <lightning-input
                label="Channel Name"
                value={channelName}
                onchange={handleChannelName}
            ></lightning-input>
            <lightning-button
                variant="success"
                label="Subscribe"
                title="Subscribe"
                onclick={handleSubscribe}
                disabled={isSubscribeDisabled}
                class="slds-m-left_x-small"
            ></lightning-button>
            <lightning-button
                variant="destructive"
                label="Unsubscribe"
                title="Unsubscribe"
                onclick={handleUnsubscribe}
                disabled={isUnsubscribeDisabled}
                class="slds-m-left_x-small"
            ></lightning-button>
        </div>
    </lightning-card>
</template>
```
<!-- prettier-ignore-end -->

In the component's JavaScript, event handlers invoke `empApi` methods.

```javascript
import { LightningElement } from "lwc";
import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled } from "lightning/empApi";

export default class EmpApiLWC extends LightningElement {
  channelName = "/event/Test__e";
  isSubscribeDisabled = false;
  isUnsubscribeDisabled = !this.isSubscribeDisabled;

  subscription = {};

  // Tracks changes to channelName text field
  handleChannelName(event) {
    this.channelName = event.target.value;
  }

  // Initializes the component
  connectedCallback() {
    // Register error listener
    this.registerErrorListener();
  }

  // Handles subscribe button click
  handleSubscribe() {
    // Callback invoked whenever a new event message is received
    const messageCallback = function (response) {
      console.log("New message received: ", JSON.stringify(response));
      // Response contains the payload of the new message received
    };

    // Invoke subscribe method of empApi. Pass reference to messageCallback
    subscribe(this.channelName, -1, messageCallback).then((response) => {
      // Response contains the subscription information on subscribe call
      console.log("Subscription request sent to: ", JSON.stringify(response.channel));
      this.subscription = response;
      this.toggleSubscribeButton(true);
    });
  }

  // Handles unsubscribe button click
  handleUnsubscribe() {
    this.toggleSubscribeButton(false);

    // Invoke unsubscribe method of empApi
    unsubscribe(this.subscription, (response) => {
      console.log("unsubscribe() response: ", JSON.stringify(response));
      // Response is true for successful unsubscribe
    });
  }

  toggleSubscribeButton(enableSubscribe) {
    this.isSubscribeDisabled = enableSubscribe;
    this.isUnsubscribeDisabled = !enableSubscribe;
  }

  registerErrorListener() {
    // Invoke onError empApi method
    onError((error) => {
      console.log("Received error from server: ", JSON.stringify(error));
      // Error contains the server-side error
    });
  }
}
```

### Usage Considerations

The `lightning/empApi` module is supported in desktop browsers with web worker or shared worker support. It is not supported in the Salesforce mobile app. For more information about web workers and browser support, see the [Web Workers W3C specification](https://www.w3.org/TR/workers/) and [Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) in the Mozilla Developer Network documentation.

You can use the `lightning/empApi` module only on the main window of a page. You can't use the `lightning/empApi` module on a child window. For example, in a screen flow, you can use the `lightning/empApi` module only on the main screen but not on a button in a screen flow. Similarly, you can’t use the `lightning/empApi` module in the utility bar pop-out window. Another example is a Visualforce page that contains a top-level window and child iframe windows. In this case, the `lightning/empApi` module must be on the top-level window.

## See Also

- [Platform Events Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_events_intro.htm)
- [Streaming API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_streaming.meta/api_streaming/intro_stream.htm)

:::::

:::::tab
::component-specification{component="empApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=8db94dd91aca77079ff6d0fc8022e0deaa27198184f4500b39399ecdc78eb098 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/emptyState/lightning-empty-state.md -->

# Empty State (Beta)

**`lightning-empty-state`**

Presents information to help users understand why a panel or other container has no content.

**For Use In**

Lightning Experience, Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

**note:** `lightning-empty-state` 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.

The `lightning-empty-state` component shows content that represents an "empty state" of a container, such as a panel or card, in which your users expect data to appear. Empty states tell users why there’s no content to show and can guide them to what they can do next.

For example, an empty state can reflect these common conditions.

- An error prevents content loading
- The system is undergoing maintenance
- A search or filter returned no results
- A shopping cart is empty
- A user cleared a list of items

The `lightning-empty-state` component provides a standardized solution for depicting empty states. Instead of creating custom layouts, styling, and illustration handling, use `lightning-empty-state` to take advantage of these benefits.

| Feature                | Developer Benefit                                                                                                |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------- |
| Consistency            | Ensures uniform empty state patterns across the platform with automatic design system compliance.                |
| Simplified Development | Provides a ready-to-use component that eliminates the need for custom empty state implementations.               |
| Dynamic Theme Support  | Illustrations dynamically adapt to themes, supporting light and dark mode and themes based on SLDS 1 and SLDS 2. |
| Responsive Design      | Built-in responsive behavior that adapts to different container sizes.                                           |

## Design

`lightning-empty-state` implements the illustration (empty state) blueprint in the Salesforce Lightning Design System (SLDS). The empty state adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                          | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Illustration (Empty State)](https://v1.lightningdesignsystem.com/components/illustration/#Using-Empty-States/) | [Empty State](https://www.lightningdesignsystem.com/2e1ef8501/p/09f001-empty-state)                             |
| **For Use In** | Lightning Experience, Experience Builder Sites                                                                  | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Compare to `lightning-illustration`

The `lightning-empty-state` component uses the `lightning-illustration` component internally to present scalable vector graphics (SVG) illustrations. Both the `lightning-empty-state` and `lightning-illustration` components currently support the same sets of Salesforce SVG illustrations for depicting empty state conditions.

Use the `lightning-empty-state` component to show text to help users understand why a container has no items to show. Optional call-to-action (CTA) controls and content can help users react, and an optional illustration can help to reassure users.

Currently, you can use [`lightning-illustration`](/docs/platform/lightning-component-reference/guide/lightning-illustration.html) for similar use cases as `lightning-empty-state` where you don’t require the supporting text or call-to-action content. More illustrations are in development for other use cases.

## Usage

Use the `lightning-empty-state` component to present informative text and an optional decorative illustration when a container doesn't display content. The component provides a friendly and consistent way to help your users understand why there's no content. You can also add a button to help them take the next action.

The only required content for `lightning-empty-state` is the `description` slot. Use the `description` slot to explain the empty state scenario and, if possible, guide users to the next activity. The `description` slot gives you flexibility in presenting the information. For example, you can use a simple `<p>` element, which we recommend. If your use case calls for it, you can use multiple paragraphs or another element such as an unordered list.

Provide an optional `title` attribute to create a heading that gets attention and tells users what’s happening. Depending on the use case of the empty state notice, titles can be playful, or more direct and terse. The component renders the title in a `<h3>` element.

Here’s an example that uses `lightning-empty-state` with a title and description, but not an illustration.

<!-- prettier-ignore -->
```html
<!-- Text-only -->

<lightning-empty-state title="No results found">
  <p slot="description">Try adjusting your search criteria.</p>
</lightning-empty-state>
```

## Present an Illustration

Specify the optional `illustration-name` attribute to include an SLDS illustration in the empty state component. The component automatically detects the SLDS version of the theme that’s enabled in Salesforce. This detection enables the component to present different illustrations for SLDS 2 and SLDS 1 themes. In SLDS 2 themes, the illustrations also adapt automatically for dark mode and theme and branding that’s in effect in the org.

`illustration-name` accepts a name in the format `set:symbol` (which you can think of as `category:name`) to retrieve an SVG image from SLDS. For example, if your component shows an empty state of a customer’s cart before the customer has placed items in it, specify `illustration-name="cart:noitems"` to show an illustration of an empty shopping bag.

<!-- prettier-ignore -->
```html
<!-- With illustration  -->

<lightning-empty-state illustration-name="cart:noitems" title="No items in cart">
  <p slot="description">Add items to get started.</p>
</lightning-empty-state>
```

<Screenshot of the component example goes here>

### Illustrations for SLDS 2 and SLDS 1

The `lightning-empty-state` component shows a unique SVG image for each illustration that you can specify with the `illustration-name` attribute. The illustration name follows the `category:name` pattern, for example, `cart:noitems` and `error:connectionissue`.

For SLDS 2 themes, `lightning-empty-state` uses new Salesforce Cosmos illustrations. For SLDS 1 themes, the component uses a smaller set of existing SLDS 1 illustrations from Lightning Experience.

Each of the SLDS 1 illustrations maps to one of the same `category:name` illustration names. The mapping enables `lightning-empty-state` to work in SLDS 1 themes. However, some SLDS 1 illustrations map to multiple illustration names. This reuse of illustrations means that SLDS 1 themes don't have a unique SVG image for each illustration name.

### Map of Illustration Names to Illustrations for SLDS 2 and SLDS 1

These illustration names are available. Visit [Empty State component design](https://www.lightningdesignsystem.com/2e1ef8501/p/09f001-empty-state) to see the current images and their use cases. This table describes the images that map to the illustration names to aid you in recalling the images. You can avoid looking them up in the design each time.

| Illustration Name       | SLDS 2                                       | SLDS 1                                     |
| :---------------------- | :------------------------------------------- | :----------------------------------------- |
| `access:deleted`        | A cocoon or chrysalis                        | An open empty treasure chest               |
| `access:limit`          | An extinguished candle                       | A closed treasure chest                    |
| `access:request`        | A locked padlock                             | A closed treasure chest                    |
| `cart:noitems`          | An empty shopping bag                        | Gone fishing \- Astro and Codey in a canoe |
| `error:appconnection`   | A stylized balloon                           | Floating hot air balloons                  |
| `error:connectionissue` | An unplugged electrical plug                 | Floating hot air balloons                  |
| `error:recoverable`     | A wilting plant                              | A rainy campsite                           |
| `error:unrecoverable`   | A rain cloud                                 | A walking path that's closed               |
| `maintenance:planned`   | A healthy plant                              | A hand under a landscape                   |
| `maintenance:unplanned` | A boomerang                                  | A hand under a landscape                   |
| `noresults:filter`      | Three plants, the tallest bending to the sun | Binoculars with a cracked lens             |
| `noresults:search`      | A telescope pointing away from the sky       | Binoculars with a cracked lens             |
| `noresults:unknown`     | Mountains and clouds                         | Binoculars with a cracked lens             |
| `success:assigned`      | Umbrella planted on a beach                  | Gone fishing \- Astro and Codey in a canoe |
| `success:new`           | A zen sand garden                            | Gone fishing \- Astro and Codey in a canoe |
| `success:selfassigned`  | A flag planted on a hill                     | Gone fishing \- Astro and Codey in a canoe |

For example, this component automatically shows different illustrations for SLDS 2 themes (an empty shopping bag), and SLDS 1 themes (a “gone fishing” scene).

<!-- prettier-ignore -->
```html
<!-- With illustration  -->
<lightning-empty-state illustration-name="cart:noitems" title="No items in cart">
  <p slot="description">When you add items to your cart, they’ll appear here.</p>
</lightning-empty-state>
```

SLDS 2 themes show the empty shopping bag image for the `cart:noitems` illustration.

![Empty bag illustration for cart:noitems in Salesforce Cosmos theme](https://developer.salesforce.com/media/no-items.png '{"class": "image-sm", "title": "Salesforce Cosmos"}')

SLDS 1 themes show the gone fishing image for the `cart:noitems` illustration.

![Gone fishing illustration for cart:noitems in Lightning Blue theme](https://developer.salesforce.com/media/gonefishing.png '{"class": "image-sm", "title": "Lightning Blue"}')

## Override the Responsive Illustration Size

`lightning-empty-state` adapts automatically to the container that it's in, scaling the size of text and illustrations. By default, the component performs responsive sizing by querying the size of the container before setting an illustration size. Based on the size of the container, the component sets one of three sizes: `medium`, `small`, and `x-small`.

| Container Type                           | Container Width | Illustration Size | Illustration Width       |
| :--------------------------------------- | :-------------- | :---------------- | :----------------------- |
| Full page or large panel                 | 366 px or more  | `medium`          | 304 px                   |
| Card                                     | 256–365 px      | `small`           | 184 px                   |
| Mobile device, small card, nested panels | 0–255 px        | `x-small`         | No illustration is shown |

To override the automatic sizing, you can specify the `size` attribute with a value of `medium`, `small`, or `x-small`. For example, to make the empty state component render an illustration as small even when it’s in a large panel, set `size="small"`. If you set `size` to `x-small`, any illustration you specify doesn't appear.

This example sets the size to small.

<!-- prettier-ignore -->
```html
<lightning-empty-state title="No results found" size="small">
  <p slot="description">Try adjusting your search criteria.</p>
</lightning-empty-state>
```

## Add an Action Button to the Empty State

The component provides a slot called `cta` for a call-to-action button. Use `lightning-button` with `slot="cta"` to give users a recommended action to perform when presented with an empty state. Use the brand variant to draw attention to the recommended action.

### Use an Illustration and an Action Button

This example shows an empty cart illustration along with a **Browse Products** call-to-action button with the brand variant.

<!-- prettier-ignore -->
```html
<!-- myEmptyState.html -->
<!-- With illustration and action -->
<lightning-empty-state illustration-name="cart:noitems" title="No items in cart">
  <p slot="description">Add items to get started.</p>
  <lightning-button variant="brand" label="Browse Products" slot="cta" onclick={handleCtaClick}>
  </lightning-button>
</lightning-empty-state>
```

<!-- prettier-ignore -->
```javascript
import { LightningElement } from "lwc";

export default class MyEmptyState extends LightningElement {
  handleCtaClick(event) {
    // go to the Shop tab
  }
}
```

### Use CTA Slot on a Container

For multiple buttons in a call-to-action, use the `cta` slot on a container element. Use no more than two buttons. If you use two buttons, use the brand variant for the primary action button and the neutral variant for the other button.

<!-- prettier-ignore -->
```html
<lightning-empty-state title="Error occurred">
  <p slot="description">Please try again.</p>
  <div slot="cta">
    <lightning-button variant="neutral" label="Cancel"> </lightning-button>
    <lightning-button variant="brand" label="Retry"> </lightning-button>
  </div>
</lightning-empty-state>
```

## Usage Considerations

The `lightning-empty-state` component works only on the Salesforce platform. It requires access to the SVG illustrations in a Salesforce org.

The component works in Experience Builder Sites, but can only display SLDS 1 illustrations. SLDS 2 isn't supported in Experience Cloud.

This component uses new Salesforce Cosmos illustrations to fit the SLDS 2 themes. Develop with the SLDS 2 version of the illustration in mind first, and then test the component with SLDS 1 themes.

## Accessibility

The `lightning-empty-state` component has an optional `alternative-text` attribute for specifying text for assistive technologies. Use `alternative-text` if the illustration conveys meaningful information such as why no results appear. Use concise, purposeful text such as "No search results." Omit `alternative-text` if the illustration is purely decorative and the title or description communicates the message.

The title renders as an `h3` element. If you use `lightning-empty-state` in a location where a level 3 heading isn’t hierarchically accurate for assistive technologies, use the `heading-level` attribute to set the level appropriately. Valid `heading-level` values are `1`, `2`, `3`, `4`, `5`, and `6`.

The illustrations support SLDS standards for high color contrast across all themes.

The call-to-action button is the only interactive element. Use keyboard navigation to get to the call-to-action button, and press Enter or the spacebar to select.

See the [lightning-button documentation](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button.html?type=Develop#accessibility) for more information about accessibility support for buttons.


:::::

:::::tab
::component-specification{component="emptyState" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=419523df4f9f0c40f54cb94389e9913c6c5f72eb7f6948da8f6a30b70b6a9159 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/expand/ui-expand.md -->

# Expand

**`ui:expand`**

Indicates that a component is expanded.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when you expand the `ui:menuList` component. To set a handler for the `ui:expand` event, use the `menuExpand` attribute on `ui:menuList`.

The following example adds or remove a CSS class to the `ui:menuList` component when it's collapsed or expanded.

```xml
<aura:component>
  <ui:menu>
    <ui:menuTriggerLink aura:id="trigger" label="Contacts" />
    <ui:menuList
      class="actionMenu"
      aura:id="actionMenu"
      menuCollapse="{!c.addMyClass}"
      menuExpand="{!c.removeMyClass}"
    >
      <ui:actionMenuItem aura:id="item1" label="All Contacts" click="{!c.doSomething}" />
      <ui:actionMenuItem aura:id="item2" label="All Primary" click="{!c.doSomething}" />
    </ui:menuList>
  </ui:menu>
</aura:component>
```

Here's the client-side controller that handles the adding and removing of the CSS classes.

```javascript
({
  addMyClass: function (component, event, helper) {
    var trigger = component.find("trigger");
    $A.util.addClass(trigger, "myClass");
  },
  removeMyClass: function (component, event, helper) {
    var trigger = component.find("trigger");
    $A.util.removeClass(trigger, "myClass");
  },
});
```

If you're using this event with a component other than `ui:menuList`, register the event first.

```xml
<aura:registerEvent
  name="menuExpand"
  type="ui:expand"
  description="The event fired when the menu list displays."
/>
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=e118b79ddf024eabd5bf56c172f58cfda017fed2e129ba384033b548b643d36b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/fileDownload/lightning-file-download.md -->

# File Download

**`lightning/fileDownload`**

Download a file in an LWR site in Experience Cloud.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add file downloads to Experience Cloud sites that use the Build Your Own (LWR) template.

To create a component that downloads a file, import `generateUrl` from `lightning/fileDownload`. Use the `generateUrl` function and pass in the record ID number of the files that you want to download. This function supports Content Document, Content Version, Attachment, or Document record IDs.

```javascript
import { generateUrl } from "lightning/fileDownload";
```

For this module's documentation, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-file-download-api.html).


:::::

:::::tab

::component-specification{component="fileDownload" model="lwc" namespace="lightning"}


:::::

::::::

<!-- document id=19447b99aac99a33b5eb6b893c0da38048b89fc6c845a8e90d7a603cb9470b02 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/fileSelector/lightning-file-selector.md -->


# File Selector

**`lightning-input`**
_type="file"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="fileSelector" model="lwc" namespace="lightning"}


:::::

:::::tab

An input field for selecting files to upload using an `Upload Files` button or a drag-and-drop zone. This field accepts files up to 3.5 MB.

To retrieve the list of selected files, use `event.target.files` in the `onchange` event handler.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-input
    type="file"
    label="Attachment"
    accept="image/png, .zip"
    onchange={handleFilesChange}
    multiple
  >
  </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                          | SLDS 2                                                                           |
| ---------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| file       | [File Selector](https://v1.lightningdesignsystem.com/components/file-selector/) | [File Selector](https://www.lightningdesignsystem.com/components/file-selector/) |

## Usage

Selected files are returned in a `FileList` object, each specified as a `File` object with the `size` and `type` attributes.

- `lastModified`
- `lastModifiedDate`
- `name`
- `size`
- `type`

For more information on the `File` object, see [MDN web docs: Getting information on selected files](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file).

To handle file uploads in your org, wire up your component to an Apex controller that creates a [ContentVersion](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentversion.htm) and [ContentVersionLink](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contentdocumentlink.htm) object.

Alternatively, use the
[`lightning-file-upload`](/docs/platform/lightning-component-reference/guide/lightning-file-upload.html) component for an integrated way to upload files to records.

To programmatically add a file, assign the file input to a `FileList` object, a `File` object, or an array of `File` objects. For example, you can add a new file to the files that are already attached.

```javascript
 handleAttachFiles() {
    // Create a reference to lightning-input lwc:ref="inputFile"
    const myFileField = this.refs.inputFile;

    // Create a File object
    const myFile = new File(['test content'], 'test.txt', { type: 'text/plain' });

    // Add the new file to existing files
    const currentFiles = myFileField.files ? Array.from(myFileField.files) : [];
    myFileField.files = [...currentFiles, myFile];
}
```

To remove all files from the file list, use one of these methods.

```javascript
// Method 1: Clear files using DataTransfer
myFileField.files = new DataTransfer().files;

// Method 2: Clear files using an empty array
myFileField.files = [];
```

## Input Validation

To validate file selection, use the `required` attribute to ensure at least one file is selected. Use the `accept` attribute to restrict file types, and validate file size in the `onchange` event handler.

<!-- prettier-ignore -->
```html
<template>
    <lightning-input
        type="file"
        label="Upload Document"
        accept=".pdf,.doc,.docx"
        required
        multiple
        lwc:ref="documentUpload"
        onchange={handleFilesChange}
        message-when-value-missing="Please select at least one file"
    >
    </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate file selection, check the file list, file types, and file sizes. If the selected file isn't valid, the `reportValidity()` method shows the error message below the file selector.

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

export default class FileValidation extends LightningElement {
  maxFileSize = 3500000; // 3.5 MB

  handleFilesChange(event) {
    const files = event.target.files;
    if (files.length === 0) {
      return;
    }

    const fileInput = this.refs.documentUpload;

    // Validate file sizes
    for (let file of files) {
      if (file.size > this.maxFileSize) {
        // Display error message
        fileInput.setCustomValidity(`File ${file.name} exceeds the maximum size of 3.5 MB`);
        fileInput.reportValidity();
        return;
      }
    }

    fileInput.setCustomValidity("");
    // Proceed with file upload
  }

  handleSubmit() {
    const fileInput = this.refs.documentUpload;
    console.log(fileInput.validity.valid); // Returns true or false
    if (!fileInput.checkValidity()) {
      fileInput.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `file` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `valueMissing` - Indicates that no file is selected when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

## Accessibility

The component links the `label` attribute you provide with a unique ID on the file selector using the `aria-labelledby` attribute. The `for` attribute is also used to link the "Or drop files" label in the drop zone to the file selector.

If you use the `label-hidden` variant, the `label` attribute maintains the unique ID on the file selector using the `aria-labelledby` attribute. The component also maintains the `for` attribute to link between the file selector and the drop zone label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the file selector and the help tooltip.

If the file selector fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

Use these keys for keyboard navigation on the file selector.

- Tab key: Users can tab to the "Choose Files" button.
- Enter or Space key: Opens the standard OS file selector dialog

After the file selector dialog closes, focus returns to the component, preventing you from losing your place on the page.

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description                                                                                                                                                 |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| files     | Object | For input type `file`, the list of selected files returned in a `FileList` object, each specified as a `File` object with the `size` and `type` attributes. |
| value     | string | For other input types, returns the input value.                                                                                                             |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=88d301fc866a8ab0bccb4f2f59c6291cf3fd34d992180fc504615cb028660d72 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/fileUpload/lightning-file-upload.md -->

# File Upload

**`lightning-file-upload`**

A file uploader for uploading and attaching files to records.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A `lightning-file-upload` component provides an integrated way for users to upload multiple files. You can configure the file uploader to accept specific file types, and the file types are filtered in the user's file browser. To upload files by using `lightning-file-upload`, you can:

- Click the button to select a file from your system's file browser
- Drag a file from your system into the file selector drop zone

To associate an uploaded file with a record, specify the `record-id` attribute.
Uploaded files are available in several locations:

- Files Home under the Owned by Me filter
- On the record's Attachments related list that's on the record detail page

If you don't specify the `record-id` attribute, the file is private to the uploading user.

Although all Salesforce-supported file formats are allowed, you
can restrict the file formats by using the `accept` attribute.

The button label is "Upload Files" by default. Use the `label` attribute to add a descriptive label above the Upload Files button.

This example creates a file uploader that allows you to upload multiple PDF and PNG files.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-file-upload
        label="Attach receipt"
        name="fileUploader"
        accept={acceptedFormats}
        record-id={myRecordId}
        onuploadfinished={handleUploadFinished}
        multiple
    >
    </lightning-file-upload>
</template>
```
<!-- prettier-ignore-end -->

You must handle the `uploadfinished` event, which is fired when the upload
is finished to return a list of the uploaded files, including
each file's name and documentId.

```javascript
import { LightningElement, api } from "lwc";
export default class FileUploadExample extends LightningElement {
  @api
  myRecordId;

  get acceptedFormats() {
    return [".pdf", ".png"];
  }

  handleUploadFinished(event) {
    // Get the list of uploaded files
    const uploadedFiles = event.detail.files;
    alert("No. of files uploaded : " + uploadedFiles.length);
  }
}
```

After you select the files to upload, the Upload Files dialog shows the upload progress. You can dismiss it by clicking the x icon or the Done button.

Use the event handler to customize what happens after your files upload successfully and the Upload Files dialog is dismissed, such as showing a toast by using the `lightning/platformShowToastEvent` module.

If your record page shows the Notes &amp; Attachments panel, your uploaded files automatically appear there after the page is refreshed.

## Design

`lightning-file-upload` implements the file selector blueprint in the Salesforce Lightning Design System (SLDS). The file selector adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                          | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [File Selector](https://v1.lightningdesignsystem.com/components/file-selector/) | [File Selector](https://www.lightningdesignsystem.com/components/file-selector/)                                |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App           | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

## File Upload Limits

By default, you can upload up to 10 files simultaneously unless your
Salesforce admin has changed that limit. The org limit for the number of files
simultaneously uploaded is a minimum of 1 file and a maximum of 25 files. The
maximum file size that you can upload is 10 GB.

In Experience Builder sites, the file size limits are lower than the default 10 GB, and they depend on your site’s URL configuration. If you use the `my.site.com` URL provided by Salesforce, the size limit per file is 128 MB. If you create a custom domain, the size limit is 500 MB. For more information, see [Configure a Custom Domain and CDN in Salesforce Help](https://help.salesforce.com/s/articleView?id=commerce.comm_configure_cdn_and_custom_domains.htm). The allowed file size limits and types also follow the settings determined by site file moderation.

## Enable Guest Users to Upload Files

By default, guest users can’t upload files and don’t have access to objects and their related records.

To enable guest users to upload files, enable the org preference **Allow site guest users to upload files**.
From Setup, in the Quick Find box, enter `Salesforce Files`, and select **General Settings**.
Select **Allow site guest users to upload files**.
However, even if you enable this setting, guest users can upload files to a record only when guest user sharing
rules are in place.

To use `lightning-file-upload` for LWR sites with LWR and guest enabled sites, you must also select
**Use the File Upload Lightning web component for LWR sites**.

The **Secure guest user record access** org preference prevents access to records by guest users.
As a result, if you specify the `record-id` in the `lightning-file-upload` component, the file
fails to upload because the guest user doesn't have access to the record.

To enable guest users to upload files to a record, the org admin can create a custom field on
the ContentVersion object. The field type can be text or picklist. The API name of the custom field must
end with `fileupload__c`. For example, you can use the API name `Guest_Record_fileupload__c`
for the custom field.

Specify the `file-field-name` and `file-field-value` attributes in `lightning-file-upload` to store
a value in the custom field in the ContentVersion object. For example, set `file-field-name` to
`Guest_Record_fileupload__c`. Set `file-field-value` to a value that can be used in Apex to associate
the file to the record.

You can omit the `record-id` attribute when specifying `file-field-name` and `file-field-value`
attributes. However, if you provide the `record-id`, `file-field-name` and `file-field-value`
attributes, the record ID is ignored if the uploading user is a guest user.

If you don't provide the `record-id` or `file-field-name` and `file-field-value`
attributes, the uploaded file is private to an authenticated user.

This example specifies `record-id`, `file-field-name`, and `file-field-value` attributes for
behavior that supports authenticated users and guest users for uploading files to records.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-file-upload
        label="Attach receipt"
        name="fileUploader"
        accept={acceptedFormats}
        record-id={myRecordId}
        file-field-name="Guest_Record_fileupload__c"
        file-field-value={encryptedToken}
        onuploadfinished={handleUploadFinished}
        multiple
    >
    </lightning-file-upload>
</template>
```
<!-- prettier-ignore-end -->

Use Apex in your JavaScript file to get the value of the custom field.

The `uploadfinished` event is fired when the upload
is finished to return a list of the uploaded files, including
each file's name and `documentId`. When a guest user uploads files,
the returned list includes only the names of the files and doesn't return `documentId`.

```javascript
import { LightningElement, api } from "lwc";
export default class FileUploadExample extends LightningElement {
  @api myRecordId;

  get encryptedToken() {
    //use apex to get
  }

  get acceptedFormats() {
    return [".pdf", ".png"];
  }

  handleUploadFinished(event) {
    // Get the list of uploaded files
    const uploadedFiles = event.detail.files;
    alert("No. of files uploaded : " + uploadedFiles.length);
  }
}
```

When guest users upload files, the component returns `ContentVersionId` and not `ContentDocumentId`.

For more information, see [Files Best Practices and Considerations for Guest Users](https://help.salesforce.com/articleView?id=networks_files_best_practices.htm&type=0) in Salesforce Help.

## Usage Considerations

`lightning-file-upload` doesn't support uploading multiple files at once on Android devices.

This component isn't supported in Lightning Out or standalone apps, and
displays as a disabled input. Additionally, if the `Don't allow HTML uploads as attachments or document records` security setting is enabled for your
organization, the file uploader can't be used to upload files with the
following file extensions: .htm, .html, .htt, .htx, .mhtm, .mhtml, .shtm,
.shtml, .acgi, .svg. For more information, see [Configure File Upload and Download Security Settings](https://help.salesforce.com/s/articleView?id=experience.admin_files_type_security.htm) in Salesforce Help.

If an error is detected on the client side, the file upload dialog shows an
informative error message. For example, the message informs you if you try
to upload a file type that isn't on the `accept` list. If an error
is detected on the server side, you see a generic "Can't upload file"
error. For example, you get this error if you don't provide a valid
record ID or the upload violates a validation rule.

We recommend that you add one or more record types to the ContentVersion
object in your org. When record types are present, the file uploader enables you to
provide details about the file and shows any error messages from the server.
This feature is useful if your org uses Apex triggers or validation rules
for file uploads, or has required custom fields in the ContentVersion object.
You can fix errors or provide required information to complete the upload
without reuploading the file.

On mobile devices, file upload doesn't work correctly when there's a required custom field in the ContentVersion object. To avoid this limitation, try one of these workarounds.

- Make the custom field optional
- Set a default value for the custom field
- Use code to populate the field after file upload

For external users, the component doesn't follow an object's org-wide default (OWD) settings and instead relies on the sharing hierarchy. Even when an object's OWD is set to Public Read/Write, external users can't add files to the object. To provide access for external users, [create a sharing set](https://help.salesforce.com/s/articleView?id=platform.networks_setting_light_users.htm).

## Custom Events

**`uploadfinished`**

The event fired when files are uploaded successfully.

The `uploadfinished` event returns the following parameter.

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| files     | object | The list of files that are uploaded. |

`event.detail.files` returns a list of uploaded files with the attributes
`name` and `documentId`. If a guest user performed the file upload, the
`documentId` isn't returned.

- `name`: The file name in the format `filename.extension`, for example, account.jpg.
- `documentId`: The ContentDocument Id in the format `069XXXXXXXXXXXX`.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event doesn't bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event doesn't propagate outside the template in which it was dispatched.                             |

## See Also

[_Salesforce Help_: Configure File Upload and Download Security Settings](https://help.salesforce.com/s/articleView?language=en_US&id=experience.admin_files_type_security.htm)

[_Salesforce Help_: Files Best Practices and Considerations for Guest Users](https://help.salesforce.com/articleView?id=networks_files_best_practices.htm)

[_Salesforce Help_: Sharing Rule Types](https://help.salesforce.com/articleView?id=platform.security_sharing_rule_types.htm)

[Guest User Record Access Development Best Practices](https://www.learnexperiencecloud.com/s/article/Guest-User-Record-Access-Development-Best-Practices)


:::::

:::::tab
::component-specification{component="fileUpload" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=5984daa35124d2ab29b7c6bad13d79e83783bc18cbba7a91bc99f8639afa0668 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/flow/lightning-flow.md -->

# Flow

**`lightning-flow`**

Represents a flow interview.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A `lightning-flow` component represents a screen flow interview in Lightning runtime. To use this component, [build a flow](https://help.salesforce.com/s/articleView?id=platform.flow_build.htm&type=5) with the Salesforce Flow Builder first.

To create a flow in your component, set the `lightning-flow` component's `flowApiName` attribute to the name of the flow that you want to use. The component includes navigation buttons (Back, Next, Pause, and Finish), for users to navigate within the flow.

This example creates and starts the Survey Customers flow.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-flow
        flow-api-name='Survey_customers'
    >
    </lightning-flow>
</template>
```
<!-- prettier-ignore-end -->

You can provide initial inputs for the interview by setting the `flowInputVariables` 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-start -->
```html
<template>
    <lightning-flow
        flow-api-name='Survey_customers'
        flow-input-variables={inputVariables}
        onstatuschange={handleStatusChange}
    >
    </lightning-flow>
</template>
```
<!-- prettier-ignore-end -->

```js
get inputVariables() {
    return [
        {
            name: 'OpportunityID',
            type: 'String',
            value: '<Opportunity.Id>'
        },
        {
            name: 'AccountID',
            type: 'String',
            value: '<Opportunity.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 `flowApiName` attribute.

If you have custom Lightning Web Components or Aura components in your flow, then you won't be able to use `lightning-flow` on Experience Cloud sites that use Lightning Web Runtime.

The `onstatuschange` event returns these parameters.

| 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 the `$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 current status of the interview.                                                                         |

These are the valid `status` values for a flow interview.

- `STARTED`: The interview is started and ongoing.
- `PAUSED`: The interview is paused successfully.
- `FINISHED`: The interview for a flow with screens is finished.
- `FINISHED_SCREEN`: The interview for a flow without screens is finished.
- `ERROR`: Something went wrong and the interview failed.

## Customizing a Flow's Finish Behavior

By default, a finished flow without screens displays the message “Your flow finished.” A finished flow with screens returns users to the first screen for a new interview.

Change this behavior with the `flowFinishBehavior` attribute to manage whether a new interview should restart or only run once.

These are the valid `flowFinishBehavior` values.

- `NONE`: The flow only runs once.
- `RESTART`: The flow restarts once it has finished.

To customize what happens when the flow finishes, add an event handler for the `onstatuschange` action when the `status` value contains `FINISHED`.


:::::

:::::tab
::component-specification{component="flow" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2a314c21d7a4bf00c789e3cccea5dcc9f3f6c2dc6ed1b9feb11e970f7f8b1e00 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/flowSupport/lightning-flow-support.md -->

# Flow Support

**`lightning/flowSupport`**

Controls flow navigation and notifies the flow of changes in attribute values.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/flowSupport` module provides events that enable a component to control flow navigation and notify the flow of changes in attribute values.

The events are supported only in components where the target is `lightning__FlowScreen`.

Events include:

- `FlowAttributeChangeEvent` — Informs the runtime that a component property has changed.
- `FlowNavigationBackEvent` — Requests navigation to the previous screen.
- `FlowNavigationNextEvent` — Requests navigation to the next screen.
- `FlowNavigationPauseEvent` — Requests the flow runtime to pause the flow.
- `FlowNavigationFinishEvent` — Requests the flow runtime to terminate the flow.

## Component Metadata

This example `toDos` component includes the `lightning__FlowScreen` target and sets a property in its `toDos.js-meta.xml` file.

```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>Todos Component</masterLabel>
    <description>This is a simple todos component</description>
    <targets>
        <target>lightning__FlowScreen</target>
    </targets>

    <targetConfigs>

        <targetConfig targets="lightning__FlowScreen">
            <property name="todos" type="String[]" label="Todos" description="list of todos"/>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>
```

## Component Template

The example `toDos` component template includes buttons that work with the flow.

<!-- prettier-ignore-start -->
```html
<template>
    List of ToDos:
    <template if:true={hasTodos} for:each={todosList} for:item="todo">
        <div key={todo.id}>{todo.text}</div>
    </template>
    <lightning-input
        label="New Todo"
        type="text"
        onchange={handleUpdatedText}
    >
    </lightning-input>
    <lightning-button
        label="Add Todo"
        title="Add a new todo"
        onclick={handleAddTodo}
    >
    </lightning-button>
    <lightning-button
        label="Go Next"
        title="Finish todos, go next"
        onclick={handleGoNext}
    >
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

## Use Events in JavaScript

The component uses the `FlowAttributeChangeEvent` and `FlowNavigationNextEvent` events from `lightning/flowSupport` in JavaScript.

```javascript
import { LightningElement, api, track } from "lwc";
import { FlowAttributeChangeEvent, FlowNavigationNextEvent } from "lightning/flowSupport";

export default class Todos extends LightningElement {
  @api
  availableActions = [];

  @api
  get todos() {
    return this._todos;
  }

  set todos(todos = []) {
    this._todos = [...todos];
  }

  @track _todos = [];

  get todosList() {
    return this._todos.map((todo) => {
      return { text: todo, id: Date.now().toString() };
    });
  }

  get hasTodos() {
    return this._todos && this._todos.length > 0;
  }

  handleUpdatedText(event) {
    this._text = event.detail.value;
  }

  handleAddTodo() {
    this._todos.push(this._text);
    // notify the flow of the new todo list
    const attributeChangeEvent = new FlowAttributeChangeEvent("todos", this._todos);
    this.dispatchEvent(attributeChangeEvent);
  }

  handleGoNext() {
    // check if NEXT is allowed on this screen
    if (this.availableActions.find((action) => action === "NEXT")) {
      // navigate to the next screen
      const navigateNextEvent = new FlowNavigationNextEvent();
      this.dispatchEvent(navigateNextEvent);
    }
  }
}
```

## See Also

[Create Flow Screen Components](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-flow-screens)


:::::

:::::tab
::component-specification{component="flowSupport" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=3666531fb56cbf2b973fff0263e657bfb21d1e6c7ef22569213ca10fc50f3220 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/forecastingTemplate/aura-forecasting-template.md -->

# Forecasting Template

**`lightning:forecastingTemplate`**

Enables a component to be used as a flexipage page template for the FORECASTING_PAGE page type.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning:forecastingTemplate` interface lets you use a component as a custom Lightning page template for Forecasting Pages. Components with `lightning:forecastingTemplate` appear in the Custom Templates section of the Lightning App Builder new page wizard for app pages. This interface is only supported for Lightning Experience and the Salesforce app.

Each component can implement only one template interface. Components using `lightning:forecastingTemplate` can't use additional interfaces, such as `flexipage:availableForAllPageTypes` or `force:hasRecordId`.

The component in the `lightning:forecastingTemplate` interface doesn't have its original function. It only functions as a custom Lightning page template for that component.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=2ceffd8bcd8464717f32cc28b65c492c7400b3223899f25d30b1a8b292df8341 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedAddress/lightning-formatted-address.md -->


# Formatted Address

**`lightning-formatted-address`**

Displays a formatted 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.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedAddress" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-address` component shows addresses in a format and field order
that's determined by the user's Salesforce locale.

Specify a valid address using attributes for `street`, `city`, `country`, `province`, and
`postal-code`.

This example specifies an address.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-address
        street="1 Market St."
        city="San Francisco"
        country="US"
        province="CA"
        postal-code="94105"
    >
    </lightning-formatted-address>
</template>
```
<!-- prettier-ignore-end -->

The output looks like this in the en-US locale.

1 Market St.\
San Francisco, CA 94105\
US

By default, the address renders as a link that
opens the given location in Google Maps in a new tab. The link
follows the format `https://www.google.com/maps/?q=your+address`.
In the example, the link corresponds to
`https://www.google.com/maps/?q=121%20Spear%20St.%0ASan%20Francisco,%20CA%2094105%0AUS`.

Specify the `disabled` attribute to show the address in plain text
without a link.

## Specify Coordinates for Mapping

You can provide the `latitude` and `longitude` attributes in addition to
the address fields. This configuration enables faster map rendering by avoiding the
geocode processing that's required for street addresses on Google Maps.
The formatted address shows the street address fields,
but the link URL uses the latitude and longitude for Google Maps.

This example specifies an address and uses latitude and longitude for mapping.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-address
        street="1 Market St."
        city="San Francisco"
        country="US"
        province="CA"
        postal-code="94105"
        latitude="37.792179"
        longitude="-122.392735"
    >
    </lightning-formatted-address>
</template>
```
<!-- prettier-ignore-end -->

The link URL with latitude and longitude follows the format
`https://www.google.com/maps/?q=37.792179,-122.392735`.

## Show a Static Map

Use the `show-static-map` attribute to show a map with your address.
The address and the static map are both linked to Google Maps.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-address
        street="1 Market St."
        city="San Francisco"
        country="US"
        province="CA"
        postal-code="94105"
        show-static-map
    >
    </lightning-formatted-address>
</template>
```
<!-- prettier-ignore-end -->

## Address Line Truncation

By default, each line of address uses the [slds-truncate](https://v1.lightningdesignsystem.com/utilities/truncation/) class.
To remove address line truncation, set `variant="plain"`. This configuration renders each address line without truncating it.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-address
        street="45 Ffordd Penmynydd"
        city="St Mary's Church in the Hollow of the White Hazel near a Rapid Whirlpool and the Church of St. Tysilio near the Red Cave"
        country="United Kingdom"
        province="Wales"
        postal-code="LL61 5UJ"
        variant="plain"
        disabled
    ></lightning-formatted-address>
</template>
```
<!-- prettier-ignore-end -->

## Accessibility

`lightning-formatted-address` specifies the `aria-label` description on the link so screen readers can announce the destination address. The `aria-label` description dynamically combines the action and the address using the format:

```
Show in Google Maps, {your_formatted_address}
```

The description provides clear intent to assistive technologies, making it obvious that interacting with the link opens the location externally.

If you specify the `disabled` attribute on the component, the address is shown in plain text instead of a link.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedAddress" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=8601c7d77088b59cda0a9fb23f03324bbed62999341697f64b4a79fbb405377d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedDateTime/lightning-formatted-date-time.md -->


# Formatted Date Time

**`lightning-formatted-date-time`**

Displays formatted date and time.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedDateTime" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-date-time` component shows formatted date and time.
This component uses the Intl.DateTimeFormat JavaScript object to format date
values. The locale set in the Salesforce user preferences determines the
default formatting. This component supports these input values.

- Date object
- ISO8601 formatted string
- Timestamp

An ISO8601 formatted string matches one of the these patterns.

- YYYY
- YYYY-MM
- YYYY-MM-DD
- YYYY-MM-DDThh:mmTZD
- YYYY-MM-DDThh:mm:ssTZD
- YYYY-MM-DDThh:mm:ss.sTZD

`YYYY` is the year in the Gregorian calendar, `MM` is the month between 01 and
12, and `DD` is the day between 01 and 31. `hh` is the number of hours that
have passed since midnight, `mm` is the number of minutes that have passed
since the start of the hour, and `ss` is the number of seconds since the start
of the minute.

`TZD` is the time zone designator, like `Z`, `+hh:mm` or `-hh:mm`. To indicate
that a time is measured in Universal Time (UTC), append a `Z` to a time.

## Default Formatting

When no attributes other than `value` are specified, the component uses the default "medium" date format based on the user's locale in Salesforce.

The locale determines the order and format of the month, day, and year. For example, the English (United States) locale's medium date format is Oct 14, 2020 and the French (France) locale's medium date format is 14 Oct 2020. The locale doesn't determine the time zone. Time zone is a separate setting.

To override the medium date format, pass in the `short` or `long` format to
the `date-style` attribute. For the previous example, the short format in English (United States) is 10/14/2020 while the long format is October 14, 2020.

The locale also determines whether to display time as 24-hour time or 12-hour time with AM and PM. You can override the locale default with the `hour12` attribute. See [Date and Time Display Examples](#date-and-time-display-examples) for more information.

Specify optional attributes listed in the Specification tab to modify the date and time display, overriding the locale's default formatting.

## Time Zone Considerations

Two different attributes affect the time zone display.

The `time-zone-name` attribute specifies how to display the time zone. Set it to `short` to display
a code such as EST, or `long` to display a description such as Eastern Standard Time.

The `time-zone` attribute sets a particular time zone to use to display the date and time,
instead of the user device's time zone setting. Specify a
time zone from the [IANA Time Zone Database](https://www.iana.org/time-zones), such as
`America/New_York`, `Europe/London`, or `Asia/Tokyo`. You can’t use a time zone short code such as
EST to set the `time-zone` attribute. You can use the code UTC however, as it's the only short code that browsers
must recognize.

When using the component to display a date only, without time, include `time-zone="UTC"` to ensure the correct date displays
in all time zones. This requirement is especially important if you specify a timestamp for the `value`. Because timestamps contain time and date information, the component converts the date to the time zone in effect on the user's device and then displays the date.

## Date and Time Display Examples

Here are some examples based on a locale of en-US.

Displays: Jan 11, 2019

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time value="1547250828000" time-zone="UTC">
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: January 11, 2019

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time value="1547250828000" date-style="long" time-zone="UTC">
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: Friday, Jan 11, 19

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value="1547250828000"
        year="2-digit"
        month="short"
        day="2-digit"
        weekday="long"
        time-zone="UTC"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: 1/11/2019, 3:53 PM PST (if user is in PST time zone)

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value="1547250828000"
        year="numeric"
        month="numeric"
        day="numeric"
        hour="2-digit"
        minute="2-digit"
        time-zone-name="short"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: 1/11/2019, 6:53 PM EST

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value="1547250828000"
        year="numeric"
        month="numeric"
        day="numeric"
        hour="2-digit"
        minute="2-digit"
        time-zone-name="short"
        time-zone="America/New_York"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: 1/11/2019, 18:53 EST

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value="1547250828000"
        year="numeric"
        month="numeric"
        day="numeric"
        hour="2-digit"
        hour12={ampm}
        minute="2-digit"
        time-zone-name="short"
        time-zone="America/New_York"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Set the `hour12` attribute using a variable. If set to `false` or any other string directly, the component interprets its value as true.

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

export default class FormattedDateTimeHour12 extends LightningElement {
  ampm = false;
}
```

## Date and Time Stored in Salesforce

Salesforce uses the ISO8601 format `YYYY-MM-DD` to store date fields, which store a date without time, and includes no time zone information.
When formatting dates without time, include `time-zone="UTC"` to ensure the correct date displays.

Salesforce uses the ISO8601 format `YYYY-MM-DDThh:mm:ss.SZ` for date/time fields, which stores date/time in UTC.

Assuming a user is in the en-US locale and Pacific time zone, here are two examples for a date field with
the value `1965-04-09`.

Displays: Apr 9, 1965

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time value={contact.Birthdate} time-zone="UTC">
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Displays: April 09, 1965

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value={contact.Birthdate}
        year="numeric"
        day="2-digit"
        month="long"
        time-zone="UTC"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

Assuming an en-US locale and a Pacific time zone,
here's an example for a date/time field with the value
`2017-12-03T20:00:00.000+00:00`.

Displays: December 03, 2017, 12:00 PM

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-date-time
        value={contact.Next_Meeting__c}
        year="numeric"
        day="2-digit"
        month="long"
        hour="2-digit"
        minute="2-digit"
    >
    </lightning-formatted-date-time>
</template>
```
<!-- prettier-ignore-end -->

## Usage Considerations

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-formatted-date-time`, see the `c-clock` component.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedDateTime" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=42f995714048e875099987e1b7acf1440ccf58d4fb8277c1d6578710f7acb452 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedEmail/lightning-formatted-email.md -->


# Formatted Email

**`lightning-formatted-email`**

Displays an email as a hyperlink with the mailto: URL scheme.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedEmail" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-email` component displays a read-only representation of
an email address as a hyperlink using the `mailto:` URL scheme. Clicking on
the email address opens the default mail application for the desktop or mobile
device.

This example displays an email address with an email icon. The email address
is displayed as the default label.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-email value="hello@example.com">
    </lightning-formatted-email>
</template>
```
<!-- prettier-ignore-end -->

This example prevents the display of the email icon.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-email value="hello@example.com" hide-icon>
    </lightning-formatted-email>
</template>
```
<!-- prettier-ignore-end -->

Multiple email addresses are supported. The label "Send a group email" is
displayed as a hyperlink in this example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-email
        value="hello@example.com,email@example.com"
        label="Send a group email"
    >
    </lightning-formatted-email>
</template>
```
<!-- prettier-ignore-end -->

This example creates an email address with values for cc, subject, and email
body. The label is displayed as a hyperlink.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-email
        value="hello@example.com?cc=email@example.com&subject=My%20subject &body=The%20email%20body"
        label="Send us your feedback"
    >
    </lightning-formatted-email>
</template>
```
<!-- prettier-ignore-end -->

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-formatted-email`, see the following components in the LWC Recipes repo.

- `c-nav-to-record`
- `c-wire-get-record-user`

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedEmail" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=8974f25745bb02371b70a76133bcdbb95c419bf996ef4aa8db8307d3e2dfdec0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedLocation/lightning-formatted-location.md -->


# Formatted Location

**`lightning-formatted-location`**

Displays a geolocation in decimal degrees using the format [latitude, longitude].

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedLocation" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-location` component shows a read-only representation
of a latitude and longitude value. Latitude and longitude are geographic
coordinates specified in decimal degrees. If one of the values is invalid or
outside the allowed range, this component doesn't show anything.

Here are a few examples of latitudes: -30, 45, 37.12345678, -10.0. Values such
as 90.5 or -90.5 aren’t valid latitudes. Here are a few examples of
longitudes: -100, -120.9762, 115.84. Values such as 180.5 or -180.5 aren't
valid longitudes.

This example displays a geolocation with a latitude of 37.7938460 and a
longitude of -122.3948370.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-location
        latitude="37.7938460"
        longitude="-122.3948370"
    >
    </lightning-formatted-location>
</template>
```
<!-- prettier-ignore-end -->

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedLocation" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=5f1a3648f2fd6b1cd34bce064a6055fa6c68b04762af219607a4b4d1d810af06 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedName/lightning-formatted-name.md -->


# Formatted Name

**`lightning-formatted-name`**

Displays a formatted name that can include a salutation and suffix.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedName" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-name` component shows formatted names in a given
format and order. The locale you set in the app's user preferences determines how
the component formats the names and how it presents the order of the names.

This example specifies "Mr. John Middleton Doe The 3rd Jo" based on the
default English United States locale with the `long` format.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-name
        first-name="John"
        middle-name="Middleton"
        last-name="Doe"
        informal-name="Jo"
        suffix="The 3rd"
        salutation="Mr."
    >
    </lightning-formatted-name>
</template>
```
<!-- prettier-ignore-end -->

The `format` attribute determines the length of the name.

| Format         | Description                                                                                     | Example                           |
| -------------- | ----------------------------------------------------------------------------------------------- | --------------------------------- |
| short          | Shows the first name and last name only.                                                        | John Doe                          |
| medium         | Shows the first name, middle name, and last name only.                                          | John Middleton Doe                |
| long (default) | Shows the name including salutation, first name, middle name, last name, suffix, informal name. | Mr. John Middleton Doe The 3rd Jo |

For more information on supported locales, see
[Supported Locales](https://help.salesforce.com/articleView?id=admin_supported_locales.htm)
in the Salesforce Help.

To create a form that takes in user input for names, you can use the
`lightning-input-name` component, which shows a name compound field that
supports user input for salutation, suffix, and so on.

## Use the Locale Information

In Lightning Experience, the `locale` value corresponds to the **Locale** field on the Language &amp; Time Zone page in the [user's personal settings](https://help.salesforce.com/s/articleView?id=xcloud.usersetup_lang_time_zone.htm).

By default, the org's locale setting determines the order of the name fields. If a user sets their personal locale setting, it overrides the org's locale setting.

For example, if you select "French (France)" in the **Locale** field, `lightning-formatted-name` uses `fr-FR` as the locale.

To enable your component to override the user's personal locale setting, set the `locale` attribute. Specify any locale code from the list of [Supported Number, Name, and Address Formats (ICU)](https://help.salesforce.com/s/articleView?id=xcloud.admin_supported_locales.htm).

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-name
          first-name="John"
          middle-name="Middleton"
          last-name="Doe"
          suffix="The 3rd"
          salutation="Mr."
          locale="en-US">
    </lightning-formatted-name>
</template>
```
<!-- prettier-ignore-end -->

If you don't specify the `locale`, `lightning-formatted-name` defaults to the user's locale in the org.

<!-- prettier-ignore-start -->
```html
<template>
    <h2>User's locale: {userLocale}</h2>
    <!--No locale specified on lightning-formatted-name -->
    <lightning-formatted-name
          lwc:ref="name"
          first-name="John"
          middle-name="Middleton"
          last-name="Doe"
          suffix="The 3rd"
          salutation="Mr.">
    </lightning-formatted-name>
</template>
```
<!-- prettier-ignore-end -->

In this example, the `userLocale` property returns `fr-FR` based on the org user's settings.

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

export default class LocaleExample extends LightningElement {
  userLocale = "";

  renderedCallback() {
    this.userLocale = this.refs.name.locale;
  }
}
```

If you pass in an invalid locale, the component uses `en-US`. The locale supports both hyphens and underscores, for example, `en-US` or `en_US`.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedName" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=fe9fea74c91e4b4788a02e59876c4764ca9e592b4a3a2ea2677445857dac6372 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedNumber/lightning-formatted-number.md -->


# Formatted Number

**`lightning-formatted-number`**

Displays formatted numbers for decimals, currency, and percentages.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedNumber" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-number` component shows formatted numbers for
decimals, currency, and percentages. Use `format-style` to specify the
number style. This component uses the [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/)
JavaScript object to format numerical values.

The locale set in your Salesforce user
settings determines where to place spaces, commas, and periods in numbers, and the currency
used by default. See the [Usage Considerations](#usage-considerations) section for limitations in some locales.

The component has several attributes to specify how to format numbers.
Among these attributes are `minimum-significant-digits` and
`maximum-significant-digits`. Significant digits refer to the accuracy of a number.
For example, 1000 has one significant digit, but 1000.0 has five significant
digits. By default, `lightning-formatted-number` shows the value 1000.0 as 1000. To include
the decimal and trailing zero, set `minimum-significant-digits` to 5.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number value="1000.0" minimum-significant-digits="5">
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

Customize the number of decimal places by using
`minimum-fraction-digits` and `maximum-fraction-digits`.

Decimal numbers default to 3 decimal places. This example returns `1234.568`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number value="1234.5678"> </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

To include all four digits in the decimal place, add the attribute `minimum-fraction-digits="4"`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number value="1234.5678" minimum-fraction-digits="4">
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

## Work With Currencies

Currency numbers default to 2 decimal places. In this example, the formatted number
is \$5,000.00.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number
        value="5000"
        format-style="currency"
        currency-code="USD"
    >
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

The `currency-display-as` attribute changes the currency display to use the `symbol`, `code`, or `name` of the currency.

To change the number of decimal places, use one or both of the `minimum-fraction-digits` and `maximum-fraction-digits` attributes.

This example renders `¥4,000` by using `minimum-fraction-digits="0"` to suppress decimals.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number
        value="4000"
        format-style="currency"
        currency-code="JPY"
        minimum-fraction-digits="0"
    >
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

This example renders `KWD 500.000` by using `minimum-fraction-digits` to include three decimal places.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number
        value="500"
        format-style="currency"
        currency-code="KWD"
        minimum-fraction-digits="3"
    >
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

## Work With Percentages

Specify `format-style="percent"` to format the number as a percent value.
Percentages default to 0 decimal places, with rounding. In this example, the formatted number
is 50%.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number value="0.503" format-style="percent">
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

To preserve the decimal points, use the `maximum-fraction-digits` attribute. In this example, the formatted number is 50.3%.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number
        value="0.503"
        format-style="percent"
        maximum-fraction-digits="1"
    >
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

To display the value as-is without multiplying it by 100, specify `format-style="percent-fixed"`.
In this example, the formatted number displays as 1% because decimal places aren't included by default
and the value is rounded.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number value="0.503" format-style="percent-fixed">
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

Add the attribute `maximum-fraction-digits="3"` to set the percentage as 0.503%.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-number
        value="0.503"
        format-style="percent-fixed"
        maximum-fraction-digits="3"
    >
    </lightning-formatted-number>
</template>
```
<!-- prettier-ignore-end -->

## Work with Large Numbers

To prevent precision loss when working with large numbers with more than 15 or 16 digits, specify the numbers as a string.

<!-- prettier-ignore-start -->
```html
<p>Balance</p>
<lightning-formatted-number
    format-style="currency"
    currency-code="USD"
    value={balance}
></lightning-formatted-number>
```
<!-- prettier-ignore-end -->

When you specify the number in JavaScript without using a string, the component renders `$123,456,789,012,345,680.00`, which is a loss in precision.

```javascript
// Don't do this
// Large numbers result in precision loss
balance = 123456789012345678;
```

To prevent precision loss for large numbers, consider using a string instead.

```javascript
// Do this instead
// Specify a large number using a string
balance = "123456789012345678";
```

## Usage Considerations

The locale set in your Salesforce user preferences determines how numbers are formatted. Some locales such as the Arabic (Lebanon) and Bangla (Bangladesh) locales also specify a numeral system other than the Hindu-Arabic numerals 0-9. The org permission “Show Hindu-Arabic Numbers” is intended to override a locale's default numerals. However, `lightning-formatted-number` displays the locale's default numerals even when this permission is enabled in your org. See [Supported Number, Name, and Address Formats (ICU)](https://help.salesforce.com/articleView?id=admin_supported_locales.htm").

The `format-style` attribute is called the `style` attribute in the Aura version of this component.
See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-formatted-date-time`, see the `c-misc-shared-javascript` component.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedNumber" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9dc06998fa6a76a534c5cccead88d3f092e0a2b6b37d2f690c66aba6096da9cc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedPhone/lightning-formatted-phone.md -->


# Formatted Phone

**`lightning-formatted-phone`**

Displays a phone number as a hyperlink with the tel: URL scheme.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedPhone" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-phone` component shows a read-only representation of
a phone number as a hyperlink by using the `tel:` URL scheme. Clicking the phone
number opens the default VOIP call app on a desktop. On mobile
devices, clicking the phone number calls the number.

If you set your org's locale to English (United States) or English (Canada), a phone number
with 10 or 11 digits that starts with 1 uses the format (999) 999-9999.

Include a "+" sign before the number to use the format +19999999999 instead.

Here are two ways to specify (425) 555-0155 as a hyperlink.

<!-- prettier-ignore-start -->
```html
<template>
    <p>
        <lightning-formatted-phone value="4255550155">
        </lightning-formatted-phone>
    </p>
    <p>
        <lightning-formatted-phone value="14255550155">
        </lightning-formatted-phone>
    </p>
</template>
```
<!-- prettier-ignore-end -->

The previous example renders the following HTML.

<!-- prettier-ignore-start -->
```html
<a href="tel:4255550155">(425) 555-0155</a>
<a href="tel:14255550155">(425) 555-0155</a>
```
<!-- prettier-ignore-end -->

Here's how to prevent the US/Canada formatting and display the number with a `+` prefix,
even when your locale is set to one of these locales.

<!-- prettier-ignore-start -->
```html
<template>
    <p>
        <lightning-formatted-phone value="+14255550155">
        </lightning-formatted-phone>
    </p>
</template>
```
<!-- prettier-ignore-end -->

The previous example renders this HTML.

<!-- prettier-ignore-start -->
```html
<a href="tel:+14255550155">+14255550155</a>
```
<!-- prettier-ignore-end -->

To display the phone number in plain text without a hyperlink, include the
`disabled` attribute. Disabling the phone number also prevents setting focus on the phone number when you use the Tab key.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-phone
        value="18005551212"
        disabled
    ></lightning-formatted-phone>
</template>
```
<!-- prettier-ignore-end -->

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-formatted-phone`, see the following components in the LWC Recipes repo.

- `c-contact-tile`
- `c-event-bubbling`

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedPhone" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=df4496646f139421a4c7f0def7d0461a96d28d9fbd328915172f3de94b9c0da7 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedRichText/lightning-formatted-rich-text.md -->


# Formatted Rich Text

**`lightning-formatted-rich-text`**

Displays rich text that's formatted with allowed tags and attributes. Other tags and attributes are removed and only their text content is displayed.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedRichText" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-rich-text` component renders a read-only representation of
rich text. Rich text refers to text that includes HTML tags for formatting, such as
`<strong>` for bold text or `<u>` for underlined text. You can pass in rich text to this component by using the `lightning-input-rich-text` component or
programmatically in JavaScript.

By default, the component creates links automatically for linkable text and email addresses.
For example, if the input is "Go to salesforce.com", `lightning-formatted-rich-text` creates a link so the output is "Go to [salesforce.com](https://www.salesforce.com/)".
Email addresses use the `mailto:` protocol.
To show links and email addresses in plain text, specify the `disable-linkify` attribute.

This example creates a rich text editor that's wired up to a
`lightning-formatted-rich-text` component. The component sets the rich text content during
initialization.

<!-- prettier-ignore-start -->
```html
<template>
    <!-- Rich text editor and formatted output -->
    <lightning-input-rich-text
        value={richtext}
        onchange={handleChange}
    ></lightning-input-rich-text>
    <lightning-formatted-rich-text
        value={richtext}
    ></lightning-formatted-rich-text>
</template>
```
<!-- prettier-ignore-end -->

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  richtext = "<h2>Default <s>Value</s></h2>";

  handleChange(e) {
    this.richtext = e.detail.value;
  }
}
```

To use double quotes in your value definitions, escape them by using the `\`
character.

```javascript
import { LightningElement } from 'lwc';
export default class MyComponentName extends LightningElement {
    richtext = "<h2 style=\"text-align: center\">Default <s>Value</s></h2>";

    ...
}
```

To pass in HTML tags in your component markup, escape the tags like this.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-rich-text value="&lt;h1>TEST&lt;/h1>">
    </lightning-formatted-rich-text>
</template>
```
<!-- prettier-ignore-end -->

## Supported HTML Tags and attributes

The component sanitizes HTML tags passed to the `value` attribute to prevent
XSS vulnerabilities. It also makes sure that the formatted output is valid HTML.
For example, if you have mismatched tags like `<div>My Title</h1>`, the
component returns `<div>My Title</div>`.

If you set unsupported tags via JavaScript, the component removes those tags and preserves the text content.
The supported HTML tags are: `a`, `abbr`, `acronym`, `address`, `br`, `big`, `blockquote`, `caption`,
`cite`, `code`, `col`, `colgroup`, `del`, `div`, `dl`, `dd`, `dt`, `em`,
`font`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `hr`, `img`, `ins`, `kbd`,
`li`, `ol`, `mark`, `p`, `param`, `pre`, `q`, `s`, `samp`, `small`, `span`,
`strong`, `sub`, `sup`, `table`, `tbody`, `td`, `tfoot`, `th`, `thead`, `tr`,
`tt`, `u`, `ul`, `var`, `strike`.

Supported HTML attributes include: `accept`, `action`, `align`, `alt`,
`autocomplete`, `background`, `bgcolor`, `border`, `cellpadding`,
`cellspacing`, `checked`, `cite`, `class`, `clear`, `color`, `cols`,
`colspan`, `coords`, `data-fileid`, `datetime`, `default`, `dir`, `disabled`,
`download`, `enctype`, `face`, `for`, `headers`, `height`, `hidden`, `high`,
`href`, `hreflang`, `id`, `ismap`, `label`, `lang`, `list`, `loop`, `low`,
`max`, `maxlength`, `media`, `method`, `min`, `multiple`, `name`, `noshade`,
`novalidate`, `nowrap`, `open`, `optimum`, `pattern`, `placeholder`, `poster`,
`preload`, `pubdate`, `radiogroup`, `readonly`, `rel`, `required`, `rev`,
`reversed`, `rows`, `rowspan`, `spellcheck`, `scope`, `selected`, `shape`,
`size`, `span`, `srclang`, `start`, `src`, `step`, `style`, `summary`,
`tabindex`, `target`, `title`, `type`, `usemap`, `valign`, `value`, `width`,
`xmlns`.

The HTML tags `b` and `i` aren't supported. This component converts the `b` tags to `strong` and `i` tags to `em` for screen reader accessibility. Other unsupported tags and attributes are removed, and only their text content is displayed.

We recommend that you use the `h1` to `h6` elements for headings and use `mark` to highlight text. For more information, see the [W3C recommendations](https://www.w3.org/TR/html52/textlevel-semantics.html).

## Supported Protocols

`lightning-formatted-rich-text` supports these protocols.

- ftp
- ftps
- http
- https
- mailto
- tel
- callto
- cid
- xmpp
- ciscotel
- navision

URLs such as `www.salesforce.com` or `salesforce.com` are also shown as links. All links, including those links that don't include a protocol, specifies the anchor tag with a target value of `_blank`.
To use links with other target values, use [lightning-formatted-url](/docs/platform/lightning-component-reference/guide/lightning-formatted-url.html) instead.

Encode parenthesis characters for URL links. Use `%28` for the opening parenthesis `(` and `%29` for the closing parenthesis `(`. Parenthesis characters that aren't URL encoded break the URL link.

## Usage Considerations

Formatting of list items for ordered and unordered lists varies across browsers. In particular, indents and alignment styles applied to lists in rich text don't render the same in `lightning-formatted-rich-text` across all browsers. See [list-style-position on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-position).

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedRichText" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6c3d906ed1da11593664f6491faccea994450cd25fc0a27a7ccc8df0c5f095ea url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedText/lightning-formatted-text.md -->


# Formatted Text

**`lightning-formatted-text`**

Displays text, replaces newlines with line breaks, and linkifies if requested.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedText" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-text` component shows a read-only representation of
text, and can convert URLs and email addresses to links, or "linkify" them.
It also converts the `\r` and `\n` characters into `<br />` tags.

By default, URLs and email addresses show as plain text.
To show URLs and email addresses in a block of text as links, include
`linkify` on the `lightning-formatted-text` tag.

`linkify` wraps URLs and email addresses in anchor tags with
`target="_blank"`. If you don't specify the URL protocol in the text,
the link's `href` uses `https://` or `http://` to match the host domain's
protocol. For example, the component prefixes `www.example.com` with `https://`
if the host domain's protocol is `https://`. The `href` uses `mailto://`
for email addresses.

This example uses domain names without protocols in the text.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-text
        value="I like salesforce.com and trailhead.salesforce.com."
        linkify
    >
    </lightning-formatted-text>
</template>
```
<!-- prettier-ignore-end -->

The example renders like this.

<!-- prettier-ignore-start -->
```html
I like <a target="_blank" href="https://salesforce.com">salesforce.com</a> and
<a target="_blank" href="https://trailhead.salesforce.com"
    >trailhead.salesforce.com</a
>.
```
<!-- prettier-ignore-end -->

## Usage Considerations

`lightning-formatted-text` supports these protocols: `http`, `https`,
`ftp`, and `mailto`.

If you're working with hyperlinks and want to specify the `target` value, use
`lightning-formatted-url` instead. If you're working with email addresses only,
use `lightning-formatted-email`.

For rich text that uses tags beyond anchor tags, use
[`lightning-formatted-rich-text`](/docs/platform/lightning-component-reference/guide/lightning-formatted-rich-text.html) instead.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedText" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=d343fbf4bf178c239594d7e507c0038686e239544527ab8fb59eedea3a99134f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedTime/lightning-formatted-time.md -->


# Formatted Time

**`lightning-formatted-time`**

Displays a formatted time in user's locale format.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedTime" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-time` component shows a read-only representation of
time in the user's locale format. Use a valid ISO8601 formatted time string only.

An ISO8601 formatted time string matches one of these patterns.

- HH:mm
- HH:mm:ss
- HH:mm:ss.SSS

`HH` is the number of hours that have passed since midnight, `mm` is the
number of minutes that have passed since the start of the hour, `ss` is
the number of seconds since the start of the minute, and `SSS` is the number
of milliseconds since the start of the second. Time is always displayed in Universal Time (UTC).

`lightning-formatted-time` doesn't support offsets and it ignores them. For example, `14:30+05:00` is treated as `14:30`.

This example returns `10:12:30 PM`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-time value="22:12:30.999"> </lightning-formatted-time>
</template>
```
<!-- prettier-ignore-end -->

Salesforce uses the format HH:mm:ss.SSSZ for time fields. The time field is a
timestamp without the date included. Time values in Salesforce aren't
localized or associated with a time zone.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedTime" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0a4fbfe0d9f21eebf91e04ba475a78036b18bacda4d44785c6012a79c21a536b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/formattedUrl/lightning-formatted-url.md -->


# Formatted URL

**`lightning-formatted-url`**

Displays a URL as a hyperlink.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedUrl" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-formatted-url` component shows a URL by using an anchor `<a>` tag with an `href` attribute. The `value` you provide can be a relative or absolute URL.
An absolute URL uses a protocol like `http://`, `https://`, or `ftp://`, followed by the domain name and path.
The component renders the link by using the `http://` protocol by default.

URLs without a protocol use the host domain's protocol. For example, `www.example.com` is prefixed with `https://` if the host domain's protocol is `https://`.

To customize the text, provide a `label`. Otherwise, the component shows the URL that you pass into `value`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-url
        value="https://salesforce.com"
        label="Visit salesforce.com"
        target="_blank"
    ></lightning-formatted-url>
</template>
```
<!-- prettier-ignore-end -->

The rendered HTML looks like this.

<!-- prettier-ignore-start -->
```html
<a href="https://salesforce.com" target="_blank">Visit salesforce.com</a>
```
<!-- prettier-ignore-end -->

By default, clicking the link takes you to the URL in the same frame.

## Create Absolute URLs

To create an absolute URL, set the `value` attribute by using one of these patterns.

- www.salesforce.com
- http://www.salesforce.com
- https://developer.salesforce.com/docs/component-library

`http://` is inserted before a value like `www.salesforce.com` or `my/path`, which doesn’t begin with a slash. This creates an absolute URL like `http://www.salesforce.com` or `http://my/path`. This behavior is contrary to that of the anchor `<a>` tag where omitting the leading slash results in a relative path from the current directory.

This example displays an absolute URL and uses the provided `value` as the `href` value for the `<a>` tag.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-formatted-url value="https://www.salesforce.com">
    </lightning-formatted-url>
</template>
```
<!-- prettier-ignore-end -->

If you don't provide a protocol, the component appends the `http://` prefix to the URL by default. The rendered HTML of the previous example
uses `https` because it specifies the protocol.

<!-- prettier-ignore-start -->
```html
<a href="https://www.salesforce.com">https://www.salesforce.com</a>
```
<!-- prettier-ignore-end -->

URLs without a protocol use the host domain's protocol. For example, the component prefixes `www.example.com` with `https://` if the host domain's protocol is `https://`.

## Create Relative URLs

To create a relative URL, set the `value` attribute by using one of these patterns.

- index.html
- /my/path
- ./my/path
- ../my/path

If the `value` includes a leading slash in the path like `/my/path`, the resulting URL is root-relative and uses the domain of the page as the prefix. For example, if the current page is located on `example.com/directory/`, the resulting URL is `http://example.com/my/path`. To create a URL from the current directory, start the URL with a dot-slash like `./my/path`. To create a URL to the parent directory of the current page, start the URL with dot-dot-slash like `../my/path`.

A relative URL navigates to a path within the current site you're on.

<!-- prettier-ignore-start -->
```html
<template>
    <!-- Resolves to http://current-domain/my/path -->
    <lightning-formatted-url value="/my/path"> </lightning-formatted-url>
</template>
```
<!-- prettier-ignore-end -->

The rendered HTML looks like this. Clicking the URL takes you to `http://current-domain/my/path`.

<!-- prettier-ignore-start -->
```html
<a href="/my/path">/my/path</a>
```
<!-- prettier-ignore-end -->

## Specify a Target

Use the `target` attribute to change where the link should open. If you don't
provide a target, `lightning-formatted-url` uses the `_self` target value.

Supported `target` values are:

- `_blank`: Opens the link in a new window or tab. In a mobile hybrid app like the Salesforce mobile app, the link is handled similar to `_self` and opens inside the app if possible.
- `_self`: Opens the link in the same frame as it was clicked. This is the default behavior. In Lightning Experience and Experience Builder sites, the link is opened in a new tab if it can't be opened inside the app. We recommend that you use [`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html) to create links within Lightning Experience and Experience Builder sites.
- `_parent`: Opens the link in the parent frame. If there's no parent, this is similar to `_self`.
- `_top`: Opens the link into the top-level browsing context. If there's no parent, this is similar to `_self`.

For more information about link targets, see the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a).

## Usage Considerations

We recommend using absolute URLs where possible as they can prevent duplicate content to improve search engine optimization.
Having your internal links as relative URLs can also expose the structure of your website.

`lightning-formatted-url` does not support email addresses or phone numbers. To create an email address with the `mailto:` protocol, use `lightning-formatted-email`.
To create a phone number with the `tel:` protocol, use `lightning-formatted-phone`.

The framework handles navigation for you, so there's no need to provide `onclick`
behavior with `lightning-formatted-url`.

To create a link with a
custom `onclick` event handler, use the HTML anchor tag `<a>` instead. To create a URL that navigates to another page in Salesforce, use
[`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html).

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="formattedUrl" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=e1243427a963a4891378228d143380cb15c85c3228b362e7157108d1ca5aaec7 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/get-started.md -->

# Get Started with Lightning Base Components

The Component Reference documents the full set of base components for both the Lightning Web Components (LWC) and Aura programming models. Base components are the UI building blocks of Lightning Experience, the Salesforce mobile app, Experience Builder sites, and more.

## Base Components and SLDS

Base components implement the Salesforce Lightning Design System (SLDS) component [blueprints](https://v1.lightningdesignsystem.com/components/overview/). They also provide logic to help you speed up UI development and work with your Salesforce data easily, so you can focus on your business logic and processes instead.

Base components automatically use [SLDS 1](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://www.lightningdesignsystem.com/) depending on which theme is enabled in your org.

![Base components are building blocks for your custom Salesforce UI](https://developer.salesforce.com/docs/media/base_components_overview.png '{"class": "image-md"}')

Using the base components is the best way to make sure your Salesforce UIs are accessible and follow SLDS best practices. The Component Reference can help you customize and style each base component using the component’s built-in HTML attributes, methods, and events.

## What's in the Component Reference?

The Component Reference contains these reference docs.

- [Components](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/components.md) - for the LWC versions of base components
- [Utility Modules](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/utilities.md) - for functionality and services to build integrated apps in LWC
- [API Modules](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/api.md) - for access to Salesforce data, platform features, and specialized APIs with wire adapters and functions in LWC
- [Legacy Components](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/components/legacy.md) - for the Aura versions of base components, and associated Aura events and interfaces

We recommend that you use LWC for new development. Learn more about developing with LWC in the [_Lightning Web Components Developer Guide_](https://developer.salesforce.com/docs/platform/lwc/).

<!-- document id=2c909d47f3d52ae6370e0529d7f7c344832c67df778852782e0fef99e9b9d45b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/clients/hasEventContext/clients-has-event-context.md -->

# Has Event Context

**`clients:hasEventContext`**

Provides context for event information. Use this interface to interact with the mail clients.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

To provide a component with an event's date or location, implement the `clients:hasEventContext` interface. This interface is used with `clients:availableForMailAppAppPage` to make a component available in Lightning for Outlook or Lightning for Gmail. For example, to provide an event's date:

```javascript
dates: {
        "start": value (String),
        "end": value (String),
}
```

To ensure that custom components appear correctly in Lightning for Outlook or Lightning for Gmail, enable them to adjust to variable widths.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_email_app_pane.htm).


:::::

:::::tab
## Attributes

| Name       | Description                                                                      | Type   | Default | Required |
| ---------- | -------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `dates`    | Read-only. An object representing the item context pertinent to the appointment. | object |         |          |
| `location` | Read-only. The location of the current event.                                    | string |         |          |

:::::

::::::

<!-- document id=851422cc4e6be5ccc62654abeb19bfa8776eb4f4f9faa1f5501b1d64aa741f12 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/clients/hasItemContext/clients-has-item-context.md -->

# Has Item Context

**`clients:hasItemContext`**

Provides the context information for emails and events. Use this interface to interact with the mail clients.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

To allow a component to access email or calendar events, implement the `clients:hasItemContext` interface. This interface is used with `clients:availableForMailAppAppPage` to make a component available in Lightning for Outlook or Lightning for Gmail.

The interface has attributes that enable your component to implement record- or context-specific logic.

The source attribute indicates whether the source is an email or appointment. Possible values include `email` and `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 the following elements.

```javascript
{
    to: [ { name: ***nameString***, email: emailString }, ... ],
    cc: [ ... ],
    from: [ { name: senderName, email: senderEmail } ],
}
```

When the source attribute is set to `event`, the `people` object contains the following elements.

```javascript
{
    requiredAttendees: [ { name: ***attendeenameString***, email: emailString }, ... ],
    optionalAttendees: [ { name: optattendeenameString, email: emailString }, ... ],
    organizer: [ { name: organizerName, email: senderEmail } ],
}
```

To ensure that custom components appear correctly in Lightning for Outlook or Lightning for Gmail, enable them to adjust to variable widths.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_email_app_pane.htm).


:::::

:::::tab
## Attributes

| Name          | Description                                                                                         | Type   | Default | Required |
| ------------- | --------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `messageBody` | Read-only. The body of the current item in plain text                                               | string |         |          |
| `mode`        | Read-only. An enum indicating the mode of the item. Possible values are 'view', 'edit'              | string |         |          |
| `people`      | Read-only. An object representing the contacts on the current item.                                 | object |         |          |
| `source`      | Read-only. An enum indicating where the source is coming from. Possible values are 'email', 'event' | string |         |          |
| `subject`     | Read-only. The subject of the current item.                                                         | string |         |          |

:::::

::::::

<!-- document id=2d28ec303d87c64392bdbfa133a647b80ed5f6f731fb6f7ad17f7ecc6064b843 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/hasPageReference/aura-has-page-reference.md -->

# Has Page Reference

**`lightning:hasPageReference`**

Enables a component to take a `pageReference` object as an attribute.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:hasPageReference` interface to indicate that a Lightning component can accept a `pageReference` object. This capability comes by default when implementing `lightning:isUrlAddressable`. This interface isn't supported for components that are embedded in a flexipage.

Implementing `lightning:hasPageReference` provides access to the `pageReference` attribute. When populated, the `pageReference` attribute describes the current page, including its type and attributes. Only top-level page components can receive the `pageReference` attribute. See [pageReference types](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation_page_definitions.htm) in the Lightning Aura Components Developer Guide.

By using `lightning:navigation`, you can jump to one of these pages or components, without needing to craft a URL by hand. Note that the `pageReference` attribute is deeply frozen and cannot be modified. See the [`lightning:isUrlAddressable` documentation](/docs/platform/lightning-component-reference/guide/aura-is-url-addressable.html) for examples on using and changing the `pageReference`.

To update a parameter on the `pageReference` while staying on the current page, use a change handler to listen for page state updates. Updating a parameter also updates the URL so that some state or data that the page holds can be retained, even when the page refreshes.

When the target of a navigation action maps to the same component, the routing container might simply update the `pageReference` attribute value instead of recreating the component. In this scenario, a change handler ensures that your component reacts correctly.

The `pageReference` attribute can be populated only for the following page types:

- standard\_\_component
- standard\_\_navItemPage (for Lightning component tab only)
- standard\_\_recordPage
- standard\_\_objectPage

## See Also

[Navigate to a Record Create Page with Default Field Values](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation_dfv.htm)


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=7a8ae225217b89e6a61ef01e4a70f6bcd30f9fa55e25e77b64c2ff1c1a937ca9 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/hasRecordId/force-has-record-id.md -->

# Has Record Id

**`force:hasRecordId`**

Indicates that a component takes a record (SObject) as an attribute.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Add the `force:hasRecordId` interface to an Aura component to enable the component to be assigned the ID of the current record. The current record ID is useful if the component is used on a Lightning record page, as an object-specific custom action or action override in Lightning Experience or the Salesforce mobile app, and so on. This interface has no effect except when used within Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.

This interface is a marker interface. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

The `force:hasRecordId` interface does two things to a component that implements it.

- It adds an attribute named recordId to your component. This attribute is of type String, and its value is an 18-character Salesforce record ID, for example: 001xx000003DGSWAA4. If you added it yourself, the attribute definition would look like the following markup:

```xml
<aura:attribute name="recordId" type="String" />
```

**note:** If your component implements `force:hasRecordId`, you don’t need to add a `recordId` attribute to the component yourself. If you do add it, don’t change the access level or type of the attribute or the component will cause a runtime error.

- When your component is invoked in a record context in Lightning Experience or the Salesforce mobile app, the `recordId` is set to the ID of the record being viewed.

The `recordId` attribute is set only when you place or invoke the component in an explicit record context. For example, when you place the component directly on a record page layout, or invoke it as an object-specific action from a record page or object home. In all other cases, such as when you invoke the component as a global action, or create the component programmatically inside another component, `recordId` isn’t set, and your component shouldn’t depend on it. These unsupported contexts include a few contexts that might seem like they should have access to the current record. Examples of these other contexts include the following:

- Invoking the component from a global action (even when you’re on a record page)
- Invoking the component from header or footer navigation in an Experience Builder site (even if the page shows a record)

`force:hasRecordId` and `force:hasSObjectName` are unsupported in these contexts. While the marker interfaces still add the relevant attribute to the component, accessing either attribute generally returns `null` or `undefined`.

## Example

This example shows the markup required to add the `force:hasRecordId` interface to an Aura component.

```xml
<aura:component implements="force:lightningQuickAction,force:hasRecordId">

    <!-- ... -->

</aura:component>
```

The component’s controller can access the ID of the current record from the `recordId` attribute, using `component.get("v.recordId")`. The `recordId` attribute is automatically added to the component by the `force:hasRecordId` interface.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_intro.htm).


:::::

:::::tab
## Attributes

| Name       | Description   | Type   | Default | Required |
| ---------- | ------------- | ------ | ------- | -------- |
| `recordId` | The record ID | string |         |          |

:::::

::::::

<!-- document id=a3b887605a4f15fd81b9a10424f0b01923a124c991ccb50012a6251042061ba5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/hasSObjectName/force-has-sobject-name.md -->

# Has SObject Name

**`force:hasSObjectName`**

Indicates that a component has the SObject name attribute.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Add the `force:hasSObjectName` interface to an Aura component to enable the component to be assigned the API name of current record’s sObject type. The sObject name is useful if the component can be used with records of different sObject types, and needs to adapt to the specific type of the current record. This interface has no effect except when used within Lightning Experience, the Salesforce mobile app, and sites based on Experience Builder templates.

This interface is a marker interface. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

This interface adds an attribute named `sObjectName` to your component. This attribute is of type String, and its value is the API name of an object, such as `Account` or `myNamespace__myObject__c`. For example:

```xml
<aura:attribute name="sObjectName" type="String" />
```

**note:** If your component implements `force:hasSObjectName`, you don’t need to add an `sObjectName` attribute to the component yourself. If you do add it, don’t change the access level or type of the attribute or the component will cause a runtime error.

**Important:** The `sObjectName` attribute is set only when you place or invoke the component in an explicit record context. For example, when you place the component directly on a record page layout, or invoke it as an object-specific action from a record page or object home. In all other cases, such as when you invoke the component as a global action, or create the component programmatically inside another component, `sObjectName` isn’t set, and your component shouldn’t depend on it. These unsupported contexts include a few contexts that might seem like they should have access to the current record. Examples of these other contexts include the following:

- Invoking the component from a global action (even when you’re on a record page)
- Invoking the component from header or footer navigation in an Experience Builder site (even if the page shows a record)

`force:hasRecordId` and `force:hasSObjectName` are unsupported in these contexts. While the marker interfaces still add the relevant attribute to the component, accessing either attribute generally returns `null` or `undefined`.

## Example

This example shows the markup required to add the `force:hasSObjectName` interface to an Aura component.

```xml
<aura:component implements="force:lightningQuickAction,force:hasSObjectName">

    <!-- ... -->

</aura:component>
```

The component’s controller can access the ID of the current record from the `recordId` attribute, using `component.get("v.sObjectName")`. The `recordId` attribute is automatically added to the component by the `force:hasSObjectName` interface.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_intro.htm).


:::::

:::::tab
## Attributes

| Name          | Description                                                                                                                                    | Type   | Default | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `sObjectName` | The API name of the custom or standard object, such as "Account", "Case", "Contact", "Lead", "Opportunity", or "namespace\_\_objectName\_\_c". | string |         |          |

:::::

::::::

<!-- document id=4a08381c4c75ae49798574d1662a82ae9079cae66eb130bcee644ed3516a2498 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/helptext/lightning-helptext.md -->


# Helptext

**`lightning-helptext`**

An icon with a text popover used for tooltips.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="helptext" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-helptext` component displays an icon with a popover containing a
small amount of text describing an element on screen. The popover is displayed
when you hover or focus on the icon that's attached to it. On iOS devices, the
helptext popover opens when you tap on the icon and closes with a second tap
on the popover or the icon.

This component is similar to a tooltip and is useful to display field-level help text, for example. HTML markup is not supported in the tooltip content.

This example creates an icon with a tooltip.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-helptext content="Your email address will be your login name">
    </lightning-helptext>
</template>
```
<!-- prettier-ignore-end -->

The popover is anchored on the lower left of the icon and shown above the icon if space is available. It automatically adjusts its position according to the viewport.

## Design

`lightning-helptext` implements the tooltip blueprint in the Salesforce Lightning Design System (SLDS). The tooltip adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Tooltip](https://v1.lightningdesignsystem.com/components/tooltips/)                                                                  | [Tooltip](https://www.lightningdesignsystem.com/components/tooltips/)                                           |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of icons, variants, and utility classes to customize your tooltip styles.

### Icons

By default, the tooltip uses the `utility:info` icon but you can specify a
different icon with the `icon-name` attribute.

The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) offers nearly 200 utility icons that can be used
in `lightning-helptext`. Although SLDS provides several
categories of icons, only the utility category can be used in
`lightning-helptext`.

When applying SLDS classes or icons, check that they are
available in the SLDS release tied to your org.
The SLDS site shows the latest SLDS
resources, and these become available only when the new release
is available in your org.

### Variants

Use the `icon-variant` attribute to change the style of the icon with the following values.

- `bare` is the default variant and doesn't need to be specified
- `error` adds a red fill for the icon to call out a user- or system-related error
- `inverse` adds a white fill for the icon, useful for dark backgrounds
- `warning` adds a yellow fill for the icon to advise caution

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin to the left of the tooltip icon using the `slds-m-left_xx-small` class.

<!-- prettier-ignore-start -->
```html
some text that appears before the tooltip icon here
<lightning-helptext
    icon-name="utility:salesforce1"
    content="tooltip content here"
    class="slds-m-left_xx-small"
></lightning-helptext>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-helptext` contains the same customizable elements as `lightning-button-icon` for the button icon. See the [`lightning-button-icon` documentation](/docs/platform/lightning-component-reference/guide/lightning-button-icon.html).

## Accessibility

`lightning-helptext` contains a focusable button element. To ensure that users who aren't using a mouse can access the tooltip, `lightning-helptext` shows the tooltip on hover or on keyboard focus when you press Enter or the spacebar. To dismiss the tooltip when it displays on hover, mouse away from it. To dismiss the tooltip when it has focus, press Escape.

The button renders with an `aria-describedby` attribute set to an ID that matches the element containing the tooltip text. The `aria-describedby` attribute enables assistive technology to announce the tooltip content.

The button renders assistive text that contains "Help" by default. To provide your own description, use the `alternative-text` attribute.
The text should describe the function of the icon, for example, "Show help text", instead of repeating the `content` description.
Providing the purpose of the icon in the description improves usability and removes repetition of content for users of assistive technology.

The component renders the tooltip using `role="tooltip"`. When you remove focus from the button or mouse away from it, the tooltip is hidden. To provide important information, display descriptive text in the component itself instead of using `lightning-helptext`.

The `content` attribute doesn't have a character limit. However, when this component is used for field-level help text on a Salesforce record, the character limit is 510. For more information, see [Define Field-Level Help](https://help.salesforce.com/s/articleView?id=platform.customhelp_defining_field_level_help.htm) in Salesforce Help.


:::::

:::::tab
::component-specification{component="helptext" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=3e591b8d306d3c7b56fbbb3e4ceb3d628d46029678482d81e716527957e056d4 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/homeTemplate/aura-home-template.md -->

# Home Template

**`lightning:homeTemplate`**

Enables a component to be used as a flexipage page template for the HOME_PAGE page type.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:homeTemplate` interface to enable your component to be used as a custom Lightning page template for the Lightning Experience Home page. This interface has no effect except when used within Lightning Experience.

Components that implement this interface appear in the Custom Templates section of the Lightning App Builder new page wizard for Home pages.

Each template component should implement only one template interface. Template components shouldn’t implement any other type of interface, such as `flexipage:availableForAllPageTypes` or `force:hasRecordId`. A template component can’t multi-task as a regular Lightning component. It’s either a template, or it’s not.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_template_component.htm).


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=cbe64ac01c939e3f227d70c734e47e64acb49e4c59eae937704512f699d36b7e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/icon/lightning-icon.md -->


# Icon

**`lightning-icon`**

Represents a visual element that provides context and enhances usability.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="icon" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-icon` component is a visual element that provides context and enhances
usability. `lightning-icon` provides you with icons in the Salesforce Lightning Design System (SLDS).
Use icons inside the body of another component or on their own.
You can specify an icon from the Lightning Design System by using the `icon-name` attribute.

Here’s an example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-icon
        icon-name="action:approval"
        size="large"
        alternative-text="Indicates approval"
    >
    </lightning-icon>
</template>
```
<!-- prettier-ignore-end -->

Alternatively, you can provide a custom icon by using the `src` attribute. See the [Use SVG Icons](#use-svg-icons) section.

## Design

`lightning-icon` implements the icons blueprint in the Salesforce Lightning Design System (SLDS). The icons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use. Visit [icons](https://v1.lightningdesignsystem.com/icons) to view the available icons.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Icons](https://v1.lightningdesignsystem.com/components/icons/)                                                                       | [Icons](https://www.lightningdesignsystem.com/components/icons/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Use SVG Icons

Use the `src` attribute to specify the path of the resource for your
icon. When this attribute is present, `lightning-icon` attempts to load an
icon from the provided resource.

Define a static resource in your org and upload your icon's SVG resource
to it. The SVG code must include a `<g>` element with an `id` value that you can reference.

For example, your static resource is named `mySVG_icon` and it contains
this `google.svg` content.

<!-- prettier-ignore-start -->
```html
<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
    &lt;title>Google icon&lt;/title>
    <g id="google">
        <path
            d="M12.24 10.285V14.4h6.806c-.275 1.765-2.056 5.174-6.806 5.174-4.095 0-7.439-3.389-7.439-7.574s3.345-7.574 7.439-7.574c2.33 0 3.891.989 4.785 1.849l3.254-3.138C18.189 1.186 15.479 0 12.24 0c-6.635 0-12 5.365-12 12s5.365 12 12 12c6.926 0 11.52-4.869 11.52-11.726 0-.788-.085-1.39-.189-1.989H12.24z"
        ></path>
    </g>
</svg>
```
<!-- prettier-ignore-end -->

Import the SVG resource into your component, and set a variable to the static resource URL plus the `<g>` ID.

```javascript
// myComponent.js
import { LightningElement } from "lwc";
import mySVG_icon from "@salesforce/resourceUrl/mySVG_icon";

export default class myComponent extends LightningElement {
  googleIcon = mySVG_icon + "#google";
}
```

Pass the static resource variable in the `src` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-icon src={googleIcon}></lightning-icon>
</template>
```
<!-- prettier-ignore-end -->

For more information about static resources and using SVG, see [Access Static Resources](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources) and [Use SVG Resources](https://developer.salesforce.com/docs/platform/lwc/guide/use-svg-in-component) in the _Lightning Web Components Developer Guide_.

### Override the Icon Fill Color of Your Imported Icons

Note that icons you import have a default fill attribute value `#fff`, which
you can override in your svg sprite directly. For example, change the color to
a shade of green by inserting `fill=#648079` in the `<svg>` element.

Alternatively, use CSS custom properties to change the fill color on your imported icon. See the non-utility icon example in the **Customize Component Styling** section.

## Component Styling

Use a combination of the `variant`, `size`, and `class` attributes to customize the icon styling.

When applying SLDS classes or icons, check that they’re
available in the SLDS release tied to your org. The latest
SLDS resources become available only when the new release
is available in your org.

### Sizes

Adjust icon sizes by using the `size` attribute with one of these values.

- `medium` is the default size, which creates a 32px by 32px icon
- `small` creates a 24px by 24px icon
- `x-small` creates a 16px by 16px icon
- `xx-small` creates a 14px by 14px icon
- `large` creates a 48px by 48px icon

### Variants

Variants are supported only for the utility icons. To change the appearance of a [utility icon](https://lightningdesignsystem.com/icons/#utility), use the `variant` attribute with one of these values.

- `inverse` adds a white fill to a utility icon, useful for dark backgrounds
- `error` adds a red fill to a utility icon to call out a user- or system-related error
- `success` adds a green fill to a utility icon to represent a successful operation
- `warning` adds a yellow fill to a utility icon to advise caution

This example uses the `error` variant to add a red fill to the error utility icon.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-icon icon-name="utility:error" variant="error"> </lightning-icon>
</template>
```
<!-- prettier-ignore-end -->

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.
For example, you can set `class="slds-m-vertical_large"` or other [margin](https://lightningdesignsystem.com/utilities/margin/) classes to add spacing around the icon.

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

Use the `alternative-text` attribute to describe the icon for assistive devices.
The description indicates what happens when you click the button, for example 'Upload
File', not what the icon looks like, 'Paperclip'.

Sometimes an icon is decorative and doesn’t need a description. But icons can
switch between being decorative or informational based on the screen size. If
you choose not to include an `alternative-text` description, check smaller
screens and windows to make sure that the icon is decorative on all formats.

## Usage Considerations

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.


:::::

:::::tab
::component-specification{component="icon" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=472c216e532d449cc059c751cebfda24f1355b80308b139887cb484b8ae6aca7 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/illustration/lightning-illustration.md -->

# Illustration (Beta)

**`lightning-illustration`**

Displays a Salesforce Lightning Design System illustration.

**For Use In**

Lightning Experience, Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

**note:** `lightning-illustration` 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.

The `lightning-illustration` component displays Salesforce Lightning Design System (SLDS) scalable vector design (SVG) illustrations to communicate errors, success, and other statuses. This component provides access to a set of standardized SVG illustrations for use in the Salesforce platform.

The `lightning-illustration` component simplifies development and maintenance while ensuring a high-quality visual experience for your custom Lightning pages that’s consistent with the Salesforce platform.

| Feature                            | Developer Benefit                                                                                                                                                             |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Automatic Design System Compliance | Ensures uniform illustrations, eliminating manual checks for adherence to design guidelines.                                                                                  |
| Simplified Updates                 | Reduces the effort of updating illustrations by enabling centralized management with the component. A change to the illustration propagates everywhere you use the component. |
| Dynamic Theme Support              | Illustrations dynamically adapt to themes, supporting light and dark mode and themes based on SLDS 1 and SLDS 2.                                                              |

## Design

`lightning-illustration` implements the [Illustration blueprint](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations) in the Salesforce Lightning Design System (SLDS). The icons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use. Consult the SLDS site for images of the available illustrations.

|                | SLDS 1                                                                        | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Illustration](https://v1.lightningdesignsystem.com/components/illustration/) | [Illustration](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations)                          |
| **For Use In** | Lightning Experience, Experience Builder sites                                | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Compare to `lightning-empty-state`

Both the `lightning-illustration` and `lightning-empty-state` components currently support only Salesforce SVG illustrations for depicting empty state conditions. The `lightning-illustration` component doesn’t currently support other standard illustrations or custom illustrations. The `lightning-illustration` component currently supports the same illustrations as `lightning-empty-state`.

To display an illustration that clarifies why a page or panel has no content, and provides text and call-to-action content, use the `lightning-empty-state` component.

Use `lightning-illustration` for similar use cases as [`lightning-empty-state`](/docs/platform/lightning-component-reference/guide/lightning-empty-state.html) where you don’t require the supporting text or call-to-action content.

## Usage

The component is useful for displaying an illustration only, without any visible text. It supports only two attributes: `illustration-name` and `alternative-text`. The `illustration-name` is required.

Here’s a basic example.

<!-- prettier-ignore -->
```html
<lightning-illustration 
  illustration-name="error:unrecoverable" 
  alternative-text="Error occurred">
</lightning-illustration>
```

## Specify Illustration Names

The `lightning-illustration` component detects the SLDS version of the theme that's enabled in Salesforce and presents different illustrations for SLDS 2 and SLDS 1 themes. In SLDS 2 themes, the illustrations also adapt automatically for dark mode and the theme and branding that’s in effect in the org.

`illustration-name` accepts a name in the pattern `set:symbol` (which you can think of as `category:name`) to retrieve an illustration from SLDS. For example, valid names include `cart:noitems` and `error:connectionissue`.

The `lightning-illustration` component displays a unique SVG image for each illustration that you specify with the `illustration-name` attribute.

### Illustrations for SLDS 2 and SLDS 1

For SLDS 2 themes, `lightning-illustration` presents new Salesforce Cosmos illustrations. For SLDS 1 themes, the component uses a smaller set of existing SLDS 1 illustrations from Lightning Experience.

Each of the SLDS 1 illustrations maps to one of the same `category:name` illustration names. The mapping enables `lightning-illustration` to work in SLDS 1 themes. However, some SLDS 1 illustrations map to multiple illustration names. This reuse of illustrations means that SLDS 1 themes don't have a unique SVG image for each illustration name.

For example, if your component encounters an error that isn't fixable at the moment, specify `illustration-name="error:unrecoverable"`.

In an SLDS 2 theme, the component displays an illustration of a rain cloud for `illustration-name="error:unrecoverable"`.

![Rain cloud illustration for error:unrecoverable ](https://developer.salesforce.com/media/raincloud.png)

In an SLDS 1 theme, the same `illustration-name="error:unrecoverable"` attribute causes the component to display an illustration of a closed walking trail.

![Closed trail illustration for error:unrecoverable](https://developer.salesforce.com/media/nowalkthrough.png)

The component automatically presents the illustration that's appropriate for the theme.

If you pass an invalid illustration name, the component falls back to the "gone fishing" illustration in SLDS 1 themes. In SLDS 2 themes, there's a console error.

![Gone fishing illustration used as a fallback](https://developer.salesforce.com/media/gonefishing.png)

### Map of Illustration Names to Illustrations for SLDS 2 and SLDS 1

These illustration names in `category:name` format are available. Visit the [Illustration component design](https://www.lightningdesignsystem.com/2e1ef8501/p/759a28-illustrations) to see the current images. This table describes the images that map to the illustration names to aid you in recalling the images. You can avoid looking them up in the design each time.

| Illustration Name       | SLDS 2                                       | SLDS 1                                     |
| :---------------------- | :------------------------------------------- | :----------------------------------------- |
| `access:deleted`        | A cocoon or chrysalis                        | An open empty treasure chest               |
| `access:limit`          | An extinguished candle                       | A closed treasure chest                    |
| `access:request`        | A locked padlock                             | A closed treasure chest                    |
| `cart:noitems`          | An empty shopping bag                        | Gone fishing \- Astro and Codey in a canoe |
| `error:appconnection`   | A stylized balloon                           | Floating hot air balloons                  |
| `error:connectionissue` | An unplugged electrical plug                 | Floating hot air balloons                  |
| `error:recoverable`     | A wilting plant                              | A rainy campsite                           |
| `error:unrecoverable`   | A rain cloud                                 | A walking path that's closed               |
| `maintenance:planned`   | A healthy plant                              | A hand under a landscape                   |
| `maintenance:unplanned` | A boomerang                                  | A hand under a landscape                   |
| `noresults:filter`      | Three plants, the tallest bending to the sun | Binoculars with a cracked lens             |
| `noresults:search`      | A telescope pointing away from the sky       | Binoculars with a cracked lens             |
| `noresults:unknown`     | Mountains and clouds                         | Binoculars with a cracked lens             |
| `success:assigned`      | Umbrella planted on a beach                  | Gone fishing \- Astro and Codey in a canoe |
| `success:new`           | A zen sand garden                            | Gone fishing \- Astro and Codey in a canoe |
| `success:selfassigned`  | A flag planted on a hill                     | Gone fishing \- Astro and Codey in a canoe |

## Size and Spacing

`lightning-illustration` automatically sizes to the full width of the container that it’s in. You can't set the size directly in the component. To control the size, specify the container size. For example, wrap the component in a `div` and add a style to set the maximum width.

<!-- prettier-ignore -->
```html
<div style="max-width: 400px;">
  <lightning-illustration
    illustration-name="maintenance:planned"
    alternative-text="Scheduled maintenance"
  >
  </lightning-illustration>
</div>
```

## Usage Considerations

The `lightning-illustration` component is supported only on the Salesforce platform. It requires access to the SVG illustrations in a Salesforce org.

The component works in Experience Builder Sites, but can only display SLDS 1 illustrations. SLDS 2 isn't supported in Experience Cloud.

Illustrations can clarify states like no data, success, access issues, or maintenance. Use `lightning-illustration` for more general status messaging, not for displaying in containers if there’s no data to display. Use `lightning-empty-state` for containers without data.

Render the illustration conditionally. For example, render an error illustration only in an error state.

This component uses new Salesforce Cosmos illustrations to fit the SLDS 2 themes. Develop with the SLDS 2 version of the illustration in mind first, and then test the component with SLDS 1 themes.

Choose an illustration that’s closest in meaning for your use case and provide messages in adjacent text components.

Rely on the component to detect the theme and handle switching between illustrations for SLDS 2 and SLDS 1. You can avoid branching your code.

Avoid changing illustration colors or shapes with custom CSS. Use layout and spacing [utility classes](https://www.lightningdesignsystem.com/2e1ef8501/p/05098e-utility-classes).

Don’t embed text in the SVG.

## Accessibility

`lightning-illustration` has an `alternative-text` attribute for specifying text for assistive technologies. Use `alternative-text` if the illustration conveys meaningful information such as why no results appear. Use concise, purposeful text such as "No search results." Omit `alternative-text` if the illustration is purely decorative and the surrounding UI communicates the message.

The illustrations support SLDS standards for high color contrast across all themes.


:::::

:::::tab
::component-specification{component="illustration" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=7defaeeb1d6909c07d6ac10358be452ad91f8d2985df973ecc0934ccc611a160 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/industriesEducationPublicApi/lightning-industries-education-public-api.md -->

# Industries Education Public API

**`lightning/industriesEducationPublicApi`**

Updates Benefit Assignment records using the `lightning/industriesEducationPublicApi` module. The `lightning/industriesEducationPublicApi` module requires API version 60.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/industriesEducationPublicApi` module includes JavaScript APIs to create and update records.

To use the Industries Education Public API in your component, import the functions in your component's JavaScript file.

```javascript
import { postBenefitAssignment } from "lightning/industriesEducationPublicApi";
```

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-industries-education-postBenefitAssignment.html).

:::::

:::::tab
::component-specification{component="industriesEducationPublicApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f15fb1b0cad21cbdc2cd425ea8f82b4b669de071713c3360a209e9257f444bd9 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/input/lightning-input.md -->


# Input

**`lightning-input`**

Represents interactive controls that accept user input depending on the type attribute.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="input" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-input` component creates an HTML `<input>` element. This component
supports many input types:

- `text` (default)
- `checkbox`
- `checkbox-button`
- `color`
- `date`
- `datetime`/`datetime-local`
- `time`
- `email`
- `file`
- `number`
- `password`
- `range`
- `search`
- `tel`
- `toggle`
- `url`

There is no behavioral difference between the `datetime` and `datetime-local` types.

These HTML input types aren't supported.

- `button` - Use [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html) instead.
- `hidden` - Use [`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) instead.
- `image` - Use [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html) or an `<img>` tag instead.
- `radio`- Use [`lightning-radio-group`](/docs/platform/lightning-component-reference/guide/lightning-radio-group.html) instead.
- `reset` - Use [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html) instead.
- `submit` - Use [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html) instead.
- `week` - Use [`lightning-combobox`](/docs/platform/lightning-component-reference/guide/lightning-combobox.html) or `lightning-input` with the `number` type instead.
- `month` - Use [`lightning-combobox`](/docs/platform/lightning-component-reference/guide/lightning-combobox.html) or `lightning-input` with the `number` type instead.

The `week` and `month` types are browser-dependent and can cause issues with styling, accessibility, and general functionality in specific browsers.

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

These input types-`email`, `number`, `password`, `search`, `tel`, `text`, `url`-use the same SLDS design.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Input](https://v1.lightningdesignsystem.com/components/input/)                                                                       | [Input](https://www.lightningdesignsystem.com/components/input/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

For other input types, see these documentation resources.

- [checkbox](/docs/platform/lightning-component-reference/guide/lightning-checkbox.html)
- [checkbox-button](/docs/platform/lightning-component-reference/guide/lightning-checkbox-button.html)
- [checkbox-toggle](/docs/platform/lightning-component-reference/guide/lightning-checkbox-toggle.html)
- [color](/docs/platform/lightning-component-reference/guide/lightning-color.html)
- [date](/docs/platform/lightning-component-reference/guide/lightning-date.html)
- [datetime](/docs/platform/lightning-component-reference/guide/lightning-datetime.html)
- [file](/docs/platform/lightning-component-reference/guide/lightning-file-selector.html)
- [time](/docs/platform/lightning-component-reference/guide/lightning-time.html)
- [range](/docs/platform/lightning-component-reference/guide/lightning-range.html)

## Email

An input field for entering an email address. UTF-8 encoding is supported for international email addresses. Valid email addresses include `name@example` and `name@example.com`. The email pattern is automatically validated during the `blur` event.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="email" label="Email"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To restrict email input to match a certain pattern, use the `pattern` attribute to specify a regular expression. For example, pass in `pattern=".+@example.com"` to accept an email address only from the domain example.com. When using `pattern`, you can provide a custom validation error message using the `message-when-pattern-mismatch` attribute.

You can also include a hint of what a user can enter using the `placeholder` attribute. The placeholder text is displayed on the field before a user enters an input, but it doesn't validate input.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="email"
        label="Email"
        pattern=".+@example.com"
        placeholder="username@example.com"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To specify the maximum number of characters for an email address, use the `maxlength` attribute.
When using `maxlength`, you can provide a custom validation error message using the `message-when-too-long` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="email"
        label="Email"
        maxlength="50"
        message-when-too-long="Your email address must not be more than 50 characters."
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To specify the minimum number of characters for an email address, use the `minlength` attribute.
When using `minlength`, you can provide a custom validation error message using the `message-when-too-short` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="email"
        label="Email"
        minlength="5"
        message-when-too-short="Your email address must be more 5 characters."
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

When `multiple` is used, the email field expects a single email address or a comma-separated list of email addresses. For example, `my@example.com,your@example.com` with or without a space after the comma.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="email" label="Email" multiple> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Number

An input field for entering a number. When working with numerical input, you
can use the attributes `max`, `min`, and `step`.

The attributes `maxlength`, `minlength`, and `pattern` can't be used with `number` type because they are for string data.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="number" label="Number" value="12345">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To specify valid increments for numerical fields, use the `step` attribute. The value of `step` constrains the numbers
that users can enter. If you don't specify `step`, the default value of 1 allows users to enter only integers.

To enable decimal number entry, specify a value for `step` that represents the number of decimal places accepted and
the increment. For example, specifying `step=".01"` permits numbers such as 0.99 and 123456.78. Specifying `step=".20"` permits
numbers such as 18.60 but not 18.61 or 18.70.

If a user enters a number that doesn't match the `step` value, the browser flags it as invalid. Some browsers can round the number instead.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="number" label="Number" step=".01" value="123.45">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To format numerical input as a percentage or currency, set `formatter` to
`percent` or `currency` respectively. To allow for decimal numbers,
specify the `step` attribute as well.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="number"
        label="Price"
        value="12345"
        formatter="currency"
        step=".01"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

For the `percent` formatter, the entered number is multiplied by 100 on blur to display the percentage. For example, when you enter .75 the value displays as 75%. When you enter 1, the value displays as 100%. To enter a percentage value as is, use `formatter="percent-fixed"`. When you enter .75, the value displays as .75%, and when you enter 1, the value displays as 1%.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="number" label="Enter a decimal value" step="0.001">
    </lightning-input>
    <lightning-input
        type="number"
        label="Enter a percentage value"
        formatter="percent"
        step="0.01"
    >
    </lightning-input>
    <lightning-input
        type="number"
        label="Enter a dollar amount"
        formatter="currency"
        step="0.01"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

Number formatting is based on the Intl.NumberFormat object and follows ISO guidelines, displaying a value based on the org currency and your Salesforce locale. For example, when using `formatter="currency" step=".01"`, entering "123.45" displays "€123,45" if your org's currency is set to EUR and your Salesforce locale is German. Your Salesforce locale is also used to determine if the number you entered is valid.

## Number Validation

The number field does not let you type invalid characters, although anything can be pasted in. When a field contains invalid characters, a default field-level error is displayed on blur and the `value` property returns an empty string.
The invalid input continues to be displayed to allow the user to correct the entry. See the [Input Validation](#input-validation) and [Error Messages](#error-messages) sections for more information. Valid characters include digits, number shortcuts, exponential numbers, positive and negative signs, and decimal separators.

The `lightning-input` component uses the Javascript `parseFloat()` function to convert input value strings to numbers. Very large numbers with more than approximately 15 or 16 total digits can lose precision and appear to be rounded. Browsers can handle this loss of numeric precision differently, causing variation in decimal point rounding.

For example, `parseFloat("12345678901234.12345")` is stored in memory as `12345678901234.123`, which appears rounded. The parsed value in memory is used for validation, not the entered number. As a result, a number that should be invalid can be accepted as valid due to the loss of precision in the stored value. If your `lightning-input` component
sets `step="0.0001"`, the entered value `12345678901234.12345` is invalid. However, the stored value
`12345678901234.123` is valid, so the entered value is accepted.

### Digits

Digits are the numbers 0 to 9. Invalid placement of 0's are removed. For example, `010` results in `10`. Trailing zeros after the decimal separator are also removed to match any given `step` pattern.

### Number Shortcuts

Shortcuts such as `k`, `K`, `m`, `M`, `b`, `B`, `t`, and `T` are allowed. For the en-US locale, when you enter `1k` the field displays `1,000`. Entering `1m` results in `1,000,000`. When the input field is focused, the input value is the multiplied number. For example, entering `1k` results in `1,000` on blur, and `1000` when the input is focused again.

Shortcuts are not supported via the `value` attribute.

### Exponential Numbers

The letter `e` or `E` is accepted when entering an exponential number. For example, when you enter `2e2` the field displays `200` on blur, and `2e2` when the input is focused again.

### Positive and Negative Signs

Use `+` and `-` characters to represent positive and negative numbers. The positive `+` sign is removed on blur. If your number starts with `+.` or `-.`, `0` is added before the decimal separator. For example, entering `+.2` results in `0.2` on blur.

### Decimal Separators

Decimal separators are valid when you use the `step` attribute. Only the `.` and `,` decimal separators are allowed. If your number starts with a decimal separator, `0` is added before the decimal separator. For example, entering `.2` results in `0.2` on blur.

### Step

We recommend using a maximum of 9 decimal places for `value` and a maximum of 15 decimal places for `step`. Browsers exhibit inconsistencies in number calculation when you use more decimal places.

For example, a `value` of `9.9999999999` has more than 9 decimal places, and is interpreted as `10.0` by some browsers. If `step` is `0.01`, `stepMismatch` validates as false when you enter `9.9999999999` because `10.0` matches the step. The `messageWhenStepMismatch` validation message isn't displayed and the field incorrectly displays as valid.

Similar behavior occurs when `step` has a value such as `0.000000000000001`, which is more than 15 decimal places.

## Password

An input field for entering a password. Characters you enter are masked.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="password" label="Password"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

Use the `value` attribute to optionally supply an initial value for the password. Use `pattern` to pass
a regular expression to validate the password characters.

You can guide users with a `field-level-help` tooltip and a `placeholder` prompt in the text field,
as described in [Add Field-Level Help and Placeholder Text](#add-field-level-help-and-placeholder-text).

## Search

An input field for entering a search string. This field displays the Lightning
Design System search utility icon.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="search" label="Search"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

A search field that contains a value displays an X button to clear the search. Press the button to remove the value on the field. It also fires the `blur`, `change`, and `commit` events in that order. When the Enter key is pressed, the search field fires the `commit` event.

To indicate activity in the search field with a spinner, such as data loading, include the `is-loading` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="search" label="Search" is-loading> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

When a search field is invalid, the field is displayed with a red border and a red search icon. However, an error icon isn't displayed as it is for the other input types.

## Tel

An input field for entering a telephone number. Use the `pattern` attribute to
define a pattern for field validation.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="tel"
        label="Telephone"
        value="343-343-3434"
        pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Text

An input field for entering text. This is the default input type.

The `value` attribute for this input type only supports string values. To clear a text field by setting the `value` attribute, use `""` to specify an empty string because `null` isn't supported.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input label="Name"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## URL

An input field for entering a URL. The address must include the protocol, such
as http:// or ftp://. The URL pattern is automatically validated during the
`blur` event. To enter the address without the protocol, such as
www.example.com, use the default `type="text"` instead.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="url" label="Website"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

Client-side input validation is available for this component. An invalid field is displayed with a red border and an error icon next to the field. An error message in red text is also displayed below the field. For example, an
error message is displayed when a URL or email address is expected for an
input type of `url` or `email`. Note that disabled and read-only inputs are
always valid.

An error icon is displayed on fields that are in an invalid state for these input types.

- email
- number
- password
- range
- tel
- text
- url

An error icon is displayed on fields, except on desktop browsers, for these input types.

- date
- datetime
- datetime-local
- time

You can define additional field requirements. For example, to set a maximum
value on a number field, use the `max` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="number" value="500" label="Quantity" max="1000">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

To check the validity states of an input, use the `validity` attribute, which
is based on the Constraint Validation API. To determine if a field is valid,
you can access the validity states in JavaScript. Let's say
you have this input field.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        class="input"
        label="Enter some text"
        onblur={handleBlur}
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

The `validity` attribute returns true for the `valid` property because all constraint validations are met,
and in this case there are none.

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

export default class DemoInput extends LightningElement {

    handleBlur(event) {
        var input = this.template.querySelector(".input");
        console.log(input.validity.valid); //returns true
    }
```

For example, you have the following form with several fields and a button. To
display error messages on invalid fields, use the `reportValidity()` method.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input label="First name" placeholder="First name" required>
    </lightning-input>
    <lightning-input label="Last name" placeholder="Last name" required>
    </lightning-input>
    <lightning-button type="submit" label="Submit" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Validate the fields in JavaScript.

```javascript
export default class InputHandler extends LightningElement {
  value = "initial value";

  handleClick(evt) {
    console.log("Current value of the input: " + evt.target.value);

    const allValid = [...this.template.querySelectorAll("lightning-input")].reduce(
      (validSoFar, inputCmp) => {
        inputCmp.reportValidity();
        return validSoFar && inputCmp.checkValidity();
      },
      true,
    );
    if (allValid) {
      alert("All form entries look valid. Ready to submit!");
    } else {
      alert("Please update the invalid form entries and try again.");
    }
  }
}
```

This `validity` attribute returns an object with these read-only `boolean`
properties. One property is set to true and the rest are false, depending on attributes set on the input field and the user's entry.

- `badInput`: Indicates that the value is invalid for any input type.
- `customError`: Indicates that a custom error has been set. See [Custom Validity Error Messages](#custom-validity-error-messages).
- `patternMismatch`: Indicates that the value doesn't match the specified `pattern` attribute for `email`, `password`, `search`, `tel`, `text`, or `url` input types.
- `rangeOverflow`: Indicates that the value is greater than the specified `max` attribute for `number`, `range`, `date`, `datetime`, or `time` input types.
- `rangeUnderflow`: Indicates that the value is less than the specified `min` attribute for `number`, `range`, `date`, `datetime`, or `time` input types.
- `stepMismatch`: Indicates that the value doesn't match the specified `step` attribute for `number` or `range` input types.
- `tooLong`: Indicates that the value exceeds the specified `maxlength` attribute for `email`, `password`, `search`, `tel`, `text`, or `url` input types.
- `tooShort`: Indicates that the value is less than the specified `minlength` attribute for `email`, `password`, `search`, `tel`, `text`, or `url` input types.
- `typeMismatch`: Indicates that the value doesn't match the required syntax for `email` or `url` input types.
- `valueMissing`: Indicates that an empty value is provided when `required` attribute is set for any input type.
- `valid`: True if none of the preceding properties are true.

## Error Messages

When an input validation fails, a default message is displayed. You can provide your own values for the error messages to override the default messages. Specify your message using an attribute that corresponds to the validity error that's returned, as shown in the following table.

| Validity Error    | Default Message                                                                                              | Attribute to Override Default   |
| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| `badInput`        | Enter a valid value.                                                                                         | `message-when-bad-input`        |
|                   | Your entry does not match the allowed format `[locale's format]`. (for types `date`, `datetime`, and `time`) |                                 |
| `badNumericInput` | Enter a valid numeric value.                                                                                 | `message-when-bad-input`        |
| `patternMismatch` | Your entry does not match the allowed pattern.                                                               | `message-when-pattern-mismatch` |
| `rangeOverflow`   | The number is too high.                                                                                      | `message-when-range-overflow`   |
|                   | Value must be `[max]` or earlier. (for types `date`, `datetime`, and `time`)                                 |                                 |
| `rangeUnderflow`  | The number is too low.                                                                                       | `message-when-range-underflow`  |
|                   | Value must be `[min]` or later. (for types `date`, `datetime`, and `time`)                                   |                                 |
| `stepMismatch`    | Your entry isn't a valid increment.                                                                          | `message-when-step-mismatch`    |
| `tooLong`         | Your entry is too long.                                                                                      | `message-when-too-long`         |
| `tooShort`        | Your entry is too short.                                                                                     | `message-when-too-short`        |
| `typeMismatch`    | You have entered an invalid format.                                                                          | `message-when-type-mismatch`    |
| `valueMissing`    | Complete this field.                                                                                         | `message-when-value-missing`    |
|                   | Complete this field with format `[locale's format]`. (for types `date`, `datetime`, and `time`)              |                                 |

**note:** Some validity errors for `date`, `datetime`, and `time` fields display a default message that varies by locale. For more information, see [Date Picker](/docs/platform/lightning-component-reference/guide/lightning-date.html?type=Develop), [Datetime Picker](/docs/platform/lightning-component-reference/guide/lightning-datetime.html?type=Develop), and [Time Picker](/docs/platform/lightning-component-reference/guide/lightning-time.html?type=Develop)

To override the default error message, use the corresponding attribute. For example, you have a text input with a minimum length of 5. If users enter fewer than five characters,
the validity error returned is `tooShort` and the default message is "Your entry is too short." Use the `message-when-too-short` attribute to display a different error message.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        label="First Name"
        minlength="5"
        message-when-too-short="Your entry must be at least 5 characters."
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

Custom errors that override the default error message are appended with the string "(Use format `[format]`)" where `[format]` is the date format that's determined by the user locale. For example, if your component sets `badInput="This is a custom error"`, the displayed error for a date field in en-US locale is "This is a custom error (Use format Dec 31, 2024)".

## Custom Validity Error Messages

The component supports `setCustomValidity()` from HTML5's Constraint
Validation API. To set an error message, provide a quoted string to display.
To reset the error message, set the message to an empty string (""). See
details at [https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity](https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity).

This example shows how to display a custom error message with
`setCustomValidity()` and `reportValidity()`. The component is a simple text
input with a button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input class="inputCmp" label="Enter your name:">
    </lightning-input>
    <lightning-button label="Register" onclick={register}> </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The `register()` function compares the input entered by the user to a
particular text string. If true, `setCustomValidity()` sets the custom error
message. The error message is displayed immediately using `reportValidity()`.

Note that when the comparison isn't true, you should set the error message to
an empty string to zero out any messages that might have been set on previous
calls.

```javascript
import { LightningElement } from "lwc";
export default class MyComponent extends LightningElement {
  register(event) {
    var inputCmp = this.template.querySelector(".inputCmp");
    var value = inputCmp.value;
    // is input valid text?
    if (value === "John Doe") {
      inputCmp.setCustomValidity("John Doe is already registered");
    } else {
      inputCmp.setCustomValidity(""); // if there was a custom error before, reset it
    }
    inputCmp.reportValidity(); // Tells lightning-input to show the error right away without needing interaction
  }
}
```

## Use Autocomplete in Input Fields

Some input types can be autofilled, based on your browser's support of the feature.
The `autocomplete` attribute passes through its value to the browser.
These `lightning-input` types support the `autocomplete` attribute:

- `email`
- `search`
- `tel`
- `text`
- `url`

The values `on` and `off` or a space-separated string of expected data types are supported, but the behavior depends on the browser. Some browsers might ignore the passed value.

To provide autocomplete guidance on the expected data type in the field, use a space-separated string that describes the meaning of the autocompletion value. For example `autocomplete="shipping street-address"`. For more information, see the [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete).

## Add Field-Level Help and Placeholder Text

To provide a hint for entering information in the field, specify help text with the `field-level-help` attribute. For example, describe the characters required in a `password` input. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

To provide sample input in the field, use the `placeholder` attribute. For example, in a `url` input, show a URL in the correct format.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        label="Event Name"
        placeholder="Grand Opening"
        field-level-help="The event name must 50 characters or less"
        maxlength="50"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

`field-level-help` isn't supported for `file`, `toggle`, and `checkbox-button` types.

`placeholder` is supported for `date`, `email`, `number`, `password`, `search`, `tel`, `text`, `time`, and `url` input types only. The `placeholder` support for `date` and `time` is a Salesforce addition and is not part of the [HTML5 standard](https://html.spec.whatwg.org/multipage/input.html#input-type-attr-summary).

## Data Binding

Bind the input value to a property in your component's JavaScript class. `lightning-input` uses the `onchange` event handler to listen a change to its value. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).

## Event Handling

The native HTML `<input>` element provides two events, `input` and `change`. The `lightning-input` component provides two custom events, `change` and `commit`. You can also define an action for input events like `blur` and `focus`.

The component's `change` event behaves the same as the native `input` and `change` events together.
It fires whenever you change the input value, as the `<input>` element's `input` event does.
It also fires when you finish changing the input, as the `<input>` element's `change` event does.

The component's `commit` event fires only when you finish changing the input,
which is the same behavior as the HTML `<input>` element's `change` event. Some input types don't support the `commit` event.

- `checkbox`
- `date`
- `datetime`
- `file`
- `time`
- `toggle`

The component doesn't provide an `input` event because the behavior is provided in the `change` event.

To summarize, the component's `change` event is equivalent to the `input` and `change` events of
the `<input>` element. The component's `commit` event is equivalent to the `change` event of
the `<input>` element.

The `change` event fires at different times, depending on the specific input type.
For information about the `change` event for the `<input>` element, see
[developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).

See the [Custom Events](#custom-events) section for more information about the component's events.

### Clear Values and Repeated Input

**note:** The `commit` event isn't fired if the input value matches the previously
committed value. To ensure that the input value is reliably updated, even when
entering the same value multiple times, use the `change` event.

This example shows how you can clear the input value using the `change` event.
When the button is clicked, it calls `handleClear()` to reset `text` to an empty string.

<!-- prettier-ignore -->
```html
 <lightning-input
    label="Text Input"
    value={text}
    onchange={handleChange}
    ></lightning-input>
<lightning-button label="clear" onclick={handleClear}></lightning-button>
```

If you use the `commit` event here, the `commit` event isn't fired if you try to
clear the input value and it matches the previously committed value. For
example, entering "hello" and clearing the value, and then entering "hello"
again and attempting to clear the value. The second attempt doesn't clear the
value because the `commit` event isn't called. `this.text` remains an empty string even
though the input value displays "hello".

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

export default class InputChangeExample extends LightningElement {
  text = "";

  handleChange(event) {
    this.text = event.target.value;
  }

  handleClear() {
    this.text = "";
  }
}
```

## Handle Number Input

In general, use `oncommit` to handle changes to number inputs. Use `onchange` for use cases where you want to process each character entered right away. For example, use `onchange` if you want to echo the content entered in another field as it is entered.

For input type `number`, the component sets the `value` to '' (an empty string) when the number input becomes invalid. The `change` event is fired each time the value changes, even when the value is set to an empty string. This enables you to reset the field in your `onchange` handler when input is invalid. Use separate variables to set the value of the number input and retrieve it.

## Set and Read Selection Indexes

The `selection-start` and `selection-end` attribute values are passed through to the `<input>` element. Only the input type `text` is currently supported. The `selection-start` value specifies the index of the first character selected in the input element, while the `selection-end` value specifies the index of the last character selected. Index values start at 0.

This example selects the characters from index 0 to the end when you click the button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="text"
        label="Enter some text"
        value={textvalue}
        onchange={handleChange}
    ></lightning-input>
    <lightning-button
        label="Focus selection"
        onclick={handleClick}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

In JavaScript, the `selectionEnd` property
is set to the length of the current input value.

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

export default class DemoInputSelection extends LightningElement {
  textvalue = "initial value";
  handleChange(event) {
    this.textvalue = event.detail.value;
  }
  handleClick(event) {
    let input = this.template.querySelector("lightning-input");
    let end = input.value.length;
    input.selectionStart = 0;
    input.selectionEnd = end;
    // Optionally, focus to highlight the selected characters
    // input.focus();
  }
}
```

## Component Styling

Use a combination of variants and utility classes to customize your input fields.

### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the fields.

- `standard` is the default, which displays the label above the field.
- `label-hidden` hides the label but make it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still displayed.
- `label-inline` aligns the label and field horizontally.
- `label-stacked` places the label above the field.

In most contexts, a stacked label (`standard` or `label-stacked` variant) results in better readability and clarity. Use horizontal labels (`label-inline` variant) when you want to conserve vertical space and have fewer than 10 fields.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example creates two fields using `lightning-input` in a compound row similar to the [SLDS form fields](https://v1.lightningdesignsystem.com/components/form-element/#Fields).

<!-- prettier-ignore-start -->
```html
<fieldset class="slds-form-element slds-form-element_compound">
    <legend class="slds-form-element__legend slds-form-element__label">
        Name
    </legend>
    <div class="slds-form-element__control">
        <div class="slds-form-element__row">
            <div class="slds-size_1-of-2">
                <lightning-input label="First Name"></lightning-input>
            </div>
            <div class="slds-size_1-of-2">
                <lightning-input label="Last Name"></lightning-input>
            </div>
        </div>
    </div>
</fieldset>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

Consider these usage guidelines.

- For a single line of plain text input, use `lightning-input`. For multiple lines of plain text input, use `lightning-textarea` instead. For more specific input such as with numbers or email addresses, use the `type` attribute. Specifying `type` ensures that built-in validation can be applied to your data input.
- To group related fields together, such as individual parts of an address, use compound input components like `lightning-input-address` or `lightning-input-location`. For name fields, use `lightning-input-name`.
- The `label` attribute is required. If you don't want to display a label,
  specify the `variant="label-hidden"` attribute. See [Accessibility](#accessibility) for more
  information.

When working with forms that interact with Salesforce records, consider using these components instead: `lightning-record-form`, `lightning-record-view-form`, and `lightning-record-edit-form` components provide a form-based UI that's metadata-driven. The components are automatically wired up to your record data, labels, and field-level help text. For more information, see [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro). Alternatively, to create your own custom UI to work with Salesforce records, use `lightning-input` with the `lightning/ui*Api` wire adapters and functions, such as `getRecord` and `updateRecord`. For more information, see [Use the Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components).

`maxlength` limits the number of characters you can enter. The
`message-when-too-long` error message isn't triggered because you can't type more
than the number of characters allowed. However, you can use the
`message-when-pattern-mismatch` and `pattern` attributes to
trigger a message on blur when too many characters are entered.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="text"
        message-when-pattern-mismatch="Too many characters"
        pattern=".{0,5}"
        label="Enter up to 5 characters"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

You can use custom labels that display translated values on input fields. For more information,
see [Access Labels](https://developer.salesforce.com/docs/platform/lwc/guide/create-labels).

## Accessibility

You must provide a text label for accessibility to make the information
available to assistive technology. The `label` attribute creates an HTML
`<label>` element for your input component. To hide a label from view and make
it available to assistive technology, use the `label-hidden` variant.

Specify the `aria-labelledby` attribute and `variant="label-hidden"` to
provide a custom label for assistive devices. Although the `label` attribute is
still required, the `<label>` element is not rendered in this case.

<!-- prettier-ignore-start -->
```html
<template>
    <p id="otherlabel">
        Your Event Name
        <lightning-input
            label="Event"
            variant="label-hidden"
            aria-labelledby="otherlabel"
        >
        </lightning-input>
    </p>
</template>
```
<!-- prettier-ignore-end -->

`lightning-input` sets the `aria-invalid` attribute to match the validity state of the input field for assistive technology. If the `validity` attribute returns a true value for the `valid` property, then `aria-invalid` is false. If the `validity` attribute returns a true value for any property other than `valid`, then `aria-invalid` is true. When the component is initially loaded, `aria-invalid` is set to false. This prevents fields that are marked required from being announced as invalid before you enter anything.

When a field-level error is displayed, `lightning-input` links the input field to the error message using the `aria-describedby` attribute, which enables assistive technology to announce the error message on the input field.

For the `datetime` type, the component renders two separate fields for date and time input. To provide accessibility features to the date field, use the `date-aria-*` attributes. For example, use `date-aria-described-by` to provide a descriptive label for the date field. To provide accessibility features to the time field, use the `time-aria-*` attributes. For example, use `time-aria-described-by` to provide a descriptive label for the time field.

In some cases, you can further improve the accessibility of your `lightning-input` implementation by specifying the [`autocomplete` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete). For supported types, see the [Use Autocomplete in Input Fields](#use-autocomplete-in-input-fields) section.

Use the [`autocomplete` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) to make it easier for a browser to prefill values in forms. For example, specify `autocomplete="given-name"` on `lightning-input` to expect the field value to be the user's first name. The field displays a list of options that anticipates what a user is typing. The user presses the Down arrow key to select an option and press Enter. For more information, see [WCAG 2.2: Using autocomplete attributes](https://www.w3.org/WAI/WCAG22/Techniques/html/H98).

The `autocomplete` attribute is helpful for fields that specifically ask for data about the user who's completing the form. Don't use the `autocomplete` attribute on a field that asks for data about other people. The list of suggested values can come from past values entered by the user or they can be pre-configured on the user's browser.

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

**`commit`**

The event fired when you press Enter after interacting with the input, or move away from the input so it loses focus. For the input type search, the event is fired when focus leaves the entire component or when the user clicks the X button to clear the search. The event is also fired when you press the Enter key. For the input type `number` the event is also fired when you press Up/Down arrow keys to change the number.

The `commit` event doesn’t return any parameters.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-input`, see the following components in the LWC Recipes repo.

- `c-lds-create-record`
- `c-misc-modal`
- `c-wire-get-picklist-values`

## See Also

[Access Elements the Component Owns](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work)

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="input" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=17bbb493275112015201c8bc7c806374faeb524a44c99358ce46a529dae9b0e6 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputAddress/lightning-input-address.md -->


# Input Address

**`lightning-input-address`**

Represents an address compound field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="inputAddress" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-input-address` component creates a compound field that includes these constituent fields.

- Street
- City
- Province
- Country
- Postal code

The street field is a multi-line text field. The other fields are individual text input fields by default.
The country and province fields use dropdown menus if you specify `country-options` and `province-options` to provide options for menu items.

To specify the initial field values, use the component attributes. This example creates an address compound field with attributes to specify values for the constituent fields.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-input-address
            address-label="Address"
            street-label="Street"
            city-label="City"
            country-label="Country"
            province-label="State"
            postal-code-label="PostalCode"
            street="1 Market St."
            city="San Francisco"
            country="US"
            province="CA"
            postal-code="94105"
            field-level-help="Enter your billing address"
        >
        </lightning-input-address>
    </div>
</template>
```
<!-- prettier-ignore-end -->

`lightning-input-address` uses the `onchange` event handler to listen to a change to its field values.

<!-- prettier-ignore-start -->
```html
<p>You are located in: {city}</p>
    <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="PostalCode"
        city={city}
        onchange={handleChange} ></lightning-input-address>
```
<!-- prettier-ignore-end -->

To bind the input value on the address fields, use the `event.target` property.

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

export default class AddressCityExample extends LightningElement {
  city = "San Francisco";

  handleChange(event) {
    this.city = event.target.city;
  }
}
```

See the [Custom Events](#custom-events) section for a list of `event.target` properties. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).

## Design

`lightning-input-address` implements the form element (address) blueprint in the Salesforce Lightning Design System (SLDS). The address fields adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                                |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element (Address)](https://v1.lightningdesignsystem.com/components/form-element/#Address)                                       | [Form Element (Address)](https://www.lightningdesignsystem.com/2e1ef8501/p/96252b-form-element/b/76ea32/t/3cb2bd3571) |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5)       |

## Create Dropdown Menus for Country and Province

To create a dropdown menu for the country and province, pass in an array of
label-value pairs to `country-options` and `province-options`. Use the `country` and
`province` attributes to specify the default values on the dropdown menus.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-input-address
            address-label="Address"
            street-label="Street"
            city-label="City"
            country-label="Country"
            province-label="Province/State"
            postal-code-label="PostalCode"
            street="1 Market St."
            city="San Francisco"
            province="CA"
            country="US"
            country-options={getCountryOptions}
            province-options={getProvinceOptions}
            postal-code="94105"
            required
            onchange={handleChange}
        >
        </lightning-input-address>
    </div>
</template>
```
<!-- prettier-ignore-end -->

JavaScript file:

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

export default class DemoInputAddress extends LightningElement {
  provinceOptions = [
    { label: "California", value: "CA" },
    { label: "Texas", value: "TX" },
    { label: "Washington", value: "WA" },
  ];

  countryOptions = [
    { label: "United States", value: "US" },
    { label: "Japan", value: "JP" },
    { label: "China", value: "CN" },
  ];

  get getProvinceOptions() {
    return this.countryProvinceMap[this._country];
  }
  get getCountryOptions() {
    return this.countryOptions;
  }

  handleChange(event) {
    this._country = event.detail.country;
  }
}
```

Alternatively, you can enable state and country picklists in your org, and
access the values by using a wire adapter.
See [Let Users Select State and Country from Picklists](https://help.salesforce.com/articleView?id=admin_state_country_picklists_overview.htm) in Salesforce Help and [getPicklistValues](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values) in the Lightning Web Components Developer Guide.

## Use the Locale Information

In Lightning Experience, the `locale` value corresponds to the **Locale** field on the Language &amp; Time Zone page in the [user's personal settings](https://help.salesforce.com/s/articleView?id=xcloud.usersetup_lang_time_zone.htm).

By default, your org's locale setting determines the order and layout of the address fields.

The locale also determines which constituent fields are required. For example, the province (state) field is required with the `en-US` locale, but it isn't required with the `fr-FR` locale. The selected `country` value doesn't change the required fields. To apply consistent validation regardless of the user's locale, set the `locale` attribute explicitly instead of relying on the org's locale setting.

For example, if you select "French (France)" in the **Locale** field, `lightning-input-address` uses `fr-FR` as the locale.

To override the locale on your user's settings, provide your own `locale` value. Specify any locale code from the list of [Supported Number, Name, and Address Formats (ICU)](https://help.salesforce.com/s/articleView?id=xcloud.admin_supported_locales.htm).

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"
        locale="en-US"></lightning-input-address>
</template>
```
<!-- prettier-ignore-end -->

If you don't specify the `locale`, `lightning-input-address` defaults to the user's locale in the org.

<!-- prettier-ignore-start -->
```html
<template>
    <h2>User's locale: {userLocale}</h2>
    <!--No locale specified on lightning-input-address -->
    <lightning-input-address
        lwc:ref="address"
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"></lightning-input-address>
</template>
```
<!-- prettier-ignore-end -->

In this example, the `userLocale` property returns `fr-FR` based on the org user's settings.

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

export default class LocaleExample extends LightningElement {
  userLocale = "";

  renderedCallback() {
    this.userLocale = this.refs.address.locale;
  }
}
```

If you pass in an invalid locale, the component uses `en-US`. The locale supports both hyphens and underscores, for example, `en-US` or `en_US`.

## Hide the Province Field

The province field is used with countries that include a province in their addresses. This field can also be used as a field for state information, such as in United States addresses.

To visually hide the province field from the component's fields layout for locales that don't require it, use the `hide-province` attribute. For example, you can use `hide-province` when the `locale` is `fr-FR` or `zh-CN`.

<!-- prettier-ignore-start -->
```html
<template>
     <lightning-input-address
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="Province"
        postal-code-label="Postal Code"
        locale="fr-FR"
        hide-province
    ></lightning-input-address>
</template>
```
<!-- prettier-ignore-end -->

If you don't provide a value for `province-label`, the component renders with a province field without a label. Hide the field using `hide-province`.

## Use Lookup to Find and Autofill an Address

To enable autocompletion of the address fields using an address lookup field, include the `show-address-lookup` attribute. The address lookup field is placed above the address fields you provide.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-address
        show-address-lookup
        address-label="Address"
        street-label="Street"
        city-label="City"
        country-label="Country"
        province-label="State"
        postal-code-label="Zip Code"
        street="1 Market St."
        city="San Francisco"
        country="US"
        province="CA"
    >
    </lightning-input-address>
</template>
```
<!-- prettier-ignore-end -->

When you start typing an address in the lookup field, a dropdown menu displays matching addresses returned by the Google Maps Places API. Select an address from the dropdown to populate the address fields.

When location services is enabled on your browser, the component uses the browser's Geolocation API to determine the initial location. A timeout can occur due to factors such as browser security settings, network conditions, and device capabilities. If the Geolocation API times out after 10 seconds, the address lookup field defaults to San Francisco, CA with a latitude of 37.790091 and longitude of -122.396848 instead of your current position. To enable location services on your browser, see [Autocomplete Addresses in Salesforce Help](https://help.salesforce.com/s/articleView?id=xcloud.customize_maps_autocomplete.htm).

## Filter Address Lookup Based on Country Options

To filter address lookups by country, pass in an array of ISO 3166-1 Alpha-2 country code strings to the `country-lookup-filter` attribute. Country codes are case-insensitive. Enable address lookup by including `show-address-lookup`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-address
        show-address-lookup
        address-label="Address"
        street-label="Street"
        city-label="City"
        province-label="State"
        country-label="Country"
        postal-code-label="Zip Code"
        country-lookup-filter={countries}
    >
    </lightning-input-address>
</template>
```
<!-- prettier-ignore-end -->

In your JavaScript file, pass in a list of country codes. You can specify a maximum of five country codes.

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

export default class CountryFilterExample extends LightningElement {
  countries = ["AU", "GB", "JP"];
}
```

For a list of valid country codes, see [_Google for Developers_: countries.csv](https://developers.google.com/public-data/docs/canonical/countries_csv).

**important:** Using an invalid two-letter country code in the array prevents the Google Maps Places API from returning results and may trigger console errors. If the array contains a country code longer than two characters or exceeds the five-country filter limit, the component defaults to using no filter. Additionally, if a non-array value is passed to the attribute, the component also defaults to using no filter.

## Use Compact Address Fields

By default, the Street address field is a textarea field. Use compact address fields if you want to separate the Street address field into two input fields instead.

To display compact address fields, include the `show-compact-address` attribute. Use `street-label` to provide a label for the first line of address, and use `subpremise-label` for the second line of address. You can add supplementary information on this field, such as a building number or unit name.

<!-- prettier-ignore-start -->
```html
<lightning-input-address
    show-compact-address
    address-label="Address"
    street-label="Street Line 1"
    subpremise-label="Street Line 2"
    city-label="City"
    country-label="Country"
    province-label="Province"
    postal-code-label="Postal Code"></lightning-input-address>
```
<!-- prettier-ignore-end -->

## Use the Compact Address Fields with Address Lookup

To enable compact address fields with address lookup, include the `show-address-lookup` and `show-compact-address` attributes. These attributes enable the first street address field as a lookup field.

<!-- prettier-ignore-start -->
```html
<lightning-input-address
    show-address-lookup
    show-compact-address
    address-label="Address"
    street-label="Street Line 1"
    city-label="City"
    country-label="Country"
    province-label="Province"
    postal-code-label="Postal Code"></lightning-input-address>
```
<!-- prettier-ignore-end -->

When you start typing an address in the lookup field, a dropdown menu displays matching addresses returned by the Google Maps Places API. Select an address from the dropdown to populate the address fields.

## Use the Subpremise Field with Address Lookup

Subpremise information includes apartment, unit, or floor number. To provide a label on the subpremise field, use the `subpremise-label` attribute. The second address field is used as the subpremise field.

You can provide a subpremise value using the `subpremise` attribute. The first input field continues to use `street-label`. The `subpremise` field doesn't require a value for submission.

<!-- prettier-ignore-start -->
```html
<lightning-input-address
    show-address-lookup
    show-compact-address
    address-label="Address"
    street-label="Street Line 1"
    subpremise-label="Street Line 2"
    city-label="City"
    country-label="Country"
    province-label="Province"
    postal-code-label="Postal Code"></lightning-input-address>
```
<!-- prettier-ignore-end -->

Google Maps API currently supports subpremises for Australia, New Zealand, and Canada only. The placement of subpremise information is different for each country. For example, Australian addresses include the subpremise information as a prefix to street number, such as `2/1 Tully Road` where `2` is the subpremise. When you enter this address and select it from the search results, the street field is populated with the subpremise and street information while the subpremise field remains empty.

Populating the subpremise field using address lookup isn't currently supported. For example, US addresses include the subpremise after the street number, such as `123 Main St, Unit 10`. When you enter the address with a subpremise, the subpremise appears with the street address in the result list. However, selecting the address from the search result doesn't populate the subpremise field. The street field also doesn't preserve the subpremise, but you can enter it manually in the street or subpremise field.

## Validate Required Fields

When you set `required`, a red asterisk is displayed on every address
field to indicate that an entry in each field is required. An error message is displayed below
a field if a user interacted with it and left it blank. The `required`
attribute is not enforced and you must validate it before submitting a form
that contains an address compound field.

Let's say you have a `lightning-button` component that calls the `handleClick`
function. You can display the error message when a user clicks the
button without providing a value on a field.

```javascript
    handleClick(e) {
        const address =
            this.template.querySelector('lightning-input-address');
        const isValid = address.checkValidity();
        if(isValid) {
            alert("Creating a new address");
        } else {
            alert("Complete all address fields");
        }
    }
```

**note:** The locale determines which fields are required. The country you select doesn't change the required fields. See [Use the Locale Information](#use-the-locale-information).

## Work with Labels and Placeholders

A label is associated with an address field and it enables screen readers to navigate the form correctly. Include a label for each field you're using, with the following attributes.

- `address-label`
- `street-label`
- `city-label`
- `province-label`
- `country-label`
- `postal-code-label`

You can hide the `address-label` visually and still make them accessible to screen readers by using `variant="label-hidden"`.

Additionally, the `show-address-lookup` boolean attribute creates a search field that doesn't have an associated label. See [Using Lookup to Find and Autofill an Address](#use-lookup-to-find-and-autofill-an-address) for more information.

You can also use custom labels that display translated values. For more information, see
[Access Labels](https://developer.salesforce.com/docs/platform/lwc/guide/create-labels).

We recommend that you provide a label even when you provide placeholder text for an address field. Without field labels, users can lose context when the placeholder text disappears as they type in the field.

Specify placeholder text to give users a hint about the content they're expected to enter in the field. Avoid repeating the field label in the placeholder for better accessibility. Consider the width of your address field as the placeholder text is cut off if it's too long, especially on mobile devices.

Include an optional placeholder for each field that you're using, with these attributes.

- `address-lookup-placeholder`
- `street-placeholder`
- `city-placeholder`
- `province-placeholder`
- `country-placeholder`
- `postal-code-placeholder`

## Component Styling

Use a combination of the `variant` and `class` attributes to customize the address fields.

### Variants

Use the `variant` attribute with one of these values to apply different label positioning.

- `label-hidden` hides the compound field label but make it available to assistive technology. This variant does not hide the constituent field labels.
- `label-inline` horizontally aligns the compound field label and address fields.
- `label-stacked` places the label above the address fields.
- `standard` is the default value, which displays the label above the address fields.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on top of address fields using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-input-address
    class="slds-p-top_small"
    address-label="Address"
    street-label="Street"
    city-label="City"
    country-label="Country"
    province-label="Province"
    postal-code-label="PostalCode"
>
</lightning-input-address>
```
<!-- prettier-ignore-end -->

The Street field renders a [textarea](https://v1.lightningdesignsystem.com/components/textarea) and the other fields render [input](https://v1.lightningdesignsystem.com/components/input/) fields.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

Using `show-address-lookup` isn't supported in Experience Builder sites, Lightning Out,
Lightning Components for Visualforce, and standalone apps.

When working with address fields such as with the `MailingAddress` field on Salesforce records, consider using the record form components. The `lightning-record-form`, `lightning-record-view-form`, and `lightning-record-edit-form` components provide a form-based UI that's metadata-driven. The components are automatically wired up to your record data, labels, and field-level help text. For more information, see [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro).

To create your own custom UI to work with Salesforce records, use `lightning-input-address` with the `lightning/ui*Api` wire adapters and functions, such as `getRecord` and `updateRecord`. For more information, see [Use the Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components).

To disable the fields so that users cannot interact with it, use the `disabled` attribute. If you want to prevent users from interacting with the country field only,
disable it using the `country-disabled` attribute.

## Accessibility

For accessibility, provide a text label using the label attributes. When you use `address-label`, `street-label`, `city-label`, and so on, the component generates the corresponding `<label>` elements and automatically binds them to their internal inputs using the correct `for` and `id` relations.

The `address-label` is the compound field label that provides the text for the `<legend>` element on the field set. To hide the compound field label from view and make it available to assistive technology, use the `label-hidden` variant.

Each constituent field corresponds to a label, such as `street-label` and `city-label`. The `label-hidden` variant has no effect on the labels on the constituent fields. If you use `label-hidden`, the constituent field labels remain visible. If you use `show-address-lookup` to display an address lookup field, the "Search Address" label also continues to be visible.

This component uses `button` elements for picklists to comply with the [Lightning Design System combobox blueprint](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) for select-only comboboxes.

To use the keyboard to move focus through each constituent address field, use the Tab and Shift + Tab keys. If you configure the `province-options` or `country-options` attributes, use arrow keys to navigate options and use Enter or Space to select an option.

When you use `show-address-lookup`, a search field is shown to provide lookup functionality by using Google Maps Places API. The search dropdown follows accessible combobox patterns. As search results appear, screen readers announce the dynamic changes, and you can navigate the address suggestions using the keyboard.

When an address field is updated via the lookup, a status message that includes the `address-label` is announced by screen readers in this format:

```
{your_address_label} updated for country {your_country}
```

For example, if the `address-label` value is Billing Address and the `country` is United States, the status message reads:

```
Billing Address updated for country United States
```

## Custom Events

**`change`**

The event fired when an item is changed in the `lightning-input-address` component.

The `change` event returns the following parameters.

| Parameter  | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| street     | string | The number and name of street.     |
| city       | string | The name of the city.              |
| province   | string | The name of the province/state.    |
| country    | string | The name of the country.           |
| postalCode | string | The postal code for the address.   |
| validity   | object | The validity state of the element. |

The `change` event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="inputAddress" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9c4ef90619b644511525ed4092bbbb5be6be001b27c244e2910cf4280ac9a547 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputField/lightning-input-field.md -->

# Input Field

**`lightning-input-field`**

Represents an editable input for a field on a Salesforce object.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Mobile Offline

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning-input-field` component in `lightning-record-edit-form` to display and edit
the value of a record field of a Salesforce object. Use the `field-name` attribute
to specify the API field name.

For standard and custom objects, find the field names in Lightning Experience from Setup > Object Manager > (object-name) > Fields & Relationships.
Standard object fields are documented in
[Standard Objects](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm).
See [Supported Objects in the `lightning-record-edit-form` documentation](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) for usage considerations about objects.

The component displays an editable field based on the data type for the field you specify.
For example, `field-name="Birthdate"` on the Contact object references a date value, so the
component renders an input field with a date picker and the label Birthdate. On the Account object, `field-name=Type"`
references a picklist, so the component renders a dropdown menu with the label Type. The list
shows the account types defined in the org.

In orgs that support multiple languages, `lightning-input-field` automatically shows the translated labels and picklist values.

For information about creating record edit forms, see the [lightning-record-edit-form](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) documentation.

Here's an example of a record edit form for creating an account record
using the input fields for Name, Phone, and BillingAddress.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="slds-p-bottom_large slds-p-left_large" style="width:500px">
        <lightning-record-edit-form object-api-name="Account">
            <lightning-messages></lightning-messages>
            <lightning-input-field field-name="Name"> </lightning-input-field>
            <lightning-input-field field-name="Phone"> </lightning-input-field>
            <lightning-input-field field-name="BillingAddress">
            </lightning-input-field>
            <lightning-button
                type="submit"
                name="submit"
                label="Create Account"
            >
            </lightning-button>
        </lightning-record-edit-form>
    </div>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input-field` implements the form element blueprint in the Salesforce Lightning Design System (SLDS). The input fields adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element](https://v1.lightningdesignsystem.com/components/form-element/)         | [Form Element](https://www.lightningdesignsystem.com/components/form-element/)                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Prepopulate Field Values

To provide a custom value on a field when the form displays, use the `value` attribute on `lightning-input-field`. If you're providing a record ID in `lightning-record-edit-form`, the value returned by the record on load does not override this custom value. You can also programmatically set the value when the form loads.

For more information, see the [`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) documentation.

## Require a Value for a Field

`lightning-input-field` supports requiredness specified on the server and client. In record forms, a required field is displayed with a red asterisk next to the field label. If you interact with a required field but don't enter a value, an error message is displayed below the field. Similarly, if you don't interact with a required field and try to submit the form, an error message is displayed.

To make an input field required on the server, mark the field Required in Setup. Input fields set as required
on the server are universally required, to be displayed with a red asterisk wherever the input fields are used. For more information,
see [Require Field Input to Ensure Data Quality](https://help.salesforce.com/articleView?id=fields_about_universally_required_fields.htm) in Salesforce help.

To make an input field required on the client only, include the `required` attribute in `lightning-input-field`. Use this attribute if you want to require a value in a field before the form can be submitted, and the field isn't marked required in Setup. If the field doesn't have a value, the component's client-side validation catches the error before the form data is submitted to the server.

The client-side `required` setting and validation for requiredness is unrelated to the Required setting on the server. Note that you can't set `required` to false to disable the required setting on the server. The required field is still displayed with a red asterisk.

## Reset the Form

To reset the form fields to their initial values, use the `reset()` method on each input field.
For more information, see [lightning-record-edit-form](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html).

## Override the Form Display Density

`lightning-input-field` inherits the display density from the enclosing parent form. To override the display density of the parent form, use the `variant` attribute in `lightning-input-field`.

When the parent form uses the `compact` density, you can reduce the whitespace between the label and field using the `slds-form-element_1-col` class on `lightning-input-field`.

For more information, see the [lightning-record-edit-form](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) documentation.

## Field Types Supported

`lightning-input-field` supports fields on objects that are UI API compliant. For supported 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).

Fields that have a spanning relationship aren't supported by `lightning-input-field`. The fields specified must be associated with only one object. A field such as Contact.Account.Ownership is a cross-object reference between the Contact object and the Account object, and can't be displayed in the form.

The supported field data types are:

- Address: Displays the input address fields, without Google address search capability.
- Checkbox: Displays a checkbox input.
- Currency: Displays an input field for entering monetary data. The user's Salesforce locale determines the currency symbol and separator characters used to format the number.
- Date: Displays an input field for entering a date. The date format is automatically validated against the user's Salesforce locale. On mobile devices, date fields use native mobile date pickers.
- Date/Time: Displays input fields for entering a date and time. The date and time formats are automatically validated against the user's Salesforce locale. On mobile devices, date and time fields use native mobile date and time pickers.
- Email: Displays an input field for entering an email address up to 80 characters. The email pattern is automatically validated. UTF-8 encoding is supported for entering an international email address.
- Geolocation: Displays input fields for entering latitude and longitude in decimal degrees. The latitude field accepts values within -90 and 90, and the longitude field accepts values within -180 and 180. See the **Geolocation Fields** section.
- Lookup: Displays an input field for creating a relationship between two objects, for example, the account associated with a contact record. On user lookup fields, the lookup value is displayed without a user icon. The lookup type is supported in Experience Builder sites, Lightning Experience, and the Salesforce mobile app. Creating a new record from the lookup field's dropdown menu is currently not supported. Lookups are not supported for the OwnerId, CreatedBy, and LastModifiedBy fields. Dependent lookups and external lookups are also not supported. Lookup fields work only for objects that are compliant with the User Interface API. A lookup from a supported object to an unsupported object or field is displayed as a text field. See the **Lookup Fields** section.
- Name: Displays one or more input fields for setting the name of a record. Input fields can include a single name field or multiple fields. For example, accounts might have a single name while contacts might have a salutation, first name, middle name, and last name. See the **Name Fields** section.
- Number: Displays an input field for entering a number, and formats for the user's Salesforce locale and currency. Number formatting is based on the Intl.NumberFormat object and follows ISO guidelines. For example, entering "123.45" displays "€123,45" if your org's currency is set to EUR and your Salesforce locale is German.
- Percent: Displays an input field for entering a percentage.
- Phone: Displays an input field for entering a phone number up to 40 characters.
- Picklist and multi-select picklist: Displays a picklist or multi-select picklist. Dependent picklists must be defined in your org before you can use them with `lightning-input-field`. Both controlling and dependent fields must be included in your component. See the **Dependent Picklist Fields** section.
- Text: Displays text input, accepts up to 255 characters.
- Text (Encrypted): Displays the encrypted text input for up to 175 characters. Characters you enter are in clear text when you type and then masked after save.
- Text Area: Displays multi-line text input for up to 255 characters.
- Text Area (Long): Displays multi-line text input for up to 131,072 characters.
- Text Area (Rich): Displays rich text input for bold or underline text, lists, and images for up to 131,072 characters including the formatting and HTML tags. Unsupported tags and attributes are removed and only their text content is displayed. For more information on supported tags, see [Rich Text Editor in Salesforce Help](https://help.salesforce.com/articleView?id=fields_using_html_editor.htm).
- Time: Displays an input field for time selection in 15-minute increments. The time format is automatically validated against the user's Salesforce locale. On mobile devices, time fields use native mobile time pickers. For more information, see [Time Custom Field in Salesforce Help](https://help.salesforce.com/articleView?id=platform.custom_field_time_overview.htm).
- URL: Displays a URL input field which checks for a protocol such as `http://` or `ftp://`.

For more information, see [Custom Field Types in Salesforce Help](https://help.salesforce.com/s/articleView?id=platform.custom_field_types.htm).

## Dependent Picklist Fields

Dependent picklist fields depend on the value of another field, called the controlling field. As such, we recommend placing the controlling field before the dependent field. If you don't provide a controlling field, the picklist displays in a disabled and read-only state.

This example uses `LeadSource` as the controlling field and `Level__c` as the
dependent field for a dependent picklist.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        id="recordViewForm"
        record-id="003R00000000000000"
        record-type-id="012R00000000000000"
        object-api-name="Contact"
    >
        <lightning-messages></lightning-messages>
        <!--Other fields here-->
        <lightning-input-field field-name="LeadSource"> </lightning-input-field>
        <lightning-input-field field-name="Level__c"> </lightning-input-field>
        <lightning-button
            id="submit"
            type="submit"
            label="Update record"
            class="slds-m-top_medium"
        >
        </lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

A dependent picklist should be lower on the page layout than its controlling field. You might encounter unexpected behavior if you place the dependent field before the controlling field on the page.

When using a record type with a dependent picklist, we don't recommend adding a default value that applies only to a specific controlling value. If you use a record type that has a default value set for the dependent picklist, this value is displayed in the picklist even though the controlling field might exclude the value.

For more information, see
[Define Dependent Picklists](https://help.salesforce.com/articleView?id=fields_defining_field_dependencies.htm) in Salesforce
Help.

## Geolocation Fields

Geocode fields and custom geolocation fields display as latitude and longitude fields.

To use a custom geolocation field, pass in the compound field. For example, pass in `Account_Site__c` instead of `Account_Site__latitude__s` and `Account_Site__longitude__s`. This behavior is different from the limitation listed at [Geolocation Custom Field](https://help.salesforce.com/articleView?id=custom_field_geolocate_overview.htm).

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form
    object-api-name="Account"
    record-id="001R00000000000000"
>
    <lightning-messages></lightning-messages>
    <lightning-input-field
        field-name="Name"
        readonly="true"
    ></lightning-input-field>
    <lightning-input-field field-name="Account_Site__c"></lightning-input-field>
    <lightning-button
        type="submit"
        label="Update"
        class="slds-m-top_small"
        variant="brand"
    ></lightning-button>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

Geocode fields like `ShippingLatitude` and `ShippingLongitude` are part of standard address fields, such as `ShippingAddress`.
Geocode fields aren't visible on records, so they won't display when you pass the address field `ShippingAddress` to `lightning-input-field`.
To use geocode fields, pass in both the latitude and longitude fields.

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form
    object-api-name="Account"
    record-id="001R00000000000000"
>
    <lightning-messages></lightning-messages>
    <lightning-input-field
        field-name="Name"
        readonly="true"
    ></lightning-input-field>
    <lightning-input-field
        field-name="ShippingLatitude"
    ></lightning-input-field>
    <lightning-input-field
        field-name="ShippingLongitude"
    ></lightning-input-field>
    <lightning-button
        type="submit"
        label="Update"
        class="slds-m-top_small"
        variant="brand"
    ></lightning-button>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

For more information, see [Geocode Fields and Accuracy](https://help.salesforce.com/articleView?id=data_dot_com_clean_geocode_information_fields.htm) in Salesforce Help.

## Lookup Fields

Lookup fields associate two records together. For example, a case record can associate the case to a contact using the `ContactId` field.

This example creates a new case using several text fields and a contact lookup field. The lookup field uses the `onchange` event handler to return the selected contact Id.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        object-api-name="Case"
        onsuccess={handleSuccess}
    >
        <div class="slds-m-around_medium">
            <lightning-input-field
                field-name="SuppliedName"
            ></lightning-input-field>
            <lightning-input-field
                field-name="ContactId"
                onchange={handleChange}
            ></lightning-input-field>
            <lightning-input-field
                field-name="Description"
            ></lightning-input-field>
            <div class="slds-m-top_medium">
                <lightning-button
                    variant="brand"
                    type="submit"
                    name="save"
                    label="Create Case"
                ></lightning-button>
            </div>
        </div>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

Use the `event.detail.value` property to retrieve the Id of the selected contact record on the lookup field. Although the Id is returned in an array, multi-select lookups are currently not supported. To return the saved record, use the `success` event. For more information on the `success` event, see the [lightning-record-edit-form](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) documentation.

```javascript
import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

export default class LookupExample extends LightningElement {
  handleSuccess(event) {
    this.dispatchEvent(
      new ShowToastEvent({
        title: "Success",
        message: event.detail.apiName + " created.",
        variant: "success",
      }),
    );
  }

  handleChange(event) {
    console.log("You selected an account: " + event.detail.value[0]);
  }
}
```

## Name Fields

Name fields are available on contact, lead, and user records.

A name compound field on records includes these constituent fields:

- `FirstName`
- `MiddleName`
- `LastName`
- `Salutation`
- `Suffix`

The `MiddleName` and `Suffix` fields are not enabled by default. For more information, see [User Fields](https://help.salesforce.com/articleView?id=user_fields.htm) in Salesforce Help.

The `Salutation` field is available as part of the `Name` compound field for contacts and leads. Passing in `Salutation` to `field-name` directly is not supported.

The `InformalName` field is not supported for editing on `lightning-record-edit-form`.

This example displays the name compound field with `Salutation`, `FirstName`, `MiddleName`, and `LastName` fields to create a contact record. To create a lead record instead, set `object-api-name="Lead"`.

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form object-api-name="Contact">
    <lightning-messages></lightning-messages>
    <lightning-input-field field-name="Name"></lightning-input-field>
    <!-- Other fields here -->
    <lightning-button
        class="slds-m-top_small"
        variant="brand"
        type="submit"
        label="Create contact"
    ></lightning-button>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

To work with the user object, specify the constituent fields instead of using the `Name` compound field.

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form object-api-name="User">
    <lightning-messages></lightning-messages>
    <lightning-input-field field-name="FirstName"></lightning-input-field>
    <lightning-input-field field-name="MiddleName"></lightning-input-field>
    <lightning-input-field field-name="LastName"></lightning-input-field>
    <!-- Other fields here -->
    <lightning-button
        class="slds-m-top_small"
        variant="brand"
        type="submit"
        label="Create contact"
    ></lightning-button>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

#### Read-Only Fields

If you want to display record data without allowing users to modify it, consider using the `read-only` attribute on `lightning-input-field`. For example, you want to enable users to edit the Name and Phone fields but not the DoNotCall field.

```html
<lightning-record-edit-form object-api-name="Contact">
  <lightning-messages></lightning-messages>
  <lightning-input-field
    field-name="DoNotCall"
    read-only
  ></lightning-input-field>
  <lightning-input-field field-name="Name"></lightning-input-field>
  <lightning-input-field field-name="Phone"></lightning-input-field>
  <div class="slds-var-m-top_medium">
    <lightning-button
      variant="brand"
      type="submit"
      name="save"
      label="Save"
    ></lightning-button>
  </div>
</lightning-record-edit-form>
```

These field types don't support the read-only mode.

- Rich text
- Picklist
- Multi-select picklist
- Lookup

A read-only field isn't submitted with the form. A read-only field isn't disabled and it can receive focus.
However, a read-only checkbox field can't receive focus. For more information, see [Checkbox in the `lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Usage Considerations

When using `lightning-input-field`, the field label for certain fields can differ from those displayed on a standard record page. For example, the `Name` field on the opportunity object displays "Name" instead of "Opportunity Name" while the `Name` field on the account object displays "Account Name".

Use `lightning-input-field` only as a direct child of `lightning-record-edit-form`. Don't include `lightning-input-field` components in a template that an aura component composes.

This component uses `button` elements for picklists to comply with the [Lightning Design System combobox blueprint](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) for select-only comboboxes.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="inputField" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=bb15e65e242def0369047e76605972cf72ca6f75351bf076ec08fd7c4fa4eff4 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputLocation/lightning-input-location.md -->


# Input Location

**`lightning-input-location`**

Represents a geolocation compound field that accepts a latitude and longitude value.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="inputLocation" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-input-location` component represents a geolocation compound field
that accepts user input for a latitude and longitude value. Latitude and
longitude are geographic coordinates specified in decimal degrees. The
geolocation compound field allows you to identify locations by their latitude
and longitude. The latitude field accepts values within -90 and 90, and the
longitude field accepts values within -180 and 180. An error message is
displayed when you enter a value outside of the accepted range.

Here are a few examples of latitudes: -30, 45, 37.12345678, -10.0. Values such
as 90.5 or -90.5 are not valid latitudes.

Here are a few examples of
longitudes: -100, -120.9762, 115.84. Values such as 180.5 or -180.5 are not
valid longitudes.

This example displays a geolocation compound field with a latitude of
37.7938460 and a longitude of -122.3948370.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-location
        label="My Coordinates"
        latitude="37.7938460"
        longitude="-122.3948370"
    >
    </lightning-input-location>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input-field` implements the form element blueprint in the Salesforce Lightning Design System (SLDS). The input fields adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element](https://v1.lightningdesignsystem.com/components/form-element/)         | [Form Element](https://www.lightningdesignsystem.com/components/form-element/)                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Input Validation

Client-side input validation is available for this component. You can require
the user to make a selection by including the `required` attribute. An error message
is automatically displayed when a user interacts with the field but leaves it empty.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` properties. For more information, see the
[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Custom Events

**`change`**

The event fired when a value is changed in the `lightning-input-location` component.

The `change` event returns the following parameters.

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| latitude  | string | The latitude of the location.  |
| longitude | string | The longitude of the location. |

The `change` event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="inputLocation" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2808e8fab1f7cfe838bd388d20cdf25ea810bf3930bc12edddc132e627f4fa6e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputName/lightning-input-name.md -->


# Input Name

**`lightning-input-name`**

Represents a name compound field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="inputName" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-input-name` component is a name compound field represented by HTML
`input` elements of type `text`. The Salutation field is a dropdown menu that
accepts an array of label-value pairs.

By default, `lightning-input-name` displays Salutation, First Name, and Last Name fields.
Use the `fields-to-display` attribute to specify a different list of fields to display. The component supports these field names for `fields-to-display`.

- `firstName`
- `lastName`
- `middleName`
- `informalName`
- `suffix`
- `salutation`

## Design

`lightning-input-name` implements the form element blueprint in the Salesforce Lightning Design System (SLDS). The input fields adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element](https://v1.lightningdesignsystem.com/components/form-element/)                               | [Form Element](https://www.lightningdesignsystem.com/components/form-element/)                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Specify Field Names

To provide initial values for fields, specify the field names as attributes in the component by using the dash-separated format of the field names. For example, specify `first-name` instead of `firstName`. Use the `options` attribute to specify the values to display in the Salutation dropdown menu.

This example creates a simple input name, consisting of just the First Name and Last Name fields, without specifying initial values. The rendered fields display default placeholder text.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-input-name label="My Name" fields-to-display={fields}>
        </lightning-input-name>
    </div>
</template>
```
<!-- prettier-ignore-end -->

JavaScript file:

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

export default class InputName extends LightningElement {
  fieldList = ["firstName", "lastName"];
  get fields() {
    return this.fieldList;
  }
}
```

This example creates an input name that specifies values for first name, middle
name, last name, informal name, suffix. The Salutation dropdown menu is set to display
"Mr." by default. The `fields-to-display` attribute determines which fields are
rendered. Although all possible fields are specified inside the component, only the
First Name and Last Name display.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-input-name
            label="Contact Name"
            first-name="John"
            middle-name="Middleton"
            last-name="Doe"
            informal-name="Jo"
            suffix="The 3rd"
            salutation="Mr."
            options={salutationOptions}
            fields-to-display={fields}
        >
        </lightning-input-name>
    </div>
</template>
```
<!-- prettier-ignore-end -->

JavaScript file:

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

export default class InputName extends LightningElement {
  salutationsList = [
    { label: "Mr.", value: "Mr." },
    { label: "Ms.", value: "Ms." },
    { label: "Mrs.", value: "Mrs." },
    { label: "Dr.", value: "Dr." },
    { label: "Prof.", value: "Prof." },
  ];

  get salutationOptions() {
    return this.salutationsList;
  }

  fieldList = ["firstName", "lastName"];
  get fields() {
    return this.fieldList;
  }
}
```

`lightning-input-name` uses the `onchange` event handler to listen to a change to its field values.

<!-- prettier-ignore-start -->
```html
<p>Your first name: {firstname}</p>
<lightning-input-name
    label="Name"
    first-name={firstname}
    middle-name="Middleton"
    last-name="Doe"
    options={salutationOptions}
    onchange={handleChange}></lightning-input-name>
```
<!-- prettier-ignore-end -->

To bind the input value on the name fields, use the `event.target` property.

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

export default class InputNameBase extends LightningElement {
  firstname = "John";
  salutationsList = [
    { label: "Mr.", value: "Mr." },
    { label: "Ms.", value: "Ms." },
    { label: "Mrs.", value: "Mrs." },
    { label: "Dr.", value: "Dr." },
    { label: "Prof.", value: "Prof." },
  ];

  get salutationOptions() {
    return this.salutationsList;
  }

  handleChange(event) {
    this.firstname = event.target.firstName;
  }
}
```

See the [Custom Events](#custom-events) section for a list of `event.target` properties. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).

## Use the Locale Information

In Lightning Experience, the `locale` value corresponds to the **Locale** field on the Language &amp; Time Zone page in the [user's personal settings](https://help.salesforce.com/s/articleView?id=xcloud.usersetup_lang_time_zone.htm).

By default, your org's locale setting determines the order of the name fields.

For example, if you select "Japanese (Japan)" in the **Locale** field, `lightning-input-name` uses `ja-JP` as the locale.

To override the locale on your user's settings, provide your own `locale` value. Specify any locale code from the list of [Supported Number, Name, and Address Formats (ICU)](https://help.salesforce.com/s/articleView?id=xcloud.admin_supported_locales.htm).

<!-- prettier-ignore-start -->
```html
<lightning-input-name
    label="Contact Name"
    first-name="John"
    last-name="Doe"
    salutation="Mr."
    locale="fr-FR"></lightning-input-name>
```
<!-- prettier-ignore-end -->

If you don't specify the `locale` attribute, `lightning-input-name` defaults to the user's locale setting in the org.

<!-- prettier-ignore-start -->
```html
<h2>User's locale: {userLocale}</h2>
<!--No locale specified -->
<lightning-input-name
    lwc:ref="name"
    label="Contact Name"
    first-name="John"
    middle-name="Middleton"
    last-name="Doe"
    informal-name="Jo"
    suffix="The 3rd"
    salutation="Mr."
    fields-to-display={fields}></lightning-input-name>
```
<!-- prettier-ignore-end -->

In this example, the `userLocale` property returns `ja-JP` based on the org user's settings.

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

export default class LocaleExample extends LightningElement {
  userLocale = "";

  fields = ["firstName", "lastName", "middleName", "salutation", "suffix", "informalName"];

  renderedCallback() {
    this.userLocale = this.refs.name.locale;
  }
}
```

If you pass in an invalid locale, the component uses `en-US`. The locale supports both hyphens and underscores, for example, `en-US` or `en_US`.

## Usage Considerations

You can use custom labels that display translated values. For more information, see the
[Access Static Resources, Labels, Internationalization Properties, and User IDs](https://developer.salesforce.com/docs/platform/lwc/guide/create-global-value-providers).

This component uses `button` elements for dropdown menus to comply with the [Lightning Design System combobox blueprint](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) for select-only comboboxes.

## Input Validation

When you set `required`, a red asterisk is displayed on the Last Name
field to indicate that it's required. An error message is displayed below the
Last Name field if a user interacted with it and left it blank. The `required`
attribute is not enforced and you must validate it before submitting a form
that contains a name compound field.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object of the Constraint Validation API. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` properties. For more information, see the
[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

Let's say you have a `lightning-button` component that calls the `handleClick`
method. You can display the error message when a user clicks the
button without providing a value for the Last Name field.

```javascript
handleClick: () => {
  var name = this.template.querySelector("lightning-input-name");
  var isValid = name.checkValidity();
  if (isValid) {
    alert("Creating new contact for " + this.name);
  } else {
    name.showHelpMessageIfInvalid();
  }
};
```

You can override the default message by providing your own value for `messageWhenValueMissing`.

To programmatically display error messages on invalid fields, use the `reportValidity()` method. For custom validity error messages, display the message using `setCustomValidityForField()` and `reportValidity()`. For more information, see the [`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Custom Events

**`change`**

The event fired when an item is changed in the `lightning-input-name` component.

The `change` event returns the following parameters.

| Parameter    | Type   | Description                           |
| ------------ | ------ | ------------------------------------- |
| salutation   | string | The value of the salutation field.    |
| firstName    | string | The value of the first name field.    |
| middleName   | string | The value of the middle name field.   |
| lastName     | string | The value of the last name field.     |
| informalName | string | The value of the informal name field. |
| suffix       | string | The value of the suffix field.        |
| validity     | object | The validity state of the element.    |

The `change` event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[Use Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components)

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="inputName" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f593318c9c8a9525bb24f6500b944ecf8b65bb027568868fe029299a06908581 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/inputRichText/lightning-input-rich-text.md -->

# Input Rich Text

**`lightning-input-rich-text`**

A WYSIWYG editor with a customizable toolbar for entering rich text

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A `lightning-input-rich-text` component creates a rich text editor based on the
Quill JS library, enabling you to add, edit, format, and delete rich text. You
can create rich text editors with different toolbar configurations.

Pasting rich content into the editor is supported if the feature is available
in the toolbar. For example, you can paste bold text if the bold button is
available in the toolbar.

This example creates a rich text editor by using `lightning-input-rich-text` and sets its content during
initialization. The `lightning-formatted-rich-text` component is used to display the formatted output.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        value={myVal}
        onchange={handleChange}>
    </lightning-input-rich-text>

    <lightning-formatted-rich-text value={myVal}></lightning-formatted-rich-text>
</template>
```
<!-- prettier-ignore-end -->

`lightning-input-rich-text` uses the `onchange` event handler to listen to a change to its value.

Initialize the rich text content in JavaScript. To bind the input value in the editor, use the `event.target.value` property. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).

```javascript
import { LightningElement } from "lwc";
export default class RichTextExample extends LightningElement {
  myVal = "<strong>Hello!</strong>";

  handleChange(event) {
    this.myVal = event.target.value;
  }
}
```

Depending on the HTML markup that's passed to the component's `value` attribute, there can be a visual difference between the view state of the component, and upon initial focus on the editor. On focus, the editor removes invalid and uncommon patterns of nested HTML tags. For example, by using `<p>` within a `<li>` tag results in the removal of the `<p>` tag.

The editor also removes inline styles from `<p>` and `<div>` tags. To preserve inline styles, use a `<span>` tag instead.

```javascript
myVal =
  '<p><span style="font-family: Times New Roman;font-size: 20px;"> Using p and span tags </span></p>';
```

The `required` attribute marks the text editor as requiring user input. To display an asterisk to indicate a required input,
set `label-visible` and `required`. A default label displays after the asterisk. See the [Accessibility](#accessibility) section for more information about labels.

The component doesn't validate for required input. See [Input Validation](#input-validation) for more information.

## Design

`lightning-input-rich-text` implements the rich text editor blueprint in the Salesforce Lightning Design System (SLDS). The rich text editor adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Rich Text Editor](https://v1.lightningdesignsystem.com/components/rich-text-editor)                        | [Rich Text Editor](https://www.lightningdesignsystem.com/components/rich-text-editor/)                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Customize the Toolbar

The toolbar provides menus and buttons that are ordered within these categories.

1. `FORMAT_FONT`: Font family and size menus. The font menu provides several font selections: Arial, Courier, Garamond, Salesforce Sans, Tahoma, Times New Roman, and Verdana. The font selection defaults to Salesforce Sans with a size of 13px. Supported font sizes are: 8, 9, 10, 11, 12, 13, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, and 72.
2. `FORMAT_TEXT`: Bold, Italic, Underline, and Strikethrough buttons.
3. `FORMAT_BODY`: Bulleted List, Numbered List, Indent, and Outdent buttons.
4. `ALIGN_TEXT`: Left Align Text, Center Align Text, and Right Align Text buttons.
5. `INSERT_CONTENT`: Image and Link buttons.
6. `REMOVE_FORMATTING`: Remove formatting button, which stands alone at the end of the toolbar.

You can disable buttons by category by using the `disabled-categories` attribute.

This example shows how to disable the `FORMAT_TEXT` category for Bold, Italic, Underline, and Strikethrough buttons.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        value={myVal}
        disabled-categories="FORMAT_TEXT"
    >
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

## Customize Editor Formatting

Customize the editor by using the `formats` attribute, which lists individual formats that the editor supports within a toolbar category.

By default, `lightning-input-rich-text` enables some formats with a corresponding toolbar button. Formats that don't provide a toolbar button support only pasted content. For example, the `table` and `header` formats are enabled by default but support pasted content only, and don’t provide toolbar buttons. You can't create or edit a table or a header in the rich text editor.

| Format Name  | Description                                                        | Enabled by Default | Provides a Toolbar Button | Toolbar Category    |
| ------------ | ------------------------------------------------------------------ | ------------------ | ------------------------- | ------------------- |
| `font`       | Changes the font on text                                           | Y                  | Y                         | `FORMAT_FONT`       |
| `size`       | Changes the size on text                                           | Y                  | Y                         | `FORMAT_FONT`       |
| `bold`       | Bolds text                                                         | Y                  | Y                         | `FORMAT_TEXT`       |
| `italic`     | Italicizes text                                                    | Y                  | Y                         | `FORMAT_TEXT`       |
| `underline`  | Underlines text                                                    | Y                  | Y                         | `FORMAT_TEXT`       |
| `strike`     | Adds a strikethrough to text                                       | Y                  | Y                         | `FORMAT_TEXT`       |
| `list`       | Creates a bulleted or numbered list                                | Y                  | Y                         | `FORMAT_BODY`       |
| `indent`     | Applies an indent or outdent to text                               | Y                  | Y                         | `FORMAT_BODY`       |
| `align`      | Aligns text to the left, center, or right                          | Y                  | Y                         | `ALIGN_TEXT`        |
| `link`       | Creates a link on text                                             | Y                  | Y                         | `INSERT_CONTENT`    |
| `image`      | Adds an image                                                      | Y                  | Y                         | `INSERT_CONTENT`    |
| `clean`      | Removes formatting from content                                    | Y                  | Y                         | `REMOVE_FORMATTING` |
| `table`      | Supports pasting of tables                                         | Y                  |                           |
| `header`     | Supports pasting of headers                                        | Y                  |                           |
| `color`      | Provides color selection for text                                  |                    | Y                         |
| `background` | Supports pasting of text with background colors                    |                    |                           |                     |
| `code`       | Supports pasting of inline text with code formatting               |                    |                           |                     |
| `code-block` | Supports pasting of blocks of text with code formatting            |                    |                           |                     |
| `script`     | Supports pasting of text with superscript and subscript formatting |                    |                           |                     |
| `blockquote` | Supports pasting of block quotes                                   |                    |                           |                     |
| `direction`  | Supports RTL and LTR text                                          |                    |                           |                     |

The `formats` attribute must include the complete list of formats to enable. If you pass in a subset of the formats, all other formats are removed from the toolbar, and pasted content by using the missing formats aren’t rendered correctly in the text editor.

This example shows how to add the `color` format to the editor, which adds a text color button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text value={myVal} formats={formats}>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

To enable the `color` format, add it to the list of formats.

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

export default class ColorFormatExample extends LightningElement {
  myVal = "**Hello**";
  formats = [
    "font",
    "size",
    "bold",
    "italic",
    "underline",
    "strike",
    "list",
    "indent",
    "align",
    "link",
    "image",
    "clean",
    "table",
    "header",
    "color",
  ];
}
```

This example shows how to remove `strike` from the editor, which removes the strikethrough button from the toolbar.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text value={myVal} formats={formats}>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

Remove the `strike` format from the list of formats to enable.

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

export default class StrikeFormatExample extends LightningElement {
  myVal = "**Hello**";
  formats = [
    "font",
    "size",
    "bold",
    "italic",
    "underline",
    "list",
    "indent",
    "align",
    "link",
    "image",
    "clean",
    "table",
    "header",
  ];
}
```

## Apply Formats Programmatically

To set formats programmatically, use the `setFormat()` method.

This example shows a button that applies a list of formats on content in the editor.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        placeholder="Type something interesting"
        formats={allowedFormats}
    >
    </lightning-input-rich-text>
    <lightning-button label="Set formats" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Pass in the formats to `setFormat()`.

This example passes formats to create right-aligned, Garamond font text
that is bold, italic, and colored red, on a black background. The `allowedFormats`
must also be set because `background` and `color` aren’t default formats.

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

export default class FormatsExample extends LightningElement {
  allowedFormats = [
    "font",
    "size",
    "bold",
    "italic",
    "underline",
    "strike",
    "list",
    "indent",
    "align",
    "link",
    "image",
    "clean",
    "table",
    "header",
    "color",
    "background",
  ];

  appliedFormats = {
    align: "right",
    font: "garamond",
    size: 10,
    bold: true,
    italic: true,
    color: "mediumvioletred",
    background: "#000000",
  };

  handleClick() {
    const editor = this.template.querySelector("lightning-input-rich-text");
    editor.setFormat(this.appliedFormats);
  }
}
```

To retrieve the formats, use `getFormat()`. The rich text editor removes any font values that are not supported.

Supported formats are as follows.

| Key        | Values                                                           | Description                                                                                                                                                                                   |
| ---------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| align      | left, right, center                                              | Aligns the text to the left, right, or centers the text block where the cursor is located.                                                                                                    |
| background | color name, hex value                                            | Applies the specified color to the background of the selected text. If no text is selected, applies to the text you enter next. Specify color by HTML color name or hexadecimal value.        |
| bold       | true, false                                                      | Applies bold format to selected text. If no text is selected, applies to the text you enter next.                                                                                             |
| code       | true, false                                                      | Applies code format inline to selected text. If no text is selected, applies to the text you enter next.                                                                                      |
| code-block | true, false                                                      | Applies code format to the line where the cursor is located. This is a block-level format, so it applies to block-level elements such as `<p>`.                                               |
| color      | color name, hex value                                            | Applies the specified color to the selected text. If no text is selected, applies to the text you enter next. Specify color by HTML color name or hexadecimal value.                          |
| font       | default, sans-serif, courier, verdana, tahoma, garamond, serif   | Applies the specified font to the selected text. If no text is selected, applies to the text you enter next. The default sans-serif font is Arial. The default serif font is Times New Roman. |
| header     | 1, 2, 3, 4, 5, 6                                                 | Applies the specified header level to the line where the cursor is located.                                                                                                                   |
| italic     | true, false                                                      | Applies italic format to selected text. If no text is selected, applies to the text you enter next.                                                                                           |
| link       | url                                                              | Creates a link to the specified URL by using the selected text as the link text. Requires text to be selected before applying the format.                                                     |
| size       | 8, 9, 10, 11, 12, 13, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, 72 | Applies the specified font size to the selected text. If no text is selected, applies to the text you enter next. The default font size is 13.                                                |
| strike     | true, false                                                      | Applies strikethrough format to selected text. If no text is selected, applies to the text you enter next.                                                                                    |
| underline  | true, false                                                      | Applies underline format to selected text. If no text is selected, applies to the text you enter next.                                                                                        |

## Insert Text Programmatically (Beta)

You can insert text programmatically in the editor with the `setRangeText()` method, replacing content
or inserting new content. The method can be used in an action for custom buttons.

The `setRangeText()` method follows the API of the standard `HTMLInputElement.setRangeText()` method described on
[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setRangeText).

The `lightning-input-rich-text` component has one exception to the `setRangeText()` standard behavior which
is described in [Insert Formatted Text Programmatically (Beta)](#insert-formatted-text-programmatically-beta).

`setRangeText()` supports these parameters.

| Parameter   | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| replacement | string | The string to insert. HTML markup is not supported.           |
| start       | number | The 0-based index of the first character to replace.          |
| end         | number | The 0-based index that follows the last character to replace. |
| selectMode  | string | Defines how the selection is set after the text is inserted.  |

Valid values for selectMode are:

- `select` - Selects the inserted text.
- `start` - Moves the selection to just before the inserted text.
- `end` - Moves the selection to just after the inserted text.
- `preserve` - Attempts to preserve the selection in effect before the insertion. This is the default.

To insert replacement text at the current cursor location, specify only the
replacement string and no other parameters. After the insertion, the cursor
remains at the original location. If text is selected when the insertion occurs,
the text is replaced.

This example uses `setRangeText()` to insert some text at the beginning of the line
without replacing any content.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text placeholder="Type something interesting">
    </lightning-input-rich-text>
    <lightning-button label="Insert Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The selectMode value causes the cursor to remain at the end of the inserted content.

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

export default class SetRangeTextExample extends LightningElement {
  start = 0;
  end = 0;
  selectMode = "end";

  handleClick() {
    const editor = this.template.querySelector("lightning-input-rich-text");
    editor.setRangeText("Some new text", this.start, this.end, this.selectMode);
  }
}
```

This example inserts a space at index 10 and removes characters at index 10 through 14.
The resulting content is `0123456789 567890`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text value="012345678901234567890">
    </lightning-input-rich-text>
    <lightning-button label="Clip Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

You can omit the final parameter of `setRangeText()` to use the default select mode, `preserve`.

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

export default class SetRangeTextPreserveExample extends LightningElement {
  handleClick() {
    const editor = this.template.querySelector("lightning-input-rich-text");
    editor.setRangeText(" ", 10, 15);
  }
}
```

These examples describe the insertion behavior with various `setRangeText()` parameter values.

```javascript
// Insert text at cursor position if nothing is selected. Replace any selected text.
// No selectMode is specified, so the original selection is preserved.
// The inserted text is selected if it replaced selected text.
editor.setRangeText("Some new text");

// Insert text to replace characters beginning at index 10 (the 11th
// character) and ending at index 15 (the 16th character). The character
// at index 14 is the last character replaced.
// No selectMode is specified, so the original selection is preserved.
editor.setRangeText("Some new text", 10, 15);

// Insert text as described in the previous example, and then select
// the new text.
editor.setRangeText("Some new text", 10, 15, "select");

// Insert text as described, and place cursor ahead of the new text.
editor.setRangeText("Some new text", 10, 15, "start");

// Insert text as described, and place cursor after the new text.
editor.setRangeText("Some new text", 10, 15, "end");

// Insert text as described, and return to the previous selection state.
editor.setRangeText("Some new text", 10, 15, "preserve");
```

If text is selected when selectMode is `preserve` and start and end values are specified,
the text insertion has no effect on the selected text. The text remains selected and isn’t replaced.

However, if the start and end values lie within the currently selected range, part of the selected text is replaced.
For example, suppose you have selected text at index 1 through 5, 0**12345**6789. If you call
`setRangeText('Insert', 2, 7)` the result is 0**1Insert**789.

## Insert Formatted Text Programmatically (Beta)

The standard `setRangeText()` method uses `preserve` selectMode behavior
if you don't specify start or end index parameters, as in this example.

`editor.setRangeText('Some new text');`

If no text is selected when the method is called, the replacement text is inserted
at the cursor position. After the insertion, no text is selected, which preserves
the select mode. If text is selected when the method is called, that text is
replaced and the inserted text is then selected.

With the standard `setRangeText()` method, you can only specify a different selectMode behavior
if you specify the index parameters too. You can't pass null or undefined
values to the parameters.

In contrast, the `lightning-input-rich-text` component's `setRangeText()` method accepts
`undefined` as a value for the start and end index parameters. You can then set the
selectMode to any valid value.

This non-standard behavior enables you to set the selectMode `select` with the
`setRangeText()` method to insert text, select the inserted text,
and then run `setFormat()` on the selected text. The text is inserted at the cursor
position if nothing is selected. If text is selected, it is replaced with the new text.

This example sets the formats supported in the text editor, and the initial content to
display in the editor panel. The separate button inserts new formatted text.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        formats="font, bold, italic, underline, strike, list, indent, align,
        link, image, clean, code, code-block, color, background, mention, header"
        value="01234567890"
    >
    </lightning-input-rich-text>

    <lightning-button label="Insert bold green text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The `handleClick()` function uses `setRangeText()` to insert text at the cursor position.
Specifying `undefined` for start and end index parameters enables the selectMode value to
be passed. The selectMode value is `select` so the inserted text is then selected. The
`setFormat()` method applies formats to the selected text to make it bold and colored green.

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

export default class InsertFormattedExample extends LightningElement {
  handleClick() {
    const editor = this.template.querySelector("lightning-input-rich-text");
    const textToInsert = "Go Green";
    editor.setRangeText(textToInsert, undefined, undefined, "select");
    editor.setFormat({ bold: true, color: "green" });
  }
}
```

## Add Custom Buttons

You can add custom buttons to the rich text editor. Custom buttons are contained
in a button group that displays at the end of the toolbar.

To create a button group, add the `lightning-rich-text-toolbar-button-group` component
in a named slot called `toolbar` inside `lightning-input-rich-text`.

Place a `lightning-rich-text-toolbar-button` component for each custom button
inside `lightning-rich-text-toolbar-button-group`.

For more information about custom buttons,
see [`lightning-rich-text-toolbar-button`](/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button.html) documentation.

## Insert Images

Clicking the image button opens a file picker that you can use to locate and select an image on your device.
The image is uploaded to the org and inserted inline in the text editor.

Supported image types are png, jpg, jpeg, and gif. The maximum image
size is 1MB.

Resizing of images is not supported. Copy and pasting of images is not supported,
although it might work on some combinations of browsers and operating systems.
By default, guest users can't upload images to Experience Builder sites.

By default, the image is visible only in the text editor as you insert it,
and when you display the editor output, for example by using the `lightning-formatted-rich-text`
component. However, the image can be accessed by any org user who has access to the image URL.

When you use `lightning-input-rich-text` in Salesforce, pasting an image from an HTTP source results in the display of a broken image icon. Mixed content is blocked in Salesforce to improve security. We recommend uploading the image as a static resource first before by using it in the component. Alternatively, enable the image toolbar button so your users can upload the image to the org.

For LWR sites in Experience Cloud, the rich text editor doesn't display the image button on the toolbar and doesn't support image uploads.

**important:** For images that shouldn't be accessible to all org users, you must restrict access to the images.

## Restrict Access to Uploaded Images

_Uploaded image files are accessible to all org users by default._

Restrict access to the image by using the `share-with-entity-id` attribute
to specify the ID of a record, org, group, or user that should have access to the image.
The image that's inserted into the text editor is shared with the entity that corresponds to that ID.

If the ID corresponds to:

- the org: all users in the org have access to the image.
- a group: only users in that group can see the image.
- a record: anyone with access to that record can see the image.
- a user: only that user can see the image.

When you use the `share-with-entity-id` attribute, the image is more
restricted, but it's also viewable in the Files tab. When you share an image
with a record ID, the image is available in the Notes
and Attachments related list of the record page. Only users with
permissions to the record can see the image in any of these locations.

This example shows the text editor used in a record page, where the image
is shared with the record ID of the record that's displayed.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        label="Make a note"
        share-with-entity-id={recordId}
    >
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

Use the `@api` decorator to create a public `recordId` property.
The record page sets the property to the ID of the current record.

```javascript
import { LightningElement, api } from "lwc";
export default class RichTextExample extends LightningElement {
  @api recordId;
}
```

For more information, see [Make a Component Aware of Its Record Context](https://developer.salesforce.com/docs/platform/lwc/guide/use-record-context) in the Lightning Web Components Developer Guide.

### Upload Images Manually (Developer Preview)

**note:** Uploading images manually 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 in production with these commands or tools.

By default, inserting an image into the rich text editor uploads the image to your org immediately.
To prevent immediate uploads, use the `manual-image-upload` attribute. Preventing automatic uploads
enables you to defer the upload, giving you control to upload the image only when you're ready.

Additionally, customize image upload behavior by using the component's [custom events](#custom-events),
such as `imageupload` and `imageuploaderror`.

<!--prettier-ignore -->
```html
<template>
  <lightning-input-rich-text
    manual-image-upload
    onimageupload={handleImageUpload}
    onimageuploaderror={handleImageUploadError}
    lwc:ref="editor"
  ></lightning-input-rich-text>
  <lightning-button label="Save" onclick={handleSave}></lightning-button>
</template>
```

For example, defer the upload so you can:

- Upload images only when a form is submitted
- Validate content before uploading
- Reduce unnecessary uploads if users delete images before saving

When you use the `manual-image-upload` attribute, inserting an image also assigns a temporary local URL to the image. To upload pending images to your org, call `uploadPendingImages()`.

### `uploadPendingImages()`

`uploadPendingImages()` uploads images to your org, updating the image's `src` value from the temporary URL to a permanent URL.
When you specify `manual-image-upload`, the `lightning-input-rich-text` component assigns a temporary local URL for an image that's inserted in the rich text editor.

**note:** Temporary URLs are valid only in the current browser session. If users navigate away or refresh before uploading the image, their pending images are lost. We recommend that you handle unsaved states by providing visual notifications to the user.

When the image is successfully uploaded, a permanent URL that's based in your org replaces the temporary URL.
The component returns these URLs via its [custom events](#custom-events).

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

export default class ManualUploadExample extends LightningElement {

    handleImageUpload(event) {
      if(event.detail.downloadUrl) {
        // Show a list of image download URLs
      }
    }

    handleImageUploadError(event) {
      if (event.detail.reason === 'SIZE_EXCEEDED') {
          // Show validation feedback to the user
      }
    }

    async handleSave() {
      const results = await this.refs.editor.uploadPendingImages();
      const failures = results.filter(r => !r.success);
      if (failures.length > 0) {
        // Show error, user can retry
        return;
      }
      // All images uploaded -- value now contains permanent URLs
      await saveRecord(this.refs.editor.value);
    }
  }
}
```

**note:** By default, uploaded image files are accessible to all org users.
To restrict image access to specific records, groups, or users, specify the `share-with-entity-id` attribute.

The `uploadPendingImages()` method returns a promise that resolves to an array of the results for each image. Each result object has these properties.

| Property         | Type    | Description                                                                                                                                        |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| imageId          | string  | The image's tracking ID, which uses `pending-img-` followed by the timestamp that represents when the image was inserted, and a unique identifier. |
| file             | file    | The image file to be uploaded.                                                                                                                     |
| success          | boolean | Returns true if the image upload is successful, or false otherwise.                                                                                |
| downloadUrl      | string  | The permanent URL for the uploaded image. `downloadUrl` isn't returned when the upload fails.                                                      |
| contentVersionId | string  | The ContentVersion ID for the image. ContentVersion IDs begin with `068`. `contentVersionId` isn't returned when the upload fails.                 |
| error            | string  | The error message, which is returned when `success` is `false`.                                                                                    |

When there are no pending images to be uploaded, an empty array is returned.

When the image upload is successful, the result object for an image returns:

```javascript
{ imageId, file, success: true, downloadUrl, contentVersionId }
```

When the image upload fails, the result object for an image returns:

```javascript
{ imageId, file, success: false, error }
```

### Manual Image Upload Considerations

A pending image is an image that you insert in the rich text editor, which is then assigned a temporary local URL. Consider these upload behaviors for pending images.

- Images that fail to upload remain in the rich text editor. Call `uploadPendingImages()` again to attempt another upload. To remove an image from the upload queue, delete it from the editor.
- Images over 1 MB are rejected immediately. They aren't inserted into the rich text editor and the `imageuploaderror` event fires. A notification to inform you about the image size exceeding 1 MB does not appear. We recommend that you handle the error to provide a visual notification for users.
- Images that you delete from the editor before upload are removed immediately and their temporary URLs are no longer available.
- Images that failed to upload maintain their temporary URLs until a successful image upload.

Images that aren't uploaded yet maintain their temporary URLs in the image's `src` attribute and the `lightning-input-rich-text` component's `value` attribute. If you access the `value` before calling `uploadPendingImages()`, the value contains `blob:` URLs. Temporary images are removed after a page reload or if you open the same page in a different session. If you reload the page, you must re-insert the images before you can upload them.

**note:** If an image upload fails, the [`imageuploaderror` event](#custom-events) is fired. When uploading multiple images, the `imageuploaderror` event is fired for each failed upload and the `imageupload` event is fired for each successful upload.

Consider these common errors and resolutions when uploading an image from a rich text editor.

- The file size exceeded the 1 MB limit: Resize or compress the image to meet the file size requirements.
- The image format isn't supported: Convert the image to a supported format (.png, .jpg, or .gif).
- The record or user ID doesn't exist: When using `share-with-entity-id`, make sure the ID is valid.
- The user who attempts an upload has insufficient permissions: Users can work with their admins to make sure they are assigned the correct user profile or permission set.

`lightning-input-rich-text` deletes the pending image in these scenarios.

- After a successful upload, the image's `src` value returns the permanent URL.
- When the `lightning-input-rich-text` component is removed from the DOM, such as when you navigate away from the page, the image is removed from the text editor. To use the image after the component loads again, reinsert the image in the rich text editor.
- If the user deletes the image from the rich text editor, the component revokes the temporary URL. Inserting the image again results in a different temporary URL.

## Input Validation

`lightning-input-rich-text` doesn't provide built-in validation but you can wire
up your own validation logic. Set the `valid` attribute to `false` to change
the border color of the rich text editor to red. Set the `required` and
`label-visible` attributes to display the asterisk near the label.

This example checks whether
the rich text content is empty or undefined.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        value={myVal}
        placeholder="Type something interesting"
        label-visible
        required
        message-when-bad-input={errorMessage}
        valid={validity}>
    </lightning-input-rich-text>
    <lightning-button
        name="validate"
        label="Validate"
        onclick={validate}>
    <lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The `validate` method toggles the validity of the rich text editor, and
displays the error message when it's invalid.

```javascript
import { LightningElement, api } from 'lwc';
export default class ValidityExample extends LightningElement {

    @api myVal = "";
    @api errorMessage = "You haven't composed anything yet." ;
    @api validity = true;

    validate() {
        if (!this.myVal) {
            this.validity = false;
        }
        else {
            this.validity = true;
        }
    }
```

## Supported HTML Tags

The rich text editor provides a WYSIWYG interface only. You can't edit HTML
tags by using the editor, but you can set the HTML tags via the `value`
attribute. When you copy content from a web page or another source and paste
it into the editor, unsupported tags are removed. Only formatting that
corresponds to an enabled toolbar button or menu is preserved.

For example, if
you disable the `FORMAT_TEXT` category, the Bold, Italic,
Underline, and Strikethrough buttons are not available. Furthermore,
pasting bold, italic, underlined, or strikethrough text in the editor are not
supported when you disable the `FORMAT_TEXT` category. Text that was enclosed
in unsupported tags is preserved as plain text. However, tables that you copy
in a browser window can be pasted into the editor and set
via the `value` attribute, even though there are no corresponding toolbar
buttons or menus for them.

The component sanitizes HTML tags passed to the `value` attribute to prevent
XSS vulnerabilities. Only HTML tags that correspond to features available on
the toolbar are supported. If you set unsupported tags via JavaScript,
those tags are removed and the text content is preserved. The
supported HTML tags are: `a`, `col`, `colgroup`, `em`,
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `img`, `li`, `ol`, `p`, `q`, `s`,
`strike`, `strong`, `table`, `tbody`, `td`, `tfoot`, `th`,
`thead`, `tr`, `u`, `ul`.

This component converts certain unsupported tags into supported tags with similar functions.

| Unsupported Tag | Becomes  |
| --------------- | -------- |
| `b`             | `strong` |
| `div`           | `p`      |
| `i`             | `em`     |
| `span`          | `p`      |

The component removes other unsupported tags and attributes, and only their text content is displayed.
Let's say you copy some text that's rendered bold with color formatting, and its HTML markup looks like this.

<!-- prettier-ignore-start -->
```html
The sky is <span style="color:blue;font-weight:bold">blue</span>.
<div style="color:#0000FF;font-weight:bold">
    This is some text in a div element.
</div>
```
<!-- prettier-ignore-end -->

If your rich text editor specifies support for the `bold` format but not the `color` format,
the editor preserves the bold formatting by converting it to a `strong` tag. However,
the color formatting in the pasted text is removed.

In Chromium-based browsers, copying content from a `lightning-formatted‑rich‑text` component
that contains links and pasting the content into the rich text editor inserts `&nbsp;`
and breaks formatting. We recommend that you use a non-Chromium based web browser,
such as Mozilla Firefox or Apple Safari, when copying and pasting content with hyperlinks.

## Accessibility

The value of the `label` attribute is read by screen readers and the
`label-visible` attribute determines whether the label is also visible on the
screen. If you don't specify either attribute, a default label is applied and
it's not visible. You can set `label` to a value of your choice. Use
`label-visible` to make the label visible, whether `label` has a default value
or one you’ve specified.

When focus first shifts to the rich text editor, initial focus is on the first item
in the toolbar, which is the font menu by default.

The font menu on the toolbar has an `aria-haspopup` value of `listbox`.
You can use the arrow keys to navigate up and down the fonts, then press Enter or
Tab to select a font. To close the font menu, press the Esc or Tab key.

Use Tab and Shift+Tab to navigate between the selectors for font, size, and color.
Tab from the color selector to the formatting buttons. Focus goes to the first button,
which is the bold button by default. If you've previously selected a different button
in the current session, focus initially returns to that button instead of the first button.

Once focus is on a formatting button, use arrow keys to navigate through the buttons.
When you select a button, the cursor goes to the editor panel where you can type
your formatted text. Press Shift+Tab to return to the toolbar.

If you highlight text in the editor, you can press Shift+Tab to move into the toolbar and
press the Spacebar to enable bold formatting. However, you can't press the Spacebar again to toggle
the bold formatting because focus moves back into the editor after you set the text to bold.
Pressing the Spacebar again removes the highlighted text from the editor.

The link button has an `aria-haspopup` value of `dialog`. To open the dialog, navigate to the
link button and press the Spacebar. Focus moves to the first input field on the dialog where you enter
the link title. To close the dialog without saving your input, press Esc. Alternatively, tab to the
Cancel button and press Enter or the Spacebar.

Unlike the bold formatting button, the remove formatting button doesn't use the `aria-pressed`
attribute as it isn't a toggle button.

When the component is in an invalid state, an error message is displayed by using an element with a
randomly generated `id` value. To enable screen readers to announce error messages during user input, the `id` value
is associated with the `aria-describedby` attribute on the rich text editor element that has the `role="textbox"`
attribute. For example, the rich text editor displays a message when an input is required but the editor is empty
when you remove focus from it.

If you provide your own `aria-describedby` value for the `lightning-input-rich-text` component, the value is appended
to the rich text editor element that has the `role="textbox"` attribute only when the component is in an invalid state.

## Component Styling

Use a combination of variants and utility classes to customize your rich text editor.

### Variants

Use the `variant` attribute to change the placement of the toolbar.

- The default variant displays the toolbar above the rich text editor
- `bottom-toolbar` displays the toolbar below the rich text editor

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on top of the rich text editor by using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-input-rich-text class="slds-p-top_small" value="HELLO!">
</lightning-input-rich-text>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Character Limits

Salesforce uses `lightning-input-rich-text` in many features, such as in a custom rich text field or Chatter feed. Each feature that uses the rich text editor enforces a character limit. Refer to the documentation in Salesforce Help for a feature's limits and allocations.

Here are several resources that discuss the character limit for features that use `lightning-input-rich-text`.

- [Rich Text Area Field Considerations](https://help.salesforce.com/s/articleView?id=platform.fields_rich_text_area_limitations.htm)
- [General Chatter Allocations](https://help.salesforce.com/s/articleView?id=experience.collab_chatter_allocations.htm)
- [Note and Attachment Fields](https://help.salesforce.com/s/articleView?id=xcloud.notes_fields.htm)

Character limits include HTML tags, even though they're not visible in the editor. By default, Quill appends an additional 7 characters `<p></p>` to the text. The actual length of text you enter always includes this additional 7 characters. Rich text formatting also adds to the character count. For example, bold formatting includes the `<b></b>` tag around your text and adds 7 more characters to your actual length of text.

## Usage Considerations

The editor automatically indents nested bulleted lists. If you insert extra indents, they are removed on save.

You can't nest a list that's a different type from its parent list. For example, if you nest a `<ul>` tag within an `<ol>` tag, the `<ul>` tag is removed and its `<li>` tags are merged with the parent `<ol>` list.

The `value` attribute only supports string values. To clear the editor by setting the `value` attribute, use `""` to specify an empty string because `null` and `undefined` aren't supported.

Output from the editor can appear differently outside of the Salesforce Lightning Experience. If the content is being viewed outside of Lightning contexts (such as in an email), there can be visual inconsistencies.

When by using `setFormat()`, navigating to a previous line removes the user's format settings for empty newlines. For example, the user can set the styling to bold and type three lines, leaving the second line empty. If the user navigates away from the second line, then navigates back, it no longer has bold styling.

Although a toolbar button for creating tables isn’t available,
creating tables programmatically or copying from a browser window and pasting
these elements preserves the formatting in the editor.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`imageupload`**

The event fired when each image uploads successfully.

The `imageupload` event returns these parameters.

| Parameter        | Type   | Description                                                                                                                                        |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| imageId          | string | The image's tracking ID, which uses `pending-img-` followed by the timestamp that represents when the image was inserted, and a unique identifier. |
| downloadUrl      | string | The permanent URL for the uploaded image.                                                                                                          |
| file             | file   | The file that was successfully uploaded.                                                                                                           |
| contentVersionId | string | The ContentVersion ID for the image. ContentVersion IDs begin with `068`.                                                                          |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | false | This event cannot be canceled.                                                 |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

**`imageuploaderror`**

The event fired when an image fails to be inserted into the rich text editor or uploaded.

The `imageuploaderror` event returns these parameters.

| Parameter | Type   | Description                                                                                                                                                                                                                               |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| error     | string | The upload error message, which can be returned when there's a permission or ID issue, or something else. When the image upload fails, the image continues to be available at the temporary URL until the image is uploaded successfully. |
| file      | file   | The rejected file, which includes the file name, size, and type.                                                                                                                                                                          |
| imageId   | string | The image's tracking ID, which uses `pending-img-` followed by the Unix timestamp that represents when the image was inserted, and a unique identifier.                                                                                   |
| maxSize   | number | The maximum file size in bytes, which is 1 MB or 1,048,576 bytes. Files exceeding this limit are not inserted into the rich text editor.                                                                                                  |
| reason    | string | The cause of the image upload error. Possible reasons are `SIZE_EXCEEDED` and `UPLOAD_FAILED`.                                                                                                                                            |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | false | This event cannot be canceled.                                                 |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

## See Also

[_Object Reference for the Salesforce Platform_: Field Types](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)


:::::

:::::tab
::component-specification{component="inputRichText" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6414693e58081c17164f38b5417b131067deca3fe69eef8273fa6bc0616ae4f8 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/isUrlAddressable/aura-is-url-addressable.md -->

# Is Url Addressable

**`lightning:isUrlAddressable`**

Enables a component to be directly navigated to through a URL.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

To enable direct navigation to a Lightning component via URL, add the `lightning:isUrlAddressable` interface to the component. This interface is used with the `lightning:navigation` component to navigate from one component to the URL-addressable component. This navigation feature is supported only in Lightning Experience and the Salesforce mobile app.

`lightning:isUrlAddressable` isn't available in sites created with Experience Cloud, since it interferes with custom domain and CDN support.

The `lightning:isUrlAddressable` interface extends the `lightning:hasPageReference` interface. A component that implements `lightning:isUrlAddressable` then gets access to the page state through the `pageReference` attribute. The page state is a representation of the current URL query parameters.

`lightning:isUrlAddressable` enables you to generate a user-friendly URL for a Lightning component with the pattern `/cmp/componentName` instead of the base-64 encoded URL you get with the deprecated `force:navigateToComponent` event.

Important: When the target of a navigation action maps to the same component, the routing container might simply update the `pageReference` attribute value instead of recreating the component. In this scenario, a change handler ensures that your component reacts correctly.

This example shows the markup required to add the `lightning:isUrlAddressable` interface to a Lightning component to get access to the current page state. `c:helloTarget` displays a string that's passed in from another component.

Important: 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.

```html
<aura:component implements="lightning:isUrlAddressable" description="c:helloTarget component">
  <aura:attribute name="id" type="String" />
  <!-- Add an "init" handler to handle the first "v.pageReference" value -->
  <aura:handler name="init" value="{!this}" action="{!c.onPageReferenceChange}" />
  <!-- Add a "change" handler to handle all changes to the "v.pageReference" value -->
  <aura:handler name="change" value="{!v.pageReference}" action="{!c.onPageReferenceChange}" />
  Hello {!v.id}.
</aura:component>
```

In `c:helloTarget` component's client-side controller, retrieve the attribute values from the page state.

```javascript
({
  onPageReferenceChange: function (cmp, evt, helper) {
    var myPageRef = cmp.get("v.pageReference");
    var id = myPageRef.state.c__id;
    cmp.set("v.id", id);
  },
});
```

In the component that you want to trigger the navigation, include an instance of the `lightning:navigation` component. Then include the component to perform the jump to the other component. In this example, a `lightning:button` component is added to `c:hello` to trigger the navigation to the URL addressable component.

```html
<aura:component description="c:hello component">
  <aura:attribute name="pageReference" type="Object" />
  <aura:handler name="init" value="{! this }" action="{! c.init }" />
  <lightning:navigation aura:id="navService" />
  <lightning:button label="Navigate" onclick="{!c.handleClick}" />
</aura:component>
```

Define your page reference for the component you’re navigating to. We recommend setting the page reference using an `init` handler. This example stores the pageReference in an attribute in the component, and is used to navigate later in the click handler.

```javascript
({
  init: function (component, event, helper) {
    var pageReference = {
      type: "standard__component",
      attributes: {
        componentName: "c__helloTarget",
      },
      state: {
        c__id: "001XXXXXXXXXXXX",
      },
    };
    component.set("v.pageReference", pageReference);
  },
  handleClick: function (component, event, helper) {
    var navService = component.find("navService");
    var pageReference = component.get("v.pageReference");
    event.preventDefault();
    navService.navigate(pageReference);
  },
});
```

Clicking the button in `c:hello` directs you to `/lightning/cmp/c__helloTarget?c__id=001XXXXXXXXXXXX`, and `Hello 001XXXXXXXXXXXX` is displayed on the `c:helloTarget` page.

## Updating the Page Reference

When building a component that implements `lightning:hasPageReference`, you probably want to update a parameter on the pageReference while staying on the current page. Use a change handler to listen for page state updates. Updating a parameter also updates the URL, so that some state or data that the page holds can be retained, even when the page refreshes. In Salesforce Lightning Experience, you see this behavior with the `filterName` attribute on an object list. To make this pageReference change, use the `lightning:navigation` component.

This example expands the `c:helloTarget` component to include a text box to enter a new ID and adds a button that switches the page to view a different record ID when clicked. It uses `lightning:navigation` to update the URL and pageReference, and observes changes to the pageReference so that the helloTarget component knows when the pageReference change has finished.

```html
<aura:component
  implements="lightning:isUrlAddressable"
  description="c:helloTarget component"
  access="global"
>
  <aura:attribute name="id" type="String" />
  <!-- Add an "init" handler to handle the first "v.pageReference" value -->
  <aura:handler name="init" value="{!this}" action="{!c.onPageReferenceChange}" />
  <!-- Add a "change" handler to handle all changes to the "v.pageReference" value -->
  <aura:handler name="change" value="{!v.pageReference}" action="{!c.onPageReferenceChange}" />
  <lightning:navigation aura:id="navService" />
  Hello {!v.id}.
  <br />
  <lightning:input aura:id="idInput" label="Id Input" />
  <lightning:button label="Update Id" onclick="{!c.updateId}" />
</aura:component>
```

The `c:helloTarget` controller binds the id parameter to a component attribute in the init handler, uses the `lightning:navigation` component to update the id state parameter, and reevaluates the id component attribute when the pageReference changes.

```javascript
({
  onPageReferenceChange: function (cmp, event, helper) {
    var myPageRef = cmp.get("v.pageReference");
    var id = myPageRef.state.c__id;
    cmp.set("v.id", id);
  },
  updateId: function (cmp, event, helper) {
    var idInput = cmp.find("idInput");
    var newId = idInput.get("v.value");
    var myPageRef = cmp.get("v.pageReference");
    var newState = Object.assign({}, myPageRef.state, { c__id: newId });
    cmp.find("navService").navigate({
      type: myPageRef.type,
      attributes: myPageRef.attributes,
      state: newState,
    });
  },
});
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=b64c8da8b3c3bb5a3cb8a3928c14c7519ac558174270b155152eca4b69e55181 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/layout/forceCommunity-layout.md -->

# Layout

**`forceCommunity:layout`**

Enables a component to be used as a custom layout for creating pages in the Experience Builder.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To appear in Experience Builder as a custom layout, a component must implement the `forceCommunity:layout` interface.

Here's the sample code for a simple two-column content layout.

```xml
<aura:component implements="forceCommunity:layout" description="Custom Content Layout" access="global">
    <aura:attribute name="column1" type="Aura.Component[]" required="false"></aura:attribute>
    <aura:attribute name="column2" type="Aura.Component[]" required="false"></aura:attribute>

    <div class="container">
        <div class="contentPanel">
            <div class="left">
                {!v.column1}
            </div>
            <div class="right">
                {!v.column2}
            </div>
        </div>
    </div>
</aura:component>
```

Mark your resources, such as a component, with `access="global"` to make the resource usable outside of your own org. For example, if you want a component to be usable in an installed package or by a Lightning App Builder user or a Experience Builder user in another org.

Next, add a CSS resource to your component bundle to style the content layout. CSS resources must be named `componentName.css`.

```css
.THIS .contentPanel:before,
.THIS .contentPanel:after {
  content: " ";
  display: table;
}
.THIS .contentPanel:after {
  clear: both;
}
.THIS .left {
  float: left;
  width: 50%;
}
.THIS .right {
  float: right;
  width: 50%;
}
```

Optionally, to define a custom icon for the content layout component, you can add an SVG resource to your component bundle.

For more information, see [Using Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_intro.htm) in the Lightning Aura Components Developer Guide.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=0e49ebc496c1580ec1580befdb9dd77291f7a536c64f3aa07090b7077c8996a1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/layout/lightning-layout.md -->


# Layout

**`lightning-layout`**

Represents a responsive grid system for arranging containers on a page.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="layout" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-layout` is a flexible grid system for arranging containers within
a page or inside another container. The default layout is mobile-first and you can
configure the layout to adapt to different devices.

Create the content of the layout by including `lightning-layout-item` components
within `lightning-layout`. You can place HTML tags and text between the `lightning-layout-item`
components, but you can't place other components or expressions between them.

## Design

`lightning-layout` implements styling from the [grid utility classes](https://lightningdesignsystem.com/utilities/grid/) in the Lightning Design System.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Utility Classes (Grid)](https://v1.lightningdesignsystem.com/utilities/grid/)                                                        | [Utility Classes (Grid)](https://www.lightningdesignsystem.com/2e1ef8501/p/61d07d-grid)                         |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Columns

`lightning-layout` creates several types of columns for your content.

- Flexible widths that adjust based on their content
- Fixed widths that take up a percentage of the container

Create a simple layout by enclosing single or multiple `lightning-layout-item` components within `lightning-layout`. `lightning-layout-item` creates a column within `lightning-layout`.

To create columns with widths that adjusts with the content, use `flexibility="auto"`. The `horizontal-align` attribute determines how to spread the layout items horizontally.

Here’s an example that creates columns with flexible widths.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="c-container">
        <lightning-layout horizontal-align={horizontalAlign}>
            <lightning-layout-item flexibility="auto" padding="around-small">
                1
            </lightning-layout-item>
            <lightning-layout-item flexibility="auto" padding="around-small">
                2
            </lightning-layout-item>
            <lightning-layout-item flexibility="auto" padding="around-small">
                3
            </lightning-layout-item>
            <lightning-layout-item flexibility="auto" padding="around-small">
                4
            </lightning-layout-item>
        </lightning-layout>
    </div>
</template>
```
<!-- prettier-ignore-end -->

Set the horizontal alignment to `space`, which evenly distributes columns horizontally with an equal amount of space separating the columns.

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

export default class MyLayout extends LightningElement {
  @api horizontalAlign = "space";
}
```

To create columns with fixed widths, use the `size` attribute on `lightning-layout-item`. For example, to create two columns where the width of the first column is 33% of the grid container and the second column is 66% of the grid container, use `size="4"` and `size="8"`.

<!-- prettier-ignore-start -->
```html
<lightning-layout>
    <lightning-layout-item size="4"> Column 1 content </lightning-layout-item>
    <lightning-layout-item size="8"> Column 2 content </lightning-layout-item>
</lightning-layout>
```
<!-- prettier-ignore-end -->

For more information, see the [SLDS grid utility classes](https://lightningdesignsystem.com/utilities/grid/), and [SLDS sizing utility classes](https://v1.lightningdesignsystem.com/utilities/sizing/).

Customize the layout by setting the `horizontal-align`, `vertical-align`, and `pull-to-boundary` attributes.

## `horizontal-align`

Spread layout items out horizontally based on these values.

- `center`: Appends the `slds-grid_align-center` class to the grid. This attribute orders the layout items into a horizontal line without any spacing, and places the group into the center of the container.
- `space`: Appends the `slds-grid_align-space` class to the grid. The layout items are spaced horizontally across the container, starting and ending with a space.
- `spread`: Appends the `slds-grid_align-spread` class to the grid. The layout items are spaced horizontally across the container, starting and ending with a layout item.
- `end`: Appends the `slds-grid_align-end` class to the grid. The layout items are grouped together and aligned horizontally on the right side of the container.

## `vertical-align`

Spread layout items out vertically based on these values.

- `start`: Appends the `slds-grid_vertical-align-start` class to the grid. The layout items are aligned at the top of the container.
- `center`: Appends the `slds-grid_vertical-align-center` class to the grid. The layout items are aligned in the center of the container.
- `end`: Appends the `slds-grid_vertical-align-end` class to the grid. The layout items are aligned at the bottom of the container.
- `stretch`: Appends the `slds-grid_vertical-stretch` class to the grid. The layout items extend vertically to fill the container.

## `pull-to-boundary`

Pull layout items to the layout boundaries based on these values.

- `small`: Appends the `slds-grid_pull-padded` class to the grid.
- `medium`: Appends the `slds-grid_pull-padded-medium` class to the grid.
- `large`: Appends the `slds-grid_pull-padded-large` class to the grid.

If padding is used on layout items, this attribute pulls the elements on either
side of the container to the boundary. Choose the size that corresponds to the
padding on your layout items. For instance, if
`lightning-layout-item padding="horizontalSmall"`, choose `pull-to-boundary="small"`.

Use the `class` or `multiple-rows` attributes to customize the styling in other
ways.

## Usage Considerations

This example creates the same layout shown in [Create Columns](#create-columns),
which creates two columns with fixed widths.

<!-- prettier-ignore-start -->
```html
<div class="slds-grid">
    <div class="slds-col slds-size_1-of-3">Column 1 content</div>
    <div class="slds-col slds-size_2-of-3">Columns 2 content</div>
</div>
```
<!-- prettier-ignore-end -->


:::::

:::::tab
::component-specification{component="layout" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=cf48d19db4233ab836d23e31aebae629985a22a3de1eb64562cf757418c9c89f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/layoutItem/lightning-layout-item.md -->


# Layout Item

**`lightning-layout-item`**

The basic element in a lightning-layout component. A layout item groups information together to define visual grids, spacing, and sections.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="layoutItem" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-layout-item` defines content within `lightning-layout`. You
can arrange one or more `lightning-layout-item` components inside `lightning-layout`.

The `lightning-layout-item` components must be adjacent, with no other components or expressions between them.

Use the attributes
of `lightning-layout-item` to configure the size of the layout item,
and change how the layout changes on different device sizes.

The layout system is mobile-first. Typically, the `small-device-size` attribute indicates a smart phone,
`medium-device-size` indicates a tablet, and `large-device-size` indicates a desktop or larger device.

If you specify the `small-device-size`, `medium-device-size`, or `large-device-size` attributes, you must also
specify the `size` attribute.

If you specify the `size` and `small-device-size`
attributes, the `size` attribute applies to small mobile
phones, and the `small-device-size` applies to smart phones. The device sizing
attributes are additive and apply to devices of the specified size and larger. For
example, if you set `medium-device-size=10` and don't set `large-device-size`, then
the `medium-device-size` setting applies to tablets, desktops, and larger
devices. You also set `size` to apply to devices smaller than tablets.

## Design

Use `lightning-layout-item` within `lightning-layout`, which implements styling from the [grid utility classes](https://lightningdesignsystem.com/utilities/grid/) in the Lightning Design System.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Utility Classes (Grid)](https://v1.lightningdesignsystem.com/utilities/grid/)                                                        | [Utility Classes (Grid)](https://www.lightningdesignsystem.com/2e1ef8501/p/61d07d-grid)                         |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

For general information on sizing, see [Lightning Design System](https://v1.lightningdesignsystem.com/utilities/sizing/#overview).

## Create Layout Items

Use the `flexibility` attribute to specify how the layout item adapts to the size of its container.
With default attribute values of size and flexibility, layout items take the size of their content and don't
occupy the entire width of the container.

Here’s an example that uses default values.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-layout>
            <lightning-layout-item padding="around-small">
                <div>1</div>
            </lightning-layout-item>
            <lightning-layout-item padding="around-small">
                <div>2</div>
            </lightning-layout-item>
            <lightning-layout-item padding="around-small">
                <div>3</div>
            </lightning-layout-item>
            <lightning-layout-item padding="around-small">
                <div>4</div>
            </lightning-layout-item>
        </lightning-layout>
    </div>
</template>
```
<!-- prettier-ignore-end -->

## Usage Considerations

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.


:::::

:::::tab
::component-specification{component="layoutItem" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=b802c485d83104bec05972e71fa39c35c9acf631593232ff7842b83ca11f2312 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/legacy.md -->

# Legacy Components

This section presents reference documentation for Aura components, events, and interfaces. Aura and LWC can coexist and interoperate on a page.

**note:** Use Lightning Web Components (LWC) where possible for new development. For more information, see [Migrate Aura Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-introduction.html).

- [Aura components](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura-components.md) provide functionality for Salesforce applications through the Aura framework. These components include form handling, data visualization, platform integration, and user interface elements built specifically for the Lightning Experience ecosystem.

- [Aura events](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/events.md) enable communication between components and respond to system-level changes. These events facilitate Omni-Channel operations, conversation management, and console workspace interactions.

- [Aura interfaces](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/interfaces.md) make your components available for use on record pages, flow screens, utility bars, and Aura-based Experience Builder sites. These interfaces enable you to integrate custom component logic with platform capabilities.

<!-- document id=cca36bb78dbcb496e3673866400f5d3db964b673662bcff01ed2994bbe1100f1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/get-started-release-notes.md -->

# Lightning Base Components Release Notes

The Component Reference provides documentation about Lightning base components for both the Lightning Web Components (LWC) and Aura programming models. Use the Salesforce Release Notes to learn about the most recent updates and changes to base components.

For new and changed base 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_.

For framework-level and overall base components changes, see [Lightning Components](https://help.salesforce.com/s/articleView?id=release-notes.rn_lc.htm) in the _Salesforce Release Notes_.

For Salesforce Lightning Design System (SLDS) changes, see [Salesforce Lightning Design System](https://help.salesforce.com/s/articleView?id=release-notes.rn_slds.htm) in the _Salesforce Release Notes_.

<!-- document id=152fd25975652da35e4b073ece893a59662ab6f17be112ec9f071aabf3427d8f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/lightningQuickAction/force-lightning-quick-action.md -->

# Lightning Quick Action

**`force:lightningQuickAction`**

Indicates that a component can be used as a custom action.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add the `force:lightningQuickAction` interface to an Aura component to allow it to be used as a custom action in Lightning Experience or the Salesforce mobile app. You can use these components as object-specific or global actions in both Lightning Experience and the Salesforce mobile app.

When used as actions, components that implement the `force:lightningQuickAction` interface display in a panel with standard action controls, such as a Cancel button. These components can display and implement their own controls in the body of the panel, but can’t affect the standard controls. They should nevertheless be prepared to handle events from the standard controls. If you implement `force:lightningQuickAction`, you can’t implement `force:lightningQuickActionWithoutHeader` within the same component.

This interface is a marker interface. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

## Example

```xml
<!--quickAdd.cmp-->
<aura:component implements="force:lightningQuickAction">

    <!-- Very simple addition -->

    <lightning:input type="number" name="myNumber" aura:id="num1" label="Number 1"/> +
    <lightning:input type="number" name="myNumber" aura:id="num2" label="Number 2"/>

    <br/>
    <lightning:button label="Add" onclick="{!c.clickAdd}"/>

</aura:component>
```

**tip:** If you use the `force:lightningQuickAction` interface, we recommend implementing the body of the panel only. The panel’s header, footer, and action controls are provided by Salesforce. To customize the entire panel or add your own header and footer, use the `force:lightningQuickActionWithoutHeader` interface.

For more information, and an example including controller code, see [Configure Components for Custom Actions](/HelpAndTrainingDoor?version=2&resource=https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_lex_s1_config_action.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=98483f362aa0bd48748e9b2c59bb42268b3bc44b083d7584ab28c7b41fff552f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/lightningQuickActionWithoutHeader/force-lightning-quick-action-without-header.md -->

# Lightning Quick Action Without Header

**`force:lightningQuickActionWithoutHeader`**

Indicates that a component can be used as a custom action.

**For Use In**

Lightning Experience, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

Add the `force:lightningQuickActionWithoutHeader` interface to an Aura component to allow it to be used as a custom action in Lightning Experience or the Salesforce mobile app. You can use these components as object-specific or global actions in both Lightning Experience and the Salesforce mobile app.

When used as actions, components that implement the `force:lightningQuickActionWithoutHeader` interface display in a panel without additional controls. The component should provide a complete user interface for the action. If you implement `force:lightningQuickActionWithoutHeader`, you can’t implement `force:lightningQuickAction` within the same component.

This interface is a marker interface. A marker interface is a signal to the component’s container to add the interface’s behavior to the component. You don’t need to implement any specific methods or attributes in your component, you simply add the interface name to the component’s `implements` attribute.

## Example

```
<!--quickAdd.cmp-->
<aura:component implements="force:lightningQuickActionWithoutHeader">

    <!-- Very simple addition -->

    <lightning:input type="number" name="myNumber" aura:id="num1" label="Number 1"/> +
    <lightning:input type="number" name="myNumber" aura:id="num2" label="Number 2"/>

    <br/>
    <lightning:button label="Add" onclick="{!c.clickAdd}"/>

</aura:component>
```

For more information, and an example including controller code, see [Configure Components for Custom Actions](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_lex_s1_config_action.htm).


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=e67407794935a5aecf5b03cc8c3d765d8f138fd4250138c0c40a2f29e1fef323 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/locationChange/aura-location-change.md -->

# Location Change

**`aura:locationChange`**

Indicates that the hash part of the url in the brower's location bar has been modified.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when the hash part of the URL has changed. Handle this event using the `aura:handler` tag.

```xml
<aura:handler event="aura:locationChange" action="{!c.update}" />
```

This client-side controller handles the `aura:locationChange` event.

```javascript
({
  update: function (component, event, helper) {
    // Get the new hash from the event
    var loc = event.getParam("token");
    // Do something else
  },
});
```

Although `aura:locationChange` tracks changes to the hash fragment in a URL, it’s not useful for tracking navigation in Lightning Experience and Salesforce mobile app.


:::::

:::::tab
## Attributes

| Name          | Description                                                                                       | Type   | Default | Required |
| ------------- | ------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `querystring` | The query string portion of the hash that is stripped off and applied to the event as parameters. | string |         |          |
| `token`       | The new hash part of the url.                                                                     | string |         |          |

:::::

::::::

<!-- document id=c521833f3954976f615c2ae48c6e6886e52b4c0ca648b3c8b7ee8f4539619c0c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/logger/lightning-logger.md -->

# Logger

**`lightning-logger`**

Logs a string as the message. The module also validates and stringifies other types. It truncates messages over a certain length and logs a blank string for an empty input. Messages are tokenized and can't be seen outside of the customer's org.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/logger` module provides a function to add observability to your Lightning web components using the Custom Component Instrumentation API. Use the `log()` function to log custom messages to Event Monitoring from your components. In your component's Javascript file, import the function from the `lightning/logger` module.

```javascript
import { log } from "lightning/logger";
```

`lightning/logger` is available only in Lightning Experience and not in the Salesforce mobile app. Event Monitoring must be enabled in your org to use `lightning/logger`.

The browser sends event logs for `lightning/logger` to the server in batches when the user interacts with the page and when the page closes or refreshes. If the user's connection is interrupted or the login session ends due to inactivity, any pending event logs for `lightning/logger` on the browser are deleted. There isn’t a way to retrieve these logs.

## `log(message)`

Logs the event data from the component.

| Parameter | Type             | Description                                                                                                                                                                                        |
| --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| message   | string or object | The message to be logged to the Lightning Logger Event Type in Event Monitoring. The maximum string length is 4096 characters. The `log()` function automatically stringifies an object passed in. |

## Usage

The following example logs a click from within a button component. The `log()` function can be used for any event.

Create the HTML template for your component.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button label="Approve" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

In the JavaScript, import `log` from `lightning/logger` and use it in the `handleClick` function. In this example, clicking on the button creates an object that is passed to Event Monitoring.

```js
import { LightningElement } from "lwc";
import { log } from "lightning/logger";

export default class HelloWorld extends LightningElement {
  handleClick() {
    let msg = {
      type: "click",
      action: "Approve",
    };
    log(msg);
  }
}
```

## See Also

[_Object Reference for the Salesforce Platform_: Lightning Logger Event Type](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_eventlogfile_lightninglogger.htm)


:::::

:::::tab
::component-specification{component="logger" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9e5a0ee35f85de87b573839d9e05ef37e1b2b48947b4ad6f5dca0a67465f2c4d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/utilities.md -->

# LWC Utility Modules

Utility modules complement Lightning base components by providing functionality and services that extend beyond individual component capabilities. These modules offer JavaScript functions and services that help you build robust and integrated apps.

Utility modules include:

- [**Distributed Marketing**](/docs/platform/lightning-component-reference/guide/lightning-distributed-marketing.html): Launch the Distributed Marketing modal
- [**File Download**](/docs/platform/lightning-component-reference/guide/lightning-file-download.html): Download a file in an LWR site in Experience Cloud
- [**Flow Support**](/docs/platform/lightning-component-reference/guide/lightning-flow-support.html): Control flow navigation and notify the flow of changes in attribute values using the `lightning/flowSupport` module
- [**Logger**](/docs/platform/lightning-component-reference/guide/lightning-logger.html): Centralize logging capabilities for debugging and monitoring using the `lightning/logger` module
- [**Media Utils**](/docs/platform/lightning-component-reference/guide/lightning-media-utils.html): Handle media files and streaming using the `lightning/mediaUtils` module
- [**Message Service**](/docs/platform/lightning-component-reference/guide/lightning-message-service.html): Communicate between components that don't have a direct parent-child relationship using the `lightning/messageService` module
- [**Navigation**](/docs/platform/lightning-component-reference/guide/lightning-navigation.html): Navigate programmatically between pages, apps, and records using the `lightning/navigation` module
- [**Page Reference Utils**](/docs/platform/lightning-component-reference/guide/lightning-page-reference-utils.html): Work with page references and URLs using the `lightning/pageReferenceUtils` module
- [**Platform Resource Loader**](/docs/platform/lightning-component-reference/guide/lightning-platform-resource-loader.html): Load static resources, stylesheets, and scripts using the `lightning/platformResourceLoader` module
- [**Platform Show Toast Event**](/docs/platform/lightning-component-reference/guide/lightning-platform-show-toast-event.html): Standardized user notifications using the `lightning/platformShowToastEvent` module
- [**Refresh**](/docs/platform/lightning-component-reference/guide/lightning-refresh.html): Trigger data refreshes across components using the `lightning/refresh` module
- [**User Consent Cookie**](/docs/platform/lightning-component-reference/guide/lightning-user-consent-cookie.html): Manage user consent preferences and cookie compliance using the `lightning/userConsentCookie` module

<!-- document id=bd05a2227b35bc3a79c624a1b4439b710d1bfc2b20b210931af80ff7f53e42c2 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/map/lightning-map.md -->

# Map (Beta)

**`lightning-map`**

Displays a map with markers for one or more locations.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `lightning-map` 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.

A `lightning-map` component shows a map of one or more locations, using geocoding data and mapping imagery from Google Maps.
The map image is shown in a container, with an optional list of the locations. The list is visible by default when multiple locations are specified. When you select a location title in the list, its map marker is activated. The list is shown beside or below the map, depending on the width of the container.

`lightning-map` loads content from the Salesforce domain `maps.a.forceusercontent.com` in an iframe. Allow `maps.a.forceusercontent.com` if you use this component in your own domain and you use the Content Security Policy `frame-src` directive, such as in Experience Builder sites or Lightning Out. For more information, see [Content Security Policy in Experience Builder sites](https://help.salesforce.com/articleView?id=networks_security_csp_overview.htm).

Pass the locations to the component's `map-markers` property.

For example:

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map map-markers={mapMarkers}> </lightning-map>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-map` implements the map blueprint in the Salesforce Lightning Design System (SLDS). The map adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Map](https://v1.lightningdesignsystem.com/components/map/)                                                           | [Map](https://www.lightningdesignsystem.com/components/map/)                                                    |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Configure the Map

`map-markers` is an array of markers that indicate location.

A marker contains map data:

- Location Information: A coordinate pair of latitude and longitude, or an address composed of address elements to be geocoded.
- Descriptive Information: Optional title, description, and an icon. These items are relevant to the marker but not specifically related to location.

### Marker Properties

Use these marker properties to customize the map.

| Property      | Type   | Description                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location`    | object | Address elements (City, Country, PostalCode, State, and Street) to be geocoded, or a set of latitude and longitude coordinates. If you specify address elements and coordinates for one location, the map uses the coordinates. To support reliable geocoding of addresses, if you specify Street, you must also specify at least one of City, Country, PostalCode, or State. |
| `title`       | string | Title text for the location, placed in the location list and in the info window when you click a marker. HTML tags aren't supported and are shown as unescaped markup.                                                                                                                                                                                                        |
| `description` | string | Text describing the location, placed in the info window when you click a marker or location title. A subset of HTML tags is supported. See [Use HTML Tags in Descriptions](#use-html-tags-in-descriptions).                                                                                                                                                                   |
| `icon`        | string | The icon that's placed next to the location title in the list. Only Lightning Design System icons are supported. Custom icons are currently not supported in the location list. The default icon is standard:location. For more information, see [Show Multiple Addresses and a Title](#show-multiple-addresses-and-a-title).                                                 |
| `value`       | string | An optional unique identifier for a marker. When you select a marker, its value is assigned to the `selected-marker-value` attribute.                                                                                                                                                                                                                                         |
| `type`        | string | A type of shape to use instead of the default map marker. Accepted values are `Circle`, `Rectangle`, and `Polygon`. See [Mark Locations with Shapes](#mark-locations-with-shapes).                                                                                                                                                                                            |
| `mapIcon`     | object | A custom SVG icon to use instead of the default map marker. See [Mark Locations with Custom Icons](#mark-locations-with-custom-icons).                                                                                                                                                                                                                                        |

## Use HTML Tags in Descriptions

HTML tags are supported for use with the `description` property. The supported HTML tags are `b`, `br`, `del`, `em`, `h1`, `h2`, `h3`, `h4`, `h5`,`h6`, `i`, `ins`, `mark`, `p`, `small`, `strong`, `sub`, and `sup`. Other HTML tags you pass to `description` are sanitized and removed.

This example formats some words in a marker description to make them bold and italicized.

```javascript
mapMarkers = [
  {
    location: {
      Street: "1 Market St",
      City: "San Francisco",
      Country: "USA",
    },
    title: "The Landmark Building",
    description: "Historic <b>11-story</b> building completed in <i>1916</i>",
  },
];
```

## Create a Single Marker

Here's an example of a marker that uses address elements.

![Map with a single marker](https://developer.salesforce.com/media/components/map-basic.png '{ "class":"image-md", "title": "Map (Single Marker)"}')

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

export default class LightningMapExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "The Landmark @ One Market, Suite 300",
      },
      value: "location001",
      title: "The Landmark Building",
      description:
        "The Landmark is considered to be one of the city&#39;s most architecturally distinct and historic properties", //escape the apostrophe in the string using &#39;
      icon: "standard:account",
    },
  ];
}
```

Here's an example of a marker that uses coordinates for latitude and longitude.

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

export default class LightningMapExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        Latitude: "37.790197",
        Longitude: "-122.396879",
      },
    },
  ];
}
```

For each map marker in the array of map markers, provide either latitude and longitude coordinates or address elements to be geocoded. If you specify both in a single marker, latitude and longitude get precedence.

## Show Multiple Addresses and a Title

When you specify multiple markers in an array, the `lightning-map` component renders a list of tiles with location titles and addresses, with a heading that's placed above the list.
Each location tile contains an icon, a title, and an address.

![Map with a single marker](https://developer.salesforce.com/media/components/map-multiple.png '{ "class":"image-md", "title": "Map (Multiple Markers)"}')

Specify the `markers-title` attribute for a custom heading for your locations. If you don't pass this attribute, the heading is "Markers(n)" where n is the number of markers you provide.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        markers-title="Lunch Gems"
        onmarkerselect={handleMarkerSelect}
        selected-marker-value={selectedMarkerValue}
    >
    </lightning-map>
</template>
```
<!-- prettier-ignore-end -->

To select a marker on load, use the `selected-marker-value` attribute. Retrieve the selected marker using the `onmarkerselect` handler.

To customize each location tile, you can specify the optional `icon`, `title`, and `description` properties. The `lightning-map` component appends the icon next to the address.
The description is shown in an info window when the user clicks the marker.

Get the selected marker using the `event.target.selectedMarkerValue` property.

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

export default class LightningMapExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        // Location Information
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "50 Fremont St",
      },

      // For onmarkerselect
      value: "SF1",

      // Extra info for tile in list & info window
      icon: "standard:account",
      title: "Julies Kitchen", // e.g. Account.Name
      description: "This is a long description",
    },
    {
      location: {
        // Location Information
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "30 Fremont St.",
      },

      // For onmarkerselect
      value: "SF2",

      // Extra info for tile in list
      icon: "standard:account",
      title: "Tender Greens", // e.g. Account.Name
    },
  ];

  selectedMarkerValue = "SF1";

  handleMarkerSelect(event) {
    this.selectedMarkerValue = event.target.selectedMarkerValue;
  }
}
```

## Show or Hide Locations

By default, the list of locations is hidden when you pass in a single marker and shown when you pass in multiple markers. To hide the list of locations for multiple markers, set `list-view="hidden"`.
To show the list of locations for a single marker, set `list-view="visible"`.

If you specify a `type` to show a shape at a location, the list view doesn't show an entry for the location. See [Mark Locations with Shapes](#mark-locations-with-shapes).

The example for specifying `zoom-level` also uses `list-view`.

## Specify Zoom Level

If you don't specify the `zoom-level` attribute, the `lightning-map` component calculates a zoom level to accommodate the markers in your map.

To specify a particular zoom level, set `zoom-level` to a value corresponding to a Google Maps API zoom level. Currently, Google Maps API supports zoom levels from `1` to `22` in desktop browsers, and from `1` to `20` on mobile. For more information, see [Zoom Levels](https://developers.google.com/maps/documentation/javascript/tutorial#zoom-levels) in the Google Maps API documentation.

Here's an example that uses `zoom-level` and `list-view` attributes.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        zoom-level={zoomLevel}
        list-view={listView}
    >
    </lightning-map>
</template>
```
<!-- prettier-ignore-end -->

The component's JavaScript sets the markers, zoom level, and list view visibility.

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

export default class LightningMapExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        Street: "1000 5th Ave",
        City: "New York",
        State: "NY",
      },

      title: "Museum of Fine Arts",
      description:
        "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
    },
  ];
  zoomLevel = 15;
  listView = "visible";
}
```

## Center the Map

When you have multiple map markers, the component centers the map on a location near the center of the markers by calculating the geometric mean.

Use the `center` attribute to specify a different location for the map's center. You can specify latitude and longitude, or at least one of the address elements: Country, State, City, and PostalCode. Street is optional.

The `center` location format is the same as the `map-markers` location format. However, you can't specify a title, icon, or description for the center.

Here's an example that centers the map using latitude and longitude.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        markers-title={markersTitle}
        center={center}
    >
    </lightning-map>
</template>
```
<!-- prettier-ignore-end -->

The markers and the center are set in JavaScript.

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

export default class LightningMapExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        Street: "1000 5th Ave",
        City: "New York",
        State: "NY",
      },

      title: "Metropolitan Museum of Art",
      description:
        "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
    },
    {
      location: {
        Street: "11 W 53rd St",
        City: "New York",
        State: "NY",
      },

      title: "Museum of Modern Art (MoMA)",
      description: "Thought-provoking modern and contemporary art.",
    },
    {
      location: {
        Street: "1071 5th Ave",
        City: "New York",
        State: "NY",
      },

      title: "Guggenheim Museum",
      description: "World-renowned collection of modern and contemporary art.",
    },
  ];

  markersTitle = "Coordinates for Centering";

  center = {
    location: { Latitude: "40.7831856", Longitude: "-73.9675653" },
  };
}
```

The same map could use address elements to center:

```javascript
center = {
  location: { Street: "170 Central Park West", PostalCode: "10024" },
};
```

## Show the Footer

The footer shows a link for opening the map in Google Maps in a new window or tab. By default, the first marker location opens. When viewing a map with multiple locations, select a location from the list before clicking the link to open that location in Google Maps.
The external Google map image shows a marker labeled with the location information that's specified for the marker in `lightning-map`. The title and description aren't included.

To show the footer, specify the `show-footer` attribute.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        markers-title={markersTitle}
        show-footer
    >
    </lightning-map>
</template>
```
<!-- prettier-ignore-end -->

## Set Map Controls

`lightning-map` enables you to specify which map controls to allow. Set the `options` attribute to
enable or disable map controls using these boolean properties.

| Property                 | Default Value | Description                                                                                                                                                                                                                                                  |
| ------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `draggable`              | true          | Enables dragging to pan the map with the mouse. Set to false to prevent dragging. This property affects the map only. Markers aren't draggable.                                                                                                              |
| `zoomControl`            | true          | Shows the +/- zoom controls on the bottom of the map. Set to false to remove the controls and prevent zooming.                                                                                                                                               |
| `scrollwheel`            | true          | Permits zooming with the mouse wheel. Set to false to disable zooming with the mouse wheel when zooming is enabled. If `zoomControl` is false or `disableDefaultUI` is true, the `scrollwheel` setting has no effect because these settings disable zooming. |
| `disableDefaultUI`       | false         | Set to true to remove Map/Satellite and +/- zoom buttons. The satellite view and zooming are disabled. Mouse scrolling and dragging is not affected by `disableDefaultUI`.                                                                                   |
| `disableDoubleClickZoom` | false         | Set to true to disable zooming with a mouse double-click when zooming is enabled.                                                                                                                                                                            |

Zooming behavior is influenced by all the properties except `draggable`.

- To prevent all zooming, set `zoomControl: false`
- To prevent all zooming and also remove the Map/Satellite buttons, set `disableDefaultUI: true`
- To allow zooming, but prevent the scroll wheel from activating zoom, set `scrollwheel: false`
- To allow zooming, but prevent a double-click from activating zoom, set `disableDoubleClickZoom: true`

This example disables dragging and also disables the default UI, which removes the zoom capability and
Map/Satellite button. The result is a static map.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        options={mapOptions}
        zoom-level="14"
    ></lightning-map>
</template>
```
<!-- prettier-ignore-end -->

The values of the `options` attribute are set in an object of boolean values in JavaScript.

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

export default class LightningExampleMapControls extends LightningElement {
  mapMarkers = [
    {
      location: {
        Street: "1000 5th Ave",
        City: "New York",
        State: "NY",
      },

      title: "Metropolitan Museum of Art",
      description:
        "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
    },
  ];
  mapOptions = {
    draggable: false,
    disableDefaultUI: true,
  };
}
```

## Mark Locations with Shapes

`lightning-map` enables you to customize your maps to use different indicators
for locations instead of the default Google Maps markers.

The `map-markers` attribute supports the `type` property to define colored shapes to mark a location. Available `type` values are `Circle`, `Rectangle`, and `Polygon`. The values are
case-sensitive.

The `type` property works with these properties to define a shape's appearance.

| `type` Value | Property        | Property Type | Description                                                                                                                              |
| ------------ | --------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `Circle`     | `radius`        | number        | The number in meters for the radius of the circle. This value represents the Earth's surface included in the circle around the location. |
| `Rectangle`  | `bounds`        | object        | Uses `north` and `south` latitude values and `east` and `west` longitude values to specify the corners of the rectangle.                 |
| `Polygon`    | `paths`         | object        | Defines a set of `lat` and `lng` properties for the latitude and longitude coordinates of the polygon's shape.                           |
| All          | `strokeColor`   | string        | Hexadecimal color code or CSS3 color name for the stroke, which creates the edge of the shape.                                           |
|              | `strokeOpacity` | number        | The degree of transparency of the stroke. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.                  |
|              | `strokeWeight`  | number        | The stroke width in pixels.                                                                                                              |
|              | `fillColor`     | string        | Hexadecimal color code or CSS3 color name to fill the shape.                                                                             |
|              | `fillOpacity`   | number        | The degree of transparency of the fill for the shape. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.      |

### Mark a Location with a Circle

This example creates a yellow circle to mark the location.

![Map with circle marker](https://developer.salesforce.com/media/components/map-circle.png '{ "class":"image-md", "title": "Map (Circle Marker)"}')

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map map-markers={mapMarkers} zoom-level="15"></lightning-map>
</template>
```
<!-- prettier-ignore-end -->

The `mapMarkers` object defines the `location` and the `type`. The properties specified after `type` define
the circle as having a 200 meter radius, and a yellow color #FFF000 for both the stroke edge and fill, with the edge more opaque than the fill.

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

export default class MapCircleShape extends LightningElement {
  mapMarkers = [
    {
      location: {
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "50 Fremont St",
      },
      type: "Circle",
      radius: 200,
      strokeColor: "#FFF000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FFF000",
      fillOpacity: 0.35,
    },
  ];
}
```

### Mark a Location with a Rectangle

This example shows the JavaScript for defining a rectangle shape for a location.

![Map with a rectangle marker](https://developer.salesforce.com/media/components/map-rectangle.png '{ "class":"image-md", "title": "Map (Rectangle Marker)"}')

The `mapMarkers` object sets the `type` to `Rectangle`. The `bounds` property defines the coordinates
of the rectangle for the location. Other properties define the characteristics of the stroke
and fill.

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

export default class MapRectangleShapeExample extends LightningElement {
  mapMarkers = [
    {
      location: {
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "500 Howard St",
      },
      type: "Rectangle",
      bounds: {
        north: 37.788,
        south: 37.774,
        east: -122.395,
        west: -122.412,
      },
      strokeColor: "#0b5411",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#0b5411",
      fillOpacity: 0.35,
    },
  ];
}
```

### Mark a Location with a Polygon

This example sets the `type` to Polygon and draws a pink polygon with a black outline.

![Map with a polygon marker](https://developer.salesforce.com/media/components/map-polygon.png '{ "class":"image-md", "title": "Map (Polygon Marker)"}')

The polygon's segments are defined in the `paths` property using coordinates
specified by the `lat` and `lng` properties.

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

export default class MapPolygonShape extends LightningElement {
  mapMarkers = [
    {
      location: {
        City: "San Francisco",
        Country: "USA",
        PostalCode: "94105",
        State: "CA",
        Street: "425 Mission St",
      },
      type: "Polygon",
      paths: [
        { lat: 37.78806990305951, lng: -122.39873856028704 },
        { lat: 37.790689809711886, lng: -122.39540189227252 },
        { lat: 37.79036762555352, lng: -122.39495128115801 },
        { lat: 37.787569651422224, lng: -122.39842742404132 },
        { lat: 37.7879172842749, lng: -122.39886730631976 },
        { lat: 37.7880699030595, lng: -122.39873856028704 },
      ],
      strokeColor: "black",
      strokeOpacity: 0.35,
      strokeWeight: 2,
      fillColor: "pink",
      fillOpacity: 0.35,
    },
  ];
}
```

### Mark Locations with Custom Icons

Pass the `mapIcon` property to the `map-markers` attribute to specify an SVG icon image in place of the Google Maps marker.

Use either `type` or `mapIcon` to customize a given location. You can't use both for one location.

The `mapIcon` property works with the following properties to define the icon's appearance.

| Property        | Type   | Description                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`          | string | SVG path notation to add a vector-based symbol as the icon for a marker.                                                                                                                                                                                                                                                                                           |
| `scale`         | number | The amount by which the marker icon is scaled in size. The default value is 1. The marker icon size is multiplied by the scale value to produce the actual output size of the marker in pixels.                                                                                                                                                                    |
| `anchor`        | Point  | Coordinates used to align the marker to the map coordinates when the zoom level changes. The default anchor is (0,0) which can lead to the marker moving when you zoom out. Set the anchor coordinates to account for the width and height of the icon. For example, set the x value equal to half the image width and the y value equal to half the image height. |
| `strokeColor`   | string | Hexadecimal color code or CSS3 color name for the stroke, which creates the edge of the custom icon.                                                                                                                                                                                                                                                               |
| `strokeOpacity` | number | The degree of transparency of the stroke. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.                                                                                                                                                                                                                                            |
| `strokeWeight`  | number | The stroke width in pixels. The default is 1.                                                                                                                                                                                                                                                                                                                      |
| `fillColor`     | string | Hexadecimal color code or CSS3 color name to fill the icon.                                                                                                                                                                                                                                                                                                        |
| `fillOpacity`   | number | The degree of transparency of the fill for the icon. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.                                                                                                                                                                                                                                 |

This example creates a gold star without an outline as the marker. The list-view is made visible to show that a location with a custom marker is displayed in the list of markers.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-map
        map-markers={mapMarkers}
        zoom-level="15"
        list-view="visible"
    ></lightning-map>
</template>
```
<!-- prettier-ignore-end -->

The `path` creates a star that's 245px x 230px. Use an SVG editor to determine the image size, which helps
determine the `anchor` coordinates needed. See [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Tools_for_SVG)
for a list of SVG tools.

The `anchor` property sets the x coordinate to 122.5 which is half the width of the image, and sets the
y coordinate to 115 which is half the height of the image. For more information about the `anchor` property, see
[Markers with vector-based icons](https://developers.google.com/maps/documentation/javascript/markers#symbols)
in the Google Maps Platform documentation.

The `scale` property sets the star to display at a comfortable size for the map viewed on a desktop.

![Map with a custom icon marker](https://developer.salesforce.com/media/components/map-custom-icon.png '{ "class":"image-md", "title": "Map (Custom Icon)"}')

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

export default class MapCustomIconExample extends LightningElement {
    mapMarkers = [
        {
            location: {
                City: 'San Francisco',
                Country: 'USA',
                PostalCode: '94105',
                State: 'CA',
                Street: '415 Mission St',
            },
            mapIcon: {
                path: 'M 125,5 155,90 245,90 175,145 200,230 125,180 50,230 75,145 5,90 95,90 z',
                fillColor: 'gold',
                fillOpacity: .8,
                strokeWeight: 0,
                scale: .10,
                anchor: { x: 122.5, y: 115 },
            },
        },
    ];
}
```

## Geocoding Addresses

The `lightning-map` component relies on data from Google for geocoding and mapping imagery. Inaccuracies or geocoding errors in the data can't be fixed by Salesforce.

You can specify a maximum of 10 geocoded address lookups per map. Lookups for both the `map-markers` and `center` attributes count toward the limit of 10 geocoded addresses. To show more markers, provide location values using a pair of latitude and longitude coordinates, which don't require geocoding. Address locations that exceed the geocoding limit are ignored.

We recommend limiting your map to 100 locations in total. For example, if you provide map markers for 5 geocoded addresses, you can provide up to 95 extra markers using latitude and longitude.

All latitude and longitude values must be valid. If you pass in an invalid latitude or longitude, the markers aren't plotted on the map. Latitude values fall within -90 and 90, and longitude values fall within -180 and 180.

Also consider these guidelines:

- If you specify an address, you must provide at least one of these values: City, PostalCode, State, or Country.
- If you pass in both an address and a latitude and longitude, the map plots the marker according to the latitude and longitude values.
- If a marker in the `map-markers` array is invalid, no markers are plotted on the map.

## Usage Considerations

`lightning-map` uses the Google Maps Platform and is bound to its terms of service. The use of Google Maps Platform is prohibited in specific territories based on IP addresses. For more information, see [Google Maps Platform Prohibited Territories](https://cloud.google.com/maps-platform/terms/maps-prohibited-territories). `lightning-map` is not supported in these territories and does not load correctly when accessed from the IP addresses associated with these territories. Users in these territories can continue to use Google Maps directly as detailed at [Google Maps Platform Coverage Details](https://developers.google.com/maps/coverage).

## Custom Events

**`markerselect`**

The event fired when a marker is selected. Select a marker by clicking it on the map or in the list of locations. The value of the selected marker is available on the `selected-marker-value` attribute on the component.

The `markerselect` event returns this parameter.

| Parameter           | Type   | Description                                             |
| ------------------- | ------ | ------------------------------------------------------- |
| selectedMarkerValue | string | The unique identifier of the currently selected marker. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |


:::::

:::::tab
::component-specification{component="map" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f0f08cb1269f9ca7a129ee7759b42569e500a7380f16803863681a413b3bc27b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/mediaUtils/lightning-media-utils.md -->

# Media Utils

**`lightning/mediaUtils`**

Given an input image (as a file handle or a blob) this method will resize and compress the image according to the specified options, and return a Blob object containing the resulting image data.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/mediaUtils` module provides the `processImage` function. In your component's Javascript file, import the function from the `lightning/mediaUtils` module.

```javascript
import { processImage } from "lightning/mediaUtils";
```

## processImage

Resizes and compresses image files.

Call this function by passing in an input image and a set of options to be used to process the input image, as further described below. It returns a promise that resolves to a `Blob` object containing the output image data.

| Parameter                       | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`                         | `file` or `blob` | Defines the input image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `options`                       | `object`         | An object that defines the options to be used when processing the input image. Optional parameter containing a number of flags. If this parameter or any of its flags are omitted, default values will be used.                                                                                                                                                                                                                                                                                       |
| `options.resizeMode`            | `string`         | Determines how the image will be resized. Valid values: <ul><li>`fill`: This is the default. The image will be resized to fill the target dimension. If necessary, the image will be stretched or squished to fit.</li> <li>`contain`: The image keeps its aspect ratio but will be resized to fit within the target dimension.</li><li>`none`: The image will not be resized and will retain its original dimension.</li></ul>                                                                       |
| `options.resizeStrategy`        | `string`         | Determines how to resize the image. Ignored if `resizeMode` is `none`. Valid values: <ul><li>`reduce`: Only resize if the image is larger than the target size (smaller images won't be resized).</li><li>`enlarge`: Only resize if the image is smaller than the target size (larger images won't be resized).</li><li>`always`: This is the default. Always resize the image to the target size regardless of the original image dimensions.</li></ul>                                              |
| `options.targetWidth`           | `number`         | The target width when resizing an image. Defaults to original image width if omitted. Ignored if `resizeMode` is `none`.                                                                                                                                                                                                                                                                                                                                                                              |
| `options.targetHeight`          | `number`         | The target height when resizing an image. Defaults to original image height if omitted. Ignored if `resizeMode` is `none`.                                                                                                                                                                                                                                                                                                                                                                            |
| `options.compressionQuality`    | `number`         | A number between 0-1 that determines the compression quality. If omitted then the browser/webview picks a default value as it sees fit. Note that this parameter will be considered as a suggested compression quality, however the browser/webview may choose to override this value if it deems it necessary. For example if the value is larger than 1 or if it is considered to be too small by the browser/webview, then it will override the value to something that it deems more appropriate. |
| `options.imageSmoothingEnabled` | `boolean`        | Determines whether scaled images are smoothed. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `options.preserveTransparency`  | `boolean`        | Determines whether transparency info should be preserved. Defaults to `true`. If input is GIF/PNG and this is `true`, output will be PNG. For all other cases the output will be a JPEG.                                                                                                                                                                                                                                                                                                              |
| `options.backgroundColor`       | `string`         | Defines a CSS color as described in the [MDN color reference](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Defaults to `white`. When `preserveTransparency` is set to `false`, the output image has its background set to this color before the input image is resized and drawn on top.                                                                                                                                                                                            |
|                                 |

## Usage

Consider an example where you upload files to a Salesforce org using a [`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) component.

<!-- prettier-ignore -->
```html
<lightning-input
  type="file"
  label="Select Files to Upload"
  accept="image/*"
  multiple
  onchange={handleFilesSelected}
>
</lightning-input>
```

In your Javascript file, use `processImage` to reduce image sizes and hence reduce the bandwidth used to upload the images, as illustrated below:

```javascript
import { LightningElement } from 'lwc';
import { processImage } from 'lightning/mediaUtils';
.
.
async handleFilesSelected(event) {
    try {
        // Using the below options we resize images to a maximum of 2048x2048 pixels
        // while containing their aspect ratio. By setting 'resizeStrategy' to 'reduce'
        // we ensure that only images that have either width or height larger than
        // 2048 pixels will be resized. Moreover, we've chosen not to preserve transparency
        // in the input images and instead convert transparent pixels to white. Lastly,
        // the images will be compressed with a 75% compression quality to reduce their byte size.
        let options = {
            resizeMode: 'contain',
            resizeStrategy: 'reduce',
            targetWidth: 2048,
            targetHeight: 2048,
            compressionQuality: 0.75,
            imageSmoothingEnabled: true,
            preserveTransparency: false,
            backgroundColor: 'white'
        };

        for (const file of event.target.files) {
            let blob = await processImage(file, options);
            // here we can upload the data contained in the blob that is returned by processImage
        }
    }
    catch (error) {
        console.error("ERROR: ", error)
    }
}
.
.
```

The `mediaUtils` library is not meant to be used for processing arbitrarily large images. This library uses JavaScript APIs and the HTML5 Canvas element to process the image. It is limited by the browser, the Canvas element, and the hardware limitations of your device, like the amount of available memory.

Most desktop browsers require the input image to have a dimension of 32,767 x 32,767 pixels or smaller, while other desktop browsers have a lower limit. However, this limit can be significantly lower on mobile devices.
Also, note that the `mediaUtils` library needs to convert the input images to an uncompressed bitmap in the device memory before they can be processed further. This means that the byte-size of your input image increases after it is converted to an uncompressed bitmap. This is especially true with JPEG images, where the image is compressed using a JPEG compression algorithm to reduce their byte-size. When you convert a JPEG image back to an uncompressed bitmap, the byte-size of the resulting bitmap may be much larger than the original image. This can stop the `mediaUtils` library from processing your input image because there is not enough memory (especially on mobile devices where device memory is often smaller than desktops).

For these reasons, consider limiting the dimension and byte-size of the images that you pass to the `mediaUtils` library. A good starting point is 4,096 x 4,096 pixels and 10 MB in size. You can then experiment and adjust these limits based on your use-case scenarios.


:::::

:::::tab
::component-specification{component="mediaUtils" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2ca3a2dd8aa22610d851e46a3e13ee20aa41cf318dcbecf7d7b6392faadaa6cd url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/menuDivider/lightning-menu-divider.md -->


# Menu Divider

**`lightning-menu-divider`**

Creates a divider in the list of items for lightning-button-menu.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="menuDivider" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning-menu-divider` component creates a dividing line after a menu item in a
[`lightning-button-menu`](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html) component.
Use a menu divider to introduce a break between item categories or separate items into groups,
for example.

To draw a line after a menu item, nest the component inside `lightning-button-menu` after the `lightning-menu-item` where you want the line. Use `lightning-menu-divider` as a sibling of `lightning-menu-item`, not as a child component.

This example shows a dropdown menu with two dividers.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu label="Veggies">
        <lightning-menu-item label="Spinach"> </lightning-menu-item>
        <lightning-menu-item label="Kale"> </lightning-menu-item>
        <lightning-menu-divider> </lightning-menu-divider>
        <lightning-menu-item label="Zucchini"> </lightning-menu-item>
        <lightning-menu-item label="Yellow Squash"> </lightning-menu-item>
        <lightning-menu-divider> </lightning-menu-divider>
        <lightning-menu-item label="Carrot"> </lightning-menu-item>
        <lightning-menu-item label="Parsnip"> </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

By default, space is added above and below the divider. Use `variant="compact"` with `lightning-menu-divider` to reduce the space.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu label="Veggies">
        <lightning-menu-item label="Spinach"> </lightning-menu-item>
        <lightning-menu-item label="Kale"> </lightning-menu-item>
        <lightning-menu-divider variant="compact"> </lightning-menu-divider>
        <lightning-menu-item label="Zucchini"> </lightning-menu-item>
        <lightning-menu-item label="Yellow Squash"> </lightning-menu-item>
        <lightning-menu-divider variant="compact"> </lightning-menu-divider>
        <lightning-menu-item label="Carrot"> </lightning-menu-item>
        <lightning-menu-item label="Parsnip"> </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

For further customization of button menus, use [`lightning-menu-subheader`](/docs/platform/lightning-component-reference/guide/lightning-menu-subheader.html) to create subheaders in the list of items. You can place dividers under subheaders or menu items.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu label="Veggies">
        <lightning-menu-subheader label="Leafy Greens">
        </lightning-menu-subheader>
        <lightning-menu-item label="Spinach"> </lightning-menu-item>
        <lightning-menu-item label="Kale"> </lightning-menu-item>
        <lightning-menu-divider variant="compact"> </lightning-menu-divider>
        <lightning-menu-subheader label="Summer Squash">
        </lightning-menu-subheader>
        <lightning-menu-item label="Zucchini"> </lightning-menu-item>
        <lightning-menu-item label="Yellow Squash"> </lightning-menu-item>
        <lightning-menu-divider variant="compact"> </lightning-menu-divider>
        <lightning-menu-subheader label="Root Vegetables">
        </lightning-menu-subheader>
        <lightning-menu-item label="Carrot"> </lightning-menu-item>
        <lightning-menu-item label="Parsnip"> </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->


:::::

:::::tab
::component-specification{component="menuDivider" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=08bc6eadcf09fb1a6b44be587ad55cd0e6cb4714c270eafb3d7873427abb883f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/menuFocusChange/ui-menu-focus-change.md -->

# Menu Focus Change (Deprecated)

**`ui:menuFocusChange`**

Deprecated as of API version 47.0. Use [`lightning:buttonMenu`](/docs/platform/lightning-component-reference/guide/aura-button-menu.html) instead.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when you scroll up and down the `ui:menuList` component, which triggers a focus change in menu items. To set a handler for the `ui:menuFocusChange` event, use the `menuFocusChange` attribute on `ui:menuList`.

The following example shows a menu with two list items. The `handleChange` client-side controller handles the `ui:menuFocusChange` event.

```xml
<aura:component>
  <ui:menu>
    <ui:menuTriggerLink aura:id="trigger" label="Contacts" />
    <ui:menuList class="actionMenu" aura:id="actionMenu" menuFocusChange="{!c.handleChange}">
      <ui:actionMenuItem aura:id="item1" label="All Contacts" />
      <ui:actionMenuItem aura:id="item2" label="All Primary" />
    </ui:menuList>
  </ui:menu>
</aura:component>
```

If you're using this event with a component other than `ui:menuList`, register the event first.

```xml
<aura:registerEvent
  name="menuFocusChange"
  type="ui:menuFocusChange"
  description="The event fired when the menu list focus changes from one menu item to another."
/>
```


:::::

:::::tab
## Attributes

| Name           | Description                              | Type        | Default | Required |
| -------------- | ---------------------------------------- | ----------- | ------- | -------- |
| `currentItem`  | The menu item that's currently focused.  | component[] |         |          |
| `previousItem` | The menu item that's previously focused. | component[] |         |          |

:::::

::::::

<!-- document id=791727cca95401db1166d692101a2da6d6fed07bb7d8b961a1cc88bb21a0b666 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/menuItem/lightning-menu-item.md -->


# Menu Item

**`lightning-menu-item`**

Represents a list item in a menu.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="menuItem" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-menu-item` is a menu item within the [`lightning-button-menu`](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html)
dropdown component. It can hold state such as checked or unchecked, and can
contain icons.

Use the `class` attribute to customize the styling.

When applying Lightning Design System classes or icons, check that they’re
available in the Lightning Design System release tied to your org. The
Lightning Design System site shows the latest Lightning Design System
resources, and these resources become available only when the new release is available
in your org.

Here’s an example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu alternative-text="Toggle menu">
        <lightning-menu-item
            label="Menu Item 1"
            value="menuitem1"
            icon-name="utility:table"
        >
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Design

Use `lightning-menu-item` within [`lightning-button-menu`](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html), which implements the menus blueprint in the Salesforce Lightning Design System (SLDS).
The menus adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Menus](https://v1.lightningdesignsystem.com/components/menus/)                                                                       | [Menus](https://www.lightningdesignsystem.com/components/menus/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Multi-select Menus

To implement a multi-select menu, use the `checked` attribute. The following
JavaScript example handles selection via the `onselect` event on
the `lightning-button-menu` component. Selecting a menu item applies the
selected state to that item.

```javascript
handleSelect (event) {
        const selectedItemValue = event.detail.value;
        const menuItem = this.privateMenuItems.find(function(item) {
            return item.value === selectedItemValue;
        });

        menuItem.checked = !menuItem.checked;
    }
```

## Add Icons to Menu Items

Use the `icon-name` attribute to add an icon after the text of the menu item.
Use the `prefix-icon-name` attribute to add an icon before the text of the menu
item.

This example displays an icon in grayscale before the menu item text.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu>
        <lightning-menu-item prefix-icon-name="utility:user" label="Menu item">
        </lightning-menu-item>
        <lightning-menu-item label="Another menu item"> </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Add Icons with Background Colors

The [SLDS action and object icons](https://v1.lightningdesignsystem.com/icons/) (standard and custom) have background colors. However, when you use these icons in menu items, the colors aren't shown by default.

To specify icons with a background color in menu items, use the `icon-type` attribute. The `icon-type` attribute accepts two values.

- `standard` (default): Sets the icon on the menu item in grayscale.
- `color`: Sets the icon on the menu item with a background color. Action icons and object icons display a white glyph on a colored background that's defined in [SLDS](https://v1.lightningdesignsystem.com/icons/#standard). Doctype and utility icons don't display with a background color.

To enable colored icons and backgrounds, use the `icon-type="color"` attribute. In this example, the `standard:event` icon specifies a background color and the `utility:settings` icon is in grayscale.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu>
        <lightning-menu-item
            prefix-icon-name="standard:event"
            icon-type="color"
            label="Standard icon with icon-type color">
        </lightning-menu-item>
        <lightning-menu-item
            icon-name="utility:settings"
            icon-type="color"
            label="Utility icon with icon-type color">
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

Setting `icon-type="color"` assigns the menu items with icons using their full color schemes, including any associated background colors. Remember that the appearance of icons can still be subject to the overall theme and styling of your Salesforce org or Lightning application.

You can find a comprehensive list of all available icons and their appearances at the [Lightning Design System Icons page](http://lightningdesignsystem.com/icons/).

## Use URLs in Menu Items

The `href` attribute allows you to use the button menu for navigation. This
example specifies a URL in the menu item's `href` attribute to create a link.
The link is applied to the content of the menu item, including text and icons.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu>
        <lightning-menu-item
            href="https://www.google.com"
            label="A linked menu item"
        >
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

If you don't provide a target, the link opens in the same frame or browser tab where it was clicked, which is the browser's default behavior.
To open the link in a new browser tab, set `target="_blank"`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu>
        <lightning-menu-item
            href="https://www.google.com"
            target="_blank"
            label="A linked menu item"
        >
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Draft Indicators

Use the `is-draft` and `draft-alternative-text` attributes together to indicate
that the menu item is in an unsaved state. The draft indicator, an asterisk,
is shown for the menu item when `is-draft` is `true`. The
`draft-alternative-text` attribute is required to provide text describing the
reason the item is considered in a draft state. The draft state can be used
to show that there's' unsaved state or data that could be lost, for example if
there's a user change in a customizable menu.


:::::

:::::tab
::component-specification{component="menuItem" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=662786a90630472cb1aa0c228a0b2858b87dd0921f83476bf2e2251512b22b60 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/menuSelect/ui-menu-select.md -->

# Menu Select (Deprecated)

**`ui:menuSelect`**

Deprecated as of API version 47.0. Use [`lightning:select`](/docs/platform/lightning-component-reference/guide/aura-select.html) or [`lightning:combobox`](/docs/platform/lightning-component-reference/guide/aura-combobox.html) instead.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when you select a menu item on the `ui:menuList` component. To set a handler for the `ui:menuSelect` event, use the `menuSelect` attribute on `ui:menuList`.

The following example shows a menu with two list items. The `handleSelect` client-side controller action handles the `ui:menuSelect` event.

```xml
<aura:component>
  <ui:menu>
    <ui:menuTriggerLink aura:id="trigger" label="Contacts" />
    <ui:menuList class="actionMenu" aura:id="actionMenu" menuSelect="{!c.handleSelect}">
      <ui:actionMenuItem aura:id="item1" label="All Contacts" click="{!c.doSomething}" />
      <ui:actionMenuItem aura:id="item2" label="All Primary" click="{!c.doSomething}" />
    </ui:menuList>
  </ui:menu>
</aura:component>
```

When a menu item is clicked, the click event is handled before the `ui:menuSelect` event.

```javascript
({
  handleSelect: function (component, event, helper) {
    var selected = event.getParam("selectedItem");

    // returns label of selected item
    var selectedLabel = selected.get("v.label");
  },

  doSomething: function (component, event, helper) {
    console.log("do something");
  },
});
```

If you're using this event with a component other than `ui:menuList`, register the event first.

```xml
<aura:registerEvent
  name="menuSelect"
  type="ui:menuSelect"
  description="The event fired when a menu item is selected."
/>
```


:::::

:::::tab
## Attributes

| Name               | Description                                                 | Type        | Default | Required |
| ------------------ | ----------------------------------------------------------- | ----------- | ------- | -------- |
| `deselectSiblings` | Deselects the siblings of the currently selected menu item. | boolean     |         |          |
| `focusTrigger`     | Sets focus to menuTrigger.                                  | boolean     |         |          |
| `hideMenu`         | Hides menu if set to true.                                  | boolean     |         |          |
| `selectedItem`     | The menu item that's selected.                              | component[] |         |          |

:::::

::::::

<!-- document id=47265b802927e158f003d8e0147690cdab0ee504a0bad7435aea2ce467996cb1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/menuSubheader/lightning-menu-subheader.md -->


# Menu Subheader

**`lightning-menu-subheader`**

Creates a subheader in the list of items in lightning-button-menu.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="menuSubheader" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning-menu-subheader` component creates a heading in the list of menu items in a
[`lightning-button-menu`](/docs/platform/lightning-component-reference/guide/lightning-button-menu.html) component.
The heading appears in bold text and is slightly larger than menu item text.
Subheaders can help categorize items and improve usability for long lists.

Specify the text of the heading using the `label` attribute.

Nest the component inside `lightning-button-menu` before the `lightning-menu-item` where you want the header. Use `lightning-menu-subheader` as a sibling of `lightning-menu-item`, not as a child component.

This example shows a dropdown menu with subheaders.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu label="Veggies">
        <lightning-menu-subheader label="Leafy Greens">
        </lightning-menu-subheader>
        <lightning-menu-item label="Spinach"> </lightning-menu-item>
        <lightning-menu-item label="Kale"> </lightning-menu-item>
        <lightning-menu-subheader label="Summer Squash">
        </lightning-menu-subheader>
        <lightning-menu-item label="Zucchini"> </lightning-menu-item>
        <lightning-menu-item label="Yellow Squash"> </lightning-menu-item>
        <lightning-menu-subheader label="Root Vegetables">
        </lightning-menu-subheader>
        <lightning-menu-item label="Carrot"> </lightning-menu-item>
        <lightning-menu-item label="Parsnip"> </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

For further customization of button menus, use [`lightning-menu-divider`](/docs/platform/lightning-component-reference/guide/lightning-menu-divider.html) to create divider lines in the list of items. You can place dividers under subheaders or menu items.


:::::

:::::tab
::component-specification{component="menuSubheader" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9aeb980227a8948b09bd9ed2941f821e3080a67e916408839a4cf0d517f65914 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/menuTriggerPress/ui-menu-trigger-press.md -->

# Menu Trigger Press (Deprecated)

**`ui:menuTriggerPress`**

Deprecated as of API version 47.0. Use [`lightning:buttonMenu`](/docs/platform/lightning-component-reference/guide/aura-button-menu.html) instead.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when you click on the `ui:menuTriggerLink` component. To set a handler for the `ui:menuTriggerLink` event, use the `menuTriggerPress` attribute on `ui:menuTriggerLink`.

The following example shows a menu with two list items. The `handleTriggerPress` client-side controller action handles the `ui:menuTriggerPress` event.

```xml
<aura:component>
  <ui:menu>
    <ui:menuTriggerLink
      aura:id="trigger"
      label="Contacts"
      menuTriggerPress="{!c.handleTriggerPress}"
    />
    <ui:menuList class="actionMenu" aura:id="actionMenu">
      <ui:actionMenuItem aura:id="item1" label="All Contacts" click="{!c.doSomething}" />
      <ui:actionMenuItem aura:id="item2" label="All Primary" click="{!c.doSomething}" />
    </ui:menuList>
  </ui:menu>
</aura:component>
```

This client-side controller retrieves the label of the trigger when it’s clicked.

```javascript
({
  handleTriggerPress: function (component, event, helper) {
    var trigger = component.find("trigger");

    // Get the label on the trigger
    var triggerLabel = trigger.get("v.label");
  },
});
```

If you're using this event with a component other than `ui:menuTriggerLink`, register the event first.

```xml
<aura:registerEvent
  name="menuTriggerPress"
  type="ui:menuTriggerPress"
  description="The event fired when the trigger is clicked."
/>
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=00fcd5091d28e3e5934be778b327809a08368f0916a0ad4cc9310bf9f1f4315e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/messageService/lightning-message-service.md -->

# Message Service

**`lightning/messageService`**

Enables communication across different types of pages.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use Lightning message service to communicate across the DOM between Visualforce pages, Aura components, and Lightning web components, including components in a pop-out utility bar.

Use the Lightning message service functions to communicate over a Lightning message channel.

In a component's Javascript file, import the functions you need from the `lightning/messageService` module. Import a message channel using the scoped module `@salesforce/messageChannel`.

```javascript
import {
  APPLICATION_SCOPE,
  createMessageContext,
  MessageContext,
  publish,
  releaseMessageContext,
  subscribe,
  unsubscribe,
} from "lightning/messageService";
import recordSelected from "@salesforce/messageChannel/Record_Selected__c";
```

## `createMessageContext()`

Returns a `MessageContext` object.

Call this function in a service component that doesn't extend `LightningElement`. In a service component, you can’t use `@wire(MessageContext)` to create a `MessageContext` object. Instead, call the `createMessageContext()` function to create the `MessageContext` object and assign it to a field, like `messageContext`. Then, pass `messageContext` into the `subscribe()` function. `MessageContext` isn’t automatically released for service components. Call `releaseMessageContext(messageContext)` to remove any subscriptions associated with your Lightning web component’s `MessageContext`.

## `publish(messageContext, messageChannel, message)`

Publishes a message to a specified message channel.

| Parameter        | Type   | Description                                                                                                                                                                                                            |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageContext` | object | The `MessageContext` object provides information about the Lightning web component that is using the Lightning message service. Get this object via the `MessageContext` wire adapter or via `createMessageContext()`. |
| `messageChannel` | object | The message channel object. To import a message channel, use the scoped module `@salesforce/messageChannel`. To create a message channel in an org, use the LightningMessageChannel metadata type.                     |
| `message`        | object | A serializable JSON object containing the message published to subscribers. A message can't contain functions or symbols.                                                                                              |

## `releaseMessageContext(messageContext)`

Releases a `MessageContext` object associated with a Lightning web component and unsubscribes all associated subscriptions.

## `subscribe(messageContext, messageChannel, listener, subscriberOptions)`

Subscribes to a specified message channel. Returns a Subscription object that you can use to unsubscribe.

By default, communication over a message channel can occur only between Lightning web components, Aura components, or Visualforce pages in an active navigation tab, an active navigation item, or a utility item. Utility items are always active. A navigation tab or item is active when it’s selected. Navigation tabs and items include:

- Standard navigation tabs
- Console navigation workspace tabs
- Console navigation subtabs
- Console navigation items

To receive messages on a message channel from anywhere in the application, pass the `subscriberOptions` parameter as `{scope: APPLICATION_SCOPE}`. Import `APPLICATION_SCOPE` from `lightning/messageService`.

| Parameter           | Type     | Description                                                                                                                                                                                                                       |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageContext`    | object   | The `MessageContext` object provides information about the Lightning web component that is using the Lightning message service.                                                                                                   |
| `messageChannel`    | object   | To import a message channel, use the scoped module `@salesforce/messageChannel`. To create a message channel in an org, use the LightningMessageChannel metadata type.                                                            |
| `listener`          | function | A function that handles the message once it is published.                                                                                                                                                                         |
| `subscriberOptions` | object   | (Optional) An object that, when set to `{scope: APPLICATION_SCOPE}`, specifies the ability to receive messages on a message channel from anywhere in the application. Import `APPLICATION_SCOPE` from `lightning/messageService`. |

## `unsubscribe(subscription)`

Unsubscribes from a message channel.

| Parameter      | Type   | Description                                                     |
| -------------- | ------ | --------------------------------------------------------------- |
| `subscription` | object | The Subscription object returned by the `subscribe()` function. |

## `MessageContext` Wire Adapter

Returns a `MessageContext` object.

The `MessageContext` object contains information about the Lightning web component that is using the Lightning message service. Pass the `MessageContext` object to the `publish()` and `subscribe()` functions. 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.

```javascript
    @wire(MessageContext)
    messageContext;
```

## Usage

These two components publish a message and subscribe to the message over the same 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);
  }
}
```

```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",
      }),
    );
  }
}
```

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/messageService`, see the following components in the LWC Recipes repo.

- `c-lms-publisher-web-component`
- `c-lms-subscriber-web-component`

## See Also

[Lightning Web Components Developer Guide: Communicate Across the DOM with Lightning Message Service](https://developer.salesforce.com/docs/platform/lwc/guide/use-message-channel)


:::::

:::::tab
::component-specification{component="messageService" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=ea94d32f1b205dadf2d7248d9209c6e83e2c38581d8d9060b0e0495644bb4120 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/methodCall/aura-method-call.md -->

# Method Call

**`aura:methodCall`**

Indicates that a public method was called.

::::::tabset{tabs='["Specifications"]'}

:::::tab
## Attributes

| Name        | Description                                          | Type   | Default | Required |
| ----------- | ---------------------------------------------------- | ------ | ------- | -------- |
| `arguments` | The list of arguments passed into the public method. | list   |         |          |
| `name`      | The name of the method called.                       | string |         |          |

:::::

::::::

<!-- document id=d4a8c9f3d1f6290e9f1ef3cd5427ba779b9449332260967c6551a08bec74daf5 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/modal/lightning-modal.md -->


# Modal

**`lightning/modal`**

Extend this component to create a modal window overlayed on the current app window.

**For Use In**

Lightning Experience, Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="modal" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning/modal` module provides the `LightningModal` component to create a modal window on top of the current app window. A modal interrupts a user’s workflow.

**note:** The `<dialog>` HTML element isn't currently supported. Use `lightning/modal` when you want to show content in a modal dialog with SLDS styling.

Create a modal component 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.

Unlike other components, this component doesn't use a `lightning-modal` tag or extend `LightningElement`. There is no `lightning-modal` component. Instead, you create a modal by extending `LightningModal` and using these helper `lightning-modal-*` components to provide a header, footer, and the body of the modal.

- `lightning-modal-body`
- `lightning-modal-header`
- `lightning-modal-footer`

## Design

Use `lightning/modal` with the `lightning-modal-*` components, which implement the modals blueprint in the Salesforce Lightning Design System (SLDS). The modals adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                            | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Modals](https://v1.lightningdesignsystem.com/components/modals/) | [Modals](https://www.lightningdesignsystem.com/components/modals/)                                              |
| **For Use In** | Lightning Experience, Standalone Lightning app                    | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

To create a modal component, import `LightningModal` from `lightning/modal`. 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.

In this example, the `content` property passes data to the modal from the component that invokes it.

```js
/* c/myModal.js */

import { api } from "lwc";
import LightningModal from "lightning/modal";

export default class MyModal extends LightningModal {
  @api content;

  handleOkay() {
    this.close("okay");
  }
}
```

The modal’s HTML template uses helper `lightning-modal-*` components to provide a header, footer, and the body of the modal. In this example, the content for the modal body comes from the `content` property we defined in the modal's JavaScript file.

<!-- prettier-ignore-start -->
```html
<!-- c/myModal.html -->

<template>
    <lightning-modal-header label="My Modal Heading"></lightning-modal-header>
    <lightning-modal-body> Content: {content} </lightning-modal-body>
    <lightning-modal-footer>
        <lightning-button label="OK" onclick={handleOkay}></lightning-button>
    </lightning-modal-footer>
</template>
```
<!-- prettier-ignore-end -->

The `lightning-modal-body` component is required for the modal template.

The `lightning-modal-header` and `lightning-modal-footer` components are optional, but recommended. The `lightning-modal-*` components render in the order they appear in the template. Place the `lightning-modal-body` component after `lightning-modal-header` and before the `lightning-modal-footer` component.

## Open a Modal Instance

`LightningModal` provides an `.open()` method, which opens a modal and returns a promise that asynchronously resolves with the result of the user’s interaction with the modal.

Each invocation of a modal component’s `.open()` method creates a unique instance of the modal. You can think of a modal as a self-contained application that starts from scratch when it opens. It displays the content that you pass in through the `.open()` method or that you set within the modal's HTML template.

When you close a modal, the modal instance is destroyed, not hidden. On close, the modal must save the user’s input data or pass it to the invoking component as the promise result. Otherwise, the data is lost when the modal instance is closed.

The `.open()` method lets you assign values to the modal's properties. `LightningModal` provides these properties.

- `label` - Required. Sets the modal's title and assistive device label. If the modal has a header, set `label` in the `lightning-modal-header` component. If the modal doesn't have a header, set the `label` property when opening the modal.

- `size` - Determines how much of the viewport width the modal uses. Supported values are `small`, `medium`, `large`, and `full`. You can set the `size` attribute when you open the modal. You can't change the modal size after the modal is opened. Default value is `medium`. The height of the modal is determined by the amount of content in the `lightning-modal-body` component, and the `size` value. For more information on the `full` variant, see the [**Styling Variants**](#styling-variants) section.

- `description` - Sets the modal's accessible description. It uses the `aria-description` attribute where supported, or falls back to `aria-describedby`. If you set a `description` value, include the label name at the beginning of your description text. Some screen readers only read the description, and not the label.

- `disableClose` - Prevents closing the modal by normal means like the ESC key, the close button, or `.close()`. For example, you can briefly set `disableClose` to true while a completed form is saving, so the user doesn't dismiss the modal early. See [**Use the `disableClose` Attribute**](#use-the-disableclose-attribute).

In this example, the app opens the `myModal` component. It invokes the `.open()` method in a `handleClick()` function bound to the app button’s `onclick` attribute, and uses `async` and `await` keywords to handle the promise returned by `.open()`. This example overrides the `size` value by setting it to `large` and sets the modal’s user-defined property `content`.

```js
/* c/myApp.js */

import { LightningElement } from "lwc";
import MyModal from "c/myModal";

export default class MyApp extends LightningElement {
  async handleClick() {
    const result = await MyModal.open({
      // `label` is not included here in this example.
      // it is set on lightning-modal-header instead
      size: "large",
      description: "Accessible description of modal's purpose",
      content: "Passed into content api",
    });
    // if modal closed with X button, promise returns result = 'undefined'
    // if modal closed with OK button, promise returns result = 'okay'
    console.log(result);
  }
}
```

The HTML template for this app contains a button that opens the modal and displays the result returned when the modal closes.

<!-- prettier-ignore-start -->
```html
<!-- c/myApp.html -->

<template>
    <lightning-button
        onclick={handleClick}
        aria-haspopup="dialog"
        label="Open My Modal">
    </lightning-button>
    <p>Result: {result}</p>
</template>
```
<!-- prettier-ignore-end -->

You can also use `.open()` to pass data from your invoking component into the modal with custom properties decorated with `@api`. These properties can be any type, such as a string or an object that’s an array of key/value pairs to be assigned to the new modal instance.

For example, this app component sets an `options` property to a set of key/value pairs in `MyModal.open()`. The promise is handled using an arrow function that logs the result to the console.

```js
/* c/myApp.js */

import { LightningElement } from "lwc";
import MyModal from "c/myModal";

export default class MyPage extends LightningElement {
  handleOpenClick() {
    MyModal.open({
      // maps to developer-created `@api options`
      options: [
        { id: 1, label: "Option 1" },
        { id: 2, label: "Option 2" },
      ],
    }).then((result) => {
      console.log(result);
    });
  }
}
```

The modal dialog can then use this property. In this case, the modal creates buttons whose labels are provided in the `options` array.

```js
/* c/myModal.js */

import { api } from "lwc";
import LightningModal from "lightning/modal";

export default class MyModal extends LightningModal {
  // Data is passed to api properties via .open({ options: [] })
  @api options = [];
}
```

<!-- prettier-ignore-start -->
```html
<!-- c/myModal.html -->

<template>
    <lightning-modal-header label="My Modal Heading"></lightning-modal-header>
    <lightning-modal-body>
        Let's make some buttons!
        <template for:each={options} for:item="option">
            <lightning-button
              onclick={handleOptionClick}
              data-id={option.id}
              key={option.id}
            >
                {option.label}
            </lightning-button>
        </template>
    </lightning-modal-body>
</template>
```
<!-- prettier-ignore-end -->

## Close a Modal Instance

Use `this.close(result)` to close the modal, where `result` is anything you want to return from the modal. The `.close()` operation is asynchronous to display a brief fade out animation before the modal is destroyed. The `result` data can’t be modified after the close operation begins.

You can also close the modal with the default close button, the X in the top right corner. Closing a modal like this is the same as calling `this.close()` with an `undefined` result, so any data input is lost.

This example shows the handler for some buttons inside a modal. When the user clicks the button, `this.close(id)` returns the option that they chose and the modal closes.

```js
/* 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);
  }
}
```

<!-- prettier-ignore-start -->
```html
<!-- c/myModal.html -->

<template>
  <template for:each={options} for:item="option">
    <lightning-button
      onclick={handleOptionClick}
      data-id={option.id}
      key={option.id}
    >
      {option.label}
    </lightning-button>
  </template>
</template>
```
<!-- prettier-ignore-end -->

## Use the `disableClose` Attribute

`disableClose` temporarily turns off the ability to dismiss the modal by normal means like the ESC key, the close button, or `this.close()`. For example, you could briefly set `disableClose` to `true` while a completed form is saving, so the user doesn't dismiss the modal early.

Preventing a modal's close should be a temporary state. Use `disableClose` for less than 5 seconds. Accessibility is affected if you trap keyboard focus inappropriately. See [No Keyboard Trap](https://www.w3.org/TR/UNDERSTANDING-WCAG20/keyboard-operation-trapping.html) for more information.

When the process using `disableClose` finishes successfully, dismiss the modal. If the process using `disableClose` fails, re-enable the ability to dismiss the modal with `disableClose = false`, or give feedback to help the user resolve the issue.

While `disableClose` is `true`, disable any processes or UI buttons that might call `Modal.close()`.

This example shows how to use `disableClose`. It's not a fully functional example, but could be used in a complex modal component.

```js
/* c/myModalForm.js */
/* This is intended as a mock example, not as fully functional code */
/* NOTE: observe values set:
   this.disableClose (in JS),
   and this.saveInProcess (in JS and HTML)
*/
import { api } from "lwc";
import LightningModal from "lightning/modal";

export default class MyModalForm extends LightningModal {
  // formData is utilized for saving current form values
  formData = {};
  failureType = null;
  saveStatus = {};
  saveInProcess = false;

  handleCloseClick() {
    this.close("canceled");
  }

  closeModal() {
    // immediately exits, so no need to trigger
    // this.disableClose = false OR
    // this.saveInProcess = false;
    // modal is destroyed, and focus moves
    // back to originally clicked item that
    // generated the modal
    this.close("success");
  }

  mitigateSaveFailure() {
    // depending on how easily the failure can be resolved
    // you may need to immediately set disableClose = false
    if (this.failureType === "recoverable") {
      // no need to call this.disableClose = false
      // or this.saveInProgress = false yet
      tryToFixFailure();
    } else {
      // can't resolve the error
      // need to allow users to exit modal
      this.disableClose = false;
      this.saveInProcess = false;
      // mock function to indicate modal state
      // while still allowing user to exit
      // preventing keyboard trap
      reportUnresolvableError();
    }
  }

  async saveData() {
    // switches disabled state on buttons
    this.saveInProcess = true;
    const saveStatus = await sendData(this.formData);
    return saveStatus && saveStatus.success ? closeModal() : mitigateSaveFailure();
  }

  async handleSaveClick() {
    if (isValid(this.formData)) {
      // begin saving data, temporarily disable
      // LightningModal's close button
      // Be sure to reenable the close button, by setting
      // this.disableClose = false, IF further interaction
      // is desired before the modal closes
      this.disableClose = true;
      await saveData();
    } else {
      // function that display form errors based on data
      showFormErrors(this.formData);
    }
  }
}
```

<!-- prettier-ignore-start -->
```html
<!-- c/myModalForm.html -->

<template>
    <lightning-modal-header
      label="My Modal Heading"
    ></lightning-modal-header>
    <lightning-modal-body>
      <!-- form here -->
    </lightning-modal-body>
    <lightning-modal-footer>
      <button
        disabled={saveInProcess}
        onclick={handleCloseClick}
        aria-label="Cancel and close"
      >Cancel</button>
      <button
        disabled={saveInProcess}
        onclick={handleSaveClick}
      >Save</button>
    </lightning-modal-footer>
</template>
```
<!-- prettier-ignore-end -->

## Modal Events

A modal can only fire events captured by the component that opened it, not the modal itself. Normal techniques can't catch events that fire from the modal, because the events bubble up to a top root element outside the component that opened the modal.

To capture modal events, attach them in the `.open()` method invoked by the component that opens the modal.

Capturing modal events requires [Lightning Web Security (LWS)](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable.html) to be enabled in the Salesforce org. See the [**Modal Events with LWS and Lightning Locker**](#modal-events-with-lws-and-lightning-locker) section for more information.

For example, here's a custom `select` event dispatched from `MyModal`.

```js
/* c/myModal.js */
dispatchSelectEvent(e) {
  // e.target might represent an input with an id and value
  const { id, value } = e.target;
  const selectEvent = new CustomEvent('select', {
    detail: { id, value }
  });
  this.dispatchEvent(selectEvent);
}
```

The `open()` method in `myApp` defines the `onselect` event handler. This example uses `onselect` to proxy events that we want to pass through.

```js
/* c/myApp.js */

// ...
// Process the select event from within the modal
handleSelectEvent(detail) {
  const { id, value } = detail;
  console.log(`select event fired elem with id ${id} and value: ${value}`);
}

// ...
// Trigger visibility of the modal
handleOpenModal() {
  MyModal.open({
    label: 'Modal Title',
    size: 'large',
    description: 'Modal Title with brief description',
    // event triggered when new CustomEvent('select', {detail: {}});
    // occurs *from within* LightningModal.
    // see dispatchSelectEvent() in c/myModal.js above
    onselect: (e) => {
      // stop further propagation of the event
      e.stopPropagation();
      // hand off to separate function to process
      // result of the event (see above in this example)
      this.handleSelectEvent(e.detail);
      // or proxy to be handled above by dispatching
      // another custom event to pass on the event
      // this.dispatchEvent(e);
    }
  });
}
```

See [Create and Dispatch Events](https://developer.salesforce.com/docs/platform/lwc/guide/events-create-dispatch) in the LWC Dev Guide for more information about events.

## Modal Events with LWS and Lightning Locker

Modal events work as expected when Lightning Web Security (LWS) is enabled within a Salesforce org, as described in the [**Modal Events**](#modal-events) section. If LWS isn't enabled in an org, Lightning Locker is in effect.

LWS is replacing Lightning Locker over time and is already enabled in many customer orgs. New orgs have LWS enabled by default. To enable LWS, see [Enable Lightning Web Security in an Org](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/lws-enable.html) in the Security for Lightning Components guide.

Under Lightning Locker, when you fire events within `LightningModal`, the browser throws a `TypeError` related to `dispatchEvent`. If your modal component runs in an org that can’t enable LWS yet, the workaround is to wrap the code that calls `dispatchEvent` in a child component that extends `LightningElement`. Use the wrapper component as a child of one of the modal components in the modal template.

See [Navigate From a Modal](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-modal) in the LWC Dev Guide for an example.

## Modal Events with Aura

For `LightningModal`, only the top level LWC component or application can communicate to the parent Aura component or application layer with eventing. This topmost component is usually the one that opens the `LightningModal`. `LightningModal`'s child components can't event to a parent Aura component or application layer.

All required eventing that should occur during the `LightningModal`'s life cycle must be passed in when you call `Modal.open()`. See `onselect` within `.open()` in the [**Modal Events**](#modal-events) section.

If you want the Aura layer to respond to events within child components embedded in the `LightningModal`, use event bubbling to move any data that you want to make available to the Aura layer into the topmost LWC component that opened the modal. Then, send the event from the LWC component.

With this in mind, there are two suggested methods for extracting data from the `LightningModal` to the Aura layer.

1. To only communicate data out of modal after it's closed, first, close the modal, and pass the data out with `this.close({ data })`, and handle the data received in `.then((result) { ... })` where the Modal is initially opened.
2. To continuously communicate data out of the `LightningModal` while the modal remains open, use events created and passed in when opening the modal from `Modal.open({ size, title, onmyevent })`.

These extracting methods fit into the larger LWC Modal-to-Aura event workflow.

1. Pass any events that should occur within the modal through `LightningModal`'s `.open()` method
2. Have the `LightningModal` JavaScript code fire any custom events
3. In the topmost LWC component that opened the modal, create an event handler to process the events, including stopping propagation.
4. Fire a separate event containing the LWC-processed event details and send it to the Aura parent component.
5. Use an Aura-based event handler to handle and process the event.

For more information, see [Send Events to an Enclosing Aura Component](https://developer.salesforce.com/docs/platform/lwc/guide/events-sending-to-aura-components) and [Events Best Practices](https://developer.salesforce.com/docs/platform/lwc/guide/events-best-practices).

Let's see this workflow in action. In this example, we'll create a button (`lightning-button`) that launches a modal (`LightningModal`) containing a tree grid component (`lightning-tree-grid`) with a button in each record row that automatically navigates our user to that record's page (`lightning-navigation`). This use case requires data passing between our LWC components and a parent Aura component.

Because `lightning-navigation` requires you to pass in a `recordId` to construct a page reference, we need to pass the record's data out of `LightningModal`, and then use the methods provided by `lightning-navigation`. With modal's limitations for event bubbling to the Aura layer, we can't just wrap the button or treegrid with `lightning-navigation`. We need to pull that data up to the topmost LWC component, where the `LightningModal` `.open()` is called, for our Aura wrapper to handle the navigation.

However, in [Aura-based Experience Builder sites](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_basics_templates.htm), the `NavigationMixin` event can reach the Aura layer without being affected by the modal's limitations.

So, we `import` the `lightning-navigation` component into the topmost LWC component that sits within the Aura layer by passing the data through `LightningModal`'s close method, `this.close({ data })`. Then the parent LWC component invokes the methods provided by `lightning-navigation`, which handles the navigation away from the page after the modal exits. From a UX perspective, this also lets us close the modal first, since `lightning-navigation` takes the user away from the current page.

Note that this sample code isn't fully functional. We're only showing the relevant code that makes the `lightning-navigation` use case work with `LightningModal`.

Here's our Aura component, containing our topmost LWC component, `myLwcAppModalLauncher`.

<!-- prettier-ignore-start -->
```html
/* c/myApp.cmp */
<aura:component>
    <!-- <c:myLwcTreeGridWithNavigation/> component is a child component
        inside of <c:myLwcAppModalLauncher/>
    -->
    <c:myLwcAppModalLauncher/>
</aura:component>
```
<!-- prettier-ignore-end -->

The topmost component, `myLwcAppModalLauncher`, launches and handles events that occur within our modal (`MyModal`). `myLwcAppModalLauncher` is also where we import the `lightning-navigation` component and use the `rowId` handed up through modal's `this.close({ ..., rowId })` function.

<!-- prettier-ignore-start -->
```html
<!-- c/myLwcAppModalLauncher.html -->

<template>
    <lightning-button
        onclick={handleModalOpen}
        aria-haspopup="dialog"
        label="Launch Navigation Modal">
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

```js
/* c/myLwcAppModalLauncher.js */

import { LightningElement, wire } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';
import MyModal from 'c/myModalWithTreeGridNavigation';

export default class MyLwcAppModalLauncher extends NavigationMixin(LightningElement) {

/// ... other modal code

handleModalOpen() {
    // open up the Modal
    MyModal.open({
        size: 'medium',
        heading: 'Navigate to Record Page',
        description: 'Navigate to a record page by clicking the row button',
        options: [{ data }, { data }],
    }).then((result) => {
        // when the LightningModal closes, result is whatever
        // data that was passed out using this.close({ data })
        if (result === null) {
            // do something else
        } else {
            // shouldNavigate is boolean, arbitrary
            // rowId is what's needed for lightning-navigation
            const { shouldNavigate, rowId } = result;
            if (shouldNavigate) {
                this.navigateToObjectHome(rowId);
            }
        }
    });
}

navigateToObjectHome(rowId) {
    // construct the page ref
    const pageRef = {
        type: 'standard__recordPage',
        attributes: {
            recordId: rowId,
            actionName: 'view'
        }
    }
    // then call the .Navigate method with the pageRef
    this[NavigationMixin.Navigate](pageRef);
}

/* ... other modal code */
```

This `template` is our modal, containing a tree grid with the navigation buttons, named `c-my-lwc-tree-grid-with-navigation`. The `handleNavSelection` function in this component processes the `rowId` data for the modal component to pass to its parent.

<!-- prettier-ignore-start -->
```html
<!-- c/myModalWithTreeGridNavigation.html -->
<template>
    <lightning-modal-header label="My Modal Heading">
        The modal tagline.
    </lightning-modal-header>
    <lightning-modal-body>
        <h2>Choose a record to navigate to:</h2>
        <!-- custom event listener when button clicked inside tree grid -->
        <div onnavselection={handleNavSelection}>
            <c-my-lwc-tree-grid-with-navigation></c-my-lwc-tree-grid-with-navigation>
        </div>
    </lightning-modal-body>
    <!-- no <lightning-modal-footer> in this example -->
</template>
```
<!-- prettier-ignore-end -->

```js
/* c/myModalWithTreeGridNavigation.js */
handleNavSelection(event) {
    event.stopPropagation();
    const { detail: { rowId } } = event;
    if (rowId) {
        // rowId value is important to lightning-navigation
        // passing this data out through the LightningModal's
        // .close() method, then handled in the .then((result) {})
        // see code above: c/myLwcAppModalLauncher.js
        this.close({ shouldNavigate: true, rowId });
    }
}
```

```js
/* c/myLwcTreeGridWithNavigation.js */

dispatchNavSelectionEvent(rowId) {
    // add rowId to event.detail
    // this custom event listener exists in
    // LightningModal body code, see code above:
    // c/myModalWithTreeGridNavigation.html
    const eventToFire = new CustomEvent('navselection', {
        detail: { rowId },
        bubbles: true,
        cancelable: false
    });
    // dispatch custom event
    // see event listener added to lightning-modal-body
    this.dispatchEvent(eventToFire);
}

handleRowButtonClick(event) {
    // simplified handler to get row.Id
    // from the tree grid row button that was clicked
    const row = event.detail.row;
    this.dispatchNavSelectionEvent(row.Id);
}
```

## Component Styling

Use a combination of styling variants and utility classes to customize your modal.

### Styling Variants

The `lightning-modal-header` and `lightning-modal-footer` child components are optional, and you can choose to not include one or the other in your modal.

The headerless variant of `LightningModal` has these additional requirements.

- Must set a descriptive modal title with the `label` property using `Modal.open({ label })` or you’ll get a console error.
- The `label` property is required for all variants of `LightningModal`. Assistive devices read the `label` value, even though the headerless modal variant doesn't display the label.
- Because this variant doesn't use `lightning-modal-header`, you have to manually create an `<h1>` heading in `lightning-modal-body`. Provide accessible structure by starting with heading level `<h1>` and using levels up to `<h6>` appropriately. For more information, see [Semantic Structure, Headings on WebAim.org](https://webaim.org/techniques/semanticstructure/#headings).

You can also create a full-screen modal component by setting the `size` attribute to `full`. This variant resizes the modal to the full width and height of the viewport on screens up to 30em (~480 pixels or less), like mobile phone devices. On screens larger than 30em (~481 pixels or larger), like desktop monitors or tablets, a `size=full` modal has the same behavior as a modal with `size=large` set.

### Utility Classes

The `LightningModal` component also supports the SLDS [Directional variant](https://v1.lightningdesignsystem.com/components/modals/#Directional) modal blueprint pattern.

The component uses a utility class to apply the directional variant.
To achieve the directional button layout, place the buttons in a `div` with the `slds-modal__footer_directional` class.

<!-- prettier-ignore-start -->
```html
<!-- c/modalDirectional.html -->

<template>
    <lightning-modal-body> Content: {content} </lightning-modal-body>
    <lightning-modal-footer>
        <div class=“slds-modal__footer_directional”>
            <lightning-button label="NO" onclick={handleNo}></lightning-button>
            <lightning-button label="OK" onclick={handleOkay}></lightning-button>
        </div>
    </lightning-modal-footer>
</template>
```
<!-- prettier-ignore-end -->

### Styling Hooks

The `lightning-modal-*` helper components support [styling hooks](https://v1.lightningdesignsystem.com/components/modals/#Styling-Hooks-Overview). The styling hooks for the template that invokes the helper components doesn't carry over to them, so you must style each helper component individually.

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

Upon opening, the modal determines where to place focus as follows.

- When the modal has multiple steps, with a different subtitle in the modal header for each step, the modal component places focus on the subtitle text.
- When the modal doesn't have multiple steps and the modal header is present, the modal component places the focus on the title text in the header.
- When a modal header isn’t present, the modal component places the focus on the first interactive element in the modal body, such as a link, button, or input field.
- When the modal body doesn’t have interactive elements, or the only interactive element is a tooltip, the modal component places focus on the close button.

The focus is based on
the [Global Focus Guidelines](https://v1.lightningdesignsystem.com/accessibility/guidelines/global-focus/#dialogs) for Lightning Design System.

The `lightning-modal-header` component renders the `label` value in an `<h1>` element. If your modal uses the header, begin any additional heading levels in the modal with `<h2>` for accessibility. Provide accessible structure by using heading levels up to `<h6>` appropriately. For more information, see [Semantic Structure, Headings on WebAim.org](https://webaim.org/techniques/semanticstructure/#headings).

To include tagline text or link content for the header section, add it between the `<lightning-modal-header>` tags.

## Unit Testing

Writing unit tests for `LightningModal` requires two sets of tests.

1. Parent components that use `c/myModal` define a mocked result when `.open()` is called during a test run. This mock speeds up testing and prevents repetition while testing actions that trigger modals.
2. The unit tests for `c/myModal` test the end-to-end functionality of the modal as a self-contained component.

This example is a mock of a component called myModal. The parent component `c/myApp` uses the modal to mock the `c/myModal` component's `.open()` method. The mock `.open()` resolves a constant value without opening the MyModal component. This example uses a button to open a modal and set the result in the template.

<!-- prettier-ignore-start -->
```html
<!-- c/myApp.html -->
<button data-button onclick={handleClick}>Select Item</button>
<div data-result>{result}</div>
```
<!-- prettier-ignore-end -->

```js
/* myApp.spec.js */

import MyModal from 'c/myModal';
jest.mock('c/myModal');

test(() => {
    // Create and appendChild(element)

    const buttonEle = element.shadowRoot.querySelector('[data-button]');
    const resultEle = element.shadowRoot.querySelector('[data-result]');

    // Mock .open() to resolve result 'option1'
    MyModal.open = jest.fn().mockResolvedValue('option1');
    // Initial value
    expect(resultEle.textContent).toBe(undefined);
    // Click modal open button
    buttonEle.click();

    // Click handler render cycle
    await Promise.resolve();
    // Render cycle triggered by tracked value {result}
    await Promise.resolve();

    // Verify result is set in the prompt template
    expect(resultEle.textContent).toBe('option1');
    // Open triggered once
    expect(MyModal.open.mock.calls).toHaveLength(1);
})
```

This example contains the unit tests for the actual `c/myModal` component. The tests use shorthand selectors to make unit testing more concise. For more information, see [Shorthand Selectors for `LightningModal`](#shorthand-selectors-for-lightningmodal).

```js
/* myModal.spec.js */

import { createElement } from "lwc";
import MyModal from "c/myModal";

describe("c-my-modal", () => {
  afterEach(() => {
    while (document.body.firstChild) {
      document.body.removeChild(document.body.firstChild);
    }
  });

  it("should select body elements", async () => {
    const element = createElement("c-mymodal", {
      is: MyModal,
    });
    document.body.appendChild(element);

    // If element apis are modified after appendChild
    // await Promise.resolve();

    // using shorthand selector for modalBody
    // see list of selectors below
    expect(element.modalBody$("button").textContent).toBe("hello world");
  });
});
```

## Shorthand Selectors for `LightningModal`

The stubs for `LightningModal` have shorthand selectors to make unit testing more concise. These are all the shorthand selectors for unit testing that you can use with `LightningModal`.

- `element.closeValue` - Value passed into `this.close(value)`
- `element.modalHeader$()` - querySelect a single node in `lightning-modal-header`
  - Usage: `element.modalHeader$('a')` Returns first link
- `element.modalHeader$$()` - querySelectAll multiple nodes in `lightning-modal-header`
  - Usage:
    - `elem.modalHeader$$()` Returns all nodes in header
    - `elem.modalHeader$$('a')` Returns all links in header
- `element.modalBody$()` - querySelect a single node in `lightning-modal-body`
  - Usage: `element.modalBody$('button')` Returns first button
- `element.modalBody$$()` - querySelectAll multiple nodes in `lightning-modal-body`
  - Usage:
    - `elem.modalBody$$()` Returns all nodes in body
    - `elem.modalBody$$('button, [data-button]')` Returns buttons in body
- `element.modalFooter$()` - querySelect a single node in `lightning-modal-footer`
  - Usage: `element.modalFooter$('button')` Returns first button
- `element.modalFooter$$()` - querySelectAll multiple nodes in `lightning-modal-footer`
  - Usage:
    - `elem.modalFooter$$()` Returns all nodes in footer
    - `elem.modalFooter$$('button, [data-button]')` Returns buttons in footer


:::::

:::::tab
::component-specification{component="modal" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9ee732561146e66a6f56f642f79731dd140e701d4c1e5e7df957901a211260bb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/modalBody/lightning-modal-body.md -->

# Modal Body

**`lightning-modal-body`**

The modal body component to display main content area in lightning modal.

**For Use In**

Lightning Experience, Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-modal-body` component renders the content of a modal.

The modal components render in the order they appear in the template. Place the `lightning-modal-body`
component after `lightning-modal-header` and before `lightning-modal-footer` components, if you're providing them.

This sample code shows the expected order of the modal components.

<!-- prettier-ignore-start -->
```html
<!-- my/modalDialog.html -->
<template>
    <lightning-modal-header label="My Modal Heading">
        Tagline content with <a href="https://salesforce.com">Salesforce.com link</a>
    </lightning-modal-header>
    <lightning-modal-body>
        <!-- modal content specified in LightningModal component -->
        { content }
        <!-- alternatively, add content here directly -->
    </lightning-modal-body>
    <lightning-modal-footer>
        Footer Content
    </lightning-modal-footer>
</template>
```
<!-- prettier-ignore-end -->

Your JavaScript class for the modal must extend from the [`lightning/modal` module](/docs/platform/lightning-component-reference/guide/lightning-modal.html).

You can nest content in `lightning-modal-body` or
`lightning-modal-body` automatically scrolls the modal's content when necessary.
The modal's maximum height is calculated to prevent the content from exceeding the screen height,
and scroll bars are automatically added.

## Design

`lightning-modal-body` implements the modals blueprint in the Salesforce Lightning Design System (SLDS). The modals adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                            | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Modals](https://v1.lightningdesignsystem.com/components/modals/) | [Modals](https://www.lightningdesignsystem.com/components/modals/)                                              |
| **For Use In** | Lightning Experience, Standalone Lightning app                    | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Accessibility

See [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/) for more information about accessibility in modals.

## See Also

[`lightning/modal`](/docs/platform/lightning-component-reference/guide/lightning-modal.html)

[_Lightning Web Components Developer Guide_: Modal Windows](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-modal.html)


:::::

:::::tab
::component-specification{component="modalBody" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=dabb46bc0fdead561236cb407594955c6289f0c694d3ec96916750a601ced33a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/modalFooter/lightning-modal-footer.md -->

# Modal Footer

**`lightning-modal-footer`**

The modal footer component to display footer content in lightning modal.

**For Use In**

Lightning Experience, Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-modal-footer` component creates a footer at the bottom of a modal dialog.
Use of a footer is optional.

The modal components render in the order they appear in the template.
Place the `lightning-modal-footer` component after the `lightning-modal-body` component.

This sample's `lightning-modal-footer` includes two `lightning-button` components,
but you can also use `<button>` elements.

<!-- prettier-ignore-start -->
```html
<!-- my/modalDialog.html -->
<template>
    <lightning-modal-header label="My Modal">
    </lightning-modal-header>
    <lightning-modal-body>
        <!-- modal content specified in LightningModal component -->
    </lightning-modal-body>
    <lightning-modal-footer>
        <lightning-button
            class="slds-button"
            variant="neutral"
            label="Cancel"
            onclick={handleDismiss}
        ></lightning-button>
        <lightning-button
            class="slds-button slds-m-left_x-small"
            variant="brand"
            label="Save"
        ></lightning-button>
    </lightning-modal-footer>
</template>
```
<!-- prettier-ignore-end -->

Your JavaScript class for the modal must extend from the [`lightning/modal` module](/docs/platform/lightning-component-reference/guide/lightning-modal.html).

## Design

Use `lightning-modal-footer` with `lightning-modal-body`, which implements the modals blueprint in the Salesforce Lightning Design System (SLDS). The modals adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                            | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Modals](https://v1.lightningdesignsystem.com/components/modals/) | [Modals](https://www.lightningdesignsystem.com/components/modals/)                                              |
| **For Use In** | Lightning Experience, Standalone Lightning app                    | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Accessibility

If you add buttons to the footer, you can use the accessibility attributes described in [`lightning-button`](/docs/platform/lightning-component-reference/guide/lightning-button.html).

When the modal opens, focus goes to the first interactive element in the modal. If there are no links in the header or any interactive elements
in the modal body, the first footer button gets initial focus.

## See Also

[`lightning/modal`](/docs/platform/lightning-component-reference/guide/lightning-modal.html)

[_Lightning Web Components Developer Guide_: Modal Windows](https://developer.salesforce.com/docs/platform/lwc/guide/use-dialog-modal.html)


:::::

:::::tab
::component-specification{component="modalFooter" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=745e33e804ed73ceb250ce75b85b063fc65de232ce262df0b4cf522d94265d77 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/modalHeader/lightning-modal-header.md -->

# Modal Header

**`lightning-modal-header`**

Creates a header to display the heading and tagline at the top of a modal.

**For Use In**

Lightning Experience, Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-modal-header` component displays header text in a panel at the top of a modal dialog.
Use of a header is optional, but when you provide a header you must specify the header text with the `label` attribute.

If you don't use the `lightning-modal-header` component, you must set a label
in the modal you create by extending `LightningModal`. A label is required for accessibility.

The modal components render in the order they appear in the template. Place the `lightning-modal-header`
component before the `lightning-modal-body` component in the template.

`lightning-modal-header` supports optional tagline text, which displays in smaller text below the heading. Enclose the
tagline text directly in the `lightning-modal-header` component, no HTML tag or attribute is needed. You can include links with `<a>`
tags, which are the only HTML elements permitted. If the header text is too long to fit on one line, it wraps in the modal header.

This sample code shows the expected order of the modal components. The modal content is
created in a separate component extended from `LightningModal`. See
[Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/)

<!-- prettier-ignore-start -->
```html
<!-- my/modalDialog.html -->
<template>
    <lightning-modal-header label="My Modal">
        Tagline can be descriptive content with <a href="https://www.example.com">links</a> and can wrap to multiple lines.
    </lightning-modal-header>
    <lightning-modal-body>
        <!-- modal content specified in LightningModal component -->
    </lightning-modal-body>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

`lightning-modal-header` implements the [modals](https://v1.lightningdesignsystem.com/components/modals/) blueprint in the Salesforce Lightning Design System (SLDS).

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

When you use `lightning-modal-header` in your modal, the rendered modal provides an `aria-labelledby` attribute set to the ID of the header element.
If you don't use `lightning-modal-header`, the accessible label is provided using `aria-label` set to the label you provide in the modal.

When the modal opens, focus goes to the first interactive element in the modal. If the header includes a link in tagline text, the link
gets initial focus.

See [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/) for more information about accessibility in modals.


:::::

:::::tab
::component-specification{component="modalHeader" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=787e465ecf788a11c57ea60610b9f7ef027912b382cd24327b09ba42b129c0ee url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateHome/force-navigate-home.md -->

# Navigate Home (Deprecated)

**`force:navigateHome`**

This event is deprecated. We recommend using the [`lightning:navigation` component](/docs/platform/lightning-component-reference/guide/aura-navigation.html) with the `standard__objectPage` page type instead.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

<!-- document id=667b4eda26ac05faaa9f49969c5887b220dcdaa7b76dd109c5e06aa03e00faac url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToComponent/force-navigate-to-component.md -->

# Navigate To Component (Deprecated)

**`force:navigateToComponent`**

Navigates from an Aura component to another.

This event is deprecated. We recommend using the [`lightning:navigation` component](/docs/platform/lightning-component-reference/guide/aura-navigation.html) with the `standard__component` page type instead.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event enables you to navigate from one Aura component to another.

**note:** Starting in API version 43.0, the `force:navigateToComponent` event is deprecated. For more information, see [Components with Minimum API Version Requirements](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_versioning_min_version.htm). We recommend implementing the `lightning:isUrlAddressable` interface on your target component and navigating to the component using [the `lightning:navigation` component](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm) with the `standard__component` page type instead. This generates a route in the format `/cmp/{componentName}?myAttr=attrValue`.

To navigate from a component to another, specify the component name using `componentDef`. This example navigates to a component `c:myComponent` and sets a value on the `contactId` attribute. The `componentAttributes` are base-64 encoded into the URL.

```javascript
navigateToMyComponent : function(component, event, helper) {
    var evt = $A.get("e.force:navigateToComponent");
    evt.setParams({
        componentDef : "c:myComponent",
        componentAttributes: {
            contactId : component.get("v.contact.Id")
        }
    });
    evt.fire();
}
```

**important:** 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.

When fired from a component embedded in Lightning Experience or Salesforce mobile app, the app creates and renders the target component in the app content area, replacing the current content. If you create a tab and associate it directly with the component, this event lets you navigate to the tab associated with the target component. For more information, see [Add Lightning Components as Custom Tabs in a Lightning App](https://help.salesforce.com/s/articleView?id=platform.aura_add_cmp_lex.htm).

This event doesn’t support target components that are embedded in another tab or in multiple tabs. You can navigate only to a component that’s marked `access="global"` or a component within the current namespace. Don’t depend on the URL generated by this event. It appears in the browser location bar and can be bookmarked, but the URL isn’t permanent.

This event is handled by the `one.app` container. It’s supported in Lightning Experience and the Salesforce mobile app.


:::::

:::::tab
## Attributes

| Name                  | Description                                                                                                                                                             | Type    | Default | Required |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `componentAttributes` | The attributes for the component.                                                                                                                                       | object  |         |          |
| `componentDef`        | The component to navigate to, for example, `c:myComponent`.                                                                                                             | string  |         |          |
| `isredirect`          | Specifies whether the navigation is a redirect. If true, the browser replaces the current URL with the new one in the navigation history. This value defaults to false. | boolean | false   |          |

:::::

::::::

<!-- document id=9beceff140e033a3e0d33ccd8623e8c2cff4feb7f75227b83e4fdd0f0948eb48 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToList/force-navigate-to-list.md -->

# Navigate To List (Beta)

**`force:navigateToList`**

Navigates to the list view specified by `listViewId`.

This event is deprecated. We recommend using the [`lightning:navigation` component](/docs/platform/lightning-component-reference/guide/aura-navigation.html) with the `standard__objectPage` page type instead.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `force:navigateToList` 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.

This event enables you to navigate to the list view specified by `listViewId`.

We recommend using `lightning:navigation` component with the `standard__objectPage` page type instead.
For more information, see the [Lightning Aura Components Developer Guide](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm).

To navigate to a list view, set the list view ID on the `listViewId` attribute and fire the event. This example displays the list views for contacts.

```javascript
gotoList : function (component, event, helper) {
    var action = component.get("c.getListViews");
    action.setCallback(this, function(response){
        var state = response.getState();
        if (state === "SUCCESS") {
            var listviews = response.getReturnValue();
            var navEvent = $A.get("e.force:navigateToList");
            navEvent.setParams({
                "listViewId": listviews.Id,
                "listViewName": null,
                "scope": "Contact"
            });
            navEvent.fire();
        }
    });
    $A.enqueueAction(action);
}
```

This Apex controller returns all list views for the contact object.

```apex
@AuraEnabled
public static List<ListView> getListViews() {
    List<ListView> listviews =
        [SELECT Id, Name FROM ListView WHERE SobjectType = 'Contact'];

    // Perform isAccessible() check here
    return listviews;
}
```

You can also provide a single list view ID by providing the list view name you want to navigate to in the SOQL query.

```sql
SELECT Id, Name FROM ListView WHERE SobjectType = 'Contact' and Name='All Contacts'
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name           | Description                                                                                                                                                        | Type   | Default | Required                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | -------------------------------------------- |
| `listViewId`   | The ID of the list view to be displayed.                                                                                                                           | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `listViewName` | Specifies the name for the list view and doesn't need to match the actual name. To use the actual name that's saved for the list view, set `listViewName` to null. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `scope`        | The name of the object in the view, for example, 'Account' or 'MyObject\_\_c'                                                                                      | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=d964f8ee299f82761b172e10abed16d90d53f743efd63273590fce63efbb2d91 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToObjectHome/force-navigate-to-object-home.md -->

# Navigate To Object Home

**`force:navigateToObjectHome`**

Navigates from a custom component to the specified object home.

This event is deprecated. We recommend using the [`lightning:navigation` component](/docs/platform/lightning-component-reference/guide/aura-navigation.html) with the `standard__objectPage` page type instead.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event enables you to navigate to the object home specified by the `scope` attribute.

We recommend using `lightning:navigation` component with the `standard__objectPage` page type instead.

For more information, see the [Lightning Aura Components Developer Guide](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm).

To navigate to an object home, set the object name on the `scope` attribute and fire the event. This example displays the home page for a custom object.

```javascript
navHome : function (component, event, helper) {
    var homeEvent = $A.get("e.force:navigateToObjectHome");
    homeEvent.setParams({
        "scope": "myNamespace__myObject__c"
    });
    homeEvent.fire();
}
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name           | Description                                                  | Type    | Default | Required                                     |
| -------------- | ------------------------------------------------------------ | ------- | ------- | -------------------------------------------- |
| `resetHistory` | Set to true to reset history.                                | boolean | false   |                                              |
| `scope`        | The name or key prefix of entity to display object home for. | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=6966e20ca34a9823eb2ceac936e60f26bc7956c485846e12d00cdd6b06fcb1ee url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToRelatedList/force-navigate-to-related-list.md -->

# Navigate To Related List (Beta)

**`force:navigateToRelatedList`**

Navigates to the related list specified by `parentRecordId`.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `force:navigateToRelatedList` 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.

This event enables you to navigate to the related list specified by `parentRecordId`.

We recommend using the `lightning:navigation` component with the `standard__recordRelationshipPage` page type instead.

For more information, see the [Lightning Aura Components Developer Guide](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm).

To navigate to a related list, set the parent record ID on the `parentRecordId` attribute and fire the event.

This example displays the related cases on a record and assumes that your component implements the `force:hasRecordId` and `flexipage:availableForRecordHome` interfaces. It uses the `recordId` attribute provided by the `force:hasRecordId` interface. Implementing these interfaces means that you can drag-and-drop the component to the record pages you want via the Lightning App Builder, such that it can navigate to related cases on an account record or contact record page, or any other record pages that support the case related list.

```javascript
gotoRelatedList : function (component, event, helper) {
    var relatedListEvent = $A.get("e.force:navigateToRelatedList");
    relatedListEvent.setParams({
        "relatedListId": "Cases",
        "parentRecordId": component.get("v.recordId")
    });
    relatedListEvent.fire();
}
```

Each object supports a subset of related lists. The page layout editor shows the related lists supported for each object. For example, account records support these related lists: `Assets`, `Cases`, `Contacts`, `Opportunities`, among many others.

However, not all related lists are automatically available in your org. For example, the Contacts to Multiple Accounts feature must be enabled for the “Related Contacts” (`AccountContactRelations`) related list to be available. To identify the `relatedListId` value of a related list, navigate to the related list and observe the URL token `/rlName/<relatedListId>/view` that’s appended to the Salesforce URL. However, don’t hard code the URL token in your component markup or JavaScript code as it might change in future releases.

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name             | Description                                                                                                                                                                                                                                                   | Type   | Default | Required                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `entityApiName`  | The API name of the related list.                                                                                                                                                                                                                             | string |         |                                              |
| `parentRecordId` | The ID of the parent record.                                                                                                                                                                                                                                  | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `relatedListId`  | The API name of the related list to display. For standard objects it is typically the related list's entity api name in plural form, such as 'Contacts' or '​Opportunitie​s'. For custom objects it takes the form of '{​YourCustom​Relationship​Label}\_\_r' | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=c4fd0b5aacd98e9b1d7fa81911ed8fe4ccb48aee3d166d39f72f5c8ce25432b0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToSObject/force-navigate-to-sobject.md -->

# Navigate To SObject

**`force:navigateToSObject`**

Navigates to a record specified by `recordId`.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `force:navigateToSObject` 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.

This event enables you to navigate to an sObject record specified by `recordId`.

We recommend using `lightning:navigation` component with the `standard__recordPage` page type instead. For more information, see the [Lightning Aura Components Developer Guide](http://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation.htm).

To display the record view, set the record ID on the `recordId` attribute and fire the event. Record IDs corresponding to ContentNote SObjects aren’t supported.

The record view contains slides that display the Chatter feed, the record details, and related information. This example displays the related information slide of a record view for the specified record ID.

You can set a specific slide in the Salesforce mobile app, but not in Lightning Experience.

```javascript
createRecord : function (component, event, helper) {
    var navEvt = $A.get("e.force:navigateToSObject");
    navEvt.setParams({
      "recordId": "00QB0000000ybNX",
      "slideDevName": "related"
    });
    navEvt.fire();
}
```

In the Salesforce mobile app, you can specify the slide within the record view to display initially. The following slide names are supported.

- `detail`: The record detail slide. This is the default value.
- `chatter`: The Chatter slide.
- `related`: The related information slide.

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name           | Description                                                                                                                                                                          | Type    | Default | Required                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | -------------------------------------------- |
| `isredirect`   | When redirecting in place, this attribute prevents the creation of multiple history entries in hybrid environments. In this case, hybrid treats redirects as a single history entry. | boolean | false   |                                              |
| `networkId`    | Inherited. Network that the event is associated with.                                                                                                                                | string  |         |                                              |
| `recordId`     | The record ID.                                                                                                                                                                       | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `slideDevName` | The developer name of the of the slide to navigate to. By default, options are 'chatter', 'related', 'detail'.                                                                       | string  |         |                                              |

:::::

::::::

<!-- document id=5ce070e0b5ccc2195df2100bf64bffa3a0d9ee40bae43647e3897f09215b907f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/navigateToURL/force-navigate-to-url.md -->

# Navigate To URL

**`force:navigateToURL`**

Navigates from a custom component to the specified URL.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Instead of using `force:navigateToURL`, we recommend navigating to web pages using the `lightning:navigate` component with the `standard__webPage` page type. For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_navigation_page_definitions.htm).

Relative and absolute URLs are supported. Relative URLs are relative to the Salesforce mobile web domain, and retain navigation history. External URLs open in a separate browser window.

Use relative URLs to navigate to different screens within your app. Use external URLs to allow the user to access a different site or app, where they can take actions that don’t need to be preserved in your app. To return to your app, the separate window that’s opened by an external URL must be closed when the user is finished with the other app. The new window has a separate history from your app, and this history is discarded when the window is closed. This also means that the user can’t click a Back button to go back to your app; the user must close the new window.

`mailto:`, `tel:`, `geo:`, and other URL schemes are supported for launching external apps and attempt to "do the right thing". However, support varies by mobile platform and device. `mailto:` and `tel:` are reliable, but we recommend that you test any other URLs on a range of expected devices.

When using `mailto:` and `tel:` URL schemes, consider using `lightning:formattedEmail` and `lightning:formattedUrl` components.

This example navigates a user to the opportunity page, `/006/o`, using a relative URL.

```javascript
gotoURL : function (component, event, helper) {
    var urlEvent = $A.get("e.force:navigateToURL");
    urlEvent.setParams({
      "url": "/006/o"
    });
    urlEvent.fire();
}
```

This example opens an external website when the link is clicked.

```javascript
navigate : function(component, event, helper) {

    //Find the text value of the component with aura:id set to "address"
    var address = component.find("address").get("v.value");

    var urlEvent = $A.get("e.force:navigateToURL");
    urlEvent.setParams({
      "url": 'https://www.google.com/maps/place/' + address
    });
    urlEvent.fire();
}
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites. However, Experience Builder sites don't support force.com URL navigation with the `force:navigateToURL` event.


:::::

:::::tab
## Attributes

| Name         | Description                                                                                                                                                                          | Type    | Default | Required                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | -------------------------------------------- |
| `isredirect` | When redirecting in place, this attribute prevents the creation of multiple history entries in hybrid environments. In this case, hybrid treats redirects as a single history entry. | boolean | false   |                                              |
| `networkId`  | Inherited. Network that the event is associated with.                                                                                                                                | string  |         |                                              |
| `url`        | The URL of the target.                                                                                                                                                               | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=a3146b5a7facc8b4c28b3f9edf98f1cbfa4b1d26926302417a43a57acd0ffb5d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/navigation/lightning-navigation.md -->

# Navigation

**`lightning/navigation`**

Generate a URL or navigate to a page reference using the `lightning/navigation` wire adapters and functions.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Mobile Offline

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

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).

`CurrentPageReference` gets a reference to the current page in Salesforce. Page URL formats can change in future releases. To future proof your apps, use page references instead of URLs. Use the page reference to create a deep link to the page. `NavigationMixin` gets a reference to the navigation service. Use the navigation service to navigate to another page in the application and generate a URL for a page.

## CurrentPageReference

Get a reference to the current page in Salesforce. Page URL formats can change in future releases. To future proof your apps, use page references instead of URLs. Use the page reference to create a deep link to the page.

```javascript
import { CurrentPageReference } from 'lightning/navigation';
@wire(CurrentPageReference)
pageRef;
```

The key-value pairs of the PageReference `state` property are serialized to URL query parameters. To create a deep link that describes the page and that a user can bookmark, update the `state` property. See [Add Query Parameters](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-add-params-url).

## NavigationMixin

Apply the `NavigationMixin` to the component's base class to gain access to its APIs.

```javascript
import { NavigationMixin } from "lightning/navigation";
export default class MyCustomElement extends NavigationMixin(LightningElement) {}
```

The `NavigationMixin` adds two APIs to your component's class. Invoking these functions before the element is connected to the DOM can have unexpected results.

- `[NavigationMixin.Navigate](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/pageReference, [replace])` - A component calls this API to navigate to another page in the application.
- `[NavigationMixin.GenerateUrl](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/pageReference)` - A component calls this API to get a `promise` that resolves to the resulting URL. The component can use the URL in the `href` attribute of an anchor.

This example shows how to invoke these API methods from `this`:

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

export default class Example extends NavigationMixin(LightningElement) {
  navigateToObjectHome() {
    // Navigate to the Account home page
    this[NavigationMixin.Navigate]({
      type: "standard__objectPage",
      attributes: {
        objectApiName: "Account",
        actionName: "home",
      },
    });
  }

  recordPageUrl;

  connectedCallback() {
    // Generate a URL to a User record page
    this[NavigationMixin.GenerateUrl]({
      type: "standard__recordPage",
      attributes: {
        recordId: "005B0000001ptf1IAE",
        actionName: "view",
      },
    }).then((url) => {
      this.recordPageUrl = url;
    });
  }
}
```

## Usage Considerations

We recommend that you use `lightning/navigation` instead of `window.location` to navigate to a page from a Lightning web component. Using `window.location` can cause unexpected behavior in different browsers, different containers such as Lightning Experience and Experience Builder sites, or when you use an iframe. Manipulating the URL directly using `window.location` can also expose you to potential security vulnerabilities.

```javascript
// Don't do this
window.location.href = "https://www.salesforce.com";
```

To navigate to a non-Salesforce web page, use the `standard__webPage` type.

```javascript
// Do this instead
handleNavToWebPage() {
        const pageref = {
            type: 'standard__webPage',
            attributes: {
                url: 'https://www.example.com/'
            }
        };

        this[NavigationMixin.Navigate](pageref);
    }
```

To navigate to a Salesforce record page, use the `standard__recordPage` type. For more information, see [PageReference Types](https://developer.salesforce.com/docs/platform/lwc/guide/reference-page-reference-type).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/navigation`, see the `c-nav-to-*` components in the LWC Recipes repo.

## See Also

[Navigate to Pages](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate)


:::::

:::::tab
::component-specification{component="navigation" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=5ed20cf371df4fb067679bdee9e6cdd39f8e5689a8918ecac102d81918f5b609 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/noAccess/aura-no-access.md -->

# No Access

**`aura:noAccess`**

Indicates that a requested resource is not accessible due to security constraints on that resource.

::::::tabset{tabs='["Specifications"]'}

:::::tab
## Attributes

| Name          | Description                                                                                      | Type   | Default | Required |
| ------------- | ------------------------------------------------------------------------------------------------ | ------ | ------- | -------- |
| `redirectURL` | A URL that the server says the application should redirect the browser to when this event fires. | string |         |          |

:::::

::::::

<!-- document id=01447e271803cec41a9ecf2f349df0e35d81f55c63c7a20dea17d27130331262 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelConnectionError/aura-omni-channel-connection-error.md -->

# Omni Channel Connection Error

**`lightning:omniChannelConnectionError`**

Indicates a network connection issue. Logs the user out of the app, if applicable.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelConnectionError` is an application event that indicates a network connection issue. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name    | Description                       | Type   | Default | Required |
| ------- | --------------------------------- | ------ | ------- | -------- |
| `error` | Network connection error message. | object |         |          |

:::::

::::::

<!-- document id=28b455cac4101034ae096de91ce410c448b2dd164042725889e7093733fa3d72 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelLoginSuccess/aura-omni-channel-login-success.md -->

# Omni Channel Login Success

**`lightning:omniChannelLoginSuccess`**

Indicates that an Omni-Channel user has logged in successfully.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelLoginSuccess` is an application event that indicates an Omni-Channel user has logged in successfully. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name       | Description                                    | Type   | Default | Required                                     |
| ---------- | ---------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `statusId` | The ID of the agent’s current presence status. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=44769007e0c1d6caca8cd0d96dfe9154006f5728112e7c96f478db4ab1c7810a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelLogout/aura-omni-channel-logout.md -->

# Omni Channel Logout

**`lightning:omniChannelLogout`**

Indicates that an agent has logged out of Omni-Channel.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelLogout` is an application event that indicates an agent has logged out successfully. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name     | Description                                                                                                                                                   | Type   | Default | Required |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `reason` | The reason why the agent is logged out. Possible values are `DuplicateLogin`, `DuplicateLoginInSameBrowser`, `MaintenanceLogout`, and `OmniSupervisorLogout`. | string |         |          |

:::::

::::::

<!-- document id=3bb7a50c3dd8f6997d7155d3ddd75ee8867099e74f4e1f1eee975f984227fc0f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelStatusChanged/aura-omni-channel-status-changed.md -->

# Omni Channel Status Changed

**`lightning:omniChannelStatusChanged`**

Indicates that an Omni-Channel user has changed their status.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelStatusChanged` is an application event that indicates an Omni-Channel user has changed their status. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name            | Description                                          | Type   | Default | Required                                     |
| --------------- | ---------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `channels`      | The JSON string of channel objects.                  | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `statusApiName` | The API name of the agent’s current presence status. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `statusId`      | The ID of the agent’s current presence status.       | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `statusName`    | The name the agent’s current presence status.        | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=81f5e481c197cce25b07d7eec0b307e4fa93c4bf8fd46707ddb551c89de78b65 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkAccepted/aura-omni-channel-work-accepted.md -->

# Omni Channel Work Accepted

**`lightning:omniChannelWorkAccepted`**

Indicates that a user has accepted a work assignment, or when a work assignment is automatically accepted.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkAccepted` is an application event that indicates a user has accepted a work assignment, or when a work assignment is automatically accepted. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name         | Description                                              | Type   | Default | Required                                     |
| ------------ | -------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `workId`     | The ID of a work assignment that’s routed to an agent.   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `workItemId` | The ID of the object that’s routed through Omni-Channel. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=713ea049067ffb7859318a718b3bfa4c4dfe95fe164472f492419b4da97cec0e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkAssigned/aura-omni-channel-work-assigned.md -->

# Omni Channel Work Assigned

**`lightning:omniChannelWorkAssigned`**

Indicates that a user is assigned a new work item.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkAssigned` is an application event that indicates a user is assigned a new work item. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name         | Description                                              | Type   | Default | Required                                     |
| ------------ | -------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `workId`     | The ID of a work assignment that’s routed to an agent.   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `workItemId` | The ID of the object that’s routed through Omni-Channel. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=25a883b4534e68c9e3d0dd548d8ac128debeb1abf96f1c60105e713e822595e2 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkClosed/aura-omni-channel-work-closed.md -->

# Omni Channel Work Closed

**`lightning:omniChannelWorkClosed`**

Indicates that a user has closed a tab in the console that’s associated with a work item.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkClosed` is an application event that indicates a user has closed a tab in the console that’s associated with a work item. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name         | Description                                              | Type   | Default | Required                                     |
| ------------ | -------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `workId`     | The ID of a work assignment that’s routed to an agent.   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `workItemId` | The ID of the object that’s routed through Omni-Channel. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=84fab890d55ec2cc5c38c3faea9e1c04393323a15cb9beff3a111fad0d960c21 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkDeclined/aura-omni-channel-work-declined.md -->

# Omni Channel Work Declined

**`lightning:omniChannelWorkDeclined`**

Indicates that a user has declined a work assignment.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkDeclined` is an application event that indicates a user has declined a work assignment. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name         | Description                                              | Type   | Default | Required                                     |
| ------------ | -------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `workId`     | The ID of a work assignment that’s routed to an agent.   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `workItemId` | The ID of the object that’s routed through Omni-Channel. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=2c7be5c61aee5eee316d5592e3c7f5d1c8cf881090a9764d98151476d5c2a031 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkFlagUpdated/aura-omni-channel-work-flag-updated.md -->

# Omni Channel Work Flag Updated

**`lightning:omniChannelWorkFlagUpdated`**

Indicates that a work item's flag has changed.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkFlagUpdated` is an application event that indicates a work item's flag has changed. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name            | Description                                                                            | Type    | Default | Required                                     |
| --------------- | -------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
| `isFlagged`     | Specifies whether the flag is raised.                                                  | boolean |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `message`       | A message associated with changing the flag.                                           | string  |         |                                              |
| `roleUpdatedBy` | The role of the user who triggered this flag change. The value is AGENT or SUPERVISOR. | string  |         |                                              |
| `updatedBy`     | The ID of the user who triggered this flag change.                                     | string  |         |                                              |
| `workId`        | The ID of a work item with the updated flag.                                           | string  |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=39221499e34d73812d70617984739a52fdf0dbb4f4de06bf42998012a5e5a139 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/omniChannelWorkloadChanged/aura-omni-channel-workload-changed.md -->

# Omni Channel Workload Changed

**`lightning:omniChannelWorkloadChanged`**

Indicates that an agent’s workload has changed.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:omniChannelWorkloadChanged` is an application event that indicates an agent’s workload has changed. This event is supported in Lightning console apps only.

For more information, see [Events for Omni-Channel](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_lightning_omnichannel_events.htm) in the Salesforce Console Developer Guide.


:::::

:::::tab
## Attributes

| Name                              | Description                                              | Type   | Default | Required                                     |
| --------------------------------- | -------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `configuredCapacity`              | The configured primary capacity for the agent.           | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `configuredInterruptibleCapacity` | The configured interruptible capacity for the agent.     | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `newInterruptibleWorkload`        | The agent’s new interruptible workload after the change. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `newWorkload`                     | The agent’s new primary workload after the change.       | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `previousInterruptibleWorkload`   | The agent’s interruptible workload before the change.    | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `previousWorkload`                | The agent’s primary workload before the change.          | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=58825c22312cca739151c419a83261d6ad8ab840b0e02a7fe539b1895de0686f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/omnistudioFlexcard/lightning-omnistudio-flexcard.md -->

# Omnistudio Flexcard

**`lightning-omnistudio-flexcard`**

A wrapper for Omnistudio Flexcards that enables you to display Flexcards in custom Lightning web components.

**For Use In**

Lightning Experience, Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Display data and launch actions with [Omnistudio Flexcards](https://help.salesforce.com/s/articleView?id=xcloud.os_omnistudio_flexcards_24388.htm&language=en_US). To create a Flexcard, use [Flexcard Designer](https://help.salesforce.com/s/articleView?id=xcloud.flexcard_workflow.htm). Omnistudio is available to select Industry Cloud customers. After you create and activate a Flexcard, you can use the `lightning-omnistudio-flexcard` component to display your Flexcard in your custom LWC component.

The `lightning-omnistudio-flexcard` component is a wrapper for the Flexcard component that's available for use in Lightning App Builder and Experience Builder Aura sites.

To use a Flexcard in your custom component, pass in the Flexcard's unique name.

```html
<lightning-omnistudio-flexcard
  flexcard-name="somecard"
></lightning-omnistudio-flexcard>
```

This example shows how to display account information based on a specific record ID.

<!-- prettier-ignore -->
```html
<lightning-omnistudio-flexcard
  flexcard-name="AccountSummaryCard"
  record-id={accountRecordId}
  object-api-name="Account"
>
</lightning-omnistudio-flexcard>
```

## LWR Compatibility

To use a Flexcard on a Lightning Web Runtime (LWR) site for Experience Cloud, include the `lwr` attribute like this:

```html
<!-- LWR-compatible flexcard -->
<lightning-omnistudio-flexcard
  flexcard-name="somecard"
  lwr
></lightning-omnistudio-flexcard>
```

This example shows how to use an LWR-compatible flexcard with record data:

<!-- prettier-ignore -->
```html
<lightning-omnistudio-flexcard
  flexcard-name="ContactCard"
  lwr
  record-id={contactRecordId}
  object-api-name="Contact"
>
</lightning-omnistudio-flexcard>
```

This example shows how to add data to the records parameter.

```javascript
//Js
export const SAMPLE_DATA = [
  {
    _id: "6862285777cfe51e4826909e",
    isActive: true,
    balance: "$3,249.31",
    age: 36,
    name: "Williamson Hyde",
    email: "williamsonhyde@dancity.com",
  },
  {
    _id: "68622857aa535d207b9e5a41",
    isActive: false,
    balance: "$1,291.33",
    age: 27,
    name: "Lakeisha Holland",
    email: "lakeishaholland@typhonica.com",
  },
  {
    _id: "68622857eb29c6a3762725b8",
    isActive: true,
    balance: "$1,558.63",
    age: 22,
    name: "Patel Green",
    email: "patelgreen@endipine.com",
  },
];

import { SAMPLE_DATA } from "./data.js";

export default class TestComponent extends LightningElement {
  constructor() {
    this.sampleData = SAMPLE_DATA;
  }
}
```

Pass the data to the `records` attribute in your component.

<!-- prettier-ignore -->
```html
<template>
  <lightning-omnistudio-flexcard
    flexcard-name="testComponent"
    parent-data
    records={sampleData}
  ></lightning-omnistudio-flexcard>
</template>
```

## Usage Considerations

When you add a Flexcard name that doesn't match any of your active Flexcards, an error is shown only when you preview the custom LWC project at runtime. In this case, you don’t see an error during deployment. Before you deploy your component to an org, verify the name of the Flexcard and that the Flexcard is active.

To make your component available in Lightning App Builder, see [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-app-builder.html). To make your component available in Experience Builder, see [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-community-builder.html).


:::::

:::::tab
::component-specification{component="omnistudioFlexcard" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f893e3de3293020a750b0cbe112ed866a149fa6acb4ada1c8996e2fb83964bd9 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/omnistudioOmniscript/lightning-omnistudio-omniscript.md -->

# Omnistudio Omniscript

**`lightning-omnistudio-omniscript`**

A wrapper for Omniscripts that allows you to use Omniscripts in custom Lightning web components.

**For Use In**

Lightning Experience, Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Create dynamic customer interactions with low code and deploy them to multiple channels and devices with Omniscripts. To create Omniscripts, use [Omniscript Designer](https://help.salesforce.com/s/articleView?id=xcloud.omniscript_workflow.htm). Omnistudio is available to select Industry Cloud customers. After you create an Omniscript, you can use the `lightning-omnistudio-omniscript` component to display your Omniscript in your custom LWC component.

The `lightning-omnistudio-omniscript` component is a wrapper for the Omniscript component that's available for use in Lightning App Builder and Experience Builder.

To use an Omniscript in your custom component, pass in the Omniscript’s `type`, `sub-type`, and `language` attributes.

```html
<lightning-omnistudio-omniscript
  type="RFC"
  sub-type="Omniscript"
  language="English"
></lightning-omnistudio-omniscript>
```

## LWR Compatibility

To use an Omniscript on a Lightning Web Runtime (LWR) site for Experience Cloud, include the `lwr` attribute like this:

```html
<!-- LWR-compatible omniscript -->
<lightning-omnistudio-omniscript
  type="RFC"
  sub-type="Omniscript"
  language="English"
  lwr></lightning-omnistudio-omniscript>
```

To make your component available in Lightning App Builder, see [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-app-builder.html) in the _Lightning Web Components Developer Guide_. To make your component available in Experience Builder, see [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-community-builder.html) in the _Lightning Web Components Developer Guide_.


:::::

:::::tab
::component-specification{component="omnistudioOmniscript" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0a3b3d4c630e416dcd7b177325ef3d4ff5d4ac1865ecab1d5c5fe4f5e283658c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/omnistudioPubsub/lightning-omnistudio-pubsub.md -->

# Omnistudio Pubsub

**`lightning-omnistudio-pubsub`**

Provides a lightweight publish-subscribe mechanism for sibling Lightning web components to communicate without direct references.

**For Use In**

Lightning Experience, Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Share data and pass messages between components that don’t have a parent-child relationship using the `lightning/omnistudioPubsub` module. Using this module, you can register, unregister, and fire events dynamically.

In Omnistudio, you can [trigger a pubsub event from an action on a Flexcard](https://help.salesforce.com/s/articleView?id=xcloud.os_trigger_a_pubsub_event_from_an_action_on_a_flexcard_28089.htm), or [communicate from an Omniscript to a Lightning web component](https://help.salesforce.com/s/articleView?id=xcloud.os_communicate_with_omniscript_from_a_lightning_web_component_18222.htm). Omnistudio is available to select Industry Cloud customers.

To use Omnistudio PubSub directly in your custom Lightning web component, use the `lightning/omnistudioPubsub` module.
The `lightning/omnistudioPubsub` module is a wrapper for the Omnistudio PubSub property.

To use the pubsub functionality, import `pubsub` from the `lightning/omnistudioPubsub` module in the component.

```javascript
import pubsub from "lightning/omnistudioPubsub";

// Register a callback
pubsub.register("eventName", callbackObject);

// Fire an event
pubsub.fire("eventName", action, payload);

// Unregister a callback
pubsub.unregister("eventName", callbackObject);
```

This utility component doesn’t have a template and can’t be directly accessed via Lightning App Builder. A custom component that uses the utility component can be accessed via Lightning App Builder. To make your component available in Lightning App Builder, see [Configure a Component for Lightning App Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-app-builder.html). To make your component available in Experience Builder, see [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-community-builder.html).

This example uses the `lightning/omnistudioPubsub` module to register, unregister, and fire a test event dynamically.

```javascript
import omnistudioPubsub from "lightning/omnistudioPubsub";

export default class TestComponent extends LightningElement {
  connectedCallback() {
    this.handleMessage = {
      testevent: this.handleTestEvent.bind(this),
      testeventnew: this.handleTestEventNew.bind(this),
    };
    omnistudioPubsub.register("testchannel", this.handleMessage);
  }

  handleTestEvent(event) {
    //Some logic here
  }

  handleTestEventNew(event) {
    //Some logic here
  }

  disconnectedCallback() {
    omnistudioPubsub.unsubscribe("testchannel", this.handleMessage);
  }
}
```

## Public Methods

**`register(eventName, callbackobj)`**

Register a set of event handlers to a specific channel.

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| eventName   | string | The name of the event to register for |
| callbackobj | object | The callback object to register       |

**`unregister(eventName, callbackobj)`**

Unregister your set of event handlers from a channel. To avoid memory leaks or potential errors, always unregister event handlers when a component is disposed or disconnected. In addition, to properly unregister event handlers, pass both the channel name and instance of your event handler objects.

| Parameter   | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| eventName   | string | The name of the event to unregister from |
| callbackobj | object | The callback object to unregister        |

**`fire(eventName, action, payload)`**

Fire an event over a specific channel to all registered handlers. The payload can be any object. However, make sure your handlers expect that particular structure. For example, if you intend to send a JSON object with various keys, your handlers should know what those keys are.

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| eventName | string | The name of the event to fire  |
| action    | string | The action to perform          |
| payload   | object | The payload data for the event |


:::::

:::::tab
::component-specification{component="omnistudioOmniscript" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c383fe1864007b15c7d92ee3045bc29b3220fa0e6452988cf2062cab81e33e95 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/openFiles/aura-open-files.md -->


# Open Files

**`lightning:openFiles`**

The `lightning:openFiles` event is no longer recommended. Use the [Lightning navigation service](/docs/platform/lightning-component-reference/guide/aura-navigation.html) instead. Application event used to open one or more file records. This event triggers a modal file previewer or download depending on the form factor.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:openFiles` is an application event used to open one or more file records.

Firing the event opens the preview of a single or multiple files in a modal dialog when on desktop, or trigger a file download on mobile devices.

```html
<aura:component>
  <aura:handler event="lightning:openFiles" action="{! c.handleOpenFiles }" />
  <lightning:button label="Open a single file" onclick="{! c.openSingleFile }" />
  <lightning:button label="Open multiple files" onclick="{! c.openMultipleFiles }" />
</aura:component>
```

```javascript
({
  openSingleFile: function (cmp, event, helper) {
    $A.get("e.lightning:openFiles").fire({
      recordIds: ["fileid0"],
    });
  },
  openMultipleFiles: function (cmp, event, helper) {
    $A.get("e.lightning:openFiles").fire({
      recordIds: ["fileid0", "fileid1", "fileid2"],
      selectedRecordId: "fileid1",
    });
  },
  handleOpenFiles: function (cmp, event, helper) {
    alert(
      "Opening files: " +
        event.getParam("recordIds").join(", ") +
        ", selected file is " +
        event.getParam("selectedRecordId"),
    );
  },
});
```

The desktop file previewer offers image and SVG-based multi page office documents preview, presentation mode and quick access to file actions (share, download, upload, delete).

On mobile and tablet a single file is downloaded when the event is fired i.e. the one specified in `selectedRecordId` or the first element from the `recordIds` list. Depending on the device this triggers a native preview of the file.

Supported entities are ContentDocument and ContentHubItem (external files).

The `lightning:openFiles` event is supported in Lightning Experience, the Salesforce mobile app, and Experience Builder sites based on the Customer Service template.


:::::

:::::tab
## Attributes

| Name               | Description                                                                                                                                                                                                 | Type   | Default | Required                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `recordIds`        | IDs of the records to open.                                                                                                                                                                                 | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `selectedRecordId` | ID of the record to open first among the one specified in the recordIds attribute. If this value is not provided or if the value provided is not in the list, the first element from the list will be used. | string |         |                                              |

:::::

::::::

<!-- document id=665154cbd531232e69a96f854f08a41e789ee554e0c74710f43fa731eb756fe1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/outputField/lightning-output-field.md -->

# Output Field

**`lightning-output-field`**

Represents a read-only display of a label, help text, and value for a field on a Salesforce object.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning-output-field` component in `lightning-record-view-form` to display
the value of a record field on a Salesforce object. Use the `field-name` attribute
to specify the API field name.

For standard and custom objects, find the field names in Lightning Experience from Setup > Object Manager > (object-name) > Fields & Relationships.
Standard object fields are also documented in
[Standard Objects](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_list.htm).
See [Supported Objects in the `lightning-record-view-form` documentation](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html#supported-objects) for usage considerations about objects.

A `lightning-output-field` component displays the field value in the correct
format based on the field type. You must provide the record ID in the wrapper
`lightning-record-view-form` component, and specify the field name on
`lightning-output-field`. If `field-name` references an email address, phone number, lookup, or URL, then a clickable link is displayed.

In orgs that support multiple languages, `lightning-output-field` automatically
shows the translated labels and picklist values.

To create a record detail layout, wrap the fields with
`lightning-record-view-form` and provide the record ID. You don't need
additional Apex controllers as data refresh happens
automatically with Lightning Data Service.

If you reference an invalid field, no output label or value is rendered.

For more information, see the [`lightning-record-view-form`](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html) documentation.

Here's an example of a record view that shows a contact record
with several contact fields.

<!-- prettier-ignore-start -->
```html
<template>
    <!-- Replace the record ID with your own -->
    <lightning-record-view-form
        record-id="003XXXXXXXXXXXXXXX"
        object-api-name="Contact"
    >
        <div class="slds-box slds-theme_default">
            <lightning-output-field field-name="Name"> </lightning-output-field>
            <lightning-output-field field-name="Phone">
            </lightning-output-field>
            <lightning-output-field field-name="Email">
            </lightning-output-field>
            <lightning-output-field field-name="Birthdate">
            </lightning-output-field>
            <lightning-output-field field-name="LeadSource">
            </lightning-output-field>
        </div>
    </lightning-record-view-form>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-output-field` implements the form element blueprint in the Salesforce Lightning Design System (SLDS).

|                | SLDS 1                                                                                                           | SLDS 2                                                                                                                         |
| :------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element (view mode/static)](https://v1.lightningdesignsystem.com/components/form-element/#View-ModeStatic) | [Form Element (view mode/static)](https://www.lightningdesignsystem.com/2e1ef8501/p/96252b-form-element/b/76ea32/t/ea06bd3eb3) |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app                                            | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5)                |

## User Locale Settings

The [user's locale settings](https://help.salesforce.com/s/articleView?id=xcloud.usersetup_lang_time_zone.htm) determine the display formats for numbers, percentages, and date and time.

For currency fields, [the currency locale](https://help.salesforce.com/s/articleView?id=xcloud.admin_currency_set_locale.htm) for the org determines the display format.

Besides field values, `lightning-output-field` displays the localized labels and help text for the fields based on their metadata, which are defined by your Salesforce admin.

Date and time field values are retrieved from the platform along with the user's Salesforce locale and timezone settings and passed to `lightning-output-field`. The component doesn't alter the retrieved date and time values, which are stored in UTC.
It displays the date and time formatted according to the user's locale setting, and calculated for the user's timezone setting. For example, let's say a user sets their Salesforce timezone as GMT+08:00 with a Japanese locale.
The user modifies a record, and then the Last Modified By field displays `2025/07/04 4:12 AM`. For another user whose Salesforce timezone is GMT-07:00 with an English (United States) locale, the same field displays as `7/3/2025 1:12 PM`.
The same server-recorded date and time can appear differently to users with different locale and timezone settings.

In Lightning Experience, the locale corresponds to the Locale field on the Language &amp; Time Zone page in the user's profile settings. For example, if `field-name` references a date and time value, then the default output value contains the date and time in the user's locale.

In LWR sites, the site configuration determines the field's language and locale. In enhanced LWR sites, the site visitor's browser timezone determines the field's timezone. In non-enhanced LWR sites, the hosting Salesforce org's timezone determines the field's timezone.

## Set the Form Display Density

`lightning-output-field` inherits the display density from the enclosing parent form. To override the display density of the parent form, use the `variant` attribute.
When the parent form uses the `compact` density, you can reduce the whitespace between the label and field using the `slds-form-element_1-col` class on `lightning-output-field`.

For more information, see the [lightning-record-view-form](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html) documentation.

## Field Types Supported

`lightning-output-field` supports fields on objects that are UI API compliant. For supported 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).

Fields that have a spanning relationship aren't supported by `lightning-output-field`. The fields specified must be associated with only one object. A field such as Contact.Account.Ownership is a cross-object reference between the Contact object and the Account object, and can't be displayed in the form.

The supported field data types are:

- Address: Displays the formatted address without a link to Google Maps.
- Auto Number: Displays a string that represents the unique number of the record.
- Checkbox: Displays a checkmark if selected or an empty dotted checkbox if not selected.
- ComboBox: Displays text of the selected value.
- Currency: Displays the formatted currency based on the user's locale.
- Date: Displays the formatted date based on the user's locale.
- Date/Time: Displays the formatted date and time based on the user's locale.
- Email: Displays the email address with the `mailto:` URL scheme.
- Encrypted String: Displays masking characters to represent an encrypted string such as a password.
- Formula: Displays the result of the formula based on its data type.
- Geolocation: Displays latitude and longitude in decimal degrees format: 90.0000, 180.0000.
- Lookup: Displays a relationship between two records, for example, the account ID associated with a contact record.
  Lookup fields show the current value of the field as a link to the record that it refers to. If the
  link address can't be computed for any reason, a plain text value is displayed. The mouseover behavior that
  displays a hover panel of record details is not supported. Lookups are not supported for the OwnerId, CreatedBy, and LastModifiedBy fields.
  Dependent lookups and external lookups are also not supported.
  On user lookup fields, the lookup value is displayed without a user icon.
- Name: Displays the formatted name.
- Number: Displays the integer or double.
- Percent: Displays the percentage number.
- Phone: Displays the phone number with the `tel:` URL scheme.
- Picklist and multi-select picklist: Displays picklist values separated by a semi-colon.
- Text: Displays text up to 255 characters.
- Text (Encrypted): Displays the encrypted text.
- Text Area: Displays multi-line text up to 255 characters.
- Text Area (Long): Displays multi-line text up to 131,072 characters.
- Text Area (Rich): Displays rich text such as bold or underline text, lists, and images. Unsupported tags and attributes are removed and only their text content is displayed. For more information on supported tags, see [Rich Text Editor in Salesforce Help](https://help.salesforce.com/articleView?id=fields_using_html_editor.htm).
- Time: Displays the formatted time based on the user's locale.
- URL: Displays a link that opens in the same browser window when it's clicked.

## Usage Considerations

`lightning-output-field` must be a child of `lightning-record-view-form`. You can't nest it in another component like `lightning-layout` though you can nest it in a `<div>` container within `lightning-record-view-form`.

When using `lightning-output-field`, the field label for certain fields can differ from those displayed on a standard record page. For example, the `Name` field on the opportunity object displays "Name" instead of "Opportunity Name" while the `Name` field on the account object displays "Account Name".

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.


:::::

:::::tab
::component-specification{component="outputField" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=51c0ddef5033792f853693b16f2204b5aa5fb014cb673b1a875939f2f3265c55 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/pageChange/wave-page-change.md -->

# Page Change

**`wave:pageChange`**

Updates the Analytics dashboard with the specified `pageid`.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:pageChange` event updates the Analytics dashboard with the specified `pageid`.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name      | Description                                                       | Type   | Default | Required                                     |
| --------- | ----------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `devName` | The fully qualified dev name for the Analytics dashboard.         | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `pageid`  | The dashboard page that should be displayed if value is supplied. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=d0710e4ae332022972400b8867919f5853356abc38b7ded4aef765b00cb7ee0b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/pageReferenceUtils/lightning-page-reference-utils.md -->

# Page Reference Utils

**`lightning/pageReferenceUtils`**

Provides utilities for encoding and decoding default field values. This component requires API version 48.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/pageReferenceUtils` module provides utilities for encoding and decoding default field values. Pass this string into the `pageReference.state.defaultFieldValues` attribute on `standard__objectPage` page reference types. This module is not supported in Lightning Out, Experience Builder sites, or the Salesforce mobile app.

In a module's Javascript file, import `encodeDefaultFieldValues()` or `decodeDefaultFieldValues()` from `lightning/pageReferenceUtils` using this syntax.

```javascript
import { encodeDefaultFieldValues } from "lightning/pageReferenceUtils";
```

## `encodeDefaultFieldValues`

Encodes default field values from a JavaScript object into a serialized string.

| Parameter          | Type   | Description                                                                   |
| ------------------ | ------ | ----------------------------------------------------------------------------- |
| defaultFieldValues | object | List of default key-value pairs for the default field values you are passing. |

## `decodeDefaultFieldValues`

Decodes default field values from a serialized string into a standard object. Use this method when overriding a standard action only.

| Parameter                       | Type   | Description                                                                                                         |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| encodedDefaultFieldValuesString | string | Encoded string of default field values. The values returned by this method are strings. Field type isn't preserved. |

## Usage

The key-value pairs of an object are encoded into a serialized string that you pass into the `pageReference.state.defaultFieldValues` property.

These objects are not supported by `lightning/pageReferenceUtils`:

- ContractLineItem
- OpportunityLineItem
- OrderItem
- QuoteLineItem
- WorkOrderLineItem

Passing the `recordTypeId` to `defaultFieldValues` is not yet supported. The `recordTypeId` influences routing behavior, layout assignment, and page assignment, so you can see unexpected results if you try to use it.

You can specify values for fields even if they’re not available in the create record form.

- If the field is hidden because it’s not on the page layout, the value specified in `defaultFieldValues` is saved with the new record.
- If the current user doesn’t have create access to the field, due to field-level security, attempts to save the new record result in an error.

Error messages can’t reference fields that the current user doesn’t have access to. This constraint means the user won’t know why the error occurred or how to resolve the issue. It’s essential to perform access checks in your own code before firing the event.

You can’t prepopulate system-maintained fields, such as Id or record modification time stamps. Default values for these fields are silently ignored.

Prepopulating rich text fields is unsupported.

Date and time field values must use the ISO 8601 format. For example:

- Date: 2017-07-18
- Datetime: 2017-07-18T03:00:00Z

While the create record page presents `datetime` values in the user’s local time, you must convert `datetime` values to UTC to prepopulate the field.

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/pageReferenceUtils`, see the `c-nav-to-new-record-with-defaults` component.

## See Also

- [Navigate to a Record Create Page with Default Field Values](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-default)


:::::

:::::tab
::component-specification{component="pageReferenceUtils" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=41b6f8a56c7ed60dd1794c2ef8861eaf35021a133a47e36404d1513a7a5e2da3 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/pill/lightning-pill.md -->


# Pill

**`lightning-pill`**

A pill displays a label that can contain links and can be removed from view.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="pill" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-pill` component represents an item, such as an account name or
case number. By default, pills include a remove button. They’re useful for read-only text that you can add or remove on demand. for example, you can add or remove an item from a list of email addresses or a list of keywords.

This example creates a basic pill with a link.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill
        label="Pill Label"
        href="https://www.example.com"
        onremove={handleRemove}
    >
    </lightning-pill>
</template>
```
<!-- prettier-ignore-end -->

URLs without a protocol use the host domain's protocol. For example, `www.example.com` is prefixed with `https://` if the host domain's protocol is `https://`.

## Design

`lightning-pill` implements the pills blueprint in the Salesforce Lightning Design System (SLDS). The pills adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Pills](https://v1.lightningdesignsystem.com/components/pills/)                                                                       | [Pills](https://www.lightningdesignsystem.com/components/pills/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Insert an Icon or Avatar

A pill can contain an icon or avatar to represent the type of object. Nest a `lightning-icon` or `lightning-avatar` component inside the `lightning-pill` component.

Insert an icon on the pill using `lightning-icon`. For more information, see [lightning-icon](/docs/platform/lightning-component-reference/guide/lightning-icon.html).

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill
        name="account"
        label="Pill Label"
        href="https://www.example.com"
    >
        <lightning-icon icon-name="standard:account" alternative-text="Account">
        </lightning-icon>
    </lightning-pill>
</template>
```
<!-- prettier-ignore-end -->

Insert an avatar on the pill by using `lightning-avatar`. For more information, see [lightning-avatar](/docs/platform/lightning-component-reference/guide/lightning-avatar.html).

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill name="user" label="User Name">
        <lightning-avatar
            src="https://v1.lightningdesignsystem.com/assets/images/avatar2.jpg"
            fallback-icon-name="standard:user"
            alternative-text="User avatar"
            variant="circle"
        ></lightning-avatar>
    </lightning-pill>
</template>
```
<!-- prettier-ignore-end -->

## Interact with Pills

A pill has three clickable elements.

- The optional icon or avatar
- The text label
- The remove button

All three elements trigger the `onclick` handler when clicked. If you provide an `href` value, clicking the text label triggers the `onclick` handler and then takes you to the provided path.

Clicking the remove button on the pill fires the `remove` event and then the `click` event. Use the optional `onremove` and `onclick` handlers to remove the pill and perform an action. You must hide or remove the pill on your own using the `onremove` handler, as shown in the next example. If you don't specify a pill removal behavior, clicking the remove button doesn't have a visible effect.

When an `href` value is present, clicking the text label navigates to a link, but clicking the icon or avatar doesn’t. To prevent your browser from navigating to a link when you click a pill's label, call `event.preventDefault()` in the `onclick` handler.

When an `href` value is present, the default variant is `link`. If no `href` is present, the default variant is `plain`.

To disable a pill's link, set `variant="plain"`, which removes the anchor element. The `plain` variant renders the pill without a link and ignores the `href` attribute.

This example hides a pill when you click its remove button.

<!-- prettier-ignore-start -->
```html
<template>
    <template if:true={showPill}>
        <lightning-pill
            label="Account"
            href="https://www.example.com"
            onremove={handleRemoveOnly}
            onclick={handleClick}
        >
        </lightning-pill>
    </template>
</template>
```
<!-- prettier-ignore-end -->

To prevent navigating to the link when the remove button is clicked, call `event.preventDefault()` in the `onremove` handler. The `click` event is still fired when you click the text label. However, calling `event.preventDefault()` in the `onremove` handler prevents the `click` event from firing when you click the remove button.

```javascript
import { LightningElement } from "lwc";
export default class PillRemoveExample extends LightningElement {
  showPill = true;

  handleRemoveOnly(event) {
    event.preventDefault();
    this.showPill = !this.showPill;
  }

  handleClick(event) {
    // this won't run when you click the remove button
    alert("The pill was clicked!");
  }
}
```

## Display an Error

Display a pill in an error state when the containing text doesn't match a
pre-defined collection of items, such as when an email address is invalid or a
case number doesn't exist.

Use the `has-error` attribute to denote an error on a pill. This attribute inserts an error icon next to the label and changes the label text to red. Providing an icon or avatar in this context has no effect on the pill; the error icon is still displayed.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill
        label="Pill with error"
        href="https://www.example.com"
        has-error
    >
    </lightning-pill>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

Use a combination of variants and utility classes to customize your pills.

### Variants

Specify the `variant` attribute using one of these values.

- `link` is the default pill variant, which creates a link in the pill when you specify the `href` value
- `plain` renders the pill without a link and ignores the `href` value

When using a [`lightning-avatar`](/docs/platform/lightning-component-reference/guide/lightning-avatar.html) or [`lightning-icon`](/docs/platform/lightning-component-reference/guide/lightning-icon.html) with the pill, consider the variants on those components.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on the left of the second pill using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-pill label="Astro"></lightning-pill>
<lightning-pill label="Codey" class="slds-p-left_x-small"></lightning-pill>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

Icons are not available in Lightning Out, but they're available in Lightning Components for Visualforce and other experiences.

To create more than one pill, use the `lightning-pill-container` component, which gives you access to the pill array via the `itemremove` event.

Specifying a target to change where the link should open is not supported. The link opens on the same tab or window. To create a URL that navigates to another page in Salesforce, use
[`lightning-navigation`](/docs/platform/lightning-component-reference/guide/lightning-navigation.html).

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Accessibility

When using `lightning-avatar`, use the `alternative-text` attribute to describe the avatar, such as a user's initials or name. This description provides the value for the `alt` attribute in the `img` HTML tag.

When using `lightning-icon`, use the `alternative-text` attribute to describe the icon. For example, specify "Account" instead of "Pill icon". This description is used as assistive text on the pill.

Press the Tab key to move focus to a pill with a link, and tab again to move focus to the remove button. To remove a pill, press the Enter key or space bar when the focus is on the remove button. You can define your own behavior to remove the pill from view, such as using the `onremove` handler shown in **Interacting with Pills**. To navigate to the target of a link on a pill, press the Enter key when the focus is on the pill.

If a pill doesn't have a link, the only focusable item is the remove button.

## Custom Events

**`remove`**

The first event fired when you click the remove button.

The `remove` event returns the following parameter.

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| name      | string | The name of the pill that's removed. |

The event properties are as follows.

| Property   | Value | Description                                                                                                              |
| ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                                                              |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event to prevent the `click` event from being fired. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                                           |


:::::

:::::tab
::component-specification{component="pill" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a01e7a881d3ecdca529e419e968c644cdbda41245f06339f2c2fbc4b5d1c7599 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/pillContainer/lightning-pill-container.md -->


# Pill Container

**`lightning-pill-container`**

A list of pills grouped in a container. This component requires API version 42.0 and later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="pillContainer" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-pill-container` component represents a list of pills in a container
that resembles an input field. Use `lightning-pill-container` to indicate a user's selections when filtering a list, such as from a multi-select picklist.

`lightning-pill-container` includes pills by using the `lightning-pill` component, which can append an icon or avatar next to the text label.

To specify the pills, set the `items` attribute to an array of values in your component's JavaScript.

By default, all pills in the container wrap to additional lines if they can't fit on one line.
For information about changing the behavior, see [Manage Pill Layout in the Container](#manage-pill-layout-in-the-container).

This example creates three pills: a text-only pill, a pill with a link and an avatar, and a pill with an icon.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill-container items={items}> </lightning-pill-container>
</template>
```
<!-- prettier-ignore-end -->

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

export default class PillContainerExample extends LightningElement {
  items = [
    {
      label: "My Pill",
      name: "mypill",
    },
    {
      type: "avatar",
      label: "Avatar Pill",
      href: "https://www.example.com",
      name: "avatarpill",
      src: "/my/path/avatar.jpg",
      fallbackIconName: "standard:user",
      variant: "circle",
      alternativeText: "User avatar",
    },
    {
      type: "icon",
      label: "Icon Pill",
      name: "iconpill",
      iconName: "standard:account",
      alternativeText: "Account",
    },
  ];
}
```

## Design

`lightning-pill-container` implements several designs in the Salesforce Lightning Design System (SLDS). The designs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                                 | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design** (`base` variant)     | [Pills with Container](https://v1.lightningdesignsystem.com/components/pills/#Pill-with-Container)                                    | [Pills with Container](https://www.lightningdesignsystem.com/components/pills/#Pill-with-Container)             |
| **Design** (`standard` variant) | [Listbox of Pill Options](https://v1.lightningdesignsystem.com/components/pills/#Listbox-Of-Pill-Options)                             | [Listbox of Pill Options](https://www.lightningdesignsystem.com/components/pills/#Listbox-Of-Pill-Options)      |
| **For Use In**                  | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

A text-only pill supports several attributes. Use these attributes to create a pill with an avatar or icon.

- `label`: Required. The text label in the pill.
- `name`: The name for the pill. This value is optional and can be used to identify the pill in a callback.

To create a pill with a link, use the following attribute.

- `href`: Required. The URL for the link.

To create a pill with an avatar, use the following attributes.

- `type`: The media type. Use `avatar`.
- `src`: Required. The URL of the avatar.
- `fallbackIconName`: The Lightning Design System name of the icon to use as a fallback when the image fails to load. Names follow the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to include. Only icons from the standard and custom categories are allowed.
- `variant`: Changes the shape of the avatar. Valid values are empty, circle, and square. This value defaults to square.
- `alternativeText`: The alternative text used to describe the avatar, which appears as hover text on the image.

To create a pill with an icon, use these attributes.

- `type`: The media type. Use `icon`.
- `iconName`: Required. The Lightning Design System name of the icon. Names are written in the format 'utility:down' where 'utility' is the category, and 'down' is the specific icon to include. Supports utility icons only.
- `alternativeText`: The alternative text used to describe the icon. Describe what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.

`lightning-pill-container` provides two variants: `bare` and `standard` (default). They’re visually the same. However, the `standard` variant renders pills in an unordered list element. For more information, see the [Accessibility](#accessibility) section.

## Remove Pills

Clicking the remove button triggers the `onitemremove` handler.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-pill-container items={items} onitemremove={handleItemRemove}>
    </lightning-pill-container>
</template>
```
<!-- prettier-ignore-end -->

You can retrieve the name of the pill that's clicked in the event handler and
remove the pill from view.

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

export default class PillContainerRemoveExample extends LightningElement {
  @track items = [
    {
      label: "My Pill",
      name: "mypill",
    },
    {
      type: "avatar",
      label: "Avatar Pill",
      name: "avatarpill",
      src: "/my/path/avatar.jpg",
      fallbackIconName: "standard:user",
      variant: "circle",
      alternativeText: "User avatar",
    },
    {
      type: "icon",
      label: "Icon Pill",
      name: "iconpill",
      iconName: "standard:account",
      alternativeText: "Account",
    },
  ];

  handleItemRemove(event) {
    const name = event.detail.item.name;
    alert(name + " pill was removed!");
    const index = event.detail.index;
    this.items.splice(index, 1);
  }
}
```

## Manage Pill Layout in the Container

Several boolean attributes control the layout of pills in the container. These attributes are set to false by default, which makes pills wrap to multiple lines.

- `is-collapsible`: Determines whether the list of pills can be expanded and collapsed. If `is-collapsible` is true, `is-expanded` can determine whether a pill list displays all the pills or one line of pills. If `is-collapsible` is false or not specified, the `is-expanded` attribute has no effect regardless of its value.
- `is-expanded`: Determines whether the full list of pills is shown. Set `is-collapsible` to true if you want to set `is-expanded` to expand and collapse the list. If you set `is-expanded` to false and don't set `is-collapsible` to true, the list is expanded.
- `single-line`: Specifies that the pill container can display one line of pills. By default, if pills can't fit on one line, they’re wrapped to additional lines to fit the container. Set `single-line` to true to limit pill display to one line. This attribute overrides `is-collapsible` and `is-expanded`.

If all pills aren't displayed, the component shows a text button indicating how many more pills there are.
For example, if there are five more pills that aren’t displayed, the text button shows `+5 more`. The text button fires the `focus` event when you click it.

To display a long list of pills as collapsed, set `is-collapsible` to true and optionally set `is-expanded` to false. Otherwise, pills are expanded by default.

### Expand and Collapse Pills Programmatically

Use `is-collapsible` and `is-expanded` to programmatically expand and collapse the pills.

This example sets `is-collapsible` and uses a button to change the value of `is-expanded`.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="width: 600px">
            <lightning-pill-container
                items={items}
                is-collapsible
                is-expanded={isExpanded}
            >
            </lightning-pill-container>
    </div>
    <lightning-button onclick={setExpanded} label="Expand and Collapse"></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The list of pills is initially collapsed. The button expands and collapses the list.

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

export default class PillContainerCanCollapse extends LightningElement {
  isExpanded = false;

  setExpanded(event) {
    this.isExpanded = !this.isExpanded;
  }

  items = [
    {
      //define the pills
    },
  ];
}
```

### Display All Pills With the `+n more` Button

If all pills aren't displayed, the component shows a text button labeled `+n more` to indicate more pills can be displayed. By default, `lightning-pill-container` doesn’t handle the `focus` event that’s fired when you click the button. You can handle the event to display more pills or write logic to do something else when the button is clicked.

This example sets the pills to be collapsible but not expanded and handles the focus event.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="width: 600px">
            <lightning-pill-container
                items={items}
                is-collapsible={collapsible}
	            is-expanded={expanded}
                onfocus={handlePillExpansion}
            >
            </lightning-pill-container>
    </div>
  </template>
```
<!-- prettier-ignore-end -->

The list of pills is initially collapsed. When there are too many pills to show, the text button labeled `+n more` displays. The handler for the `focus` event enables all the pills to display.

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

export default class PillContainerMoreButtonExpands extends LightningElement {
  collapsible = true;
  expanded = false;

  handlePillExpansion() {
    this.expanded = true;
  }

  items = [
    {
      //define the pills
    },
  ];
}
```

## Component Styling

Use a combination of variants and utility classes to customize your pills.

### Variants

When using a [`lightning-avatar`](/docs/platform/lightning-component-reference/guide/lightning-avatar.html) or [`lightning-icon`](/docs/platform/lightning-component-reference/guide/lightning-icon.html) with the pill, consider the variants on those components.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


`lightning-pill-container` renders pills using `lightning-pill`. Use the `--slds-c-pill-*` custom properties on `lightning-pill`. CSS custom properties for pill containers work only with particular `lightning-pill-container` variants for the remove button.

| CSS Custom Property                      | `lightning-pill-container` Variants |
| ---------------------------------------- | ----------------------------------- |
| `--slds-c-icon-color-background`         | `standard` (default)                |
| `--slds-c-icon-color-foreground-default` | `standard` (default)                |
| `--slds-c-button-color-background`       | `bare`                              |
| `--slds-c-button-color-border`           | `bare`                              |
| `--slds-c-button-radius-border`          | `bare`                              |
| `--slds-c-button-sizing-border`          | `bare`                              |

## Accessibility

By default, `lightning-pill-container` renders pills using the `standard` variant, which uses an unordered list element to display pills. Press the Tab key to focus on the first pill and use the Left Arrow and Right Arrow keys to navigate through the pills. Use the Tab key to navigate to the remove button in a pill with a link. Use arrow keys to navigate between pills.
The focus goes to a link if present, otherwise focus goes to the remove button.

The `bare` variant only supports the Tab key for navigating between focusable elements in the container's pills. The arrow keys aren't supported.

On mobile devices, both container variants display pills with the close button as a focusable element for accessibility.

To remove a pill, press Enter or the space bar when the pill's remove button receives focus. On mobile devices, you can tap the remove button to remove a pill.

For pills with links, use the Tab key or arrow keys to focus on the pill's link, then press Enter to navigate to the link target. If you don't navigate away from the pill, tabbing again puts focus on the remove button.

## Custom Events

**`itemremove`**

The event fired when a pill is removed.

The `itemremove` event returns the following parameters.

| Parameter | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| item      | string | The name of the pill that's removed.   |
| index     | number | The position of the pill in the array. |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |


:::::

:::::tab
::component-specification{component="pillContainer" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6f2b66847ea8353bba55335da97338deb7cc5bf3c91183c54ae1c600ce1571b1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/platformNavigationItemApi/lightning-platform-navigation-item-api.md -->

# Platform Navigation Item API

**`lightning/platformNavigationItemApi`**

Work with navigation items in the menu of a Lightning console app by using the `lightning/platformNavigationItemApi` module. The `lightning/platformNavigationItemApi` module requires API version 67.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/platformNavigationItemApi` module provides methods to control navigation items in the menu of a Lightning console app. All the methods return a promise. The `setSelectedNavigationItem` method requires the navigation item's `developerName` to be passed as an argument. The other methods take no arguments.

To use the Navigation Item API in your component, import the functions in your component's JavaScript file.

```javascript
import {
  focusNavigationItem,
  getNavigationItems,
  getSelectedNavigationItem,
  refreshNavigationItem,
  setSelectedNavigationItem,
} from "lightning/platformNavigationItemApi";
```

This example selects the Accounts navigation item in the Lightning console app.

```javascript
// c/myComponent.js
import { LightningElement, wire } from "lwc";
import {
  IsConsoleNavigation,
  setSelectedNavigationItem,
} from "lightning/platformNavigationItemApi";

export default class MyComponent extends LightningElement {
  @wire(IsConsoleNavigation) isConsoleNavigation;

  onSelectAccounts(event) {
    if (!this.isConsoleNavigation) {
      return;
    }
    setSelectedNavigationItem("standard-Account").then((isSelected) => {
      console.log(
        `Select navigation item ${isSelected ? "successfully" : "failed"}`,
      );
    });
  }
}
```

For this module's documentation, see [Methods for Navigation Items in Lightning Experience](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_lightning_navigationItemAPI.htm) in the Console Developer Guide.

:::::

:::::tab
::component-specification{component="platformNavigationItemApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=adad5fb99718a56901acf178110c2cfa46f70a30645e315653934da618bda2dc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/platformResourceLoader/lightning-platform-resource-loader.md -->

# Platform Resource Loader

**`lightning/platformResourceLoader`**

Use third-party libraries that are uploaded as a static resource in your org.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/platformResourceLoader` module has two methods, `loadScript` and `loadStyle`. Both methods create and return promises, which can be chained or used in parallel. You control the load sequence of your scripts or styles. In your component's JavaScript file, import the functions from the `lightning/platformResourceLoader` module.

```javascript
import { loadStyle, loadScript } from "lightning/platformResourceLoader";
```

## `loadScript(self, fileUrl): Promise`

Accesses a .js file in a static resource. Returns a promise that resolves after the file has loaded.

- `self` - A reference to the component. The value must be `this`.
- `fileUrl` - A string that contains the path to the JavaScript file. To build the string, concatenate the resourceName and the path to the file within the static resource archive.

## `loadStyle(self, fileUrl): Promise`

Accesses a .css file in a static resource. Returns a promise that resolves after the file has loaded.

- `self` - A reference to the component. The value must be `this`.
- `fileUrl` - A string that contains the path to the CSS file. To build the string, concatenate the resourceName and the path to the file within the static resource archive.

## Usage

To import a third-party JavaScript or CSS library, use the `platformResourceLoader` module.

1. Download the JavaScript or CSS files from the third-party library's site.
2. Upload the library to your Salesforce organization as a static resource, which is a Lightning security requirement for using third-party code. For more information, see [Access Static Resources](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.html) in the _Lightning Web Components Developer Guide_.
3. In a component's JavaScript file:

   - Import the static resource.

     `import myResourceName from '@salesforce/resourceUrl/myResourceName';`

   - Import methods from the `platformResourceLoader` module. Dynamic imports of this module aren’t allowed.

     `import { loadStyle, loadScript } from 'lightning/platformResourceLoader';`

4. Load the library and call its functions in a promise `then()` method.

```javascript
loadScript(this, myResourceName + "/myResourceName.js").then(() => {
  // your code with calls to the JS library
});
```

This example shows how to use `platformResourceLoader` with the Leaflet library to create an interactive map.

```javascript
import { LightningElement } from "lwc";
import { loadStyle, loadScript } from "lightning/platformResourceLoader";

import leaflet from "@salesforce/resourceUrl/leaflet";

export default class MyMap extends LightningElement {
  // invoke the loaders in connectedCallback() to ensure that
  // the page loads and renders the container before the map is created

  connectedCallback() {
    Promise.all([
      loadStyle(this, leaflet + "/leaflet.css"),
      loadScript(this, leaflet + "/leaflet.js"),
    ]).then(() => {
      // initialize the library using a reference to the container element obtained from the DOM
      const el = this.template.querySelector("div");
      const mymap = L.map(el).setView([51.505, -0.09], 13);

      // Load and display tile layers with your access token
      L.tileLayer(
        "https://api.tiles.mapbox.com/v4/{id}/{z}/{x}/{y}.png?access_token={accessToken}",
        {
          maxZoom: 18,
          id: "mapbox.streets",
          accessToken: "your.mapbox.access.token",
        },
      ).addTo(mymap);
    });
  }
}
```

### Aura Components That Load the Same Script

If an Aura component uses [`ltng:require`](/docs/platform/lightning-component-reference/guide/ltng-require.html) to load a script url, and an LWC component uses `loadScript` from `lightning/platformResourceLoader` to load the same script url in the same page, the script duplication is not detected and the script is loaded twice. The script must protect itself from duplication, for instance by checking if a global is already defined.

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/platformResourceLoader`, see these components in the LWC Recipes repo.

- `c-libs-chartjs`
- `c-libs-d3`

## See Also

[Use Third-Party JavaScript Libraries](https://developer.salesforce.com/docs/platform/lwc/guide/js-third-party-library)

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


:::::

:::::tab
::component-specification{component="platformResourceLoader" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=169dd49d7ba873c6f74f701d881a627deb29293e68306e7a16aedc8689141ba3 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/platformShowToastEvent/lightning-platform-show-toast-event.md -->

# Platform Show Toast Event (Beta)

**`lightning/platformShowToastEvent`**

Provides feedback and confirmation after a user action.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Display toasts to provide feedback to a user following an action, such as after a record is created.

`lightning/platformShowToastEvent` isn't supported in LWR sites for Experience Cloud. Use `lightning/toast` in LWR sites instead. To specify your toast position and the maximum number of toasts to display, use `lightning/platformShowToastEvent` or `lightning/toast` with `lightning/toastContainer`.

You can style a toast to provide information, an error, a success, or a warning. You can also configure the visibility of the toast. It remains visible for 20 seconds, until the user clicks to dismiss it, or a combination of both.

To trigger a toast from a Lightning web component, in the component's JavaScript class, import `ShowToastEvent` from `lightning/platformShowToastEvent`. Create a `ShowToastEvent` with a few parameters, and dispatch it. The app handles the rest.

In this example, when a user clicks the button, the app displays a
toast with the `info` variant, which is the default. The toast remains visible for 20 seconds or until the user clicks the close
button, denoted by the X in the top right corner, which is also the default.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button label="Show Toast" onclick={showToast}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

The `showToast` function creates and dispatches the event. An info toast displays in Lightning Experience for 5 seconds or until the user clicks to close it.

```javascript
import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
export default class MyComponent extends LightningElement {
  showToast() {
    const event = new ShowToastEvent({
      title: "Get Help",
      message:
        "Salesforce documentation is available in the app. Click ? in the upper-right corner.",
    });
    this.dispatchEvent(event);
  }
}
```

## Displaying Links in Toasts

To display a link in the message, use the `messageData` attribute to pass in `url` and `label` values for the `message` string. In the following example, `handleButtonClick()` displays a toast with a link in the message. `handleRecordClick()` displays a toast with a link to a record, which uses the `lightning/navigation` module to generate the URL.

```javascript
import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { NavigationMixin } from "lightning/navigation";

export default class LightningToastExample extends NavigationMixin(LightningElement) {
  handleButtonClick() {
    const event = new ShowToastEvent({
      title: "Success!",
      message: "Record {0} created! See it {1}!",
      messageData: [
        "Salesforce",
        {
          url: "http://www.salesforce.com/",
          label: "here",
        },
      ],
    });
    this.dispatchEvent(event);
  }

  handleRecordClick() {
    this[NavigationMixin.GenerateUrl]({
      type: "standard__recordPage",
      attributes: {
        recordId: "003xx000000001eAAA",
        actionName: "view",
      },
    }).then((url) => {
      const event = new ShowToastEvent({
        title: "Success!",
        message: "Record {0} created! See it {1}!",
        messageData: [
          "Salesforce",
          {
            url,
            label: "here",
          },
        ],
      });
      this.dispatchEvent(event);
    });
  }
}
```

## Parameters

| Parameter     | Type               | Description                                                                                                                                                                                                                                                                                                                                           |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | String             | (Required) The title of the toast, displayed as a heading.                                                                                                                                                                                                                                                                                            |
| `message`     | String             | (Required) A string representing the body of the message. It can contain placeholders in the form of `{0} ... {N}`. The placeholders are replaced with the links on `messageData`.                                                                                                                                                                    |
| `messageData` | String[] or Object | `url` and `label` values that replace the `{index}` placeholders in the `message` string.                                                                                                                                                                                                                                                             |
| `variant`     | String             | Changes the appearance of the notice. Toasts inherit styling from [toasts](https://v1.lightningdesignsystem.com/components/toast) in the Lightning Design System. Valid values are: `info` (default), `success`, `warning`, and `error`.                                                                                                              |
| `mode`        | String             | Determines how persistent the toast is. Valid values are: `dismissible` (default), remains visible until you click the close button or 20 seconds has elapsed, whichever comes first; `pester`, remains visible for 20 seconds and disappears automatically. No close button is provided; `sticky`, remains visible until you click the close button. |

## Design Guidelines

A toast appears in reaction to a user action: creating, editing, deleting. For example, a user edits a record and saves it. For more information, see [Messaging Design Guidelines](https://lightningdesignsystem.com/guidelines/messaging/overview/).

## Usage Considerations

`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](/docs/platform/lightning-component-reference/guide/lightning-toast.html) instead.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/platformShowToastEvent`, see the following components in the LWC Recipes repo.

- `c-lds-create-record`
- `c-misc-toast-notification`

## See Also

[Toast Notifications](https://developer.salesforce.com/docs/platform/lwc/guide/use-toast)


:::::

:::::tab
::component-specification{component="platformShowToastEvent" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=f88ba1dbaa554de104a24377d4aa2c0536c94a114e54b0ca37cf744c514fc06d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/platformUtilityBarApi/lightning-platform-utility-bar-api.md -->

# Platform Utility Bar API

**`lightning/platformUtilityBarApi`**

Work with a utility within the utility bar of a Lightning app using the `lightning/platformUtilityBarApi` module. The utility bar is a footer that gives users quick access to frequently used tools and components. Each utility is a single-column Lightning page that includes a standard or custom Lightning component. The `lightning/platformUtilityBarApi` module requires API version 61.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/platformUtilityBarApi` module provides LWC Utility Bar API methods to control a utility within the utility bar of a Lightning app. All the methods in the `lightning/platformUtilityBarApi` module return a Promise. Required method parameters are explicitly passed as individual arguments. Optional parameters are passed into an object as the last argument of the method.

To use the Utility Bar API in your component, import the functions in your component's JavaScript file.

```javascript
import {
  enableModal,
  enablePopout,
  getAllUtilityInfo,
  getUtilityInfo,
  minimize,
  onUtilityClick,
  open,
  updatePanel,
  updateUtility,
} from "lightning/platformUtilityBarApi";
```

The following example minimizes an open utility panel.

```javascript
// c/myComponent.js
import { LightningElement, wire } from "lwc";
import { EnclosingUtilityId, minimize } from "lightning/platformUtilityBarApi";

export default class MyComponent extends LightningElement {
  @wire(EnclosingUtilityId) utilityId;

  onMinimize(event) {
    if (!this.utilityId) {
      return;
    }
    minimize(this.utilityId).then((isMinimized) => {
      console.log(`Minimize utilty ${isMinimized ? "successfully" : "failed"}`);
    });
  }
}
```

For this module's documentation, see [Methods for the Utility Bar in Lightning Experience](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_methods_lightning_utilityBarAPI.htm) in the Console Developer Guide.

:::::

:::::tab
::component-specification{component="platformUtilityBarApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=39262be9bb9d2c252453360d2bd96aadc09e8c69e9fe2b28ccb91d2930e66d5d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/platformWorkspaceApi/lightning-platform-workspace-api.md -->

# Platform Workspace API

**`lightning/platformWorkspaceApi`**

Work with workspace tabs and subtabs in a Lightning console app using the `lightning/platformWorkspaceApi` module. The `lightning/platformWorkspaceApi` module requires API version 59.0 or later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/platformWorkspaceApi` module provides LWC Workspace API methods to control workspace tabs and subtabs in a Lightning console app. All the methods in the `lightning/platformWorkspaceApi` module return a promise. Required method parameters are explicitly passed as individual arguments. Optional parameters are passed into an object as the last argument of the method.

To use the Workspace API in your component, import the functions in your component's JavaScript file.

```javascript
import {
  EnclosingTabId,
  IsConsoleNavigation,
  closeTab,
  disableTabClose,
  focusTab,
  getAllTabInfo,
  getFocusedTabInfo,
  getTabInfo,
  openSubtab,
  openTab,
  refreshTab,
  setTabHighlighted,
  setTabIcon,
  setTabLabel,
} from "lightning/platformWorkspaceApi";
```

The following example toggles the highlight of a focused tab in the Lightning console app.

```javascript
// c/myComponent.js
import { LightningElement, wire } from "lwc";
import {
  IsConsoleNavigation,
  getFocusedTabInfo,
  setTabHighlighted,
} from "lightning/platformWorkspaceApi";

export default class MyComponent extends LightningElement {
  @wire(IsConsoleNavigation) isConsoleNavigation;

  onToggleHighlightTab(event) {
    if (!this.isConsoleNavigation) {
      return;
    }
    const { highlighted } = event.detail;
    getFocusedTabInfo().then((tabInfo) => {
      const { tabId } = tabInfo;
      setTabHighlighted(tabId, highlighted, {
        pulse: true,
        state: "success",
      });
    });
  }
}
```

For this module's documentation, see [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) in the Console Developer Guide.

To work with Lightning console app events in your component, subscribe to the [Lightning message channels for the Aura application events](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/sforce_api_console_js_events.htm) that you want to listen for.

:::::

:::::tab
::component-specification{component="platformWorkspaceApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0492761ad810e392cae3cfea7b3df530373a43ff09df3d688049607e882e65fa url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceChatter/postCreated/forceChatter-post-created.md -->

# Post Created

**`forceChatter:postCreated`**

Fired when a post is made.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when a post is created on the publisher, such as when you post to your profile feed and other feeds, create a poll, or create a question.

Handle the event by adding an `aura:handler` tag and defining a client-side controller action. You can handle this event when using `forceChatter:publisher` and `forceChatter:feed`, or on any page that has a publisher.

This example displays a toast message when a post is created, assuming the component is added to a record page. The toast is displayed when you create a post on the record page.

```xml
<aura:component implements="flexipage:availableForRecordHome" controller="ContactController">
	<aura:handler event="forceChatter:postCreated" action="{!c.handlePostCreated}"/>
	<lightning:notificationsLibrary aura:id="notifLib"/>
</aura:component>
```

This client-side controller displays the toast.

```javascript
handlePostCreated: function(cmp, event, helper) {
     cmp.find('notifLib').showToast({
        "title": "Success!",
        "message": "You just shared a post."
    });
}
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab
## Attributes

| Name         | Description                                    | Type   | Default | Required |
| ------------ | ---------------------------------------------- | ------ | ------- | -------- |
| `feedItemId` | The ID of the feed item that has been created. | string |         |          |

:::::

::::::

<!-- document id=c84665eae888f238f5718e2ebe39cba2aabec4b92d98d8bd8b63e2370d076936 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/profileMenuInterface/forceCommunity-profile-menu-interface.md -->

# Profile Menu Interface

**`forceCommunity:profileMenuInterface`**

Enables a component to be used as a custom profile menu in Experience Builder.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To appear in Experience Builder as a custom profile menu, a component must implement `forceCommunity:profileMenuInterface`.

Here's the sample code for a simple profile menu component.

```xml
<aura:component implements="forceCommunity:profileMenuInterface" access="global">
    <aura:attribute name="options" type="String[]" default="Option 1, Option 2"/>
    <ui:menu >
        <ui:menuTriggerLink aura:id="trigger" label="Profile Menu"/>
        <ui:menuList class="actionMenu" aura:id="actionMenu">
            <aura:iteration items="{!v.options}" var="itemLabel">
                <ui:actionMenuItem label="{!itemLabel}" click="{!c.handleClick}"/>
            </aura:iteration>
        </ui:menuList>
    </ui:menu>
</aura:component>
```

After you create a custom profile menu component, admins can select it in Experience Builder in Settings | Theme to replace the template’s standard Profile Header component.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=3db8a2e2fdc4a6a3a37a404d46e20320b93f477a6dba068f1060bc7e347b1298 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/progressBar/lightning-progress-bar.md -->


# Progress Bar

**`lightning-progress-bar`**

Displays a horizontal progress bar from left to right to indicate the progress of an operation.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="progressBar" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-progress-bar` component shows the progress of an operation from
left to right, such as for a file download or upload.

This example loads the progress bar when you click the Start button.
The Start button becomes a Stop button when the progress bar is incrementing its value.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="slds-p-bottom_medium">
        <lightning-button label={computedLabel} onclick={toggleProgress}>
        </lightning-button>
    </div>
    <lightning-progress-bar value={progress}> </lightning-progress-bar>
</template>
```
<!-- prettier-ignore-end -->

Here's the JavaScript that changes the value of the progress bar.
Specifying `this.progress === 100 ? this.resetProgress() : this.progress + 10`
increases the progress value by 10% and stops the animation when the progress
reaches 100%. The progress bar is updated every 200 milliseconds.

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

export default class DemoComponent extends LightningElement {
  progress = 0;
  isProgressing = false;

  updateProgress() {
    this.progress = this.progress === 100 ? this.resetProgress() : this.progress + 10;
  }

  resetProgress() {
    this.progress = 0;
    clearInterval(this._interval);
  }

  disconnectedCallback() {
    clearInterval(this._interval);
  }

  get computedLabel() {
    return this.isProgressing ? "Stop" : "Start";
  }

  toggleProgress() {
    if (this.isProgressing) {
      // stop
      this.isProgressing = false;
      if (!this.progress) {
        this.progress = 0;
      }
      clearInterval(this._interval);
    } else {
      // start
      this.isProgressing = true;
      this._interval = setInterval(this.updateProgress.bind(this), 200);
    }
  }
}
```

## Design

`lightning-progress-bar` implements the progress bar blueprint in the Salesforce Lightning Design System (SLDS). The progress bar adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Progress Bars](https://v1.lightningdesignsystem.com/components/progress-bar/)                                                        | [Progress Bars](https://www.lightningdesignsystem.com/components/progress-bar/)                                 |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of variants, sizes, and utility classes to customize the progress bar.

### Variants

Specify the `variant` attribute using one of these values.

- `base` is the default variant, which shows a rectangular progress bar
- `circular` shows a progress bar with rounded ends

### Sizes

Adjust the progress bar sizes by using the `size` attribute with one of these values.

- `x-small` creates a progress bar with a height of 2px
- `small` creates a progress bar with a height of 4px
- `medium` is the default variant, which creates a progress bar with a height of 8px
- `large` creates a progress bar with a height of 12px

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.


:::::

:::::tab
::component-specification{component="progressBar" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=888c45e190c14cb256b6e772b9f558651db05c5d24a0662edba9c38a19abc023 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/progressIndicator/lightning-progress-indicator.md -->


# Progress Indicator (Beta)

**`lightning-progress-indicator`**

Provides a visual indication on the progress of a particular process.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="progressIndicator" model="lwc" namespace="lightning"}


:::::

:::::tab

**note:** `lightning-progress-indicator` 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.

A `lightning-progress-indicator` component shows a horizontal list of steps
in a process, indicating:

- The number of steps in a given process
- The current step
- The prior steps that are completed

For example, Sales Path uses a progress indicator to guide sales reps through the stages of the sales process.

To create steps, use one or more `lightning-progress-step` component along with `label` and `value` attributes. To specify the current step, the `current-step`
attribute must match one of the `value` attributes on a
`lightning-progress-step` component.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-progress-indicator current-step="step2">
        <lightning-progress-step label="Step One" value="step1">
        </lightning-progress-step>
        <lightning-progress-step label="Step Two" value="step2">
        </lightning-progress-step>
        <lightning-progress-step label="Step Three" value="step3">
        </lightning-progress-step>
    </lightning-progress-indicator>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-progress-indicator` implements several designs in the Salesforce Lightning Design System (SLDS). The designs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                          | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design** (`base` type) | [Progress Indicator](https://v1.lightningdesignsystem.com/components/progress-indicator/)                                             | [Progress Indicator](https://www.lightningdesignsystem.com/components/progress-indicator/)                      |
| **Design** (`path` type) | [Path](https://v1.lightningdesignsystem.com/components/path/)                                                                         | [Path](https://www.lightningdesignsystem.com/components/path/)                                                  |
| **For Use In**           | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

You can create progress indicators with different visual styling by specifying
the `type` attribute.

- Set `type="base"` to create a progress indicator. The vertical progress indicator isn't currently supported.
- Set `type="path"` to create a path. Stage coaching information isn't currently supported.

If the type isn’t specified, the default type `base` is used.
The `label` value is displayed in a tooltip when you hover
over the step. If the progress indicator type is `path`, the label appears on hover if the step is completed or on the step itself if it's a
current or incomplete step.

## Create a Path Type Progress Indicator

This example creates a path showing the current step at "Step Two". "Step One"
is marked completed and "Step Three" isn’t yet completed.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-progress-indicator type="path" current-step="step2">
        <lightning-progress-step label="Step One" value="step1">
        </lightning-progress-step>
        <lightning-progress-step label="Step Two" value="step2">
        </lightning-progress-step>
        <lightning-progress-step label="Step Three" value="step3">
        </lightning-progress-step>
    </lightning-progress-indicator>
</template>
```
<!-- prettier-ignore-end -->

The component shows the current step in an active state. It marks all steps preceding the current step as completed.

## Implement the Error State

To denote an error on the current step, set `has-error` to `true`. Only the `base` type supports the error state.
This example creates a progress indicator that updates to the next step and applies an error on the current step.

<!-- prettier-ignore-start -->
```html
<lightning-progress-indicator
    current-step={current}
    type="base"
    has-error={error}
>
    <lightning-progress-step
        label="Step 1"
        value="s1"
    ></lightning-progress-step>
    <lightning-progress-step
        label="Step 2"
        value="s2"
    ></lightning-progress-step>
    <lightning-progress-step
        label="Step 3"
        value="s3"
    ></lightning-progress-step>
    <lightning-progress-step
        label="Step 4"
        value="s4"
    ></lightning-progress-step>
</lightning-progress-indicator>
<lightning-button label="Next step" onclick={nextStep}></lightning-button>
<lightning-button label="Show error" onclick={addError}></lightning-button>
```
<!-- prettier-ignore-end -->

Applying an error state on the current step updates the completed icon to an error icon,
similar to the [progress indicator](https://v1.lightningdesignsystem.com/components/progress-indicator/#Error-in-a-Step) SLDS blueprint.

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

export default class ProgressIndicatorError extends LightningElement {
  current = "s3";
  error = false;

  nextStep() {
    this.current = "s4";
  }

  addError() {
    this.error = true;
  }
}
```

## Accessibility

Each progress step is rendered with assistive text, which is constructed from the step's label and a description of the step's state.
For example, for a step labeled Contacted, the assistive text is "Contacted - Current Stage" when the step is the current step, and "Contacted - Stage Complete" when the step is completed. The text of the step's state can't be changed.

| Step      | Assistive Text         |
| --------- | ---------------------- |
| Current   | Label - Current Stage  |
| Inactive  | Label                  |
| Completed | Label - Stage Complete |
| Error     | Label                  |

The assistive text for a step that's inactive or has an error doesn't include information about the step's state.

For the `base` type, you can use the Tab key to navigate from one step to the next. Each step connects to the next
step with a horizontal progress bar, such that two steps share one bar.
Press Shift+Tab to go to the previous step. The progress bar renders with `aria-valuenow` set to a scale of 0 to 100,
which defines the current value for the progress bar. For example, if you have 4 steps and the third step is the current,
`aria-valuenow` is set to 66, since 2 out of 3 bars are marked as completed.
Similarly, the `aria-valuemin` and `aria-valuemax` attributes are set to 0 and 100 respectively.

For the `path` type, press Tab to set focus on the active stage and use the Up and Down Arrow keys
or the Left and Right arrow keys to navigate from one stage to another. The `aria-selected` attribute on the hyperlink element associated with the stage is set to `true` when a stage receives focus and `false` when it doesn't receive focus.

When you navigate away from the current active stage, the stage remains the current stage but the shift in focus makes it inactive. The current stage changes color from dark blue to white to indicate it's not the active stage.

Consider these additional scenarios.

- Navigating to an incomplete stage makes it an active incomplete stage, which changes its color from gray to dark blue
- Navigating to a completed stage makes it an active completed stage, which changes its color from green to dark blue


:::::

:::::tab
::component-specification{component="progressIndicator" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=be0590365452391b7236ccc7d4d7da1158838c4d5a44bdc5d7bc05e04b699c98 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/progressRing/lightning-progress-ring.md -->


# Progress Ring

**`lightning-progress-ring`**

Displays a circular progress indicator to provide feedback about an action or process. This component requires API version 48.0 and later.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="progressRing" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-progress-ring` component is a circular progress indicator. It shows a value from 0 to 100 by filling the ring with a green color by default, and supports variants to change its styling. The color fill is displayed in a clockwise or counterclockwise direction. It informs users the status of a process or action, such as loading data or saving updates.

This example creates a progress ring in a clockwise direction with a value of 75, which fills three quarters of the ring, or 75%.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="75"> </lightning-progress-ring>
```
<!-- prettier-ignore-end -->

## Design

`lightning-progress-ring` implements the progress bar blueprint in the Salesforce Lightning Design System (SLDS). The progress ring adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Progress Ring](https://v1.lightningdesignsystem.com/components/progress-ring/)                                                       | [Progress Ring](https://www.lightningdesignsystem.com/components/progress-ring/)                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Component Styling

Use a combination of variants, sizes, and utility classes to customize the progress bar.

### Variants

Use variants to change the ring's styling to provide contextual feedback to users, such as whether an action is successful, active, at risk of failing, or unsuccessful.

By default, the progress ring fills in with green as the value increases, to indicate success.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="80"> </lightning-progress-ring>
```
<!-- prettier-ignore-end -->

To display an active step in blue, use the `active-step` variant. This variant indicates that the progress status is ongoing and not yet determined to be successful, at risk of failing, or unsuccessful.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="75" variant="active-step">
</lightning-progress-ring>
```
<!-- prettier-ignore-end -->

To indicate a problem with an action or process, use the `warning` variant.
This variant displays the warning icon inside the ring and uses a yellow fill color.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="80" variant="warning">
</lightning-progress-ring>
```
<!-- prettier-ignore-end -->

To indicate an unsuccessful action or process, use the `expired` variant.
This variant displays the error icon inside the ring and uses a red fill color.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="0" variant="expired"> </lightning-progress-ring>
```
<!-- prettier-ignore-end -->

To indicate a successful action or process, use the `base-autocomplete` variant. This variant is styled the same as the default `base` variant when the value is 0 to 99. When the value is 100, the success icon displays as a checkmark on a green background matching the fill color of the ring.

<!-- prettier-ignore-start -->
```html
<lightning-progress-ring value="100" variant="base-autocomplete">
</lightning-progress-ring>
```
<!-- prettier-ignore-end -->

### Sizes

Adjust the progress ring sizes by using the `size` attribute with one of these values.

- `medium` is the default variant, which displays the progress ring with a dimension of 24px by 24px
- `large` displays the progress ring with a dimension of 32px by 32px

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

## Accessibility

The `warning`, `expired`, and `base-autocomplete` variants provide icons and descriptive text for accessibility. The `active-step` variant currently does not have either, so it's not accessible. The `active-step` and `base` default variant appear the same except for color. Consider this accessibility limitation when using the `active-step` variant.


:::::

:::::tab
::component-specification{component="progressRing" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0447edbfa4fd6142c73fab17b374640096a7a1efd5ac15cb759c13c5e2de5c11 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/progressStep/lightning-progress-step.md -->


# Progress Step (Beta)

**`lightning-progress-step`**

Defines a step in the lightning-progress-indicator.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="progressStep" model="lwc" namespace="lightning"}


:::::

:::::tab

**note:** `lightning-progress-step` 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.

A `lightning-progress-step` component specifies a step inside the [`lightning-progress-indicator`](/docs/platform/lightning-component-reference/guide/lightning-progress-indicator.html) component.
Specify the `label` attribute to define the text for the name or tooltip for the step.
Specify the `value` attribute to set the value used to reference the step.

To specify the current step, the `current-step` attribute on `lightning-progress-indicator`
must match one of the `value` attributes on a `lightning-progress-step` component.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-progress-indicator current-step="step2">
        <lightning-progress-step label="Step One" value="step1">
        </lightning-progress-step>
        <lightning-progress-step label="Step Two" value="step2">
        </lightning-progress-step>
        <lightning-progress-step label="Step Three" value="step3">
        </lightning-progress-step>
    </lightning-progress-indicator>
</template>
```
<!-- prettier-ignore-end -->

If the progress indicator type isn’t specified or is set to `base`, the
`label` text appears in a tooltip when you hover
over the step.

If the progress indicator type is `path`, the label appears on hover if the step is completed or on the step itself if it's a
current or incomplete step.

For `base` type progress indicators, custom events implemented in `lightning-progress-step` fire during user interactions with the steps. Each event returns the index of the step. See the **Custom Events** section for more information.

For example, to get the index of the step that released focus, use the `event.detail` property on the `onstepblur` event handler.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-progress-indicator current-step="step2">
        <lightning-progress-step
            label="Step One"
            value="step1"
            onstepblur={handleStepBlur}
        >
        </lightning-progress-step>
        <lightning-progress-step
            label="Step Two"
            value="step2"
            onstepblur={handleStepBlur}
        >
        </lightning-progress-step>
        <lightning-progress-step
            label="Step Three"
            value="step3"
            onstepblur={handleStepBlur}
        >
        </lightning-progress-step>
    </lightning-progress-indicator>
</template>
```
<!-- prettier-ignore-end -->

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

export default class MyDemoComponent extends LightningElement {
  handleStepBlur(event) {
    const stepIndex = event.detail.index;
  }
}
```

## Design

Use `lightning-progress-step` within `lightning-progress-indicator`, which implements several designs in the Salesforce Lightning Design System (SLDS). The designs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                          | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design** (`base` type) | [Progress Indicator](https://v1.lightningdesignsystem.com/components/progress-indicator/)                                             | [Progress Indicator](https://www.lightningdesignsystem.com/components/progress-indicator/)                      |
| **Design** (`path` type) | [Path](https://v1.lightningdesignsystem.com/components/path/)                                                                         | [Path](https://www.lightningdesignsystem.com/components/path/)                                                  |
| **For Use In**           | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage Considerations

`lightning-progress-step` supports the custom events listed in the next section. It doesn't support the `click` event. To enable users to interactively update their progress to the next or previous steps, include a clickable element that updates the `current-step` value on `lightning-progress-indicator`. For more information, see the [lightning-progress-step documentation](/docs/platform/lightning-component-reference/guide/lightning-progress-step.html).

## Custom Events

The `lightning-progress-step` component supports these events for the `base` type of `lightning-progress-indicator`.

**`stepblur`**

The event fired when a step releases focus.

The `stepblur` event returns this parameter.

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| index     | string | The index of the step that released focus. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

**`stepfocus`**

The event fired when a step receives focus.

The `stepfocus` event returns the following parameter.

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| index     | string | The index of the step that received focus. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

**`stepmouseenter`**

The event fired when the mouse pointer moves onto the step.

The `stepmouseenter` event returns the following parameter.

| Parameter | Type   | Description                                         |
| --------- | ------ | --------------------------------------------------- |
| index     | string | The index of the step the mouse pointer moves onto. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

**`stepmouseleave`**

The event fired when the mouse pointer moves off the step.

The `stepmouseleave` event returns the following parameter.

| Parameter | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| index     | string | The index of the step the mouse pointer moves out of. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

## Accessibility

Each progress step is decorated with assistive text, which is also the label
of that step. For the `base` type, you can use the Tab key to navigate from one
step to the next. Press Shift+Tab to go to the previous step. For the `path`
type, press Tab to activate the current step and use the Up and Down Arrow key
or the Left and Right arrow key to navigate from one step to another.


:::::

:::::tab
::component-specification{component="progressStep" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=b230e886d23f9175f044312abd642d307ff03ae670aaa31429ab2ee74b6066fd url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/prompt/lightning-prompt.md -->


# Prompt

**`lightning-prompt`**

Create a prompt modal within your component that asks the user to provide information before they continue.

**For Use In**

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="prompt" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning/prompt` module provides the `LightningPrompt` component to create a prompt modal within your component. Use `LightningPrompt` on a component to ask the user to provide information before they continue.

**note:** Use `LightningPrompt.open()` instead of the native `window.prompt()` for a more consistent user experience. They have similar functions, but `LightningPrompt.open()` works in cross-origin iframes, where the `.prompt()` method is no longer supported in Chrome and Safari. Unlike `window.prompt()`, `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 prompt has closed.

## Design

`lightning/prompt` implements the prompt blueprint in the Salesforce Lightning Design System (SLDS). The prompt adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                         | SLDS 2                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Prompt](https://v1.lightningdesignsystem.com/components/prompt/)                              | [Prompt](https://www.lightningdesignsystem.com/components/prompt/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

Import `LightningPrompt` from the `lightning/prompt` module in the component that opens the prompt modal, and call `LightningPrompt.open()` with your desired attributes.

This example creates a prompt modal with a header, message, and two buttons. If you enter text and click **OK** in the prompt, the `.open()` function returns a promise that resolves to the input value. If you click **Cancel**, the function returns a promise that resolves to `null`.

<!-- prettier-ignore-start -->
```html
<!-- c/myApp.html -->
<template>
    <lightning-button onclick={handlePromptClick} label="Open Prompt Modal">
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

```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: "initial input value", //this is optional
    }).then((result) => {
      //Prompt has been closed
      //result is input text if OK clicked
      //and null if cancel was clicked
    });
  }
}
```

`LightningPrompt` supports these attributes:

- `message`: Message text that displays in the prompt.
- `defaultValue`: Optional. Initial leading text for the input text box.
- `label`: Header text, also used as the `aria-label`. Default string is `Prompt`.
- `variant`: See the [Variants](#variants) section.
- `theme`: See the [Themes](#themes) section.

## Component Styling

Use a combination of variants, themes, and utility classes to customize your prompts.

### Variants

Specify the `variant` attribute with one of these values.

- `header` is the default variant, which displays the prompt with header text
- `headerless` displays the prompt without header text

### Themes

Specify the `theme` attribute for the prompt header with one of these color [options](https://v1.lightningdesignsystem.com/utilities/themes) from SLDS.

- `default`: white
- `shade`: gray
- `inverse`: dark blue
- `alt-inverse`: darker blue
- `success`: green
- `info`: gray-ish blue
- `warning`: yellow
- `error`: red
- `offline`: ​black​

If an invalid value is provided, `LightningPrompt` uses the `default` theme. `LightningPrompt` ignores the `style` attribute.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

## Test Your Prompt

Code using `LightningPrompt` can be tested by mocking the `LightningPrompt.open()` method.

This example uses a button to open a prompt dialog and sets the result in a template.

<!-- prettier-ignore-start -->
```html
<button data-button onclick={handleClick}>Open Prompt</button>
<div data-result>{result}</div>
```
<!-- prettier-ignore-end -->

```js
import LightningPrompt from 'lightning/prompt';
jest.mock('lightning/prompt');
​
test(() => {
    // Create and appendChild(element)
​
    const buttonEle = element.shadowRoot.querySelector('[data-button]');
    const resultEle = element.shadowRoot.querySelector('[data-result]');
​
    // Mock .open()
    // Pass string representing input text if testing when user clicks "OK"
    // Pass null if testing when user clicks "Cancel"
    LightningPrompt.open = jest.fn().mockResolvedValue('test value');
    // Initial value
    expect(resultEle.textContent).toBe('unknown');
    // Click modal open button
    buttonEle.click();
​
    // Click handler render cycle
    await Promise.resolve();
    // Render cycle triggered by tracked value {result}
    await Promise.resolve();
​
    // Verify result is set in the template
    expect(resultEle.textContent).toBe('test value');
    // Open triggered once
    expect(LightningPrompt.open.mock.calls).toHaveLength(1);
})
```


:::::

:::::tab
::component-specification{component="prompt" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=ce6601ed9c694daceb320dbb55103321d49dd5c0486fc58f9c1580be5f7a838e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/quickActionPanel/lightning-quick-action-panel.md -->

# Quick Action Panel (Beta)

**`lightning-quick-action-panel`**

Creates a modal with a body and a footer for a custom quick action.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `lightning-quick-action-panel` 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.

Use the `lightning-quick-action-panel` component (Beta) to build your own action modals that use the Salesforce Lightning Design System (SLDS) modal styling. You can create custom screen actions and maintain a consistent UI across all actions, including standard Salesforce and Aura Lightning quick actions.

![Quick action panel with input fields](https://developer.salesforce.com/media/components/quick-action-panel-basic.png '{ "class":"image-md", "title": "Quick Action Panel"}')

This component has a `header` attribute and two slots:

- The default slot for the body
- A `footer` slot for custom footer actions

The modal header renders only if you set the `header` attribute to a non-empty string. The modal footer renders only if you set the `footer` slot.

This example creates a simple modal with a header, body, and footer.

<!-- prettier-ignore-start -->
```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>
```
<!-- prettier-ignore-end -->

## Design

`lightning-quick-action-panel` implements the modal blueprint in the Salesforce Lightning Design System (SLDS). The modal adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                            | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Modals](https://v1.lightningdesignsystem.com/components/modals/) | [Modals](https://www.lightningdesignsystem.com/components/modals/)                                              |
| **For Use In** | Lightning Experience                                              | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create A Form in the Modal Body

You can create a form for the modal in one of several ways.

- Use the [lightning-record-edit-form component](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html)
- Use the [lightning-record-form](/docs/platform/lightning-component-reference/guide/lightning-record-form.html) component
  In both approaches, the cancel and submit buttons are nested within the component itself, so the footer slot isn't needed.

Alternatively, use `lightning-input` and `lightning-button` components. With this approach, use the `lightning-quick-action-panel` component's footer slot to contain the buttons. For more information, see [Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-quick-actions).

## Enable the Component as a Screen Action

To enable your component to be used in an LWC screen action, add the `lightning__RecordAction` target to the `component.js-meta.xml` configuration file. This target designates the component as a record page action. For more information about `lightning__RecordAction`, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags).

```js
<?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>
```

The `actionType` value can be `Action` or `ScreenAction`. It defaults to `ScreenAction`.
This configuration enables the component to appear under the **Lightning Web Component** menu in **Object Manager** so you can create a new action using the component. You must also add the action to the **Salesforce Mobile and Lightning Experience Actions** section of your page layout. For more information, see [Quick Actions](https://help.salesforce.com/articleView?id=platform.actions_overview.htm&type=5).

## Component Styling

`lightning-quick-action-panel` provides a consistent UI for your custom screen action, matching the UI for standard Salesforce and Aura Lightning quick actions.

This component implements the standard scrolling logic for Salesforce modals. When the text content reaches the maximum height, the header and footer remain fixed, and only the body content scrolls.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding around the content of the modal body.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-quick-action-panel header="My action">
        <div class="slds-p-around_large">Hello!</div>
    </lightning-quick-action-panel>
</template>
```
<!-- prettier-ignore-end -->

Similarly, add a utility class such as `slds-m-left_x-small` to your `lightning-button` component in the footer for uniform spacing.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

This component uses SLDS styling. If you want a fully customized component and action modal, create your own component markup and styling. Provide your markup without using `lightning-quick-action-panel` in the HTML template and include the configuration file as described in the [Enable the Component as a Screen Action](#enable-the-component-as-a-screen-action) section.

You can also create a custom action that directly executes your code without any UI, known as a _headless action_. For more information, see [Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-quick-actions).

The `lightning-record-form` component provides another way to create a form in the modal body.

To create links in the component that navigate to pages, records, or lists in Lightning Experience, use the [navigation service](/docs/platform/lightning-component-reference/guide/lightning-navigation.html).

## Accessibility

The modal window renders with `role="dialog"` and `aria-modal="true"`. A modal dialog traps focus.
When the modal opens, a user can't interact with the content behind the modal until they close the dialog.
The viewport behind the modal is marked with `aria-hidden="true"`, which prevents assistive technology from reading out the inactive content.

To close the modal, press the Esc key or click the X close button. Closing the modal moves focus back to the element that triggered the modal to open.

Press the Tab key to navigate through the focusable elements on the modal. Focus returns to the first focusable element at the top of modal, which is the X close button.
Press the Shift+Tab keys at the top of modal to return focus back to the last focusable element at the bottom of the modal.

## See Also

[Work with Records using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro)

[Configure a Component for Quick Actions](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-quick-actions)

[_Salesforce Help_: Quick Actions](https://help.salesforce.com/articleView?id=platform.actions_overview.htm&type=5)


:::::

:::::tab
::component-specification{component="quickActionPanel" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=3df83185b5696d47231f92dddace6dff5f86b74351b3fcd4625dbd8f5625541a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/radioGroup/lightning-radio-group.md -->


# Radio Group

**`lightning-radio-group`**

A radio button group that can have a single option selected.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="radioGroup" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-radio-group` component represents a group of radio buttons that permit only
one button for selection at a time. The component renders radio button `<input>` elements
and assigns the same value to the `name` attribute for each element. The common
`name` attribute joins the elements in a group. If you select any radio button in that
group, any previously selected button in the group is deselected.

If you specify the `required` attribute, at least one radio button must be selected.
When a user interacts with the radio button group and doesn't make a selection, an
error message appears.

If you specify the `disabled` attribute, you can't interact with the radio buttons.

**note:** Setting the `name` attribute in `lightning-radio-group` isn't recommended.
The component automatically generates a unique value for `name` if none is provided. The generated value ensures a common name for the `<input>` elements rendered for the radio button group, and is unique on the page. See [Use Multiple Radio Groups on a Page](#use-multiple-radio-groups-on-a-page).

## Design

`lightning-radio-group` implements the radio button blueprint in the Salesforce Lightning Design System (SLDS). The radio button adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Radio Button](https://v1.lightningdesignsystem.com/components/radio-group/)                                                          | [Radio Button](https://www.lightningdesignsystem.com/components/radio-group/)                                   |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

This example creates a radio button group with two options and `option1` is selected
by default. One radio button must be selected as the `required` attribute is
specified.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-radio-group
        label="Radio Button Group"
        options={options}
        value={value}
        onchange={handleChange}
        required
    >
    </lightning-radio-group>
</template>
```
<!-- prettier-ignore-end -->

You can check which values are selected by using the `value` attribute.
To retrieve the values when the selection is changed, use the `onchange` event handler and call
`event.detail.value`.

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  options = [
    { label: "Ross", value: "option1" },
    { label: "Rachel", value: "option2" },
  ];

  // Select option1 by default
  value = "option1";

  handleChange(event) {
    const selectedOption = event.detail.value;
    console.log("Option selected with value: " + selectedOption);
  }
}
```

To create radio buttons, pass in these properties to the `options` attribute.

| Property | Type   | Description                                                        |
| -------- | ------ | ------------------------------------------------------------------ |
| label    | string | The text that displays next to a radio button.                     |
| value    | string | The string that's used to identify which radio button is selected. |

## Input Validation

A radio group that's disabled is always valid. If the radio group is marked required and no option is selected, after you remove focus from the radio group an error message is displayed.

You can override the default message using `message-when-value-missing` when a radio group is required and no option is selected. This message is displayed when you remove focus from the radio group.

<!-- prettier-ignore-start -->
```html
<form onsubmit={handleSubmit}>
    <lightning-radio-group name="radioGroup"
        label="Will you be attending the event?"
        options={options}
        value={value}
        type="radio"
        lwc:ref="radiogroup"
        message-when-value-missing="Select an option"
        required></lightning-radio-group>
    <lightning-button variant="brand" label="Submit" onclick={handleSubmit} type="submit"></lightning-button>
</form>
```
<!-- prettier-ignore-end -->

To programmatically display error messages on invalid fields, use the `reportValidity()` method. This method returns false if the input is invalid.

For custom error messages, display the message using `setCustomValidity()` and `reportValidity()`. For more information, see the [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

```javascript
import { LightningElement } from 'lwc';
export default class ValidationExample extends LightningElement {

  value = '';
  get options() {
    return [
      { label: 'Yes', value: 'yes' },
      { label: 'No', value: 'no' },
    ];
  }

  handleSubmit(e) {
    const allValid = this.refs.radiogroup.reportValidity();
    if (!allValid) {
      e.preventDefault();
      this.refs.radiogroup.setCustomValidity("Please select an option");
      this.refs.radiogroup.showHelpMessageIfInvalid();
    }
  }
```

If you're creating a form for Salesforce record data, we recommend using [`lightning-record-form`](/docs/platform/lightning-component-reference/guide/lightning-record-form.html), [`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html), or [`lightning-record-view-form`](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html). The record form components are automatically wired up to your record data, labels, and field-level help text. For more information, see [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro).

## Use Multiple Radio Groups on a Page

If multiple `lightning-radio-group` instances on a page or across Salesforce app console tabs share a `name` attribute, their rendered `<input>` elements also share the same selection scope. Selecting an option in any single group clears active selections in the remaining groups.

To keep radio group selections independent on the same page or across tabs, choose one of these approaches:

- Omit the `name` attribute to enable the component to automatically generate a unique name on each instance.
- Enclose each `lightning-radio-group` component in a `<form>` element and provide your own value for `name`. This solution isolates the scope so you can reuse custom `name` values without causing selection conflicts across radio groups.

## Component Styling

Use a combination of variants and utility classes to customize the radio group.

Set `type="button"` to create a component that implements the
[radio button group](https://v1.lightningdesignsystem.com/components/radio-button-group/) blueprint in SLDS.

### Variants

Use the `variant` attribute with one of these values to change the appearance of the radio group.

- `label-hidden` hides the radio group label but makes it available to assistive technology. This variant doesn’t hide the option labels.
- `label-inline` horizontally aligns the label and radio group.
- `label-stacked` places the label above the radio group.
- `standard` is the default variant, which displays the radio group label above the options.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a margin around the radio group using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-radio-group
    label="Radio Group"
    options={options}
    value={value}
    class="slds-m-around_x-small"
>
</lightning-radio-group>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Accessibility

The radio group is nested in a `fieldset` element that contains a `legend`
element. The legend contains the `label` value. The `fieldset` element enables
grouping of related radio buttons to facilitate tabbing navigation and speech
navigation for accessibility purposes. Similarly, the `legend` element
improves accessibility by assigning a caption to the `fieldset`.


:::::

:::::tab
::component-specification{component="radioGroup" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=baaf2b08feba7cdfd13e524333f17b1ba78e5bca05f9d8f8b7c2e1ed9927875a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/range/lightning-range.md -->


# Range

**`lightning-input`**
_type="range"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="range" model="lwc" namespace="lightning"}


:::::

:::::tab

A slider control for entering a number within a given range. When working with numerical input, you
can use attributes like `max`, `min`, and `step`.

The attributes `maxlength`, `minlength`, and `pattern` can't be used with `range` type because they're for string data.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="range" label="Number" min="0" max="10">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

The `lightning-input` component of `type="range"` doesn't implement the Salesforce Lightning Design System (SLDS). To render an `<input>` element of `type="range"` that implements SLDS, use the [`lightning-slider` component](/docs/platform/lightning-component-reference/guide/lightning-slider.html) instead.

## Usage

Use the `range` type input field if the control's exact value isn't important.
The default value is halfway between the minimum and maximum values. No pattern validation is available for this type.
Consider these default values.

- The default `min` value is 0.
- The default `max` value is 100.
- The default `step` value is 1.

## Input Validation

To ensure a value is provided, use the `required` attribute. Use `min`, `max`, and `step` attributes to constrain the allowed values. You can also programmatically validate the input using the validity API.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="range"
    label="Volume Level"
    min="0"
    max="100"
    step="5"
    required
    lwc:ref="volumeRange"
    message-when-value-missing="Please set a volume level"
    message-when-range-underflow="Volume must be at least 0"
    message-when-range-overflow="Volume cannot exceed 100"
    message-when-step-mismatch="Volume must be in increments of 5"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the range input, check its validity using the `checkValidity()` method or access the `value` property. If the value isn't valid, the `reportValidity()` method shows the error message below range input.

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

export default class RangeValidation extends LightningElement {
  handleSubmit() {
    const rangeInput = this.refs.volumeRange;
    console.log(rangeInput.validity.valid); // Returns true or false
    if (!rangeInput.checkValidity()) {
      rangeInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const volumeLevel = rangeInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `range` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `rangeOverflow` - Indicates that the value is greater than the specified `max` attribute
- `rangeUnderflow` - Indicates that the value is less than the specified `min` attribute
- `stepMismatch` - Indicates that the value doesn't match the specified `step` attribute
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the range slider.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the range slider and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the range slider and the help tooltip.

If the range slider fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

Use these keys for keyboard navigation on the range slider.

- Left and Right arrow keys: Increments the value by the step amount. Defaults to 1.
- Up and Down arrow keys: Decrements the value by the step amount. Defaults to 1.
- Home and End keys: Moves the slider to the min or max value.
- Page Up and Page Down keys: Moves the slider by a larger increment, if supported by the browser or OS.

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=346687ce85e477f884f336308baaadd9be66f867df60ca95748bb8d699d912e2 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/recordEditForm/lightning-record-edit-form.md -->

# Record Edit Form

**`lightning-record-edit-form`**

Represents a record edit layout that displays one or more fields, provided by lightning-input-field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning-record-edit-form` component to create a form that's used to add a Salesforce record or update fields in an existing record on an object. The component displays fields with their labels and the current values, and enables you to edit their values.

![Record edit form with Name and Email fields](https://developer.salesforce.com/media/components/record-edit-form-basic.jpg '{"class": "image-lg", "title": "Record Edit Form"}')

`lightning-record-edit-form` supports the following features.

- Editing a record's specified fields, given the record ID.
- Creating a record by using specified fields.
- Customizing the form layout
- Custom rendering of record data

If you don't require customizations, use [`lightning-record-form`](/docs/platform/lightning-component-reference/guide/lightning-record-form.html) instead.

To specify editable fields, use `lightning-input-field` components inside `lightning-record-edit-form` component. See the **Editing a Record** section.

To display record fields as read-only in `lightning-record-edit-form`, use `lightning-output-field` components to specify those fields. You can also use HTML and other components such as `lightning-formatted-name` to present non-editable content.

To display all fields as read-only, use the `lightning-record-form` component with `mode="readonly"` or the `lightning-record-view-form` component instead of `lightning-record-edit-form`.

To understand the different use cases, see [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro).

## Design

`lightning-record-edit-form` implements the form element (edit mode) blueprint in the Salesforce Lightning Design System (SLDS). The form adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                              | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element (Edit Mode)](https://v1.lightningdesignsystem.com/components/form-element/#Edit-Mode) | [Form Element (Edit Mode)](https://www.lightningdesignsystem.com/components/form-element/#Edit-Mode)            |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App                               | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

`lightning-record-edit-form` implements Lightning Data Service and doesn't require additional Apex controllers to create or update record data. This component also takes care of field-level security and sharing for you, so users see only the data they have access to. For more information, see [Lightning Data Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-ui-api).

When possible, let `lightning-record-edit-form` load and manage the data for you as it implements Lightning Data Service. Using `lightning-record-edit-form` to create or update records with Apex controllers can lead to unexpected behaviors. Additionally, data provisioned by Apex isn’t managed and you must handle data refresh by invoking the Apex method again on your own.

To access raw record data or create a form that needs more customization than the `lightning-record-*-form` components allow, use Lightning Data Service wire adapters and functions, such as those from the `lightning/ui*Api` module.

You can use Apex if you are working with an object that's not supported by the User Interface API, or if you have to use a SOQL query to select certain records. See the **Supported Objects** section.

## Object API Name and Record ID

Each Salesforce record is associated with a Salesforce object. For example, a contact record is associated with the Contact object. Record IDs are created with prefixes that indicate the object. The `lightning-record-edit-form` component requires you to specify the `object-api-name` attribute to establish the relationship between a record and an object. The object API name must be appropriate for the use of the component. For example, if you include `lightning-record-edit-form` on a record page for an account, set `object-api-name="Account"`. The component submits changes only if the record ID agrees with the specified object API name. If there's a mismatch, and the component includes `lightning-messages`, users see an error indicating the API name is invalid.

## Specify Object API and Field Names

We strongly recommend importing references to objects and fields by using the `@salesforce/schema` syntax especially when you plan to distribute your component as a managed package.

For example, create a form that enables users to edit the name field on a contact record page.

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form
    object-api-name={objectApiName}
    record-id={recordId}
>
    <lightning-input-field field-name={nameField}> </lightning-input-field>
    <div class="slds-var-m-top_medium">
        <lightning-button variant="brand" type="submit" label="Save">
        </lightning-button>
    </div>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

To specify an editable field in the form, use the `lightning-input-field` component and set the `field-name` to the API name of the field. Labels for certain fields can differ from those on a standard record page. For example, the `Name` field on the opportunity object displays "Name" instead of "Opportunity Name" while the `Name` field name on the account object uses "Account Name".

Although you can set the field name directly with the `field-name` attribute, we recommend that you import a reference to the name field. In this example, the form uses the object API name and record ID of the record page it's placed in.

```js
import { LightningElement, api } from "lwc";
import NAME_FIELD from "@salesforce/schema/Contact.Name";

export default class RecordEditFormExample extends LightningElement {
  // Expose a field to make it available in the template
  nameField = NAME_FIELD;

  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;
}
```

To use your component in a managed package with your custom object, import the object using your namespace, for example, `@salesforce/schema/namespace__object`.

```js
import MY_CUSTOM_OBJECT from "@salesforce/schema/namespace__Custom_object__c";
```

When you import the references, 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. For more information, see [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about#import-references-to-salesforce-objects-and-fields).

For simplicity, the object API name and fields in the examples below are hardcoded in the templates. Note that passing in the object and fields using strings doesn’t provide compile-time validation. Use the `@salesforce/schema` imports to ensure the validity of your objects and fields.

## Supported Objects

This component doesn't support all Salesforce standard objects. This limitation also applies to a record
that references a field that belongs to an unsupported object.

This component supports the Task object but `Task.IsRecurrence` and `Task.IsReminderSet` fields don't render even when requested.

This component supports the Event object but `Event.IsRecurrence`, `Event.IsRecurrence2`, and `Event.IsReminderSet` fields don't render even when requested.

External objects are not supported. The `InformalName` field is not supported for editing.

For a list of supported 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).

If you’re working with an unsupported object or if you use SOQL to query certain records, create your own UI and use Apex to work with Salesforce data. For more information, see [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines) in the Lightning Web Components Developer Guide.

## Edit a Record

To enable record editing, pass in the ID of the record and the corresponding
object API name to be edited. Specify the fields that you want to include in the
record edit layout by using `lightning-input-field`. For more information, see the
[`lightning-input-field`](/docs/platform/lightning-component-reference/guide/lightning-input-field.html) documentation.

Include a `lightning-button` component with `type="submit"`. When you press the Enter key or click the button, it validates the fields and submits the values.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id="003XXXXXXXXXXXXXXX"
        object-api-name="Contact"
    >
        <lightning-messages> </lightning-messages>
        <lightning-output-field field-name="AccountId">
        </lightning-output-field>
        <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-button
            class="slds-m-top_small"
            variant="brand"
            type="submit"
            name="update"
            label="Update"
        >
        </lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

## Create a Record

To enable record creation, pass in the object API name for the record to be
created. Specify the fields that you want to include in the record create layout
by using `lightning-input-field` components. For more information, see the
[`lightning-input-field`](/docs/platform/lightning-component-reference/guide/lightning-input-field.html) documentation.

Include a `lightning-button` component with `type="submit"`. When you press the Enter key or click the button, it validates the fields and submits the values.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form object-api-name="Contact">
        <lightning-messages> </lightning-messages>
        <lightning-input-field field-name="Name"> </lightning-input-field>
        <lightning-button
            class="slds-m-top_small"
            type="submit"
            label="Create new"
        >
        </lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

## Submit Form Values with a Button

`lightning-record-edit-form` renders the fields within the HTML `form` element and uses a button for form submission.
Customizing the `form` element for form submission is not supported.
We recommend that you use `lightning-button` with `type="submit"` as shown in the previous sections.
The default `type` on `lightning-button` is `button`, which does nothing unless you include an `onclick` handler.
If you use an HTML `button` element within `lightning-record-edit-form`, the default is `type="submit"`.

When you submit the form, the component fires the custom events in this order.

- `click` if you use the `onclick` event handler on the button
- `submit`
- `success` or `error`

You can edit the field values programmatically by using the `onsubmit` event handler or selectively handle any of the custom events. See [Override Default Behaviors](#override-default-behaviors).

## Error Handling

`lightning-record-edit-form` handles field-level validation errors and Lightning Data Service errors automatically.
For example, entering an invalid email format for the Email field
results in an error message when you move focus away from the field. Similarly, a
required field like the Last Name field shows an error message when you leave
the field blank and move focus away.

A Lightning Data Service error is returned when a resource becomes inaccessible on the server or an invalid record ID is passed in, for example. To display the error message automatically, include `lightning-messages` immediately before or after the `lightning-input-field` components. For more information, see [Override Default Behaviors](#override-default-behaviors).

`lightning-record-edit-form` also verifies data input based on your validation rules. The form submits and saves data input only if all data in the fields are valid. The form clears validation rule errors when an `onchange` event is fired on the overall form, and also when you update a field with a validation rule error.

If a single field has multiple validation errors, the form shows only the first error on the field. Similarly, if a submitted form has multiple errors, the form shows only the first error encountered. When you correct the error, the next error is shown.

We recommend using custom validation rules to verify data input instead of implementing client-side validation errors. A validation rule can contain a formula or expression that evaluates the data in one or more fields. You can show an error message on an invalid field. See [Validation Rules](https://help.salesforce.com/articleView?id=fields_about_field_validation.htm) in Salesforce Help for more information.

## Return the Record ID

A record ID is generated when a record is created successfully. To return the ID, use the `onsuccess` handler.
This example shows an `Id` field that's populated when you create an account by providing an account name and pressing the **Create Account** button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        object-api-name="Account"
        onsuccess={handleSuccess}
    >
        <lightning-messages></lightning-messages>
        <div class="slds-m-around_medium">
            <lightning-input-field
                field-name="Id"
                value={accountId}
            ></lightning-input-field>
            <lightning-input-field field-name="Name"></lightning-input-field>
            <div class="slds-m-top_medium">
                <lightning-button
                    variant="brand"
                    type="submit"
                    name="save"
                    label="Create Account"
                >
                </lightning-button>
            </div>
        </div>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

The record ID of the newly created account is assigned to the `accountId` property.

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

export default class createRecordForm extends LightningElement {
  accountId;
  handleSuccess(event) {
    this.accountId = event.detail.id;
  }
}
```

## Create Forms Based on a Record Type

If your org uses record types, picklist fields display values according to
your record types. You must provide a record type ID using the `record-type-id`
attribute 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 a list of record type IDs in your org, use the `getObjectInfo` wire adapter. For more information, see the [getObjectInfo documentation](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info).

Passing in a record type as a field on this component is not supported.

## Use Multiple Columns

To create a multi-column layout for your record edit layout, use the Grid
utility classes in Lightning Design System. This example creates a two-column
layout.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id="003XXXXXXXXXXXXXXX"
        object-api-name="Contact"
    >
        <div class="slds-grid">
            <div class="slds-col slds-size_1-of-2">
                <!-- Your lightning-input-field components here -->
            </div>
            <div class="slds-col slds-size_1-of-2">
                <!-- More lightning-input-field components here -->
            </div>
        </div>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

## Prepopulate Field Values

To provide a custom field value when the form displays, use the `value` attribute on `lightning-input-field`. If you're providing a record ID, the value returned by the record on load doesn’t override this custom value.

This example shows a form with a custom value for the account name field.
The form creates a new account record when the button is clicked.

<!-- prettier-ignore-start -->
```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>
```
<!-- prettier-ignore-end -->

This example displays a form with a custom value for the account name field.
The form updates the account record when the button is clicked.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id={recordId}
        object-api-name={objectApiName}
    >
        <lightning-input-field
            field-name="Name"
            value="My Field Value"
        ></lightning-input-field>
        <lightning-button
            class="slds-m-top_small"
            type="submit"
            label="Update record"
        ></lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

Define the `recordId` and the `objectApiName` in your JavaScript code. The component inherits the record ID and object API name from the record page it's placed on.

```javascript
import { LightningElement, api } from "lwc";
export default class FieldValueExample extends LightningElement {
  @api recordId;
  @api objectApiName;
}
```

To set the value programmatically when the form loads, provide your value in JavaScript. This example sets the value using the `myValue` property. You can set this value programmatically at a later time, as shown by the `onclick` event handler, which calls the `overrideValue` method.

<!-- prettier-ignore-start -->
```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>
```
<!-- prettier-ignore-end -->

The `myValue` property reassigned a new value when the **Override Value** button is clicked.

```javascript
import { LightningElement, api } from "lwc";
export default class FieldValueCreateExample extends LightningElement {
  myValue = "My Account Name";
  overrideValue(event) {
    this.myValue = "My New Name";
  }
}
```

## Form Display Density

In the Salesforce user interface, the Display Density setting lets users choose how densely the content is displayed. The Comfy density shows labels on top of the fields and more space between page elements. Compact density shows labels next to the fields and less space between page elements.

The record form components, `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form`,
handle form density in similar ways. The `density` attribute is set to `auto` by default for all record form components.

Display density is supported for `lightning-input-field` and `lightning-output-field` within the form; display density is not supported for custom components within the form.

With `auto` density:

- Record form components detect the Display Density setting and the width of the form's container to determine label position. The record form components don't change the space between elements, however.
- If your Salesforce density setting is Comfy, the fields always display with their labels above them.
- If your Salesforce density setting is Compact, the fields initially display with their labels next to them. If you resize the form container below a certain width or use the form in a narrow container, the fields appear with their labels above them. This behavior is similar to how other elements behave in Lightning Experience when Compact density is enabled. The record form components use the same width settings to determine when to switch the display density.
- If a record form component doesn't detect the Salesforce density setting, the fields appear with their labels next to them. If you resize the form container to a narrow width, the fields appear with their labels above them.

Detecting the user's density setting is only supported in Lightning Experience. When a record form component runs outside Lightning Experience, and density is set to `auto`, the fields appear with their labels next to them, and switch to labels above the fields when in a narrow container.

If you specify a variant for `lightning-input-field` or `lightning-output-field`, the variant overrides the display density for that field.

## Set the Form Display Density

To display a record form with a particular density, set the `density` attribute to one of these values.

- `comfy` makes the form always display labels on top of fields and doesn't detect the user setting.
- `compact` makes the form display labels next to their fields and doesn't detect the user setting. However, the form switches to the comfy density if the form is narrowed to the width that triggers the automatic change. To reduce the whitespace 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`.
- `auto` makes the form use the default behavior described in **Form Display Density**.

## Override Default Behaviors

To customize the behavior of your form when it loads or when data is
submitted, use the `onload` and `onsubmit` attributes to specify event
handlers. If you capture the submit event and submit the form
programmatically, use `event.preventDefault()` to cancel the default behavior
of the event. This prevents a duplicate form submission.

Errors are automatically handled. To customize the behavior of the form when
it encounters an error on submission or when data is submitted successfully,
use the `onerror` and `onsuccess` attributes to specify event handlers.

Here are some example event handlers for `onsubmit` and `onsuccess`.

```javascript
handleSubmit(event){
   event.preventDefault();       // stop the form from submitting
   const fields = event.detail.fields;
   fields.Street = '32 Prince Street';
   this.template.querySelector('lightning-record-edit-form').submit(fields);
}
handleSucess(event){
   const updatedRecord = event.detail.id;
   console.log('onsuccess: ', updatedRecord);
}
```

To see all the response data:

```javascript
handleSuccess(event){
    const payload = event.detail;
    console.log(JSON.stringify(payload));
}
```

## Reset the Form

To reset the form fields to their initial values, use the `reset()` method on `lightning-input-field`.

We recommend creating a button that reverts the field values to their initial values using `lightning-button`. The default `type` for `lightning-button` is `button`, which does nothing unless you include an `onclick` handler.

If you use an HTML `button` element within `lightning-record-edit-form` to perform an action such as resetting the field values, specify `type="button"`.
By default, an HTML `button` element uses `type="submit"` when it's rendered in an HTML `form` element. Additionally, using `type="reset"` on a button deletes the form values and does not preserve the intial values.

This example creates a form with two fields, followed by Cancel and Save Record buttons. When you click the Cancel button, the `handleReset` method resets the fields to their initial values. Add this example to an account record page to inherit its record ID.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id={recordId}
        object-api-name={objectApiName}
    >
        <lightning-input-field field-name="Name"></lightning-input-field>
        <lightning-input-field field-name="Industry"></lightning-input-field>
        <div class="slds-m-top_medium">
            <lightning-button
                class="slds-m-top_small"
                label="Cancel"
                onclick={handleReset}
            ></lightning-button>
            <lightning-button
                class="slds-m-top_small"
                type="submit"
                label="Save Record"
            ></lightning-button>
        </div> </lightning-record-edit-form
></template>
```
<!-- prettier-ignore-end -->

Call the `reset()` method on each field.

```javascript
handleReset(event) {
   const inputFields = this.template.querySelectorAll(
       'lightning-input-field'
   );
   if (inputFields) {
       inputFields.forEach(field => {
           field.reset();
       });
   }
}
```

## Reset Individual Fields

To reset the value of a specific field, first find the fields to reset using the `class` or `name` attribute.

This example uses the `class` attribute to assign a unique identifier to the Name compound field and Title field. It assumes that you created a custom class `contactName`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id={recordId}
        object-api-name={objectApiName}
    >
        <!--Other fields here -->
        <lightning-input-field field-name="Name" class="contactName">
        </lightning-input-field>
        <lightning-input-field field-name="Title" class="contactName">
        </lightning-input-field>
        <lightning-button
            class="slds-m-top_small"
            label="Cancel"
            onclick={handleReset}
        ></lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

Use `querySelectorAll` to query all fields matching the `.contactName` class.

```javascript
handleReset(event) {
    const inputFields = this.template.querySelectorAll(
        '.contactName'
    );
    if (inputFields) {
        inputFields.forEach(field => {
            field.reset();
        });
    }
}
```

If you are not using a custom class, use `name` instead. This example uses the `name` attribute to assign an identifier for the field to be reset
to its initial value.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-edit-form
        record-id={recordId}
        object-api-name={objectApiName}
    >
        <!--Other fields here -->
        <lightning-input-field name="email" field-name="Email">
        </lightning-input-field>
        <lightning-button
            class="slds-m-top_small"
            label="Reset Email"
            onclick={handleReset}
        >
        </lightning-button>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

You can use the same `name` attribute values on multiple fields. Match the field name in the `forEach` block to trigger a reset on the email field.

```javascript
handleReset(event) {
    const inputFields = this.template.querySelectorAll(
        'lightning-input-field'
    );
    if (inputFields) {
        inputFields.forEach(field => {
            if(field.name === "email") {
                field.reset();
            }
        });
    }
}
```

## Display Fields Conditionally

To display a field conditionally, use the `if:true|false` directive.
This example displays or hides the `Name` and `Industry` account fields when you select or unselect a checkbox.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox"
        label="Show/Hide"
        checked={showFields}
        onchange={toggleFields}
    >
    </lightning-input>

    <lightning-record-edit-form
        record-id={recordId}
        object-api-name={objectApiName}
        density="compact"
    >
        <template if:true={showFields}>
            <lightning-input-field field-name="Name"></lightning-input-field>
            <lightning-input-field field-name="Industry">
            </lightning-input-field>
        </template>
    </lightning-record-edit-form>
</template>
```
<!-- prettier-ignore-end -->

The checkbox toggles between hiding and showing the fields using the `onchange` event handler.

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

export default class RecordEditFormConditional extends LightningElement {
  @api recordId;
  @api objectApiName;
  showFields = true;

  toggleFields() {
    this.showFields = !this.showFields;
  }
}
```

## Work with Person Accounts

A person account is a record type on the account object. It combines certain fields from the account and contact object into a single record. To use person accounts in your org, you must enable the Person Accounts setting first. After Person Accounts is enabled, it can’t be disabled. For more information, see [Enable Person Accounts](https://help.salesforce.com/articleView?id=sales.account_person_enable.htm).

To access person account fields, use the account object with `object-api-name="Account"`.

Specify the fields using the field names listed in the **IsPersonAccountFields** section for the Account object in the [Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm).

The fields that begin with `Person` are the fields from the contact object.

For standard fields on the contact object, use `Person<ContactFieldName>`. For example, use `field-name="PersonMobilePhone"` for the `MobilePhone` field on the contact object.

For custom fields on the account object, use `CustomFieldName__c` as usual.

For custom fields on the contact object, use `CustomFieldName__pc`.

This example creates a form to update a person account record.

<!-- prettier-ignore-start -->
```html
<lightning-record-edit-form record-id={recordId} object-api-name="Account">
    <!-- Name field on account -->
    <lightning-input-field field-name="Name"> </lightning-input-field>

    <!-- Nickname__c field on account -->
    <lightning-input-field field-name="Nickname__c"> </lightning-input-field>

    <!-- MobilePhone field on contact -->
    <lightning-input-field field-name="PersonMobilePhone">
    </lightning-input-field>

    <!-- Contact_Nickname__c field on contact -->
    <lightning-input-field field-name="Contact_Nickname__pc">
    </lightning-input-field>
    <lightning-button
        class="slds-m-top_small"
        variant="brand"
        type="submit"
        label="Update"
    >
    </lightning-button>
</lightning-record-edit-form>
```
<!-- prettier-ignore-end -->

For more information, see [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about).

## Usage Considerations

Multiple currencies aren't supported. If you enabled Activate Multiple Currencies in your org, `lightning-record-edit-form` displays currency fields using the corporate currency, even when the default currency of a record is different. For more information, see [Manage Multiple Currencies](https://help.salesforce.com/articleView?id=sales.admin_currency.htm&type=5).

Nesting `lightning-record-edit-form` in another instance of the component, or nesting it in `lightning-record-form` or `lightning-record-view-form` is not supported.

The form displays read-only input fields the same as output fields, without borders or gray backgrounds, unlike disabled input fields.

The `Id` field for a record ID displays as read-only even when specified with `lightning-input-field`.

Formula fields are automatically calculated, and displayed read-only on record forms. Formula fields always display the calculated value.

For more information about supported field types such as name fields and lookup fields, see the
[`lightning-input-field`](/docs/platform/lightning-component-reference/guide/lightning-input-field.html) documentation.

Use `lightning-input-field` only as a direct child of `lightning-record-edit-form`. Don't include `lightning-input-field` components in a template that an aura component composes.

The form displays read-only input fields the same as output fields, without borders or gray backgrounds, unlike disabled input fields.

Consider using the [`lightning-record-form`](/docs/platform/lightning-component-reference/guide/lightning-record-form.html)
component to create record forms more easily.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`error`**

The event fired when the record edit form returns a server-side error.

Use the `event.detail` property to return the error.

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                         |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| message   | string | General description of error.                                                                                                                                                                                                                                                                                                       |
| detail    | object | Description of error details, if any.                                                                                                                                                                                                                                                                                               |
| output    | object | [Record exception errors](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_exception.htm#ui_api_responses_record_exception) with `errors` and `fieldErrors` properties. For example, to return the error details when a required field is missing, use `event.detail.output.fieldErrors`. |

To display your error messages in the form, we recommend using `lightning-messages` as shown in the examples. `lightning-messages` can be used without a custom `error` event handler.

Include `lightning-messages` immediately before or after the `lightning-input-field` components to automatically display the string that's returned by `message`, and the `detail` or `fieldErrors` message if it's available.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`load`**

The event fired when the record edit form loads record data.
If you load the fields dynamically, `load` is fired before the child elements of `lightning-record-edit-form` finish loading. Consider the [`connectedCallback()` lifecycle](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom) hook to perform initialization tasks. Alternatively, to load values or set properties dynamically, use a [getter and setter](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getters-setters) instead.

`load` is fired when the form gets new data from Lightning Data Service, which can be once or multiple times after the component is initialized. For example, the `load` event is fired when:

- The `record-id` value changes
- The `fields` list changes
- The form includes picklist fields
- The record type changes

If you require the `load` event to be called only once, write code to prevent it from running more than once.

Use the `event.detail` property to return the [record UI](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_ui.htm), and [picklist values](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_picklist_values.htm) if you include picklist fields in the form.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`submit`**

The event fired when the submit button is pressed. Client-side validation errors, if any, are displayed. The form is then submitted only when all fields in the form are valid. The form can be submitted only after it's loaded.

The `submit` event returns the following parameters.

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fields    | object | The editable fields that are provided for submission during a record create or edit. For example, if you include a `lightning-input-field` component with the `Name` field, `fields` returns `FirstName`, `LastName`, and `Salutation`. Read-only fields, such as the record ID, can't be changed in a form. If you include a read-only field in a form, it's not included in the `fields` object returned by the `onsubmit` event handler. |

The event properties are as follows.

| Property   | Value | Description                                                                |
| ---------- | ----- | -------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                     |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched. |

**`success`**

The event fired when the record data is updated successfully. The `load` event then fires to return the updated data.

Use the `event.detail` property to return the saved record. For more information, see the [User Interface API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm).

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-record-edit-form`, see the following components in the LWC Recipes repo.

- `c-record-edit-form-dynamic-contact`
- `c-record-edit-form-static-contact`

## See Also

[Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro)

[recordEditFormStaticContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordEditFormStaticContact) example in lwc-recipes repository

[recordEditFormDynamicContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordEditFormDynamicContact) example in lwc-recipes repository


:::::

:::::tab
::component-specification{component="recordEditForm" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=cc9cfe4454784951d09b3662594d7ac2b79eda73e4c80aa05d1cd96d627a75c2 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/recordForm/lightning-record-form.md -->

# Record Form

**`lightning-record-form`**

Creates an editable form or display form for a record.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta)

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning-record-form` component to quickly create forms to add,
view, or update a record.

Using this component to create record forms is
easier than building forms manually with `lightning-record-edit-form` or
`lightning-record-view-form`.

The `lightning-record-form` component switches between view and edit modes automatically when the user begins editing a field in a view form.

![Record view form with Name and Email fields](https://developer.salesforce.com/media/components/record-form-view.png '{"class": "image-lg", "title": "Record Edit Form"}')

When you click the edit icon on a field, the form becomes editable.

![Record view form with Name and Email fields](https://developer.salesforce.com/media/components/record-form-edit.jpg '{"class": "image-lg", "title": "Record Edit Form"}')

Additional features include:

- Provides Cancel and Save buttons automatically in edit forms
- Uses the object's default record layout with support for multiple columns
- Loads all fields in the object's compact or full layout, or only the fields you specify

`lightning-record-form` is less customizable. To customize the form layout or provide custom rendering of record data, use:

- [`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html) for adding or updating a record
- [`lightning-record-view-form`](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html) for viewing a record

The `object-api-name` attribute is always required, and the `record-id` is
required only when you’re editing or viewing a record.

## Design

`lightning-record-form` implements the form element (edit mode and view mode) blueprint in the Salesforce Lightning Design System (SLDS). The form adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                              | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element (Edit Mode)](https://v1.lightningdesignsystem.com/components/form-element/#Edit-Mode) | [Form Element (Edit Mode)](https://www.lightningdesignsystem.com/components/form-element/#Edit-Mode)            |
|                | [Form Element (View Mode)](https://v1.lightningdesignsystem.com/components/form-element/#View-Mode) | [Form Element (View Mode)](https://www.lightningdesignsystem.com/components/form-element/#View-Mode)            |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App                               | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

`lightning-record-form` implements Lightning Data Service and doesn't require additional Apex controllers to create or edit record data. It also takes care of field-level security and sharing for you, so users see only the data that they have access to. To access raw record data or create a form that needs more customization than the `lightning-record-*-form` components allow, use Lightning Data Service wire adapters and functions, such as those from the `lightning/ui*Api` module.

Each Salesforce record is associated with a Salesforce object. For example, a contact record is associated with the Contact object. Record IDs are created with prefixes that indicate the object. The `lightning-record-form` component requires you to specify the `object-api-name` attribute to establish the relationship between a record and an object. The object API name must be appropriate for the use of the component. For example, if you include `lightning-record-form` on a record page for an account, set `object-api-name="Account"`. The component submits changes only if the record ID is in agreement with the specified object API name. If there's a mismatch, users see an error indicating the API name is invalid.

## Specify Object API and Field Names

We strongly recommend importing references to objects and fields by using the `@salesforce/schema` syntax especially when you plan to distribute your component as a managed package.

For example, create a form that enables users to edit the name field on a contact record page.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    object-api-name={objectApiName}
    record-id={recordId}
    fields={fields}
>
</lightning-record-form>
```
<!-- prettier-ignore-end -->

Import a reference to the name field on the contact object. In this example, the form uses the object API name and record ID of the record page it's placed in.

```js
import { LightningElement, api } from "lwc";
import NAME_FIELD from "@salesforce/schema/Contact.Name";

export default class RecordFormExample extends LightningElement {
  // Expose a field to make it available in the template
  fields = [NAME_FIELD];

  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;
}
```

To use your component in a managed package with your custom object, import the object by using your namespace, for example, `@salesforce/schema/namespace__object`.

```js
import MY_CUSTOM_OBJECT from "@salesforce/schema/namespace__Custom_object__c";
```

When you import the references, 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. For more information, see [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about).

For simplicity, the object API name and fields in some examples below are hardcoded in the templates. Note that passing in the object and fields using strings doesn’t provide compile-time validation. Use the `@salesforce/schema` imports to ensure the validity of your objects and fields.

## Supported Objects

This component doesn't support all Salesforce standard objects. This limitation also applies to a record that references a field that belongs to an unsupported object.

This component supports the Task object but `Task.IsRecurrence` and `Task.IsReminderSet` fields don't render even when requested.

This component supports the Event object but `Event.IsRecurrence`, `Event.IsRecurrence2`, and `Event.IsReminderSet` fields don't render even when requested.

External objects are not supported. The `InformalName` field isn't supported for editing.

For a list of supported 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).

If you’re working with an unsupported object or if you use SOQL to query certain records, create your own UI and use Apex to work with Salesforce data. For more information, see [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines) in the Lightning Web Components Developer Guide.

## Modes

The component accepts a `mode` value that determines the user interaction
allowed for the form. The value for `mode` can be one of the following:

- `edit` - Creates an editable form to add a record or update an existing one. When updating an existing record, specify the `record-id`. Edit mode is the default when `record-id` is not provided, and shows a form to create new records.
- `view` - Creates a form to display a record that the user can also edit. The record fields each have an edit button. View mode is the default when `record-id` is provided.
- `readonly` - Creates a form to display a record without enabling edits. The form doesn't include any buttons.

## Specify Record Fields

For all modes, the component expects the `fields` attribute or the `layout-type` attribute.

Use the `fields` attribute to pass record fields as an array of strings.
The fields appear in the order you list them.

Use the `layout-type` attribute to specify a `Full` or `Compact` layout.
Layouts are typically defined (created and modified) by administrators. Specifying record data using `layout-type` loads the fields in the layout definition. All fields that have been assigned to the layout are loaded into the form. This behavior is the same as the [getRecordUi wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-record-ui) (deprecated). Retrieving a layout using an alternative wire adapter isn't currently supported.

To see the fields in the layout types in your org:

- `Full` - The full layout corresponds to the fields on the record detail page. From the management settings for the object that you want to edit, go to Page Layouts.
- `Compact` - The compact layout corresponds to the fields on the highlights panel at the top of the record. From the management settings for the object that you want to edit, go to Compact Layouts.

For more information, see [Page Layouts](https://help.salesforce.com/articleView?id=customize_layout.htm).

`lightning-record-form` renders a field as required only if the field is marked as required on the object. If a field is marked as required only on a page layout, the form doesn't render the field with the styling or validation for a required field.

To specify the field order, use `fields` without the `layout-type` attribute. We don't recommend using the `fields` attribute with the `layout-type` attribute as the display order of the fields can vary. Alternatively,
use the `lightning-record-edit-form` or `lightning-record-view-form` component to display a custom layout.

Fields that have a spanning relationship aren't supported by `lightning-record-form`. The fields specified must be associated with the same `object-api-name`. A field such as Contact.Account.Ownership is a cross-object reference between the Contact object and the Account object, and can't be displayed in the form.

## View a Record with Option to Edit Fields

To create a form that lets you view a record and optionally edit field values, use `mode="view"`.
Use `record-id` and `object-api-name` to pass the ID of the record and the corresponding object API name to be displayed.
Specify the fields using the `fields` attribute, or
`layout-type` attribute to display all the fields defined on the `Full` or `Compact` layout.

The view mode loads the form using output fields with inline editing enabled.
You can edit fields that are marked updateable in the User Interface API. If the user clicks an edit icon next to a field,
all fields that are updateable become editable, and the form displays Cancel and
Save buttons.

This example creates a form for an account record in view mode with fields from the full layout.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    record-id="001XXXXXXXXXXXXXXX"
    object-api-name="Account"
    layout-type="Full"
    mode="view"
>
</lightning-record-form>
```
<!-- prettier-ignore-end -->

## View a Record with Read-Only Fields

To create a form that lets you view a record but not edit its field values, use `mode="readonly"`.
Use `record-id` and `object-api-name` to pass the ID of the record and the corresponding object API name to be displayed.
Specify the fields using the `fields`
attribute, or `layout-type` attribute to include all the fields defined on the
`Full` or `Compact` layout.

The readonly mode loads the form with output fields only, and without Cancel
or Save buttons.

This example creates a form for an account record in readonly mode with a single column and fields from the compact layout.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    record-id="001XXXXXXXXXXXXXXX"
    object-api-name="Account"
    layout-type="Compact"
    columns="1"
    mode="readonly"
>
</lightning-record-form>
```
<!-- prettier-ignore-end -->

## Edit a Record

To create a form that lets you edit a record, specify the `mode="edit"` attribute. Use `record-id` and `object-api-name` to pass the ID of the record and the corresponding object API name to be edited. Specify the fields using the `fields` attribute, or
`layout-type` attribute to load all the fields defined on the `Full` or `Compact` layout.

When `record-id` is passed, edit mode loads the form with input fields
displaying the specified record's field values. The form also displays Cancel
and Save buttons.

This example creates an editable two-column form for an account record using the compact layout. Place the form on an account record page to inherit its `record-id` and `object-api-name` properties. The `onsubmit` attribute specifies an action to override the handler for the submit.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    record-id={recordId}
    object-api-name={objectApiName}
    fields={fields}
    columns="2"
    mode="edit"
    onsubmit={handleSubmit}
>
</lightning-record-form>
```
<!-- prettier-ignore-end -->

Define an array of field names in your JavaScript using the `fields` property.

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

import NAME_FIELD from "@salesforce/schema/Account.Name";
import REVENUE_FIELD from "@salesforce/schema/Account.AnnualRevenue";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class RecordFormEditExample extends LightningElement {
  // The record page provides recordId and objectApiName
  @api recordId;
  @api objectApiName;

  fields = [NAME_FIELD, REVENUE_FIELD, INDUSTRY_FIELD];

  handleSubmit(event) {
    event.preventDefault(); // stop the form from submitting
    const fields = event.detail.fields;
    fields.LastName = "My Custom Last Name"; // modify a field
    this.template.querySelector("lightning-record-form").submit(fields);
  }
}
```

## Create a Record

To create a form that lets you create a record, do not specify a `record-id`.
The form loads in edit mode by default when you don't specify a record ID.
Use `object-api-name` to pass the object API name for the record to be created. Specify the fields you want using the
`fields` attribute, or use `layout-type="Full"` to load all fields in the full layout.

The compact layout cannot be used for creating records. If you specify `layout-type="Compact"`,
the full layout is shown. If you specify the `fields` attribute, be sure
to include any fields that are designated as required for the object's records.

Because no record ID is passed, edit mode loads the form with input fields that
aren't populated with field data. The form displays Cancel and Save buttons.

This example displays a form with the required name field and several others for creating account records. Place the form on an account record page to inherit its `object-api-name` property. The `onsuccess` attribute specifies an action to override the handler when an account is successfully created.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    object-api-name={objectApiName}
    fields={fields}
    onsuccess={handleSuccess}
>
</lightning-record-form>
```
<!-- prettier-ignore-end -->

When an account is successfully edited or created, a toast message is displayed using the
`ShowToastEvent` event, which is dispatched by the `handleSuccess` event handler. The `onsuccess` event returns the [record](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm) object, including the ID of the newly created account.

```javascript
import { LightningElement, api } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";

import NAME_FIELD from "@salesforce/schema/Account.Name";
import REVENUE_FIELD from "@salesforce/schema/Account.AnnualRevenue";
import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";

export default class RecordFormCreateExample extends LightningElement {
  // objectApiName is "Account" when this component is placed on an account record page
  @api objectApiName;

  fields = [NAME_FIELD, REVENUE_FIELD, INDUSTRY_FIELD];

  handleSuccess(event) {
    const evt = new ShowToastEvent({
      title: "Account created",
      message: "Record ID: " + event.detail.id,
      variant: "success",
    });
    this.dispatchEvent(evt);
  }
}
```

## Prepopulate Field Values

`lightning-record-form` does not support prepopulating of field values when the form loads.
To create a form that displays custom field values, use the `lightning-record-edit-form` component.

## Display Forms Based on a Record Type

If your org uses record types, picklist fields display values according to
your record types. You must provide a record type ID using the `record-type-id`
attribute 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 a list of record type IDs in your org, use the `getObjectInfo` wire adapter.
For more information, see the [getObjectInfo documentation](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-object-info).

## Form Display Density

In the Salesforce user interface, the Display Density setting lets users choose how densely the content is displayed. The Comfy density shows labels on top of the fields and more space between page elements. Compact density shows labels next to the fields and less space between page elements.

The record form components, `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form`,
handle form density in similar ways. The `density` attribute is set to `auto` by default for all record form components.

Display density is supported for `lightning-input-field` and `lightning-output-field` within the form; display density is not supported for custom components within the form.

With `auto` density:

- Record form components detect the Display Density setting and the width of the form's container to determine label position. The record form components don't change the space between elements, however.
- If your Salesforce density setting is Comfy, the fields always display with their labels above them.
- If your Salesforce density setting is Compact, the fields initially display with their labels next to them. If you resize the form container below a certain width or use the form in a narrow container, the fields appear with their labels above them. This behavior is similar to how other elements behave in Lightning Experience when Compact density is enabled. The record form components use the same width settings to determine when to switch the display density.
- If a record form component doesn't detect the Salesforce density setting, the fields appear with their labels next to them. If you resize the form container to a narrow width, the fields appear with their labels above them.

Detecting the user's density setting is only supported in Lightning Experience. When a record form component runs outside Lightning Experience, and density is set to `auto`, the fields appear with their labels next to them, and switch to labels above the fields when in a narrow container.

### Set the Form Display Density

To display a record form with a particular density, set the `density` attribute to one of these values.

- `comfy` makes the form always display labels on top of fields and doesn't detect the user setting.
- `compact` makes the form display labels next to their fields and doesn't detect the user setting. However, the form switches to the comfy density if the form is narrowed to the width that triggers the automatic change.
- `auto` makes the form use the default behavior described in [Form Display Density](#form-display-density).

Passing in a record type as a field on this component is not supported.

## Override Default Behaviors

To customize the behavior of your form when it loads or when data is submitted, specify your own event handlers using the `onload` and `onsubmit` attributes.

Errors are automatically handled. If a single field has multiple validation errors,
the form shows only the first error on the field. Similarly, if a submitted form
has multiple errors, the form displays only the first error encountered. When you
correct the displayed error, the next error is displayed.

To customize the behavior of the form when
it encounters an error on submission or when data is submitted successfully,
use the `onerror` and `onsuccess` attributes to specify event handlers.

To customize the behavior when the Cancel button is clicked, use the `oncancel` attribute.

For examples of event handlers, see the documentation
for [`lightning-record-edit-form`](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html).

## Work with Person Accounts

A person account is a record type on the account object. It combines certain fields from the account and contact object into a single record. To use person accounts in your org, you must enable the Person Accounts setting first. After Person Accounts is enabled, it can’t be disabled. For more information, see [Enable Person Accounts](https://help.salesforce.com/articleView?id=sales.account_person_enable.htm).

To access person account fields, specify the account object with `object-api-name="Account"`.

<!-- prettier-ignore-start -->
```html
<lightning-record-form
    record-id={recordId}
    object-api-name="Account"
    fields={PARTICIPANTFIELDS}
></lightning-record-form>
```
<!-- prettier-ignore-end -->

Specify the fields using the field names listed in the **IsPersonAccountFields** section for the Account object in the [Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm).

The fields that begin with `Person` are the fields from the contact object.

Import standard fields on the account object using `Account.FieldName`.

```js
import NAME from "@salesforce/schema/Account.Name";
```

For standard fields on the contact object, import `Account.Person<ContactFieldName>`. For example, import the `MobilePhone` field from a contact using `Account.PersonMobilePhone`.

```js
import MOBILEPHONE from "@salesforce/schema/Account.PersonMobilePhone";
```

For custom fields on the account object, import `Account.CustomField__c` as usual.

```js
import NICKNAME from "@salesforce/schema/Account.Nickname__c";
```

For custom fields on the contact object, pass in the object representation of the person account field using the `<ContactCustomFieldNAme>__pc` API name.

```js
PARTICIPANTFIELDS = [
  NAME,
  MOBILEPHONE,
  NICKNAME,
  { fieldApiName: "Contact_Nickname__pc", objectApiName: "Account" },
];
```

For more information, see [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about).

## Usage Considerations

Multiple currencies aren't supported in edit mode. If you enabled Activate Multiple Currencies in your org, `lightning-record-form` displays currency fields using the corporate currency, even when the default currency of a record is different. For more information, see [Manage Multiple Currencies](https://help.salesforce.com/articleView?id=sales.admin_currency.htm&type=5).

Nesting `lightning-record-form` in another instance of the component, or nesting it in `lightning-record-edit-form` or `lightning-record-view-form` is not supported.

`lightning-record-form` shares the same usage considerations as `lightning-record-edit-form` and `lightning-record-view-form`.

`lightning-record-form` loads fields using `lightning-input-field` and `lightning-output-field` internally. As a result, it supports the same field types as listed in the documentation for those components.

## Custom Events

**`cancel`**

The event fired when the user clicks the Cancel button. If the form includes the `recordId` attribute, pressing the Cancel button returns the user to view mode with initial values provided by the record. If you don't provide the `recordId` attribute, pressing the Cancel button resets the fields to blank values.

The `cancel` event returns no parameters.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

Additionally, `lightning-record-form` supports the following custom events.

- `error`
- `load`
- `submit`
- `success`

For more information, see [Custom Events in the `lightning-record-edit-form` documentation](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html#custom-events).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-record-form`, see the following components in the LWC Recipes repo.

- `c-record-form-dynamic-contact`
- `c-record-form-static-contact`

## See Also

[lightning-input-field](/docs/platform/lightning-component-reference/guide/lightning-input-field.html)

[lightning-output-field](/docs/platform/lightning-component-reference/guide/lightning-output-field.html)

[lightning-record-edit-form](/docs/platform/lightning-component-reference/guide/lightning-record-edit-form.html)

[lightning-record-view-form](/docs/platform/lightning-component-reference/guide/lightning-record-view-form.html)

[Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro)

[recordFormStaticContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordFormStaticContact) example in lwc-recipes repository

[recordFormDynamicContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordFormDynamicContact) example in lwc-recipes repository


:::::

:::::tab
::component-specification{component="recordForm" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c0a26a4d0627b4de73aef307504873c7c54ca883a63ecb149c600aaaebd230e7 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/recordHomeTemplate/aura-record-home-template.md -->

# Record Home Template

**`lightning:recordHomeTemplate`**

Enables a component to be used as a flexipage page template for the RECORD_PAGE page type.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:recordHomeTemplate` interface to enable your component to be used as a custom Lightning page template for object record pages. This interface has no effect except when used within Lightning Experience.

Components that implement this interface appear in the Custom Templates section of the Lightning App Builder new page wizard for record pages.

Each template component should implement only one template interface. Template components shouldn’t implement any other type of interface, such as `flexipage:availableForAllPageTypes` or `force:hasRecordId`. A template component can’t multi-task as a regular Lightning component. It’s either a template, or it’s not.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_config_for_app_builder_template_component.htm).


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=d3ecede8dedccb9bd54ce150d935b02138332ca99566922cbae35b62e3c33890 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/recordPicker/lightning-record-picker.md -->

# Record Picker

**`lightning-record-picker`**

A component that provides an input search field, that can search for Salesforce records.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-record-picker` component enables you to search for a list of [Salesforce records](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record.htm) that match search input.

![Record picker with partial matches](https://developer.salesforce.com/media/components/record-picker-basic.jpg '{"class": "image-lg", "title": "Record picker"}')

It uses the [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.html) to search for records, displays the records, and enables you to select a record.

![Record picker with a selected record](https://developer.salesforce.com/media/components/record-picker-selected.jpg '{"class": "image-lg", "title": "Record picker (selected)"}')

This example creates a record picker component that searches for Account objects.

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
    label="Accounts"
    placeholder="Search Accounts..."
    object-api-name="Account"
>
</lightning-record-picker>
```
<!-- prettier-ignore-end -->

## Design

`lightning-record-picker` implements the autocomplete combobox (lookup) blueprint in the Salesforce Lightning Design System (SLDS). The combobox adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                                                 |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Autocomplete Combobox (Lookup)](https://v1.lightningdesignsystem.com/components/combobox/#Entity-Autocomplete-Combobox-%28Lookup%29) | [Autocomplete Combobox (Lookup)](https://www.lightningdesignsystem.com/components/combobox/#Entity-Autocomplete-Combobox-%28Lookup%29) |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App                                                                 | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5)                        |

## Specify a Filter

The `filter` attribute specifies which records the component lists in the record picker. The value for `filter` is an object with a `criteria` property and an optional `filterLogic` property. The value for `criteria` is an array with a list of filter criteria objects.

This example filters records where the `Website` field equals "https://www.grenoble.fr" or `null`, the `Name` of the related `Parent` doesn't start with "Acme", and `Type` doesn't equal "Partner".

```js
filter = {
  criteria: [
    {
      fieldPath: "Website",
      operator: "eq",
      value: "https://www.grenoble.fr",
    },
    {
      fieldPath: "Website",
      operator: "eq",
      value: null,
    },
    {
      fieldPath: "Type",
      operator: "ne",
      value: "Partner",
    },
    {
      fieldPath: "Parent.Name",
      operator: "like",
      value: "Acme%",
    },
  ],
  filterLogic: "(1 OR 2) AND NOT(4) AND 3",
};
```

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
    object-api-name="Account"
    label="Accounts"
    filter={filter}>
</lightning-record-picker>
```
<!-- prettier-ignore-end -->

## Define Filter Logic

To define logic for the set of filter criteria objects in the `criteria` array, specify the `filterLogic` property in the `filter` object. If `filterLogic` is undefined, all criteria apply with an `AND` logical operator by default. Valid operators are `AND`, `OR`, and `NOT`. The `AND` operator has higher precedence than `OR`. Parentheses are supported.

The example in [Specify a Filter](#specify-a-filter) shows how to use `filterLogic`.

## Define Filter Criteria

The `filter` object defines the criteria for individual filters. You can combine these filters by using logical operators that you specify with the `filterLogic` property.

The `filter` object requires these properties for each element in the `criteria` array.

| Name                   | Type   | Description                                                                                                 |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `fieldPath` (required) | string | The name of the field in the API to filter on. Cross-object references such as Account.Phone are supported. |
| `operator` (required)  | string | The filter operator. Can be any of the supported types and operators listed in the next table.              |
| `value` (required)     | string | The value to filter against. If using a date filter, see the next table for accepted values.                |

## Supported Operator Values for Filters

| Type Family       | Field Type            | eq  | ne  | lt  | gt  | lte | gte | in  | nin | like | includes | excludes |
| ----------------- | --------------------- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :--: | :------: | :------: |
| Boolean           | Checkbox              |  ✓  |  ✓  |     |     |     |     |     |     |      |          |          |
| Date and Time     | Date                  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Date and Time     | Date/Time             |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Date and Time     | Time                  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| ID                | ID                    |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Number            | Currency              |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Number            | Geolocation           |     |     |  ✓  |  ✓  |     |     |     |     |      |          |          |
| Number            | Latitude              |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Number            | Longitude             |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Number            | Number                |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Number            | Percent               |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |
| Picklist          | Multi-Select Picklist |  ✓  |  ✓  |     |     |     |     |     |     |      |    ✓     |    ✓     |
| Picklist          | Picklist              |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | Auto Number           |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | Email                 |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | Encrypted Text        |     |     |     |     |     |     |     |     |      |          |          |
| Text              | Long Text             |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | Phone                 |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | Rich Text             |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Text              | URL                   |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Calculated Fields | Formula               |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓   |          |          |
| Calculated Fields | Roll-up Summary       |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |      |          |          |

The `like` operator works similarly to the [SOQL like operator](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_comparisonoperators.htm#:~:text=specified%20value.-,LIKE,-Like), with `%` and `_` wildcards. The `%` wildcard matches zero or more characters. The `_` wildcard matches exactly one character.

## Filter on Date Types

For date types (`Date`, `DateTime`, and `Time`), `value` is passed as an object with either a `value` or `literal` property. Use `value` if referring to an absolute date, time, or datetime. Use `literal` if referring to a relative date or time.

A `value` must be passed as a string (not a JavaScript date) that corresponds to the type of field. Use the JavaScript methods in the following table to convert to the correct format. The API throws an error if the date format is incorrect.

| Field Type |           Format           |        JS Date Conversion         |
| :--------: | :------------------------: | :-------------------------------: |
| `DateTime` | "2023-03-10T14:24:44.567Z" |       `date.toISOString()`        |
|   `Date`   |        "2023-01-01"        | `date.toISOString().slice(0, 10)` |
|   `Time`   |      "14:29:50.659Z"       |  `date.toISOString().slice(11)`   |

This example uses a `Date` value to filter results to a specific date.

```js
filter = {
  criteria: [
    {
      fieldPath: "LastModifiedDate",
      operator: "gt",
      value: { value: new Date("2024-01-01").toISOString() },
    },
  ],
};
```

A `literal` is a date literal that represents a relative range of time, such as last month, this week, or next year. The value for `literal` must be a value from the GraphQL API list of [Literal Values for Relative Dates](https://developer.salesforce.com/docs/platform/graphql/guide/filter-fields.html#date-datetime-and-time-field-types).

The following example uses the `TODAY` literal to filter results to today's date.

```js
filter = {
  criteria: [
    {
      fieldPath: "LastModifiedDate",
      operator: "lt",
      value: { literal: "TODAY" },
    },
  ],
};
```

## Customize the Display of Record Suggestions

To customize the way record suggestions appear in the record picker, use the `display-info` attribute. The `display-info` attribute references an object that specifies the main field and an additional field to display. By default, the value of the name field of the target object is displayed.

This example sets the primary field to the name of the related account and adds `Title` as a display field in the returned record picker results.

```js
displayInfo = {
  primaryField: "Account.Name",
  additionalFields: ["Title"],
};
```

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
    object-api-name="Contact"
    label="Contacts"
    display-info={displayInfo}>
</lightning-record-picker>
```
<!-- prettier-ignore-end -->

The `display-info` referenced object (`displayInfo` in the example) has the following properties. One or both properties are required if using `display-info`. Cross-object fields such as `Account.Name` are supported for both `primaryField` and `additionalFields`.

| Name               | Type   | Description                                                                                                                                                                                                           |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryField`     | string | The first field displayed in record suggestions. The default value is the name field.                                                                                                                                 |
| `additionalFields` | array  | An extra field to display in record suggestions. The value for `additionalFields` is an array with a single string element representing the additional field to display. Only the first element of the array is used. |

## Customize the Fields to Match in Search

By default, the search is conducted on the name field of the target object. To look for a match to a different field or additional fields, specify the `matching-info` attribute. The `matching-info` attribute references an object that defines which fields to query for the search terms in the record picker.

Cross-object fields such as `Account.Phone` are supported.

The `matching-info` referenced object (`matchingInfo` in the example) has the following properties. One or both properties are required if using `matching-info`.

| Name               | Type   | Description                                                                                                                                                                                                   |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `primaryField`     | object | The primary field used to query the search terms. Only Text and Formula (Text) fields are supported. Object must be in the format `{ fieldPath: 'Name' }`.                                                    |
| `additionalFields` | array  | The additional fields used to query the search terms. You can only specify one additional field. Only Text and Formula (Text) fields are supported. Array must be in the format `[ { fieldPath: 'Phone' } ]`. |

You can specify a matching mode for both the primary field and the additional fields using the `mode` property as shown in the following example. Specifying a matching mode can be useful in addressing performance concerns when searching through large datasets within an org.

The `mode` property accepts two values:

- `startsWith`: matches results that start with the search term
- `contains`: (default) matches results that contain the search term

This example shows a `matchingInfo` config that queries records whose `Name` field starts with the search term or whose `Phone` field contains the search term.

```js
matchingInfo = {
  primaryField: { fieldPath: "Name", mode: "startsWith" },
  additionalFields: [{ fieldPath: "Phone" }],
};
```

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
    object-api-name="Contact"
    label="Contacts"
    matching-info={matchingInfo}>
</lightning-record-picker>
```
<!-- prettier-ignore-end -->

## Custom Events

### `change`

The event fired when a record has been selected or cleared.

The `change` event returns the following parameter.

| Parameter | Type   | Description                                              |
| --------- | ------ | -------------------------------------------------------- |
| recordId  | string | Returns the ID of the selected record or `null` if none. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | The event doesn't bubble.                                                                                 |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | The event doesn't propagate outside the component in which it was dispatched.                             |

### `error`

The event fired when Lightning Data Service returns an error.

The `error` event returns an object with these parameters.

| Parameter       | Type   | Description                                                                                                                                 |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| error.message   | string | The error message.                                                                                                                          |
| error.output    | string | The error details.                                                                                                                          |
| error.errorCode | string | The error code having the format: `ERR_RP00x`. See the [Error Handling](#error-handling) section to explore the possible error code values. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | The event doesn't bubble.                                                                                 |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | The event doesn't propagate outside the component in which it was dispatched.                             |

### `focus`

The event fired when the focus is set.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | The event doesn't bubble.                                                                                 |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | The event doesn't propagate outside the component in which it was dispatched.                             |

### `blur`

The event fired when the focus is removed.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | The event doesn't bubble.                                                                                 |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | The event doesn't propagate outside the component in which it was dispatched.                             |

### `ready`

The event fired when the component stops loading and is rendered. To call a method on the component, use the `ready` event. For example,
you can call `this.template.querySelector('lightning-record-picker').focus();` by using this event to put focus on the component after
it finishes rendering.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | The event doesn't bubble.                                                                                 |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | The event doesn't propagate outside the component in which it was dispatched.                             |

## Error Handling

`lightning-record-picker` can return blocking and non-blocking errors. When a blocking error occurs, the input is disabled and a red message appears. To handle these errors, change the component configuration to exit the blocking error state based on what specific error was thrown.

When a non-blocking error occurs, a red message appears but the user can still interact with the component. The user must change their search or reload the page to exit the non-blocking error state.

The following is a list of errors emitted by the `lightning-record-picker` component.

| Error Code  | Error Message                                                                                           | Description                                                                          | Blocking? |
| ----------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------- |
| `ERR_RP001` | Missing or invalid required object-api-name attribute                                                   | The `object-api-name` attribute is omitted or formatted incorrectly.                 | ✓         |
| `ERR_RP002` | lightning-record-picker supports only objects with a name field...                                      | The `object-api-name` refers to an sObject that doesn't provide a name field.        | ✓         |
| `ERR_RP003` | Error calling getObjectInfo for `<object-api-name>`                                                     | Object information can't be retrieved.                                               | ✓         |
| `ERR_RP004` | Error with getRecord...                                                                                 | The default selected record can't be retrieved.                                      |           |
| `ERR_RP005` | Invalid filter configuration.                                                                           | The filter configuration is invalid.                                                 | ✓         |
| `ERR_RP006` | Invalid display info configuration.                                                                     | Display info configuration is invalid.                                               | ✓         |
| `ERR_RP007` | Invalid matching info configuration.                                                                    | Matching info configuration is invalid.                                              | ✓         |
| `ERR_RP008` | [GraphQL error message](https://developer.salesforce.com/docs/platform/graphql/guide/query-status.html) | Search results can't be retrieved.                                                   |           |
| `ERR_RP009` | Missing required label attribute.                                                                       | Label attribute isn't provided or is invalid. Valid values are any non-empty strings | ✓         |

## Validation Messages

Validation messages display when the component loses focus or when the component uses the `reportValidity()` method. Validation messages also display when a user types a search term but doesn't select a record, or the component is required and the user doesn't select a record.

Set a custom validation message with the `setCustomValidity()` method. Setting a message puts the component in an invalid state. The custom message isn't automatically displayed. Call `reportValidity()` to display the custom message.

## Objects and Fields Support

The `lightning-record-picker` component only supports objects in the [User Interface API](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_all_supported_objects.htm) with at least one name field as part of the `nameFields` array from the [`getObjectInfo` response](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_object_info.htm).

The fields that are displayed for the records may not be an exact match for the records returned by the API. The displayed record fields are determined by the `primaryField` and `additionalFields` properties set for `display-info`. If the `matching-info` properties are set to record fields that aren't used by `display-info`, the displayed records can confuse users because the matching fields aren't displayed.

When you search for results with a search term, wildcards characters ('%' and '\_') are escaped in the search term.

`lightning-record-picker` doesn't support searching on encrypted fields, including encrypted fields configured in the `matching-info` attribute.

When configuring the `primaryField` property of the `display-info` attribute, we recommend that you pick a field that's marked as required in the sObject definition. Using a required field prevents displaying a blank selection when a record is selected.

`lightning-record-picker` uses [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.html) and inherits any GraphQL limitations. For more information, see [GraphQL Known Limitations](https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql.html#known-limitations).

## Usage Considerations

When working with a public method on `lightning-record-picker`, make sure the component is fully rendered before calling the method. Don't call `focus()` from `renderedCallback()` as the component and its child components may not be fully rendered. For example, you can call the public method using the `ready` event instead.

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
  label="Choose a Record"
  placeholder="Search Contacts"
  object-api-name="Contact"
  onready={handleOnReady}
></lightning-record-picker>
```
<!-- prettier-ignore-end -->

In your JavaScript file, set the focus on the record picker. This example assumes that you have only one `lightning-record-picker` component on the page.

```javascript
handleOnReady(){
    this.template.querySelector('lightning-record-picker').focus();
 }
```

Alternatively, use [the `lwc:ref` directive](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-dom-work.html#refs) with the `ready` event to locate the component.

<!-- prettier-ignore-start -->
```html
<lightning-record-picker
  lwc:ref="recordPicker"
  label="Choose a Record"
  placeholder="Search Contacts"
  object-api-name="Contact"
  onready={handleOnReady}
></lightning-record-picker>
```
<!-- prettier-ignore-end -->

```javascript
handleOnReady(){
    this.refs.recordPicker.focus();
 }
```

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-record-picker`, see the `c-record-picker-*` components in the LWC Recipes repo.


:::::

:::::tab
::component-specification{component="recordPicker" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=85b9ed75277bacb839cead7a3092d79ff0ba2ed396360b4361f95ba782501d07 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/recordSave/force-record-save.md -->

# Record Save

**`force:recordSave`**

Saves the record for [the `force:recordEdit` component](/docs/platform/lightning-component-reference/guide/force-record-edit.html).

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

This event is handled by the [`force:recordEdit` component](/docs/platform/lightning-component-reference/guide/force-record-edit.html). This example shows a `force:recordEdit` component, which takes in user input to update a record specified by the `recordId` attribute. The button fires the `force:recordSave` event.

```xml
<force:recordEdit aura:id="edit" recordId="003R00000000000000"/>
<lightning:button label="Save" onclick="{!c.save}"/>
```

This client-side controller fires the event to save the record.

```javascript
save : function(component, event, helper) {
      component.find("edit").get("e.recordSave").fire();
      }
```

We recommend using `lightning:inputField` for a record edit layout that uses Lightning Data Service and Lightning Design System, and provides error handling out-of-the-box.

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=6e33cc148628971e0fb426a2aab08e81b8b2e5fe6e41585a4290991878ddb89b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/recordSaveSuccess/force-record-save-success.md -->

# Record Save Success

**`force:recordSaveSuccess`**

Indicates that the record has been successfully saved.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

This event is handled by the `force:recordEdit` component. This example shows a `force:recordEdit` component, which takes in user input to update a record specified by the `recordId` attribute. The button fires the `force:recordSave` event.

```xml
<aura:attribute name="recordId" type="String" default="003R00000000000000"/>
<aura:attribute name="saveState" type="String" default="UNSAVED" />
<aura:handler name="onSaveSuccess" event="force:recordSaveSuccess" action="{!c.handleSaveSuccess}"/>

<force:recordEdit aura:id="edit" recordId="{!v.recordId}" />
<lightning:button label="Save" onclick="{!c.save}"/>
Record save status: {!v.saveState}
```

This client-side controller fires the event to save the record and handle it accordingly.

```javascript
({
  save: function (cmp, event) {
    // Save the record
    cmp.find("edit").get("e.recordSave").fire();
  },

  handleSaveSuccess: function (cmp, event) {
    // Display the save status
    cmp.set("v.saveState", "SAVED");
  },
});
```

We recommend using `lightning:inputField` for a record edit layout that uses Lightning Data Service and Lightning Design System, and provides error handling out-of-the-box.

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=78586ae83e7abb21343c1837fc7d6b408110d7b363a27e0a165098fd967faf00 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/recordViewForm/lightning-record-view-form.md -->

# Record View Form

**`lightning-record-view-form`**

Represents a record view layout that displays one or more fields, provided by lightning-output-field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning-record-view-form` component to create a form that shows Salesforce record data for specified fields associated with that record. The fields are rendered with their labels and current values as read-only.

![Record view form with Name and other fields](https://developer.salesforce.com/media/components/record-view-form.jpg '{"class": "image-xxs", "title": "Record View Form"}')

You can customize the form layout or provide custom rendering of record data.
If you don't require customizations, use `lightning-record-form` instead.

To specify read-only fields, use `lightning-output-field` components inside `lightning-record-view-form`.

## Design

`lightning-record-edit-form` implements the form element (view mode) blueprint in the Salesforce Lightning Design System (SLDS). The form adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                              | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Form Element (View Mode)](https://v1.lightningdesignsystem.com/components/form-element/#View-Mode) | [Form Element (View Mode)](https://www.lightningdesignsystem.com/components/form-element/#View-Mode)            |
| **For Use In** | Lightning Experience, Experience Builder Sites, Salesforce Mobile App                               | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

`lightning-record-view-form` requires
a record ID to display the fields on the record. It doesn't require additional
Apex controllers or Lightning Data Service to display record data. This
component also takes care of field-level security and sharing for you, so
users see only the data that they have access to.

To access raw record data or create a form that needs more customization than the `lightning-record-*-form` components allow, use Lightning Data Service wire adapters and functions, such as those from the `lightning/ui*Api` module.

## Object API Name and Record ID

Each Salesforce record is associated with a Salesforce object. For example, a contact record is associated with the Contact object. Record IDs are created with prefixes that indicate the object. The `lightning-record-view-form` component requires you to specify the `object-api-name` attribute to establish the relationship between a record and an object. The object API name must be appropriate for the use of the component. For example, if you include `lightning-record-view-form` on a record page for an account, set `object-api-name="Account"`. If the record ID and object API name don't agree, the form doesn't display.

## Specify Object API and Field Names

We strongly recommend importing references to objects and fields by using the `@salesforce/schema` syntax especially when you plan to distribute your component as a managed package.

For example, create a form that enables users to view the name field on a contact record page.

<!-- prettier-ignore-start -->
```html
<lightning-record-view-form
    object-api-name={objectApiName}
    record-id={recordId}
>
    <lightning-output-field field-name={nameField}> </lightning-output-field>
</lightning-record-view-form>
```
<!-- prettier-ignore-end -->

To include a read-only field in the form, use the `lightning-output-field` component and set the `field-name` to the API name of the field. Labels for certain fields can differ from those fields on a standard record page. For example, the `Name` field on the opportunity object displays "Name" instead of "Opportunity Name" while the `Name` field name on the account object displays "Account Name".

Although you can set the field name directly with the `field-name` attribute, we recommend that you import a reference to the name field. In this example, the form uses the object API name and record ID of the record page it's placed in.

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

import NAME_FIELD from "@salesforce/schema/Contact.Name";

export default class RecordViewFormStaticContact extends LightningElement {
  // Expose a field to make it available in the template
  nameField = NAME_FIELD;

  // Flexipage provides recordId and objectApiName
  @api recordId;
  @api objectApiName;
}
```

To use your component in a managed package with your custom object, import the object by using your namespace, for example, `@salesforce/schema/namespace__object`.

```js
import MY_CUSTOM_OBJECT from "@salesforce/schema/namespace__Custom_object__c";
```

When you import the references, 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. For more information, see [Import References to Salesforce Objects and Fields](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about#import-references-to-salesforce-objects-and-fields).

## Supported Objects

This component doesn't support all Salesforce standard objects. This limitation also applies to a record that references a field that belongs to an unsupported object.

This component supports the Task object but `Task.IsRecurrence` and `Task.IsReminderSet` fields don't render even when requested.

This component supports the Event object but `Event.IsRecurrence`, `Event.IsRecurrence2`, and `Event.IsReminderSet` fields don't render even when requested.

External objects aren't supported.

For a list of supported 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).

If you’re working with an unsupported object or if you use SOQL to query certain records, create your own UI and use Apex to work with Salesforce data. For more information, see [Data Guidelines](https://developer.salesforce.com/docs/platform/lwc/guide/data-guidelines) in the Lightning Web Components Developer Guide.

## Display Record Fields

To display the fields on a record, specify the fields by using the
`lightning-output-field` component with the `field-name` attribute
set to the API field name.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-view-form
        record-id="003XXXXXXXXXXXXXXX"
        object-api-name="My_Contact__c"
    >
        <div class="slds-box">
            <lightning-output-field field-name="Name"> </lightning-output-field>
            <lightning-output-field field-name="Email__c">
            </lightning-output-field>
        </div>
    </lightning-record-view-form>
</template>
```
<!-- prettier-ignore-end -->

For more information, see the [`lightning-output-field`](/docs/platform/lightning-component-reference/guide/lightning-output-field.html) documentation.

## Use Record Edit Form and Record View Form Together

Here's an example that displays a record edit form and a record view form
for the same contact record. When you make edits and click the **Update Record**
button to submit the record edit form, the record view form updates automatically.

The forms are separate from each other. A form can't be nested in another form.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="slds-p-bottom_large slds-p-left_large" style="width:500px">
        <lightning-record-edit-form
            id="recordEditForm"
            record-id="003R00000000000000"
            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="Birthdate">
            </lightning-input-field>
            <lightning-input-field field-name="Phone"> </lightning-input-field>
            <!--Picklist-->
            <lightning-input-field field-name="LeadSource">
            </lightning-input-field>
            <lightning-button
                type="submit"
                label="Update Record"
                class="slds-m-top_medium"
            >
            </lightning-button>
        </lightning-record-edit-form>
    </div>
    <!-- Record Display -->
    <div class="slds-p-bottom_large slds-p-left_large" style="width:500px">
        <lightning-record-view-form
            record-id="003R00000000000000"
            object-api-name="Contact"
        >
            <div class="slds-box">
                <lightning-output-field field-name="Name">
                </lightning-output-field>
                <lightning-output-field field-name="Birthdate">
                </lightning-output-field>
                <lightning-output-field field-name="Phone">
                </lightning-output-field>
                <lightning-output-field field-name="LeadSource">
                </lightning-output-field>
            </div>
        </lightning-record-view-form>
    </div>
</template>
```
<!-- prettier-ignore-end -->

## Create Multiple Columns

To create a multi-column layout for your record view, use the [Grid utility
classes](https://v1.lightningdesignsystem.com/utilities/grid/) in Lightning Design System.
This example creates a two-column layout.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-record-view-form
        record-id="003XXXXXXXXXXXXXXX"
        object-api-name="My_Contact__c"
    >
        <div class="slds-grid">
            <div class="slds-col slds-size_1-of-2">
                <!-- Your lightning-output-field components here -->
            </div>
            <div class="slds-col slds-size_1-of-2">
                <!-- More lightning-output-field components here -->
            </div>
        </div>
    </lightning-record-view-form>
</template>
```
<!-- prettier-ignore-end -->

## Form Display Density

In the Salesforce user interface, the Display Density setting determines how densely you want to show the content. The Comfy density shows labels on top of the fields and more space between page elements. Compact density shows labels next to the fields and less space between page elements.

The record form components, `lightning-record-form`, `lightning-record-edit-form`, and `lightning-record-view-form`,
handle form density in similar ways. The `density` attribute is set to `auto` by default for all record form components.

Display density is supported for `lightning-input-field` and `lightning-output-field` within the form; display density is not supported for custom components within the form.

With `auto` density:

- Record form components detect the Display Density setting and the width of the form's container to determine label position. The record form components don't change the space between elements, however.
- If your Salesforce density setting is Comfy, the fields always display with their labels above them.
- If your Salesforce density setting is Compact, the fields initially display with their labels next to them. If you resize the form container below a certain width or use the form in a narrow container, the fields display with their labels above them. This behavior is similar to how other elements behave in Lightning Experience when Compact density is enabled. The record form components use the same width settings to determine when to switch the display density.
- If a record form component doesn't detect the Salesforce density setting, the fields display with their labels next to them. If you resize the form container to a narrow width, the fields display with their labels above them.

Detecting the user's density setting is only supported in Lightning Experience. When a record form component runs outside Lightning Experience, and density is set to `auto`, the fields display with their labels next to them, and switch to labels above the fields when in a narrow container.

If you specify a variant for `lightning-output-field`, the variant overrides the display density for that field.

### Set the Form Display Density

To display a record form with a particular density, set the `density` attribute to one of these values.

- `comfy` makes the form always display labels on top of fields and doesn't detect the user setting.
- `compact` makes the form display labels next to their fields and doesn't detect the user setting. However, the form switches to the comfy density if the form is narrowed to the width that triggers the automatic change. To reduce the whitespace 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`.
- `auto` makes the form use the default behavior described in **Form Display Density**.

## Display Fields Conditionally

To display a field conditionally, use the `if:true|false` directive.
This example displays or hides the `Name` and `Industry` account fields when you select or unselect a checkbox.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox"
        label="Show/Hide"
        checked={showFields}
        onchange={toggleFields}
    >
    </lightning-input>

    <lightning-record-view-form
        record-id={recordId}
        object-api-name={objectApiName}
        density="compact"
    >
        <template if:true={showFields}>
            <lightning-output-field field-name="Name"></lightning-output-field>
            <lightning-output-field field-name="Industry">
            </lightning-output-field>
        </template>
    </lightning-record-view-form>
</template>
```
<!-- prettier-ignore-end -->

The checkbox toggles between hiding and showing the fields using the `onchange` event handler.

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

export default class RecordViewFormConditional extends LightningElement {
  @api recordId;
  @api objectApiName;
  showFields = true;

  toggleFields() {
    this.showFields = !this.showFields;
  }
}
```

## Work with Person Accounts

A person account is a record type on the account object. It combines certain fields from the account and contact object into a single record. To use person accounts in your org, you must enable the Person Accounts setting first. After Person Accounts is enabled, it can’t be disabled. For more information, see [Enable Person Accounts](https://help.salesforce.com/articleView?id=sales.account_person_enable.htm).

To access person account fields, use the account object with `object-api-name="Account"`.

Specify the fields using the field names listed in the **IsPersonAccountFields** section for the Account object in the [Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm).

The fields that begin with `Person` are the fields from the contact object.

For standard fields on the contact object, use `Person<ContactFieldName>`. For example, use `field-name="PersonMobilePhone"` for the `MobilePhone` field on the contact object.

For custom fields on the account object, use `CustomFieldName__c` as usual.

For custom fields on the contact object, use `CustomFieldName__pc`.

This example creates a form to view a person account record.

<!-- prettier-ignore-start -->
```html
<lightning-record-view-form record-id={recordId} object-api-name="Account">
    <!-- Name field on account -->
    <lightning-output-field field-name="Name"> </lightning-output-field>

    <!-- Nickname__c field on account -->
    <lightning-output-field field-name="Nickname__c"> </lightning-output-field>

    <!-- MobilePhone field on contact -->
    <lightning-output-field field-name="PersonMobilePhone">
    </lightning-output-field>

    <!-- Contact_Nickname__c field on contact -->
    <lightning-output-field field-name="Contact_Nickname__pc">
    </lightning-output-field>
    <lightning-button
        class="slds-m-top_small"
        variant="brand"
        type="submit"
        label="Update"
    >
    </lightning-button>
</lightning-record-view-form>
```
<!-- prettier-ignore-end -->

For more information, see [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about).

## Usage Considerations

Nesting `lightning-record-view-form` in another instance of the component, or nesting it in `lightning-record-edit-form` or `lightning-record-form` is not supported.

Consider using the [`lightning-record-form`](/docs/platform/lightning-component-reference/guide/lightning-record-form.html)
component to create record forms more easily.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`load`**

The event fired when the record view form loads record data.
If you load the fields dynamically, `load` is fired before the child elements of `lightning-record-view-form` finish loading. Consider the [`connectedCallback()` lifecycle](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks-dom) hook to perform initialization tasks. Alternatively, to load values or set properties dynamically, use a [getter and setter](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getters-setters) instead.

`load` is fired when the form gets new data from Lightning Data Service, which can be once or multiple times after the component is initialized. For example, the `load` event is fired when:

- The `record-id` value changes
- The `fields` list changes
- The form includes picklist fields
- The record type changes

If you require the `load` event to be called only once, write code to prevent it from running more than once.

Use the `event.detail` property to return the [record UI](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_responses_record_ui.htm).

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-record-view-form`, see the following components in the LWC Recipes repo.

- `c-record-view-form-dynamic-contact`
- `c-record-view-form-static-contact`

## See Also

[Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro)

[recordViewFormStaticContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordViewFormStaticContact) example in lwc-recipes repository

[recordViewFormDynamicContact](https://github.com/trailheadapps/lwc-recipes/tree/master/force-app/main/default/lwc/recordViewFormDynamicContact) example in lwc-recipes repository


:::::

:::::tab
::component-specification{component="recordViewForm" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=db331a93a96b423e153324a2db0dc22d06b30bc863fc75a478e94ca49eff0ee8 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/refresh/lightning-refresh.md -->

# Refresh

**`lightning/refresh`**

Refreshes component data.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/refresh` module API provides a standard way to refresh component data in LWC.
Update the data for a specific hierarchy of components (a "view"), without reloading an entire page.

For this module's specification and examples, see the [Lightning Web Components Developer Guide: `lightning/refresh` Module](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-refresh).


:::::

:::::tab
::component-specification{component="refresh" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9ab2945d6b2409cc3d50e3d3f9e03e148330fc82e9d976ba889c25b6445e5e4d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/refreshView/force-refresh-view.md -->

# Refresh View (Beta)

**`force:refreshView`**

Reloads the view without a page reload.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

**note:** `force:refreshView` 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 refresh a view, run `$A.get('e.force:refreshView').fire();`, which reloads data for standard components. Custom components are refreshed with known limitations, as described below. The `force:refreshView` event impacts performance and should be avoided, if possible. Repeated firing of this event by a single component or multiple components on a page is not supported. This event is supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.

This example refreshes the view after an action is successfully completed.

If you fire this event on a Lightning page, such as a record page in Lightning Experience, only standard components are refreshed. This example displays a form using `lightning:recordForm`, which enables you to create a contact record on an account record page. The custom component then refreshes the data on standard components on the record page, such as the contact related list.

```xml
<aura:component implements="flexipage:availableForRecordHome,force:hasRecordId" access="global">
  <aura:attribute name="fields" type="String[]" default="['FirstName','LastName']" />

  <lightning:card title="Create Contact">
    <div class="slds-m-horizontal_small">
      <lightning:recordForm
        aura:id="myForm"
        objectApiName="Contact"
        fields="{!v.fields}"
        onsubmit="{!c.createContact}"
        onsuccess="{!c.handleSuccess}"
      />
    </div>
  </lightning:card>
</aura:component>
```

During the submit event, assign the account ID to the contact record. When the contact record saves successfully, fire the `force:refreshView` event to reload the contact related list on the account page, which is a standard component on the record page.

```javascript
({
  createContact: function (component, event, helper) {
    event.preventDefault();
    var fields = event.getParam("fields");
    fields.AccountId = component.get("v.recordId");
    component.find("myForm").submit(fields);
  },

  handleSuccess: function (component, event, helper) {
    $A.get("e.force:refreshView").fire();
  },
});
```

Refreshing the following views recreates and refreshes the custom components within it.

- Action override for a record action using `lightning:actionOverride`
- Lightning component that’s directly addressable using `lightning:isUrlAddressable`
- Lightning tab

This example refreshes the view after a server-side action that changes the data is successfully completed.

```javascript
({
  refresh: function (component, event, helper) {
    var action = component.get("c.myController");
    action.setCallback(component, function (response) {
      var state = response.getState();
      if (state === "SUCCESS") {
        // Refresh the view
        // after data is updated
        $A.get("e.force:refreshView").fire();
      } else {
        // Handle the 'ERROR' or 'INCOMPLETE' state
      }
    });
    $A.enqueueAction(action);
  },
});
```

## Usage Considerations

`force:refreshView` does not impact storable Aura Actions as they are stored in the cache. To improve performance, we recommend you use storable Aura actions. For more information, see [Storable Actions](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/controllers_server_storable_actions.htm).

We don’t recommend you to handle this event as it’s handled automatically by the app. To maintain the latest data on your page while reading and modifying your data, we recommend using force:recordData, which is built on [Lightning Data Service](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/data_service.htm).

Always consider using Lightning Data Service first to work with Salesforce data. If you’re creating custom components with Lightning Web Components, use the Lightning Data Service wire adapters and functions in the [lightning/ui\*Api modules](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reference_ui_api.html) to work with record data. For example, use `getRecordNotifyChange()` to refresh the Lightning Data Service cache after you update a record outside of its mechanisms, such as via imperative Apex or Visualforce. To illustrate, the first example on this page can be rewritten using `force:recordData` without firing the `force:refreshView` event. For more information, see [Creating a Record](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/data_service_create_record.htm).


:::::

:::::tab
Markdown content for specifications
:::::

::::::

<!-- document id=68ae18f293c0a69a31418f47afb86b0533ba11e1ba6a49627e3f2718e6a4253d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/relativeDateTime/lightning-relative-date-time.md -->


# Relative Date Time

**`lightning-relative-date-time`**

Displays the relative time difference between the source date-time and the provided date-time.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="relativeDateTime" model="lwc" namespace="lightning"}


:::::

:::::tab

The `lightning-relative-date-time` component displays relative time that shows
how much time has passed or how much time is left until a given date/time.
It formats the relative time for the current locale following the rules
from [Unicode CLDR](http://cldr.unicode.org/translation/date-time-1/date-time-names).

Use the `value` attribute to pass the date to format.
When you provide a timestamp or JavaScript Date object,
`lightning-relative-date-time` displays a string that describes the relative
time between the current time and the provided time.

The unit of time that's displayed corresponds to how much time has passed since the
provided time, for example, "a few seconds ago" or "5 minutes ago". A given
time in the future returns the relative time, for example, "in 7 months" or
"in 5 years".

This example returns the relative time between the current time and a given
time in the past and future.

<!-- prettier-ignore-start -->
```html
<template>
    <div>
        <lightning-relative-date-time value={past}>
        </lightning-relative-date-time>
    </div>
    <div>
        <lightning-relative-date-time value={future}>
        </lightning-relative-date-time>
    </div>
</template>
```
<!-- prettier-ignore-end -->

The `past` and `future` attributes return:

- 2 hours ago
- in 2 days

```javascript
import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  get past() {
    return Date.now() - 2 * 60 * 60 * 1000;
  }
  get future() {
    return Date.now() + 2 * 60 * 60 * 1000;
  }
}
```

Other sample output includes:

- Relative past: a few seconds ago, a minute ago, 2 minutes ago, an hour ago, 2 hours ago, 2 days ago, 2 months ago, 2 years ago
- Relative future: in a few seconds, in a minute, in 2 minutes, in an hour, in 2 hours, in 2 days, in 2 months, in 2 years in 2 days, in 2 months

The user's language setting in an org determines the language displayed for the units of time. If the locale uses a different language, the output uses the language setting and ignores the locale. For example, if you set the locale to Arabic and the language to English, the output uses digits 0-9 for numbers and English instead of Arabic numerals to be consistent with the language on the user interface. For more information, see [Supported Languages](https://help.salesforce.com/articleView?id=faq_getstart_what_languages_does.htm).

Supported units of time include:

- seconds
- minutes
- hours
- days
- months
- years

To obtain the language and locale information in your org, use the `@salesforce/i18n` scoped module. For more information, see [Access Internationalization Properties](https://developer.salesforce.com/docs/platform/lwc/guide/create-i18n).

This component doesn't support localization in LWR Sites.


:::::

:::::tab
::component-specification{component="relativeDateTime" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=94e3ba20824f3aba323d5e65c20420655e7d423fc68ceff67ceb3439955510fc url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/richTextToolbarButton/lightning-rich-text-toolbar-button.md -->

# Rich Text Toolbar Button

**`lightning-rich-text-toolbar-button`**

A custom button on the lightning-input-rich-text toolbar.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-rich-text-toolbar-button` component creates a button for
the toolbar for `lightning-input-rich-text`.

Place `lightning-rich-text-toolbar-button` inside the
`lightning-rich-text-toolbar-button-group` component, which groups
the custom buttons.

You can include multiple button groups, and each group can contain multiple buttons.

For more information about custom button groups, see
[`lightning-rich-text-toolbar-button-group`](/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button.html)
documentation.

Use the `icon-name` attribute to specify a Lightning Design System
[utility icon](https://v1.lightningdesignsystem.com/icons/#utility)
to display on the button.

Use `icon-alternative-text` to describe the button's function for users of
assistive technologies.

The `selected` attribute reflects the state of the button. Specify `selected`
in the `lightning-rich-text-toolbar-button` component to indicate when the
button is selected, and the button background color is dark. By default,
`selected` is false and the button background color is light.

Specify the `disabled` attribute to display the button icon as light gray and
prevent the button from being selected.

## Design

Use `lightning-rich-text-toolbar-button` within `lightning-input-rich-text`, which implements the rich text editor blueprint in the Salesforce Lightning Design System (SLDS). The rich text editor adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Rich Text Editor](https://v1.lightningdesignsystem.com/components/rich-text-editor)                        | [Rich Text Editor](https://www.lightningdesignsystem.com/components/rich-text-editor/)                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Custom Buttons

You can create buttons by using the `lightning-rich-text-toolbar-button` component
attributes and the `onclick` handler to perform an action. For example, you can
create a handler to format text, insert text, attach a file to a feed post,
or open a popup.

For information about formatting or inserting text programmatically, see the
[`lightning-input-rich-text`](/docs/platform/lightning-component-reference/guide/lightning-input-rich-text.html)
documentation.

This example includes one button group that contains one button for applying
`code-block` format. The `code-block` format isn’t a default format in
`lightning-input-rich-text`, so the `formats` attribute specifies all the
formats required in the toolbar.

![Rich text editor with a custom toolbar button](https://developer.salesforce.com/media/components/rich-text-toolbar-button.gif '{"class": "image-md", "title": "Rich Text Editor with Custom Toolbar Button"}')

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        formats="font, bold, italic, underline, strike,
    list, indent, align, link, image, clean, code, code-block, color, background, header"
    >
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="First group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:insert_tag_field"
                icon-alternative-text="Code Snippet"
                onclick={handleCodeBlockButtonClick}
            >
            </lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

The handler gets the format currently set in the editor, and applies or
removes the `code-block` format, depending on the current format.

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

export default class CustomButtonDemo extends LightningElement {
  handleCodeBlockButtonClick() {
    const inputRichText = this.template.querySelector("lightning-input-rich-text");
    let format = inputRichText.getFormat();

    // Set or unset code-block format based on format on current selection
    if (format["code-block"]) {
      inputRichText.setFormat({ "code-block": false });
    } else {
      inputRichText.setFormat({ "code-block": true });
    }
  }
}
```

## Open Popups with Custom Buttons (Beta)

The `lightning-rich-text-toolbar-button` component provides methods that
enable you to open and close popups from custom buttons.

Use the `showPopup()` method to open a popup from a custom button, and use `closePopup()` to close it.

Provide the content of the popup by nesting components inside `lightning-rich-text-toolbar-button`.

Popups close by default if you click outside the popup. The `popupclickout` event fires when you click outside,
so you can use a handler on this event to prevent closing if needed.

This example creates a Save button that opens a popup to prompt the user to save the content.
The popup content consists of a text input field and two buttons. The Save custom button
prevents the default clickout behavior.

To indicate to assistive technologies that the button can open an interactive dialog,
specify `aria-haspopup="dialog"`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text>
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="First group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:save"
                icon-alternative-text="Save"
                onclick={openPopup}
                onpopupclickout={handlePopupClickout}
                aria-haspopup="dialog"
            >
                <!-- Popup Items -->
                <lightning-input label="Save As"></lightning-input>
                <div class="slds-m-top_small">
                    <lightning-button
                        variant="brand"
                        label="Save"
                        onclick={handleSave}
                    >
                    </lightning-button>
                    <lightning-button
                        variant="bare"
                        label="Cancel"
                        onclick={closePopup}
                        style="margin-left: .25rem"
                    >
                    </lightning-button>
                </div>
            </lightning-rich-text-toolbar-button>
            <lightning-rich-text-toolbar-button
                icon-name="utility:brush"
                disabled
            ></lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>

        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="Second group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:email"
            ></lightning-rich-text-toolbar-button>
            <lightning-rich-text-toolbar-button
                icon-name="utility:call"
            ></lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

The JavaScript simply calls `showPopup()` to create the popup.
The component handles the positioning and styling of the popup for you.

The example's `handlePopupClickout` function calls `event.preventDefault()` to prevent
the popup from closing. The user can only close it by clicking the popup's Save or Cancel
buttons, or by pressing the Escape key.

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

export default class CustomButtonPopupDemo extends LightningElement {
  preventCloseOnClickOut = true;

  openPopup(event) {
    event.target.showPopup();
  }

  closePopup() {
    this.template.querySelectorAll("lightning-rich-text-toolbar-button")[0].closePopup();
  }

  handleSave() {
    const name = this.template.querySelector("lightning-input");
    this.enteredText = name.value;
    // save the content
    this.closePopup();
  }

  handlePopupClickout(event) {
    if (this.preventCloseOnClickOut) {
      event.preventDefault();
    }
  }
}
```

## Accessibility

Use `icon-alternative-text` to describe the button's function. The text is assigned to the `title`
attribute for the button tooltip. The text is also used as assistive text for users of assistive technologies.

Use `aria-haspopup` to indicate the availability and type of interactive popup element on a toggle button.
See [MDN web docs: aria-haspopup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup).

When a toolbar button is clicked once, the `aria-pressed` attribute is appended with a value of `true`,
which tells assistive technologies that a button is in a pressed state. The button remains in the pressed state
until it's clicked another time, which changes the value back to `false`. For example, the bold formatting button
is a toggle button that either applies or removes bold formatting on selected text. The button turns blue when clicked once
and `aria-pressed` is `true`. When the button is clicked another time, the blue background on the button is removed and
`aria-pressed` is `false`.

Toolbar buttons that open a dialog use `aria-haspoup` and not `aria-pressed` as they aren't toggle buttons.

## Custom Events

**`popupclickout`**

The event fired when a popup is open and you click outside it.

The `popupclickout` event returns no parameters.

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |


:::::

:::::tab
::component-specification{component="richTextToolbarButton" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=9e340c4ddc290671853d38152334974473f310606a4c48a73fc81a711ad82555 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/richTextToolbarButtonGroup/lightning-rich-text-toolbar-button-group.md -->

# Rich Text Toolbar Button Group

**`lightning-rich-text-toolbar-button-group`**

Creates a custom button group in lightning-input-rich-text.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning-rich-text-toolbar-button-group` component is a container
component for custom buttons in `lightning-input-rich-text`. The `lightning-input-rich-text` component inserts the button group in a named slot.

To include the button group, place the `lightning-rich-text-toolbar-button-group` component inside
`lightning-input-rich-text` and specify the attribute `slot="toolbar"`
to create a group for custom buttons. The rich text editor displays the button group at the end of the toolbar after the **Remove formatting** button.

Place `lightning-rich-text-toolbar-button` components inside
`lightning-rich-text-toolbar-button-group` to define custom buttons.

A group is required for custom buttons, even if there’s only one custom button.

You can include multiple custom button groups in `lightning-input-rich-text`
and include multiple custom buttons in each `lightning-rich-text-toolbar-button-group`.

## Design

Use `lightning-rich-text-toolbar-button-group` within `lightning-input-rich-text`, which implements the rich text editor blueprint in the Salesforce Lightning Design System (SLDS). The rich text editor adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Rich Text Editor](https://v1.lightningdesignsystem.com/components/rich-text-editor)                        | [Rich Text Editor](https://www.lightningdesignsystem.com/components/rich-text-editor/)                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

This example shows basic usage for two button groups, each using the `toolbar` slot.

![Rich text editor with a custom toolbar groups](https://developer.salesforce.com/media/components/rich-text-toolbar-button-group.jpg '{"class": "image-lg", "title": "Rich Text Editor with Custom Toolbar Button Groups"}')

The component inserts the button groups after the **Remove formatting** button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text>
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="Template Button Group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:insert_template"
                icon-alternative-text="Insert Doc Template"
                onclick={handleInsertDocTemplate}
            >
            </lightning-rich-text-toolbar-button>
            <lightning-rich-text-toolbar-button
                icon-name="utility:email"
                icon-alternative-text="Insert Email Template"
                onclick={handleInsertEmailTemplate}
            >
            </lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="Save Button Group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:save"
                icon-alternative-text="Save"
                onclick={handleSave}
            >
            </lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

For more information about custom buttons, see
[`lightning-rich-text-toolbar-button`](/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button.html)
documentation.

## Accessibility

Specify the attribute `aria-label` to provide a label to inform
assistive device users about the button group.

Use the Tab key to navigate to the buttons, and then use
Left and Right arrow keys to navigate among the buttons until
you reach the custom button group.


:::::

:::::tab
::component-specification{component="richTextToolbarButtonGroup" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=b270db45673077473304c3c364ec6927e7b7c6488f6b837830b2763b883820fa url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/routeChange/forceCommunity-route-change.md -->

# Route Change

**`forceCommunity:routeChange`**

Indicates that a page's url is changed.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

`forceCommunity:routeChange` is fired when a page’s URL changes. Custom Lightning components can listen to this system event and handle it as required—for example, for analytics or SEO purposes.

This example listens to the event and updates a counter that denotes the number of times the route has changed.

```xml
<aura:component implements="forceCommunity:availableForAllPageTypes">
    <aura:attribute name="routeChangeCounter" default="0" type="Integer" required="false"/>
    <aura:handler event="forceCommunity:routeChange" action="{!c.handleRouteChange}"/>
    <h1>Route was changed: {!v.routeChangeCounter} times</h1>
</aura:component>
```

This client-side controller updates the counter.

```javascript
handleRouteChange : function(component, event, helper) {
    component.set('v.routeChangeCounter', component.get('v.routeChangeCounter') + 1);
}
```

This event is supported in Aura-based Experience Builder sites only.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::
::::::

<!-- document id=e814dc2082e011b43ade14fe294e91726c36249b042df09b3a802f77f36e1b4f url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/searchInterface/forceCommunity-search-interface.md -->

# Search Interface

**`forceCommunity:searchInterface`**

Enables a components to be used as a custom search component in the Experience Builder.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

To appear in Experience Builder as a custom search component, a component must implement `forceCommunity:searchInterface`.

Here's the sample code for a simple search component.

```xml
<aura:component implements="forceCommunity:searchInterface" access="global">
    <div class="search">
        <div class="search-wrapper">
            <form class="search-form">
                <div class="search-input-wrapper">
                    <input class="search-input" type="text" placeholder="My Search"/>
                </div>
                <input type="hidden" name="language" value="en" />
            </form>
        </div>
    </div>
</aura:component>
```

After you create a custom search component, admins can select it in Experience Builder in Settings | Theme to replace the template’s standard Search & Post Publisher component.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=ef4c253a739e48278f6500aacc656b4344262025e3bb82e30a918bd234df6510 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/select/lightning-select.md -->


# Select

**`lightning-select`**

A menu of options for single or multiple selection.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="select" model="lwc" namespace="lightning"}


:::::

:::::tab

`lightning-select` enables single and multiple selections on a menu of options by using the HTML `select` element and `option` elements. To specify whether multiple options can be selected, use the `multiple` attribute. The `size` attribute can be used to specify how many options are visible at once. `lightning-select` also accepts most general form input attributes such as `required` and `disabled`.

Here's an example on how to create a menu of options. Pass a default value to the `value` attribute to make it selected by default when the component loads.

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
></lightning-select>
```
<!-- prettier-ignore-end -->

In your JavaScript, define an array of options. Each option has a `value` and `label` property. The `value` is returned when you select an option. The `label` value is the text to show on the menu.

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

export default class SimpleSelect extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }
}
```

Selecting an option triggers the `change` event, which calls the
`onchange` handler. To check which option is selected,
use `event.detail.value`. If your `value` attribute is null, `event.detail.value` returns an empty string.

## Design

`lightning-select` implements the select blueprint in the Salesforce Lightning Design System (SLDS). The component adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Select](https://v1.lightningdesignsystem.com/components/select/)                                                                     | [Select](https://www.lightningdesignsystem.com/components/select/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Select Multiple Options

To enable multiple selection of options, use the `multiple` attribute. You can use the `size` attribute to specify the number of options to display by default.

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    multiple
    size="3"
></lightning-select>
```
<!-- prettier-ignore-end -->

When you specify `multiple`, most browsers show a scrolling list box instead of a single-line dropdown. Alternatively, use the [lightning-dual-listbox](/docs/platform/lightning-component-reference/guide/lightning-dual-listbox.html) component to move options between two lists and reorder the list options.

## Create Options

To create menu options, pass in the following properties to the `options` attribute.

| Property | Type    | Description                                                            |
| -------- | ------- | ---------------------------------------------------------------------- |
| label    | string  | The text to show next to a checkbox.                                   |
| value    | string  | The string that's used to identify which checkbox is selected.         |
| disabled | boolean | If true, the option isn’t selectable and users can’t interact with it. |

## Input Validation

Client-side input validation is available for this component. You can make
the selection required by adding the `required` attribute. An error message is
automatically displayed when an item isn’t selected and the element is `required`.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` attributes.

You can override the default message by providing your own value for
`message-when-value-missing`.

Here's an example that displays a custom field-level message when a user interacts with the component but doesn’t select an option.

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    required
    message-when-value-missing="Which area can we help you with?"
>
</lightning-select>
```
<!-- prettier-ignore-end -->

Set the default value to an empty string so that an option isn’t selected by default.

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

export default class RequiredSelect extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }
}
```

## Custom Validity Error Messages

`lightning-select` supports `setCustomValidity()` from HTML5's Constraint Validation API.
To set an error message, specify a quoted string.
To reset the error message, set the message to an empty string (""). See
details at [https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity](https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity).

This example shows how to specify a custom error message with `setCustomValidity()` and `reportValidity()`.

<!-- prettier-ignore-start -->
```html
<lightning-select
    name="myselect"
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    required
></lightning-select>

<lightning-button label="Register" onclick={register}></lightning-button>
```
<!-- prettier-ignore-end -->

When you click the **Register** button, the `register()` function shows a custom error message if no option is selected, or clears the error message if an option has been selected.

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

export default class CustomSelectError extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }

  register(event) {
    const selectCmp = this.template.querySelector("lightning-select");
    if (this.selectVal === "") {
      selectCmp.setCustomValidity("You have not selected an option");
    } else {
      selectCmp.setCustomValidity("");
    }
    // Display the error without user interaction
    selectCmp.reportValidity();
  }
}
```

## Component Styling

Use a combination of the `variant` and `class` attributes to customize the dropdown menu.

### Variants

Use the `variant` attribute with one of these values to position the labels differently relative to the dropdown menu.

- `standard` is the default, which displays the label above the dropdown menu.
- `label-hidden` hides the label but make it available to assistive technology. If you provide a value for `field-level-help`, the tooltip icon is still displayed.
- `label-inline` aligns the label and dropdown menu horizontally.
- `label-stacked` places the label above the dropdown menu.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute. For example, you can add padding on the top of the component using the `slds-p-top_medium` SLDS class.

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-select` uses `delegatesFocus` to manage focus. `tabindex` is not supported. See [Handle Focus](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-focus) for more information.

Option groupings and disabled options are currently not supported.

`lightning-select` has usage differences from its Aura counterpart (`lightning:select`). [`lightning:select`](/docs/platform/lightning-component-reference/guide/aura-select.html) does not support multiple selection, and it takes in menu options as subcomponents in `lightning:select`. `lightning:select` doesn't currently support multiple selection.

Alternatively, consider using [`lightning-combobox`](/docs/platform/lightning-component-reference/guide/lightning-combobox.html) if your dropdown menu doesn't need mobile support or multiple selection.

## Accessibility

Provide a text label for accessibility using the `label` attribute, which creates an HTML `<label>` element for your input component.
To hide the label from view and make it available to assistive technology, use the `label-hidden` variant.

When the component is in an invalid state, an error message is displayed under the `<select>` element. The message is contained in a `<div>` element that specifies `role="status"`.
To enable screen readers to announce the error message, the `id` value is associated with the `aria-describedby` attribute on the `<select>` element.
The label is also used as assistive text for screen readers.

On desktop, select multiple options by clicking an option and dragging up or down the list. Alternatively, hold the Ctrl, Command, or Shift keys
(depending on your operating system) and then click multiple options to select or deselect them.
For more information, see [Selecting multiple options](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#Usage_notes) in the MDN web docs.

Validation errors are displayed below the dropdown menu using `role="status"`. When an error is displayed, the `select` element updates the `aria-describedby` value to the ID of the element that contains the error message. The `label` value is also used as assistive text for screen readers.

## Custom Events

**`change`**

The event fired when an option is selected.

The `change` event returns the following parameter.

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| value     | string | The value of the selected option. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |


:::::

:::::tab
::component-specification{component="select" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=0115ee483396d1cd46f30a6e777cb8305585669f4db83eac5533b2e0c2076195 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/selectSObject/ltng-select-sobject.md -->

# Select SObject

**`ltng:selectSObject`**

Sends the `recordId` of an object when you select the object in the UI.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Fire this event when you want to select an object, for example, when you are displaying a list of records and you want another component to display the selected record. To select an object, set the record ID on the `recordId` attribute. Optionally, specify a channel for this event so that your components can select if they want to listen to particular event messages. Using a channel is useful if you want to put multiple components on a page and you want to separate them into channels to prevent conflicts.

```javascript
selectedObj: function(component, event) {
 var selectedObjEvent = $A.get("e.ltng:selectSObject");
 selectedObjEvent.setParams({
          "recordId": "0061a000004x8e1",
          "channel": "AccountsChannel"
 });
 selectedObjEvent.fire();
}
```


:::::

:::::tab
## Attributes

| Name       | Description                                                                                                                                 | Type   | Default | Required                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `channel`  | Represents the channel name. Specify this attribute if you want particular components to process some event messages while ignoring others. | string |         |                                              |
| `recordId` | The record ID associated with the record to select.                                                                                         | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=2e6fbb0fa8ef3e8fafab0d5d1c9a8694d0d7e13c4f26a038d833315207121e16 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/selectionChanged/wave-selection-changed.md -->

# Selection Changed

**`wave:selectionChanged`**

Indicates that a selection was made in your component. The event sends the payload and the ID of the dashboard that fired the event.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:selectionChanged` event react to selections in your Analytics dashboard and get the row data for the selection.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name      | Description                                                                        | Type   | Default | Required |
| --------- | ---------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `id`      | The identifier of the Analytics asset for which a selection change event occurred. | string |         |          |
| `noun`    | The type of the Analytics asset for which a selection change event occurred.       | string |         |          |
| `payload` | Contains the selection information from the asset that fired the event.            | string |         |          |
| `verb`    | The action that occurred on the Analytics asset.                                   | string |         |          |

:::::

::::::

<!-- document id=32cd56b0a3bf3fd55556f2824d3652a31e4efe0f8479b5c1845deef0309a0a77 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/sendChatterExtensionPayload/aura-send-chatter-extension-payload.md -->

# Send Chatter Extension Payload

**`lightning:sendChatterExtensionPayload`**

For Chatter Rich Publisher Apps only. Sends the payload and metadata that needs to be saved for the extension with the feed item.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:sendChatterExtensionPayload` is a component event that sends your custom component's payload into a Chatter feed. You must use this event with the `lightning:availableForChatterExtensionComposer` and `lightning:availableForChatterExtensionRenderer` interface to make your component available to the Chatter publisher.

Rich Publisher Apps are available to Experience Builder sites in topics, group, and profile feeds and in direct messages.

For example, you can create a custom component that generates a random quote in the Chatter feed.

```html
<aura:component implements="lightning:availableForChatterExtensionComposer">
  <aura:handler name="init" value="{!this}" action="{!c.init}" />
  <div class="container">
    <span class="quote" aura:id="quote"></span>
    <span class="author" aura:id="author"></span>
    <lightning:button label="Get next Quote" onclick="{!c.getQuote}" />
  </div>
</aura:component>
```

In your client-side controller, fire the `lightning:sendChatterExtensionPayload` event with your payload.

```javascript
({
  getQuote: function (cmp, event, helper) {
    // get quote from the source
    var compEvent = cmp.getEvent("sendChatterExtensionPayload");
    compEvent.setParams({
      payload: "<payload object>",
      extensionTitle: "<title to use when extension is rendered>",
      extensionDescription: "<description to use when extension is rendered>",
    });
    compEvent.fire();
  },
});
```

Next, create a custom component that implements the `lightning:availableForChatterExtensionRenderer` interface to determine how the quote is displayed in the Chatter feed.

```html
<aura:component implements="lightning:availableForChatterExtensionRenderer">
  <aura:attribute name="_quote" type="String" />
  <aura:attribute name="_author" type="String" />
  <aura:handler name="init" value="{!this}" action="{!c.init}" />

  <div class="container">
    <span class="quote" aura:id="quote">{!v._quote}</span>
    <span class="author" aura:id="author">--- {!v._author} ---</span>
  </div>
</aura:component>
```

Finally, create a ChatterExtension object in your org and make the components available in the Chatter Publisher via the Administration page in Experience Workspaces.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_integrate_customapps_to_publisher.htm).


:::::

:::::tab
## Attributes

| Name                    | Description                                                         | Type   | Default | Required                                     |
| ----------------------- | ------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `extensionDescription`  | The description for the extension to be saved with the feed item.   | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `extensionThumbnailUrl` | The thumbnail URL for the extension to be saved with the feed item. | string |         |                                              |
| `extensionTitle`        | The title for the extension to be saved with the feed item.         | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `payload`               | The payload data to be saved with the feed item.                    | object |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=0ac85a7e0fb1d76c841e9f669015130a0ef51366ea5286a58219b00f74dcac52 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ltng/sendMessage/ltng-send-message.md -->

# Send Message

**`ltng:sendMessage`**

Sends some data (String or JSON) to other components within the application.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Fire this event when you want to send a message to another component. To send a message, specify a string of text that you want to pass between components. Optionally, specify a channel for this event so that your components can select if they want to listen to particular event messages Using a channel is useful if you want to put multiple components on a page and you want to separate them into channels to prevent conflicts.

```javascript
sendMsg: function(component, event) {
 var sendMsgEvent = $A.get("e.ltng:sendMessage");
 sendMsgEvent.setParams({
          "message": "Hello World",
          "channel": "AccountsChannel"
 });
 sendMsgEvent.fire();
}
```


:::::

:::::tab
## Attributes

| Name      | Description                                                                                         | Type   | Default | Required                                     |
| --------- | --------------------------------------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `channel` | Represents the channel name. Use a channel to enable a component to filter down to specific events. | string |         |                                              |
| `message` | A message in the form of a String or JSON.                                                          | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=0bce13cefdfd494459e29658816c84ffc6713a725d30a1bfedee222ac566c1e1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/serviceCloudVoiceToolkitApi/lightning-service-cloud-voice-toolkit-api.md -->

# Service Cloud Voice Toolkit API

**`lightning-service-cloud-voice-toolkit-api`**

A collection of front-end event listeners and API methods for interacting with Service Cloud Voice using the `lightning-service-cloud-voice-toolkit-api` component. This component requires API version 52.0 and later.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Service Cloud Voice Toolkit API is a collection of front-end event listeners and API methods for interacting with the Service Cloud Voice product. This toolkit takes advantage of Einstein Next Best Action to give agents what they need when they need it during a conversation.

To use the Service Cloud Voice Toolkit API in your component:

- Add the `lightning-service-cloud-voice-toolkit-api` component to your component's HTML template file.

<!-- prettier-ignore-start -->
```html
<!-- yourComponent.html -->

<template>
    <lightning-service-cloud-voice-toolkit-api>
    </lightning-service-cloud-voice-toolkit-api>
    ...
</template>
```
<!-- prettier-ignore-end -->

- Include the `lightning__ServiceCloudVoiceToolkitApi` capability in your component’s configuration file, `<component>.js-meta.xml`.

```xml
// yourComponent.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>
  <capabilities>
    <capability>lightning__ServiceCloudVoiceToolkitApi</capability>
  </capabilities>
</LightningComponentBundle>
```

For more information about configuration files, see [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags).

## Service Cloud Voice Events

Make your components context-aware by listening to events that take place during phone calls.

To subscribe to an event, add an event listener. For instance, the following code subscribes and unsubscribes to the `callstarted` event type.

```javascript
// Subscribe
const toolkitApi = this.template.querySelector('lightning-service-cloud-voice-toolkit-api');
toolkitApi.addEventListener('callstarted', <listener>);

// Unsubscribe
const toolkitApi = this.template.querySelector('lightning-service-cloud-voice-toolkit-api');
toolkitApi.removeEventListener('callstarted', <listener>);
```

When an event occurs, your listener function receives a JSON payload that contains the event type, along with any relevant data. For instance, the `callstarted` event contains the following payload.

```
{
  "type":  "callstarted",
  "detail":  {
    "callId":  "d7a9f1b7-fc17-43fe-8ca7-e584a2b34792",
    "callType":  "outbound",
    "participant":  "+1 (415) 999-0000"
  }
}
```

For information about the available events, see [Service Cloud Voice LWC Toolkit API Events](https://developer.salesforce.com/docs/atlas.en-us.voice_developer_guide.meta/voice_developer_guide/voice_lc_toolkit_telephony_lwc.htm).

## Next Best Action

The toolkit provides the `updateNextBestActions` method, which enables your component to give recommendations in real time with Next Best Action.

For more information, see [Service Cloud Voice LWC Toolkit Next Best Action](https://developer.salesforce.com/docs/atlas.en-us.voice_developer_guide.meta/voice_developer_guide/voice_lc_toolkit_nba_lwc.htm).

## See Also

- [Service Cloud Voice ToolkitAPI Sample LWC Component](https://github.com/service-cloud-voice/examples-from-doc/tree/main/ToolkitAPI/SampleLWCComponent)
- [Toolkit API example](https://github.com/service-cloud-voice/examples-from-doc/tree/main/ToolkitAPI)


:::::

:::::tab
::component-specification{component="serviceCloudVoiceToolkitApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c36f25c94c2fd4790e045ea2e2dcf5c6fb2c39e1fa2d2d752b37fce6c57aa644 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/serviceKnowledgeApi/lightning-service-knowledge-api.md -->

# Service Knowledge API (Beta)

**`lightning/serviceKnowledgeApi`**

Work with knowledge articles.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
**note:** `lightning/serviceKnowledgeApi` 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.

The `lightning/serviceKnowledgeApi` module includes a JavaScript method to work with Knowledge APIs.

The module contains this method:

- `updateViewStat({articleOrVersionId: string})`

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-knowledge-update-view-stat.html).

:::::

:::::tab
::component-specification{component="serviceKnowledgeApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=b532218da12da651915b8594518a34ef9d3afc5afc580c212936bc14a5df4e00 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/force/showToast/force-show-toast.md -->

# Show Toast

**`force:showToast`**

Displays page-level toasts.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A toast displays a message below the header at the top of a view. The message is specified by the `message` attribute.

`force:showToast` isn't available on login pages.

This example displays a toast message "Success! The record has been updated successfully."

```javascript
showToast : function(component, event, helper) {
    var toastEvent = $A.get("e.force:showToast");
    toastEvent.setParams({
        "title": "Success!",
        "message": "The record has been updated successfully."
    });
    toastEvent.fire();
}
```

This event is handled by the `one.app` container. It’s supported in Lightning Experience, the Salesforce mobile app, and Aura-based Experience Builder sites.

The background color and icon used by a toast is controlled by the `type` attribute. For example, setting it to `success` displays the toast notification with a green background and checkmark icon. This toast displays for 20000ms, with a close button in the top right corner when the mode attribute is `dismissible`.

While message supports a text-only string, `messageTemplate` supports a string containing links. You can provide a string with placeholders, which are replaced by labels provided in `messageTemplateData`. The parameters are numbered and zero-based. For example, if you have three parameters, `{0}`, `{1}`, and `{2}`, the labels are substituted in the order they're specified. The label is also used for the title attribute on the anchor tag.

This example displays a toast with a message that contains a link.

```javascript
showMyToast : function(component, event, helper) {
    var toastEvent = $A.get("e.force:showToast");
    toastEvent.setParams({
        mode: 'sticky',
        message: 'This is a required message',
        messageTemplate: 'Record {0} created! See it {1}!',
        messageTemplateData: ['Salesforce', {
            url: 'http://www.salesforce.com/',
            label: 'here',
            }
        ]
    });
    toastEvent.fire();
}
```

The following modes are supported.

- `dismissible`: Remains visible until you press the close button or `duration` has elapsed, whichever comes first.
- `pester`: Remains visible until `duration` has elapsed. No close button is displayed.
- `sticky`: Remains visible until you press the close buttons.

We recommend using [`lightning:notificationsLibrary](/docs/platform/lightning-component-reference/guide/lightning-notifications-library.html) for displaying messages in the app via notices and toasts.


:::::

:::::tab
## Attributes

| Name                  | Description                                                                                                                                                                                                                                                                                               | Type     | Default | Required                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------- |
| `duration`            | Length of time the toast is visible for, in milliseconds. Applies to 'dismissible' or 'pester' toast modes. The default is 20000ms. If you provide a value that's less than 20000ms, the value is raised to 20000ms per [WCAG 2.2.1](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html). | integer  |         |                                              |
| `key`                 | Icon to use when toast type is 'other'. Icon keys are available at the Lightning Design System Icons page.                                                                                                                                                                                                | string   |         |                                              |
| `message`             | The message to display in the toast.                                                                                                                                                                                                                                                                      | string   |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `messageTemplate`     | Overwrites message string with the specified message. Requires `messageTemplateData`.                                                                                                                                                                                                                     | string   |         |                                              |
| `messageTemplateData` | An array of text and actions to be used in `messageTemplate`.                                                                                                                                                                                                                                             | object[] |         |                                              |
| `mode`                | The toast mode, which controls how users can dismiss the toast. Valid values are 'pester' and 'sticky'. The default is 'dismissible', which displays the close button.                                                                                                                                    | string   |         |                                              |
| `title`               | Specifies the title for a message to display. The title is shown above the message in a slightly larger font.                                                                                                                                                                                             | string   |         |                                              |
| `type`                | The toast type, which can be 'error', 'warning', 'success', or 'info'. The default is 'other', which is styled like an 'info' toast and doesn’t display an icon, unless specified by the key attribute.                                                                                                   | string   |         |                                              |

:::::

::::::

<!-- document id=c66b3272a5239f3b077c38f618f0ef9b4f0470292091200646d5ba607999de5e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/slider/lightning-slider.md -->


# Slider

**`lightning-slider`**

An input range slider for specifying a value between two specified numbers.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="slider" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-slider` component is a horizontal or vertical slider for
specifying a value between two specified numbers. For example, this slider can
be used to capture user input about order quantity or when you want to use an
input field of `type="range"`. To orient the slider vertically, set
`type="vertical"`. Older browsers that don't support the slider fallback and
treat it as `type="text"`.

Here's an example of a slider with a step increment of 10.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-slider
        label="Volume"
        step="10"
        value={myValue}
        onchange={handleChange}
    >
    </lightning-slider>
    <div class="slds-m-vertical_medium">
        <p>
            The value of the slider is:
            <span class="slds-text-heading_small">{myValue}</span>
        </p>
    </div>
</template>
```
<!-- prettier-ignore-end -->

Handle the `change` event and get the slider value by using the `event.detail` property.

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

export default class SliderExample extends LightningElement {
  myValue = 20; //initial value

  handleChange(event) {
    this.myValue = event.detail.value;
  }
}
```

## Design

`lightning-slider` implements the slider blueprint in the Salesforce Lightning Design System (SLDS). The slider adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Slider](https://v1.lightningdesignsystem.com/components/slider/)                                                                     | [Slider](https://www.lightningdesignsystem.com/components/slider/)                                              |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Input Validation

Client-side input validation is available for this component. Note that a disabled slider is always valid.

To programmatically show error messages on invalid fields, use the `reportValidity()` method.
For custom validity error messages, specify the message using `setCustomValidity()` and `reportValidity()`.

For more information, see the [lightning-input](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Component Styling

Use a combination of variants, sizes, positioning type, and utility classes to customize the slider.

### Variants

Specify the `variant` attribute with one of these values.

- `standard` is the default variant, which includes the text label before the range values and slider
- `label-hidden` hides the text label from view

### Sizes

Specify the `size` attribute with one of these values.

- `x-small` takes up a width of 192px
- `small` takes up a width of 240px
- `medium` takes up a width of 320px
- `large`takes up a width of 400px

The default slider size takes up the width of the view port.

### Positioning Type

Specify the `type` attribute with one of these attributes.

- `horizontal` is the default position type, which places the slider horizontally across the view port
- `vertical` places the slider vertically with a height of 192px

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding above the slider using an SLDS class.

<!-- prettier-ignore-start -->
```html
<div class="slds-p-top_large">
    <lightning-slider label="Volume" step="10" value="20"> </lightning-slider>
</div>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Customize Units and Number Formatting

By default, the slider displays the range after the label as `min-max`, such as `0-100`, and the current value as a plain number. To customize how the range and value appear on the slider, use these attributes:

- `unit` defines a unit label that annotates the range display and value readout, such as `%`. The default is an empty string, which shows the plain range and value with no unit.
- `unit-position` sets the placement of the unit relative to the range and value. Valid values include `suffix` (default) or `prefix`.
- `format-number` is a formatter function that converts each range endpoint and the value readout to text, replacing the built-in formatting. The default is undefined.
- `minimum-fraction-digits` is the minimum number of fractional digits for the range endpoints and value readout, acting as a floor on the step-derived precision. The default is 0.

These attributes changes the range and value labels only. The numeric `value` that you get from the `change` event remains the same. The next section describes each attribute with examples.

### unit

To annotate both the range and the value readout with a unit label, specify the `unit` attribute. The unit can be any string, such as a symbol (`%`, `$`, `°C`) or an abbreviation (`MB`).

The string unit is used exactly as provided, so include a leading space if you want to separate the unit from the number, such as `unit=" pts"`.

This example displays the range as `0-100%` and a value of 50 as `50%`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-slider label="Volume" value="50" unit="%"> </lightning-slider>
</template>
```
<!-- prettier-ignore-end -->

### unit-position

To control where the unit appears relative to the number, specify the `unit-position` attribute with these values:

- `suffix` places the unit after the number, such as `50%`. `suffix` is the default.
- `prefix` places the unit before the number, such as `$50`. Use `prefix` for currency symbols, if the symbol must appear before the number.

This example displays the range as `$0-500` and a value of 250 as `$250`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-slider
        label="Price"
        min="0"
        max="500"
        value="250"
        unit="$"
        unit-position="prefix"
    >
    </lightning-slider>
</template>
```
<!-- prettier-ignore-end -->

### minimum-fraction-digits

To set the minimum number of digits to display after the decimal point, specify the `minimum-fraction-digits` attribute. The effective number of decimal places is the greater of the `minimum-fraction digits` and the `step` attribute. Use `minimum-fraction-digits` to force a consistent decimal display, such as for a decimal field whose step is a whole number.

When you set `minimum-fraction-digits` to a value greater than 0, the range display becomes asymmetric; the minimum endpoint stays bare and the maximum endpoint carries the decimals. This example displays the range as `0-1500.0` and a value of 1500 as `1,500.0`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-slider
        label="Amount"
        min="0"
        max="1500"
        value="1500"
        minimum-fraction-digits="1"
    >
    </lightning-slider>
</template>
```
<!-- prettier-ignore-end -->

A finer `step` takes precedence over the floor. For example, with `step="0.05"` and `minimum-fraction-digits="1"`, the maximum reads with two decimal places, such as `0-1.00`.

### format-number

The `format-number` attribute takes a formatter function with the signature `(numericValue) => string`. The function provides the number-to-text conversion for each range endpoint and for the value readout, replacing the slider's built-in step-precision formatting. Any `unit` and `unit-position` decoration is then applied around the function's output. Use `format-number` to inject domain- or locale-specific formatting, such as compact currency, without teaching the slider about currencies or locales.

Because `format-number` is a function rather than a string, bind it as a property with the `{}` syntax instead of a static attribute value.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-slider
        label="Budget"
        min="0"
        max="1000000"
        value="250000"
        format-number={currencyFormatter}
    >
    </lightning-slider>
</template>
```
<!-- prettier-ignore-end -->

Define the formatter in your JavaScript. This example uses `Intl.NumberFormat` with compact notation to render a value of 250000 as `$250K`, with the range showing `$0-$1M`.

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

export default class SliderExample extends LightningElement {
  currencyFormatter = (value) =>
    new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: "USD",
      notation: "compact",
      maximumFractionDigits: 1,
    }).format(value);
}
```

If you combine `format-number` with `unit`, the unit decorates the formatter's output. For example, a formatter that returns `#50` with `unit=" pts"` produces `#50 pts`.

## Usage Considerations

Use the `change` event to detect changes to the slider value instead of the `blur`
event. Browsers such as Safari don't give focus to the slider so the `blur` event doesn't fire.

By default, the `min` and `max` values are 0 and 100, but you can specify your
own values. If you specify your own step increment value, you can drag the
slider based on the step increment only. If you set the value lower than the
`min` value, then the value is set to the `min` value. Similarly, setting the
value higher than the `max` value results in the value being set to the `max`
value.

For precise numerical values, we recommend using the `lightning-input`
component of `type="number"` instead.


:::::

:::::tab
::component-specification{component="slider" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=965f21c8a468fec671d885f92ca022c2bf9b97a007b4c9d7ac841b0b293f6f90 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/spinner/lightning-spinner.md -->


# Spinner

**`lightning-spinner`**

Displays an animated spinner.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="spinner" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-spinner` displays an animated spinner image to indicate that a
feature is loading. This component can be used when retrieving data or anytime
an operation doesn't immediately complete.

The `variant` attribute changes the appearance of the spinner. If you set
`variant="brand"`, the spinner matches the Lightning Design System brand
color. Setting `variant="inverse"` displays a white spinner. The default
spinner color is dark blue.

## Design

`lightning-spinner` implements the spinner blueprint in the Salesforce Lightning Design System (SLDS). The spinner adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Spinner](https://v1.lightningdesignsystem.com/components/spinners/)                                                                  | [Spinner](https://www.lightningdesignsystem.com/components/spinners/)                                           |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

Here is an example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-spinner variant="brand" size="large"> </lightning-spinner>
</template>
```
<!-- prettier-ignore-end -->

`lightning-spinner` is intended to be used conditionally. You can use
`if:true` and `if:false` or the Lightning Design System utility classes to show or hide the spinner.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button label="Toggle" variant="brand" onclick={toggle}>
    </lightning-button>

    <div class="slds-m-around_large">
        <p if:true={isLoaded}>Content has been loaded.</p>

        <div if:false={isLoaded} class="slds-is-relative">
            <lightning-spinner alternative-text="Loading...">
            </lightning-spinner>
        </div>
    </div>
</template>
```
<!-- prettier-ignore-end -->

The `toggle()` function toggles the boolean value of the `isLoaded` variable.

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

export default class DemoSpinner extends LightningElement {
  @api isLoaded = false;

  // change isLoaded to the opposite of its current value
  toggle() {
    this.isLoaded = !this.isLoaded;
  }
}
```

## Component Styling

Use a combination of variants, sizes, and utility classes to customize the slider.

### Variants

Specify the `variant` attribute with one of these values.

- `base` is the default variant, which shows a gray animated spinner
- `brand` shows a blue animated spinner
- `inverse` shows a white animated spinner, for use on a darker background

### Sizes

Specify the `size` attribute with one of these values.

- `xx-small` takes up a width of 8px
- `x-small` takes up a width of 16px
- `small` takes up a width of 20px
- `medium` is the default variant, which takes up a width of 32px
- `large` takes up a width of 44px

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.


:::::

:::::tab
::component-specification{component="spinner" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=2aa32229283c43163d99d90d47f9f1c3038401a4f78eebdfc88b085c1874d2ca url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/systemError/aura-system-error.md -->

# System Error

**`aura:systemError`**

Indicates that an error has occurred.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when an error is encountered during the execution of a server-side action. Handle this event using the `aura:handler` tag.

```xml
<aura:handler event="aura:systemError" action="{!c.handleError}" />
```

This example shows a button that triggers an error and a handler for the `aura:systemError` event.

```xml
<aura:component controller="myController">
  <aura:handler event="aura:systemError" action="{!c.showSystemError}" />
  <aura:attribute name="response" type="Aura.Action" />
  <!-- Other component markup here -->
  <lightning:button aura:id="trigger" label="Trigger error" onclick="{!c.trigger}" />
</aura:component>
```

This client-side controller triggers the firing of an error and handles that error.

```javascript
({
  trigger: function (cmp, event) {
    // Call an Apex controller that throws an error
    var action = cmp.get("c.throwError");
    action.setCallback(cmp, function (response) {
      cmp.set("v.response", response);
    });
    $A.enqueueAction(action);
  },
  showSystemError: function (cmp, event) {
    // Handle system error
  },
});
```


:::::

:::::tab
## Attributes

| Name      | Description                                  | Type   | Default | Required |
| --------- | -------------------------------------------- | ------ | ------- | -------- |
| `error`   | The system error that's returned.            | string |         |          |
| `message` | The message to be displayed during an error. | string |         |          |

:::::

::::::

<!-- document id=37cb50c313da55eef69033fcfca3dfa00167e6735b3468d9004729e375eb3c14 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/tab/lightning-tab.md -->

# Tab

**`lightning-tab`**

A single tab in a tabset component.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

A `lightning-tab` component keeps related content in a single container. The tab content is visible when you click the tab. Use `lightning-tab`
as a child of the [`lightning-tabset`](/docs/platform/lightning-component-reference/guide/lightning-tabset.html) component.

Use the `label` attribute to specify the tab's text label.

To append an icon at the beginning of the label, use the `icon-name` attribute. Provide alternative text for the icon by using `icon-assistive-text`.

To append an icon at the end of the label, use the `end-icon-name` attribute. Provide alternative text for that icon by using `end-icon-alternative-text`.

Specify the `show-error-indicator` attribute to include an error indicator in the tab after the label. If an end icon is present, the error indicator is appended after the icon.

## Design

Use `lightning-tab` within `lightning-tabset`, which implements the tabs blueprint in the Salesforce Lightning Design System (SLDS). The tabs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Tabs](https://v1.lightningdesignsystem.com/components/tabs/)                                                                         | [Tabs](https://www.lightningdesignsystem.com/components/tabs/)                                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

Tab content is lazy loaded. You can only query the content for the active and previously active tabs.

See [`lightning-tabset`](/docs/platform/lightning-component-reference/guide/lightning-tabset.html) for more
information.

You can nest `lightning-tab` within other elements, such as `<div>` or `<template>`, for example to render tabs conditionally using `if:true` and `if:false`. Otherwise, you must nest
`lightning-tab` directly within `lightning-tabset` tags.

For example, you want to show a tab conditionally.

<!-- prettier-ignore-start -->
```html
<lightning-tabset>
    <lightning-tab label="Item One"> Content for tab 1 </lightning-tab>
    <template if:true={showTabTwo}>
        <lightning-tab label="Item Two"> Content for tab 2 </lightning-tab>
    </template>
</lightning-tabset>
```
<!-- prettier-ignore-end -->

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`active`**

The event fired when a tab becomes active.

The event properties are as follows.

| Property   | Value | Description                                                                |
| ---------- | ----- | -------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                     |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched. |


:::::

:::::tab
::component-specification{component="tab" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=5dc291b51a1090c45ba6b512e20db80a08afe7b95c9ba964818c847443c02180 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabClosed/aura-tab-closed.md -->

# Tab Closed

**`lightning:tabClosed`**

Fires when a Console workspace or subtab has been successfully closed.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabClosed` is an application event that indicates a tab has been closed successfully. This event is supported in Lightning console apps only.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabClosed" action="{! c.onTabClosed }" />
</aura:component>
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name    | Description        | Type   | Default | Required                                     |
| ------- | ------------------ | ------ | ------- | -------------------------------------------- |
| `tabId` | The closed tab ID. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=38ee7a621f77ba71afbaf140e8cfa9014d85d674480920c0a5f861aab89c9293 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabCreated/aura-tab-created.md -->

# Tab Created

**`lightning:tabCreated`**

Fires when a Console workspace or subtab has been successfully created.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabCreated` is an application event that indicates a tab has been created successfully. This event is supported in Lightning console apps only.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabCreated" action="{! c.onTabCreated }" />
</aura:component>
```

In your client-side controller, retrieve the ID of the new tab and set a label on the tab.

```javascript
({
  onTabCreated: function (component, event, helper) {
    var newTabId = event.getParam("tabId");
    var workspace = component.find("workspace");
    workspace.setTabLabel({
      tabId: newTabId,
      label: "New Tab",
    });
  },
});
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name    | Description               | Type   | Default | Required                                     |
| ------- | ------------------------- | ------ | ------- | -------------------------------------------- |
| `tabId` | The newly created tab ID. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=793aaa75897a34f4395e7bb5c9e602002bb10cedfe2487b48ab3433bd868747a url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabFocused/aura-tab-focused.md -->

# Tab Focused

**`lightning:tabFocused`**

Fires when a Console workspace or subtab is focused.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabFocused` is an application event that indicates a successful tab focus change. The event fires when any tab is successfully focused. This event is supported only in Lightning console apps.

`lightning:tabFocused` fires whenever a user selects a workspace tab or subtab, so console navigation users frequently trigger this application event in typical use. This event also fires when going from a tab to a navigation item, or going from a navigation item to a tab.

Aura application events notify all listeners registered in the default phase, including listeners in background tabs. Multiple listeners responding at the same time can impact performance.

To minimize performance impact, use a [background utility item](/docs/platform/lightning-component-reference/guide/aura-background-utility-item.html) as the only listener, or use a custom component event instead.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabFocused" action="{! c.onTabFocused }" />
</aura:component>
```

In your client-side controller, retrieve the ID of the tab that's currently focused.

```javascript
({
  onTabFocused: function (component, event, helper) {
    var focusedTabId = event.getParam("currentTabId");
    var workspaceAPI = component.find("workspace");
    workspaceAPI.getTabInfo({
      tabId: focusedTabId,
      callback: function (error, response) {
        console.log(response);
      },
    });
  },
});
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name            | Description                    | Type   | Default | Required                                     |
| --------------- | ------------------------------ | ------ | ------- | -------------------------------------------- |
| `currentTabId`  | The currently focused tab ID.  | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `previousTabId` | The previously focused tab ID. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=2d8cb55254595c1b02f4aa717062ea4627c647b2d9d1f556b361912450af14f1 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabRefreshed/aura-tab-refreshed.md -->

# Tab Refreshed

**`lightning:tabRefreshed`**

Fires when a Console workspace or subtab has been successfully refreshed.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabRefreshed` is an application event that indicates a tab has been refreshed successfully. This event is supported in Lightning console apps only.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabRefreshed" action="{! c.onTabRefreshed }" />
</aura:component>
```

In your client-side controller, retrieve the ID of the tab that's refreshed.

```javascript
({
  onTabRefreshed: function (component, event, helper) {
    var refreshedTabId = event.getParam("tabId");
    var workspaceAPI = component.find("workspace");
    workspaceAPI.getTabInfo({
      tabId: refreshedTabId,
      callback: function (error, response) {
        console.log(response);
      },
    });
  },
});
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name    | Description                     | Type   | Default | Required                                     |
| ------- | ------------------------------- | ------ | ------- | -------------------------------------------- |
| `tabId` | The currently refreshed tab ID. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=e594e877749315c86ad516915e0f5516eae68df080a29a2957b1eefec59d4f4c url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabReplaced/aura-tab-replaced.md -->

# Tab Replaced

**`lightning:tabReplaced`**

Fires when a Console primary tab or subtab has been successfully replaced, such as when saving a new record and the create form is replaced with the newly created Record Home.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabReplaced` is an application event that indicates a tab has been replaced successfully. This event is supported in Lightning console apps only.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabReplaced" action="{! c.onTabReplaced }" />
</aura:component>
```

In your client-side controller, retrieve the ID of the replaced tab.

```javascript
({
    onTabReplaced : function(component, event, helper) {
        var replacedTabId = event.getParam("tabId");
        var workspaceAPI = component.find("workspace");
        workspaceAPI.getTabURL({
            tabId : replacedTabId;
            callback : function(error, response){
                console.log(response);
            }
        });
    }
})
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name    | Description                  | Type   | Default | Required                                     |
| ------- | ---------------------------- | ------ | ------- | -------------------------------------------- |
| `tabId` | The ID of the refreshed tab. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=c354bf7bae6c85e92eff08ce77a3a82e5912873abf88f721617dd8782c5cf2ef url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/tabUpdated/aura-tab-updated.md -->

# Tab Updated

**`lightning:tabUpdated`**

Fires when a Console workspace or subtab has been updated, such as when a label, icon, or content changes.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

`lightning:tabUpdated` is an application event that indicates a tab has been updated successfully. This event is supported in Lightning console apps only.

Handle the event using `aura:handler`.

```html
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
  <lightning:workspaceAPI aura:id="workspace" />
  <aura:handler event="lightning:tabUpdated" action="{! c.onTabUpdated }" />
</aura:component>
```

In your client-side controller, retrieve the ID of the updated tab.

```javascript
({
  onTabUpdated: function (component, event, helper) {
    var updatedTabId = event.getParam("tabId");
    console.log(updatedTabId);
  },
});
```

For more information, see the [Salesforce Console Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_console.meta/api_console/).


:::::

:::::tab
## Attributes

| Name    | Description                         | Type   | Default | Required                                     |
| ------- | ----------------------------------- | ------ | ------- | -------------------------------------------- |
| `tabId` | The ID of the tab that was updated. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=82533919e7d5b73acc000743c290d0e12c2675e5a61de2c8c98c08b10aa838fb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/tabset/lightning-tabset.md -->


# Tabset

**`lightning-tabset`**

Represents a list of tabs.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="tabset" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-tabset` shows a tabbed container with multiple content areas,
only one of which is visible at a time. Tabs are shown horizontally inline
with content shown below it, by default. Use tabs to separate information into logical sections based on functionality or use case.

A tabset can hold multiple [`lightning-tab`](/docs/platform/lightning-component-reference/guide/lightning-tab.html) components as part of its body. The first tab is activated by default.

## Design

`lightning-tabset` implements the tabs blueprint in the Salesforce Lightning Design System (SLDS). The tabs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Tabs](https://v1.lightningdesignsystem.com/components/tabs/)                                                                         | [Tabs](https://www.lightningdesignsystem.com/components/tabs/)                                                  |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

Use `lightning-tabset` to enable users to switch easily between tabs to perform tasks without leaving the page. Assign a default tab based on the most important use case for the page.

Here's an example of a standard horizontal tabset.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tabset>
        <lightning-tab label="Tab One"> Content of Tab One </lightning-tab>
        <lightning-tab label="Tab Two"> Content of Tab Two </lightning-tab>
    </lightning-tabset>
</template>
```
<!-- prettier-ignore-end -->

We don't recommend by using tabs to define a linear, ordered process since each tab functions independently of the others.

Tab labels must be consistent. For example, use a verb to let users identify a tab's purpose quickly.

`lightning-tabset` doesn’t currently support mobile-oriented tabs. This component doesn’t adjust the tab styling when there are two or more immediately adjacent tab sets on mobile.

## Add Content To Tab Programmatically

To add content programmatically to the tab body, use the `onactive` event handler on `lightning-tab`.
Here's an example with two tabs, which loads content when the tabs are selected.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tabset>
        <lightning-tab label="Item One" value="1" onactive={handleActive}>
            Here's the content for Item One: {tabContent}
        </lightning-tab>
        <lightning-tab label="Item Two" value="2" onactive={handleActive}>
            Here's the content for Item Two: {tabContent}
        </lightning-tab>
    </lightning-tabset>
</template>
```
<!-- prettier-ignore-end -->

Identify the active tab by using `event.target.value`.

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

export default class ActiveTabExample extends LightningElement {
  tabContent = "";

  handleActive(event) {
    const tab = event.target;
    this.tabContent = `Tab ${event.target.value} is now active`;
  }
}
```

## Component Styling

Set the `variant` attribute to change the look of the tabset. The `variant` attribute can be set to `default`, `scoped`, or `vertical`.

Use a combination of the `variant` and `class` attributes to customize the tab content styles.

### Variants

Specify the `variant` attribute with one of these values.

- `default` creates global tabs. When you select a tab, its content replaces the content of the previously selected tab. The default variant tab encapsulates the content underneath it without enclosing it visually.

- `scoped` creates a tab set that has a closed container with a defined border. Scoped tabs are useful for stacking several tabbed sections, where you want to change only a portion of the content to show. When you click those tabs, the content at the bottom remains the same while the content at the top changes for the activity.

- `vertical` resembles the scoped variant in appearance, but the tabs appear vertically to the side instead of on the top.

You can nest scoped tabs within a global tab set, but don't nest global tabs. If additional hierarchy is necessary, consider using a [`lightning-tree` component](/docs/platform/lightning-component-reference/guide/lightning-tree.html).

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds a gray background and padding to the content area on the first tab by using SLDS classes.

<!-- prettier-ignore-start -->
```html
<lightning-tabset>
    <lightning-tab label="Item One" class="slds-theme_shade">
        <p class="slds-p-left--small">Hello Tab 1!</p>
    </lightning-tab>
    <lightning-tab label="Item Two"> </lightning-tab>
</lightning-tabset>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

When a tabset contains more tabs than can fit in the viewport, the extra tabs are moved into an overflow dropdown menu next to the last visible tab. The active tab always shows and is never moved into the overflow.

Truncating the tab label isn't supported. When the tab label has more characters than can fit the viewport, the extra characters are not truncated but are hidden from view.

You can nest `lightning-tab` within other elements such as `<div>` or `<template>`, for example to render tabs conditionally by using `if:true` and `if:false`. Otherwise, you must nest
`lightning-tab` directly within `lightning-tabset` tags.

Tab content is lazy loaded; only the active and previously
active tabs content is queryable. In the example, the text `Content of Tab Two` is inserted in the DOM of the page only when the second tab is selected.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Accessibility

Use the Tab or arrow keys to navigate to the More menu that’s created when the viewport is too narrow to show all the tabs.

Several attributes enable accessibility features for a tabset heading.

Use `heading-label` to specify custom assistive text for a tabset heading. The value of `heading-label` is rendered as the text content of a `div` element with `role="heading"` and `aria-level="2"`. If you don't specify `heading-label` the default assistive text is "Tabs" in a `div` element with `aria-level="2"`.

Use `heading-level` to pass a value between 1 and 6 to the rendered `aria-level` attribute. The default value is 2. This attribute requires you to also specify `heading-label`.

Specify `heading-visible` to display the assistive text above the tabset when you specify `heading-label`. By default, this attribute is not present so the assistive text is read by screen readers but isn't displayed. When `heading-visible` is present, the assistive text is read by screen readers and displayed.

This example sets custom assistive text for a heading, specifies `heading-level` to change the rendered `aria-level`, and makes the heading visible.

<!-- prettier-ignore-start -->
```html
<template>
  <lightning-tabset heading-label="Example tabset" heading-level="3" heading-visible>
    <lightning-tab label="Item One"> One Content! </lightning-tab>
    <lightning-tab label="Item Two"> Two Content! </lightning-tab>
  </lightning-tabset>
</template>
```
<!-- prettier-ignore-end -->


:::::

:::::tab
::component-specification{component="tabset" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=ead8363482de54d549424ce0b58ac61193a3d8718e78fbf8ae89bdc0a95d4187 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/textarea/lightning-textarea.md -->


# Textarea

**`lightning-textarea`**

Represents a multiline text input field.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="textarea" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-textarea` component creates an HTML `textarea` element for
entering multi-line text input. A text area holds an unlimited number of
characters.

To set the input for the text area, specify its value using the `value` attribute. Setting this value overwrites any initial value that's provided.

This example creates a text area with a maximum length of 300 characters.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        value="initial value"
        label="What are you thinking about?"
        max-length="300"
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-textarea` implements the textarea blueprint in the Salesforce Lightning Design System (SLDS). The textarea adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Textarea](https://v1.lightningdesignsystem.com/components/textarea/)                                                                 | [Textarea](https://www.lightningdesignsystem.com/components/textarea/)                                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

In many browsers, the text area is resizable by default, and a vertical scrollbar is displayed when the content exceeds the number of rows. Consider these limitations:

- Specifying the `rows` and `cols` attributes isn't supported.
- Specifying the CSS width and height properties isn't supported.

You can define a function in JavaScript to handle input events like
`blur`, `focus`, and `change`. For example, to handle a `change` event on
the component, use the `onchange` attribute.

To retrieve the content of the text area field, use `event.detail.value` property.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        name="myTextArea"
        value="initial value"
        label="What are you thinking about?"
        onchange={countLength}
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

Client-side input validation is available for this component. Set a maximum
length using the `maxlength` attribute or a minimum length using the
`minlength` attribute. An error message is automatically displayed in these cases:

- A required field is empty when `required` is present on the `lightning-textarea` tag.
- The input value contains fewer characters than that specified by the `minlength` attribute.
- The input value contains more characters than that specified by the `maxlength` attribute.

To check the validity states of an input, use the `validity` attribute, which
is based on the `ValidityState` object. You can access the validity states in
your JavaScript. This `validity` attribute returns an object with
`boolean` properties. For more information, see the
[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

You can override the default message by providing your own values for
`message-when-value-missing`, `message-when-bad-input`, `message-when-too-long`, or
`message-when-too-short`.

For example, provide an error message when a required field's value is missing.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea
        name="myText"
        label="Your Name"
        message-when-value-missing="This field is required."
        required
    >
    </lightning-textarea>
</template>
```
<!-- prettier-ignore-end -->

## Insert Text Programmatically

You can insert text programmatically in the text area with the `setRangeText()` method, replacing content
or inserting new content.

The `setRangeText()` method follows the API of the standard `HTMLInputElement.setRangeText()` method described on
[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setRangeText).

`setRangeText()` supports these parameters.

| Parameter   | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| replacement | string | The string to insert.                                         |
| start       | number | The 0-based index of the first character to replace.          |
| end         | number | The 0-based index that follows the last character to replace. |
| selectMode  | string | Defines how the selection is set after the text is inserted.  |

Valid values for selectMode are:

- `select` - Selects the inserted text. The text area must have focus when `setRangeText()` is called.
- `start` - Moves the selection to just before the inserted text.
- `end` - Moves the selection to just after the inserted text.
- `preserve` - Attempts to preserve the selection in effect before the insertion. This is the default.

To insert replacement text at the current cursor location, specify only the
replacement string and no other parameters. After the insertion, the cursor
remains in the original location. If text is selected when the insertion occurs,
the text is replaced.

This example uses `setRangeText()` to insert some text at the beginning of the line
without replacing any content.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea placeholder="Type something interesting">
    </lightning-textarea>
    <lightning-button label="Insert Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Setting the start and end values to 0 begins the insertion with the character at
index 0, but ends at the character before index 0. The result is that no characters are
replaced, and the text is inserted in front of the character at index 0.

The selectMode value `select` causes the inserted content to be selected. Call the `focus()`
method before `setRangeText()` to enable the selection.

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

export default class SetRangeTextExample extends LightningElement {
  start = 0;
  end = 0;
  selectMode = "select";

  handleClick() {
    const textarea = this.template.querySelector("lightning-textarea");
    textarea.focus();
    textarea.setRangeText("Some new text", this.start, this.end, this.selectMode);
  }
}
```

This example inserts a space at index 10 and removes characters at index 10 through 14.
The resulting content of the text area is `0123456789 567890`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-textarea value="012345678901234567890"> </lightning-textarea>
    <lightning-button label="Clip Text" onclick={handleClick}>
    </lightning-button>
</template>
```
<!-- prettier-ignore-end -->

You can omit the final parameter of `setRangeText()` to use the default select mode, `preserve`.

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

export default class SetRangeTextExample extends LightningElement {
  handleClick() {
    const textarea = this.template.querySelector("lightning-textarea");
    textarea.setRangeText(" ", 10, 15);
  }
}
```

These examples describe the insertion behavior with various `setRangeText()`parameter values.

```javascript
// Insert text at cursor position. Replace any selected text.
textarea.setRangeText("Some new text");

// Insert text to replace characters beginning at index 10 (the 11th
// character) and ending at index 15 (the 16th character). The character
// at index 14 is the last character replaced.
// No selectMode is specified, so the original selection is preserved.
textarea.setRangeText("Some new text", 10, 15);

// Set focus on the text area.
// Insert text as described in the previous example, and then select
// the new text.
textarea.focus();
textarea.setRangeText("Some new text", 10, 15, "select");

// Insert text as described, and place cursor ahead of the new text.
textarea.setRangeText("Some new text", 10, 15, "start");

// Insert text as described, and place cursor after the new text.
textarea.setRangeText("Some new text", 10, 15, "end");

// Insert text as described, and return to the previous selection state.
textarea.setRangeText("Some new text", 10, 15, "preserve");
```

If text is selected when selectMode is `preserve` and start and end values are specified,
the text insertion has no effect on the selected text. The text remains selected and is not replaced.

## Autocomplete Support

Textarea fields can be autofilled, based on your browser's support of the feature.
The `autocomplete` attribute passes through its value to the browser.

See [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for more information.

## Component Styling

Use a combination of variants and utility classes to customize your textarea field.

### Variants

Specify the `variant` attribute with one of these values.

- `standard` is the default variant, which shows the text label above the textarea field
- `label-hidden` hides the text label from view, but makes it available to assistive technology
- `label-inline` horizontally aligns the text label and textarea field
- `label-stacked` places the label above the textarea field

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

This example adds padding on top of the textarea using an SLDS class.

<!-- prettier-ignore-start -->
```html
<lightning-textarea class="slds-p-top_small" label="Enter comments">
</lightning-textarea>
```
<!-- prettier-ignore-end -->

### Styling Hooks

Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component 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) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-textarea` determines the width of the field using the container's layout. Providing your own width on the component isn't recommended as the component is then no longer responsive to the change on the container's layout, such as when the browser is resized.

End users can resize the text area vertically by default on browsers that support it. You can't disable resizing using the `resize` CSS property. End users can't resize read-only text area fields.

To prevent users from resizing the field more than a specific width or height, pass in your custom class using the `class` attribute with the `max-width` and `max-height` CSS properties. Using these CSS properties on a read-only field isn't supported.

When working with `lightning-textarea`, consider these usage guidelines.

- Use `lightning-textarea` component with the `disabled` or `read-only` attribute, but not both simultaneously. Applying both `disabled` and `read-only` attributes to the component can result in unexpected behavior.
- When you specify `read-only`, the component displays with a bottom border only. The height of the component can't be changed. Using a styling hook to override the minimum height is also not supported for read-only text area fields. The component determines the height based on the amount of text content in `value`. Specify `read-only` if you want to prevent users from modifying the field, but still allow for interaction, which includes being able to tab into the field, place focus and set `.focus()`, and submit the field `value` with the form.
- When you specify `disabled`, the text area is grayed out, but you can adjust the height of the text area. Specify `disabled` to prevent users from interacting with the text area. In a disabled text area, you can't gain focus or set focus programmatically using `.focus()`. The disabled field value is excluded from form submission.
- The vertical scrollbar is displayed only when `lightning-textarea` is either `disabled` or editable, and when the content exceeds the text area's height. Scrollbars do not appear when `read-only` property is applied, as height is determined by the amount of text content in `value`.

## Accessibility

Use the `label` attribute to identify the text area for users of assistive technology.
The `label` attribute creates an HTML label element on the input element. To hide a
label from view and make it available to assistive technology, use the `label-hidden` variant.

When the character count provided by `maxlength` is reached, the component renders an error message
as assistive text with `role="alert"`, which notifies users of assistive technologies that the limit is reached.


:::::

:::::tab
::component-specification{component="textarea" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=4c6a37cc0ab6aa9e3b6ff0a191598a500c3a4ba032761a993176dd302bfcf838 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/forceCommunity/themeLayout/forceCommunity-theme-layout.md -->

# Theme Layout

**`forceCommunity:themeLayout`**

Represents the layout for a theme and hosted inside the Experience Builder.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

A custom theme layout transforms the appearance and overall structure of the pages in the Customer Service template. To appear in Experience Builder as a custom theme layout component, a component must implement the `forceCommunity:themeLayout` interface.

Explicitly declare `{!v.body}` in your code to ensure that your theme layout includes the content layout. Add `{!v.body}` wherever you want the page’s contents to appear within the theme layout. To create a custom theme layout that reuses the existing components in the Template Header region, declare the `search`, `profileMenu`, or `navBar` attributes.

Here's the sample code for a simple theme layout.

```
<aura:component implements="forceCommunity:themeLayout" access="global" description="Sample Custom Theme Layout">
    <aura:attribute name="search" type="Aura.Component[]" required="false"/>
    <aura:attribute name="profileMenu" type="Aura.Component[]" required="false"/>
    <aura:attribute name="navBar" type="Aura.Component[]" required="false"/>
    <aura:attribute name="newHeader" type="Aura.Component[]" required="false"/>
    <div>
        <div class="searchRegion">
            <!-- Search Publisher component -->
            {!v.search}
        </div>
        <div class="profileMenuRegion">
            <!-- User Profile Menu component -->
            {!v.profileMenu}
        </div>
        <div class="navigation">
            <!-- Navigation Menu component -->
            {!v.navBar}
        </div>
        <div class="newHeader">
            {!v.newHeader}
        </div>
        <div class="mainContentArea">
            {!v.body}
        </div>
    </div>
</aura:component>
```

Mark your resources, such as a component, with `access="global"` to make the resource usable outside of your own org. For example, if you want a component to be usable in an installed package or by a Lightning App Builder user or a Experience Builder user in another org.

You can add components to the regions in your markup or leave regions open for users to drag-and-drop components into. Attributes declared as `Aura.Component[]` and included in your markup are rendered as open regions in the theme layout that users can add components to.

Next, you can expose theme layout properties in Experience Builder by adding a design resource to your bundle. Design resources must be named `componentName.design`.

```
<design:component label="Small Header">
    <design:attribute name="blueBackground" label="Blue Background"/>
    <design:attribute name="smallLogo" label="Small Logo"/>
</design:component>
```

Implement the properties in the component.

```
<aura:component implements="forceCommunity:themeLayout" access="global" description="Small Header">
    <aura:attribute name="blueBackground" type="Boolean" default="false"/>
    <aura:attribute name="smallLogo" type="Boolean" default="false" />
    ...
```

If you experience overlapping issues with positioned elements, such as dialog boxes, you can apply additional styling to your CSS resource in the bundle.

For more information, see [Using Components](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/components_using_intro.htm) in the Lightning Components Developer Guide.


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=b25668ccab44a3c75e86640560db96453f62d42656b55ef8664130cbaf788fc6 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/tile/lightning-tile.md -->


# Tile

**`lightning-tile`**

A grouping of related information associated with a record.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="tile" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-tile` component groups related information associated with a
record. The information can be actionable and paired with a figure, such as a
`lightning-icon` or `lightning-avatar` component.

Here's an example.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tile label="Lightning component team" href="/path/to/somewhere">
        <p class="slds-truncate" title="7 Members">7 Members</p>
    </lightning-tile>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-tile` implements the tiles blueprint in the Salesforce Lightning Design System (SLDS). The tiles adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Tiles](https://v1.lightningdesignsystem.com/components/tiles/)                                                                       | [Tiles](https://www.lightningdesignsystem.com/components/tiles/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

To insert an icon or avatar, pass it into the `media` slot. You can
create a tile with an icon by using definition lists. This example aligns an icon
and some text by using utility classes like `slds-dl_horizontal`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tile label="Salesforce UX" href="/path/to/somewhere" type="media">
        <span slot="media">
            <lightning-icon
                icon-name="standard:groups"
                alternative-text="Groups"
            >
            </lightning-icon>
        </span>
        <dl class="slds-dl_horizontal">
            <dt class="slds-dl_horizontal__label">
                <p class="slds-truncate" title="Company">Company:</p>
            </dt>
            <dd class="slds-dl_horizontal__detail slds-tile__meta">
                <p class="slds-truncate" title="Salesforce">Salesforce</p>
            </dd>
            <dt class="slds-dl_horizontal__label">
                <p class="slds-truncate" title="Email">Email:</p>
            </dt>
            <dd class="slds-dl_horizontal__detail slds-tile__meta">
                <p class="slds-truncate" title="salesforce-ux@salesforce.com">
                    salesforce-ux@salesforce.com
                </p>
            </dd>
        </dl>
    </lightning-tile>
</template>
```
<!-- prettier-ignore-end -->

You can also create a list of tiles with avatars by using an unordered list.
This example places tiles in a list and creates dividers by using utility classes
like `slds-has-dividers_bottom-space`.

<!-- prettier-ignore-start -->
```html
<template>
    <ul class="slds-has-dividers_bottom-space">
        <li class="slds-item">
            <lightning-tile
                type="media"
                label="Astro"
                href="/path/to/somewhere"
            >
                <span slot="media">
                    <lightning-avatar
                        src="/path/to/img"
                        alternative-text="Astro"
                        fallback-icon-name="standard:person_account"
                    >
                    </lightning-avatar>
                </span>
                <ul class="slds-list_horizontal slds-has-dividers_right">
                    <li class="slds-item">Trailblazer, Salesforce</li>
                    <li class="slds-item">Trailhead Explorer</li>
                </ul>
            </lightning-tile>
        </li>
        <!-- More list items here -->
    </ul>
</template>
```
<!-- prettier-ignore-end -->

You can add a dropdown menu with actions to a tile. To find out which sections are active, use the `actiontriggered` event.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tile
        label="My Open Cases"
        href="/path/to/my-open-cases"
        actions={actions}
        onactiontriggered={handleAction}
    >
        <p class="slds-truncate" title="10 Cases">10 Cases</p>
    </lightning-tile>
</template>
```
<!-- prettier-ignore-end -->

Use the `detail` property to return the selected action.

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

export default class DemoTileAction extends LightningElement {
  @track actions = [
    { label: "Edit", value: "edit", iconName: "utility:edit" },
    { label: "Delete", value: "delete", iconName: "utility:delete" },
  ];

  handleAction(event) {
    // Get the value of the selected action
    const tileAction = event.detail.action.value;
  }
}
```

## Component Styling

Use a combination of tile types and utility classes to customize the tile.

### Tile Types

Specify the `type` attribute with one of these values.

- `standard` is the default type, which shows a tile without an image or icon
- `media` shows a tile with an image or icon that's passed into `slot="media"`

### Utility Classes

To style the tile body, use the Lightning Design System utility classes.

## Design Guidelines

A tile requires a label and can include a supporting icon or avatar, and additional elements. You interact with elements within the tile, such as buttons and links, not the tile as a whole. Data is presented as label­-value pairs. The user interacts with elements within the tile, such as buttons and links, not the tile as a whole.

Use tiles when you’re horizontally constrained for space. Tiles are appropriate for short lists, using a `<ul>` or `<dl>` for example, that are fewer than 10 items. Tile layouts don't stretch well, so to use available horizontal space, add a column of tiles. On wider screens where more than 2 columns of tiles appear, tile lists responsively expand into tables.

## Usage Considerations

Icons aren't available in Lightning Out, but they're available in Lightning Components for Visualforce and other experiences.

This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide.

## Custom Events

**`actiontriggered`**

The event fired when an action on the dropdown menu is triggered.

The `actiontriggered` event returns the following parameter.

| Parameter | Type   | Description          |
| --------- | ------ | -------------------- |
| action    | object | The selected action. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |


:::::

:::::tab
::component-specification{component="tile" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=71098ab8abbdc121072fdfbe5c7902c475d8bf867fd74b001c568aeb0c128132 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/time/lightning-time.md -->


# Time Picker

**`lightning-input`**
_type="time"_

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="time" model="lwc" namespace="lightning"}


:::::

:::::tab

A time field includes a text input to type a time and a timepicker
to select a time.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="time" label="Time"> </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                    | SLDS 2                                                                     |
| ---------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| time       | [Timepicker](https://v1.lightningdesignsystem.com/components/timepicker/) | [Timepicker](https://www.lightningdesignsystem.com/components/timepicker/) |

## Usage

On mobile devices, this component uses the native timepicker, which ignores the `time-style` attribute. The native timepicker uses the user's device settings for the input time format.

On desktop, this component uses a timepicker styled with the Lightning Design System. This picker uses the user's Salesforce locale setting for the time format, either 12-hr time with AM/PM or 24-hr time format. The entered date and time are validated against the user's Salesforce locale format during the `blur` event.

## Time Style

The component uses the attribute `time-style="short"` by default, so the timepicker
displays time without seconds. To display time including seconds, set `time-style="medium"`.

Use the `value` attribute to optionally supply an initial time as an ISO8601 formatted time string
such as `14:00:00.000`.

## Time Range

Set `min` and `max` to ISO8601 formatted time strings to constrain the allowed time value. The time picker displays time values that are within the range only. If you type a time that's outside the range, the `blur` event triggers the field to display a validation error message.

## Add Field-Level Help and Placeholder Text

To provide a hint for entering information in the field, specify help text with the `field-level-help` attribute. Field-level help adds an info icon next to the input label, with a tooltip displaying your specified help text.

Adding a `placeholder` value shows the placeholder text in both the date and time fields.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="time"
        label="Event Time"
        field-level-help="The event time must be between 9AM and 9PM"
    >
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Input Validation

To ensure a time is provided, use the `required` attribute. Use `min` and `max` attributes to constrain the allowed time range. The component automatically validates the time format based on the user's Salesforce locale.

```html
<template>
  <lightning-input
    type="time"
    label="Appointment Time"
    required
    min="09:00:00.000"
    max="17:00:00.000"
    lwc:ref="appointmentTime"
    message-when-value-missing="Appointment time is required"
    message-when-range-underflow="Appointment must be after 9:00 AM"
    message-when-range-overflow="Appointment must be before 5:00 PM"
  >
  </lightning-input>
</template>
```

An error icon is displayed on an invalid time field, except on desktop browsers.

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the time input, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the time field.

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

export default class TimeValidation extends LightningElement {
  handleSubmit() {
    const timeInput = this.refs.appointmentTime;
    console.log(timeInput.validity.valid); // Returns true or false
    if (!timeInput.checkValidity()) {
      timeInput.reportValidity();
      return;
    }
    // Proceed with form submission
    const selectedTime = timeInput.value;
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `time` type, these attributes apply:

- `badInput` - Indicates that the value is invalid or doesn't match the allowed format for the user's locale
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `patternMismatch` - Indicates that the value doesn't match the allowed pattern
- `rangeOverflow` - Indicates that the time is greater than the specified `max` attribute
- `rangeUnderflow` - Indicates that the time is less than the specified `min` attribute
- `typeMismatch` - Indicates that an invalid format was entered
- `valueMissing` - Indicates that no value is provided when the `required` attribute is set
- `valid` - True if none of the preceding properties are true

The `badInput` validity error for `date` and `datetime` fields displays a default message that varies by locale. For example, "Your entry does not match the allowed format Dec 31, 2024" is displayed for en-US locale, but a different date format is shown for a different locale.

The `valueMissing` validity error for `date` and `datetime` displays "Complete this field with format `[format]`" where `[format]` is the date format that's determined by the user locale. For example: "Complete this field with format Dec 31, 2024"

## Usage Considerations

By default, the timepicker renders above all modals and the main Salesforce header.

You can guide users with a `field-level-help` tooltip and a `placeholder` prompt in the text field,
as described in [Add Field-Level Help and Placeholder Text](#add-field-level-help-and-placeholder-text).

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the time field.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the time field and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the time field and the help tooltip.

If the time field fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns one of the following `event.target` parameters, depending on input type.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| value     | string | Returns the input value. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::

<!-- document id=358885fb584192bca26b3b8677ff79e2f63d06de4ea8ca6aa7754e8eb56bb9c0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/toast/lightning-toast.md -->


# Toast

**`lightning-toast`**

A notification element used to convey a label.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="toast" model="lwc" namespace="lightning"}


:::::

:::::tab

Use the `lightning/toast` module to display a toast notification with an icon, label, message, and links.

Toast notifications convey small pieces of information to the user, such as feedback and confirmation after the user takes an action. You can set toast notifications to disappear after a certain duration or until the user clicks the close button.

To specify your toast position and the maximum number of toasts to display, use `lightning/toast` with `lightning/toastContainer`.

## Design

`lightning/toast` implements the toast blueprint in the Salesforce Lightning Design System (SLDS). The toast adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                | SLDS 2                                                                                                          |
| :------------- | :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Toast](https://v1.lightningdesignsystem.com/components/toast/)       | [Toast](https://www.lightningdesignsystem.com/components/toast/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

To show a toast notification, call the function `show(config, comp)` from `lightning/toast`. The function creates a single page-level toast container if one does not exist. The `show(config, comp)` function contains two parameters:

- The `config` parameter references an object that specifies toast configuration attributes. See the [Toast Configuration Attributes](#toast-configuration-attributes) section for a list of properties to include in the config.
- The `comp` parameter is a reference to the local component or `this`.

This example creates an informational toast that displays until the user dismisses it.
The toast title and message each include links, using two different approaches.
The component's `handleClick` handler triggers the toast opening.

```javascript
import { LightningElement } from 'lwc';
import Toast from 'lightning/toast';

export default class MyComponent extends LightningElement {
    ...
    handleClick() {
        ...
        Toast.show({
            label: 'This is a toast label which shows {0}, you can learn more about its accessibility from {1}',
            labelLinks : [{
                url: 'https://www.lightningdesignsystem.com/components/toast/',
                label: 'LDS link'
            }, {
                url: 'https://www.lightningdesignsystem.com/accessibility/guidelines/global-focus/#toasts',
                label: 'toast guideline'
            }],
            message: 'I want to show a {salesforceLink} and a {slackLink}',
            messageLinks: {
                salesforceLink: {
                    url: 'http://www.salesforce.com',
                    label: 'Salesforce link'
                },
                slackLink: {
                    url: 'https://slack.com',
                    label: 'Slack link'
                }
            },
            mode: 'sticky',
            variant: 'info'
        }, this);
    }
}
```

A page-level [`ToastContainer` component](/docs/platform/lightning-component-reference/guide/lightning-toast-container.html) manages and displays the toast component.

The required `label` string specifies the toast title and the optional `message` string is the toast message.
The `{0}`, `{1}`, `{salesforceLink}`, and `{slackLink}` placeholders are replaced with links that are specified in their `url` properties.

`label` can have index-based or name-based link placeholders. In the case of index-based link placeholders, `labelLinks` must be defined as an array. Otherwise, `labelLinks` must be defined as individual objects. The same rules apply to `message`.

In the example, `label` uses index-based link placeholders, and `message` uses name-based link placeholders.

**note:** External links always open in a new tab. Links that navigate to another page in your Salesforce org or links that use a relative path open in the same tab. Changing the link targets isn't supported.

## Small Screens and Mobile Environment

`Toast` is responsive to your screen resolution. For smaller screens or mobile environments, the toast's icon and description (text stored in `message`, and `messageLinks`, for example) is not shown due to the screen's width limitation. See [Toast blueprint screen variants](https://v1.lightningdesignsystem.com/guidelines/messaging/components/toasts/#flavor-variants-screen).

To provide links in toasts on small screens and mobile environments, we recommend that you include links in the toast's title using `label` and `labelLinks`.

## Toast Configuration Attributes

For more information on the toast configuration attributes, see the Specification tab.

When you use `labelLinks` or `messageLinks`, the content of `label` or `message` is rendered using [`lightning-formatted-rich-text`](/docs/platform/lightning-component-reference/guide/lightning-formatted-rich-text.html). See the
[`lightning-formatted-rich-text` documentation](/docs/platform/lightning-component-reference/guide/lightning-formatted-rich-text.html) for expected styling when rendering a link.

## Component Styling

Specify the `variant` attribute with one of these values to set the component's color and icon.

| Value            | Color  | Icon              |
| ---------------- | ------ | ----------------- |
| `info` (default) | grey   | `utility:info`    |
| `success`        | green  | `utility:success` |
| `warning`        | orange | `utility:warning` |
| `error`          | red    | `utility:error`   |

Passing in SLDS utility classes and using [SLDS styling hooks](https://v1.lightningdesignsystem.com/components/toast/#Styling-Hooks-Overview) aren't supported with programmatic creation of toasts via `Toast.show()`.

## Toast Dismissal

The `mode` attribute sets the component's dismissal.

- `dismissible` - The component automatically disappears after a certain duration. The user can dismiss it early by clicking the close button. The time duration for `dismissible` is 20 seconds.
- `sticky` - The component stays on screen until the user clicks the close button.

If you don't provide a `mode` value, the toast dismissal is determined by the value of `variant` and whether the `toast` has a link or links present in `label` or `message`.

| Variant   | Has link? | Default Mode  |
| --------- | --------- | ------------- |
| `info`    | Yes       | `sticky`      |
| `info`    | No        | `sticky`      |
| `success` | Yes       | `sticky`      |
| `success` | No        | `dismissible` |
| `warning` | Yes       | `sticky`      |
| `warning` | No        | `sticky`      |
| `error`   | Yes       | `sticky`      |
| `error`   | No        | `sticky`      |

## Accessibility

`lightning/toast` specifies the `role="alert"` attribute that identifies the toast as an alert region. It uses `aria-live="polite"` so the screen reader doesn't interrupt current announcements.

Toast container follows the [SLDS Global Focus Orchestration accessibility guidelines](https://v1.lightningdesignsystem.com/accessibility/guidelines/global-focus/#global-orchestration). Use these keyboard shortcuts to navigate between toasts.

- Ctrl+F6 (Windows) or Cmd+F6 (Mac) - Move focus to the next toast, if any.
- Shift+Ctrl+F6 (Windows) or Shift+Cmd+F6 (Mac) - Move focus to the previous toast, if any.

Additionally, your keyboard settings determine if you must use the Fn key with F6.


:::::

:::::tab
::component-specification{component="toast" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=e63758183875f3d5a7d881917752fe40137f3e9fad210009ed4836b9fa58713d url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/toastContainer/lightning-toast-container.md -->

# Toast Container

**`lightning/toastContainer`**

Manages a list of toast components and their display position and order.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Use the `lightning/toastContainer` module to manage a list of toast components and their order. Each site page supports a single toast container. You can create toast notifications with [lightning/toast](/docs/platform/lightning-component-reference/guide/lightning-toast.html) and manage them using `lightning/toastContainer`.

This example creates a basic toast container component that handles and displays all the page-level toast messages.

```javascript
const toastContainer = ToastContainer.instance();
```

## Customization

By default, the toast container shows a maximum of 3 toast notifications at the same time. Set the `maxToasts` attribute to change the maximum number of toasts shown at a time.

Toast components display at the top center of the container by default. The most recent toast displays at the top of the container, and the oldest toast notification displays at the bottom. Change the toasts' position in the container with the `toastPosition` attribute.

The container position is fixed to the viewport. Adjust the position of the container relative to its parent element with the `containerPosition` attribute. This attribute has two values.

- `fixed` - positions the container relative to the initial containing block established by the viewport.
- `absolute` - positions the container relative to a positioned parent element.

This example creates a page-level toast container in the top-right in the viewport that shows a maximum of 5 toast messages at one time.

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

export default class MyApp extends LightningElement {
  connectedCallback() {
    const toastContainer = ToastContainer.instance();
    toastContainer.maxToasts = 5;
    toastContainer.toastPosition = "top-right";
  }
}
```

## Accessibility

Toast container follows the SLDS [Global Focus Orchestration](https://v1.lightningdesignsystem.com/accessibility/guidelines/global-focus/#global-orchestration) accessibility guidelines. Use these keyboard shortcuts to navigate between toasts.

- Ctrl+F6 (Windows) or Cmd+F6 (Mac) - Move focus to the next toast, if any.
- Shift+Ctrl+F6 (Windows) or Shift+Cmd+F6 (Mac) - Move focus to the previous toast, if any.

Additionally, your keyboard settings determine if you must use the Fn key with F6.


:::::

:::::tab
::component-specification{component="toastContainer" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c545e2e301970f6041e88181ab178aa589c5f7e9304be4f34e851e4d2f56be4b url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/tree/lightning-tree.md -->


# Tree

**`lightning-tree`**

Displays a nested tree.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="tree" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-tree` component shows visualization of a structural hierarchy,
such as a sitemap for a website or a role hierarchy in an organization. Items
are presented as hyperlinks and items in the hierarchy can be nested. Items
with nested items are also known as branches.

## Design

`lightning-tree` implements the trees blueprint in the Salesforce Lightning Design System (SLDS). The trees adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Trees](https://v1.lightningdesignsystem.com/components/trees/)                                                                       | [Trees](https://www.lightningdesignsystem.com/components/trees/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

To create a tree, pass in an array of key-value pairs to the `items`
attribute.

| Key      | Type    | Description                                                                                                                            |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| label    | string  | Required. The title and label for the hyperlink.                                                                                       |
| metatext | string  | Text to provide users with supplemental information and aid with identification or disambiguation.                                     |
| items    | object  | Nested items as an array of key-value pairs.                                                                                           |
| name     | string  | The unique name for the item for the `onselect` event handler to return the tree item that was clicked.                                |
| href     | string  | The URL for the link.                                                                                                                  |
| expanded | boolean | Specifies whether a branch is expanded. An expanded branch displays its nested items visually. The default is false.                   |
| disabled | boolean | Specifies whether an item is disabled. A disabled item is grayed out and can't be focused or perform any action. The default is false. |

Here's an example of a tree with more than one level of nesting. To retrieve the selected item ID, use the `onselect` event handler. The `select` event is also fired when you select an item with an `href` value.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tree items={treeList} onselect={handleSelect}>
    </lightning-tree>
</template>
```
<!-- prettier-ignore-end -->

Define the tree items in your JavaScript file. Use the `detail` property to retrieve the name of the selected tree item.

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

const items = [
  {
    label: "Western Sales Director",
    name: "1",
    expanded: true,
    items: [
      {
        label: "Western Sales Manager",
        name: "2",
        expanded: true,
        items: [
          {
            label: "CA Sales Rep",
            name: "3",
            expanded: true,
            items: [],
          },
          {
            label: "OR Sales Rep",
            name: "4",
            expanded: true,
            items: [],
          },
        ],
      },
    ],
  },
  {
    label: "Eastern Sales Director",
    name: "5",
    expanded: false,
    items: [
      {
        label: "Eastern Sales Manager",
        name: "6",
        expanded: true,
        items: [
          {
            label: "NY Sales Rep",
            name: "7",
            expanded: true,
            items: [],
          },
          {
            label: "MA Sales Rep",
            name: "8",
            expanded: true,
            items: [],
          },
        ],
      },
    ],
  },
];

const mapping = {
  1: "Western Sales Director",
  2: "Western Sales Manager",
  3: "CA Sales Rep",
  4: "OR Sales Rep",
  5: "Eastern Sales Director",
  6: "Eastern Sales Manager",
  7: "NY Sales Rep",
  8: "MA Sales Rep",
};

export default class TreeExample extends LightningElement {
  treeList = items;
  selected = "";

  handleSelect(event) {
    //set the name of selected tree item
    this.selected = mapping[event.detail.name];
  }
}
```

## Add or Remove Items in a Tree

You can add or remove items in a tree. Let's say you have a tree that looks
like this, with a button to add a nested item to the tree.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button
        label="Add to Tree"
        id="change-button"
        onclick={handleClick}
    >
    </lightning-button>
    <lightning-tree items={treeList}> </lightning-tree>
</template>
```
<!-- prettier-ignore-end -->

Define the items in your JavaScript code.

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

const items = [
  {
    label: "Go to Record 1",
    href: "#record1",
    items: [],
    expanded: true,
  },
  {
    label: "Go to Record 2",
    href: "#record2",
    items: [],
    expanded: true,
  },
  {
    label: "Go to Record 3",
    href: "#record3",
    items: [],
    expanded: true,
  },
];

export default class AddRemoveExample extends LightningElement {
  treeList = items;
}
```

This example `handleClick()` function adds a nested item at the end of the tree when the button is clicked.

```javascript
export default class AddRemoveExample extends LightningElement {
  treeList = items;

  handleClick(e) {
    const newItems = Array.from(this.treeList);
    const branch = newItems.length;
    const label = "New item added at Record" + branch;
    const newItem = {
      label: label,
      expanded: true,
      disabled: false,
      items: [],
    };
    newItems[branch - 1].items.push(newItem);
    this.treeList = newItems;
  }
}
```

When providing an `href` value to an item, the `onselect` event handler is
triggered before navigating to the hyperlink.

## Select a Tree Item Programmatically

To select a tree item using JavaScript, pass in the tree item name using `selected-item`.

This example selects the **United States Sales** tree item on load. Press the **Change Selected** button to select the **Americas** tree item.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-tree
        items={treeList}
        selected-item={selected}
    ></lightning-tree>
    <lightning-button
        label="Change Selected"
        onclick={handleClick}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Define the items in your JavaScript code and pass in the selected item name.

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

const items = [
  {
    label: "Asia Pacific Sales",
    name: "Asia Pacific Sales",
    items: [
      {
        label: "Asia Sales",
        name: "Asia Sales",
        items: [],
      },
    ],
  },
  {
    label: "Europe Sales",
    name: "Europe Sales",
    items: [
      {
        label: "UK Sales",
        name: "UK Sales",
        items: [],
      },
      {
        label: "EU Sales",
        name: "EU Sales",
        items: [],
      },
    ],
  },
  {
    label: "Americas",
    name: "Americas",
    items: [
      {
        label: "Northern America Sales",
        name: "Northern America Sales",
        items: [
          {
            label: "United States Sales",
            name: "United States Sales",
            items: [],
          },
        ],
      },
    ],
  },
];

export default class SelectItemExample extends LightningElement {
  treeList = items;
  selected = "United States Sales";

  handleClick() {
    this.selected = "Americas";
  }
}
```

## Expand or Collapse A Branch

To expand or collapse a branch programmatically, get the tree items and update its `expanded` property.

```javascript
// expand the first branch
this.template.querySelector("lightning-tree").items[0].expanded = true;

// collapse the first branch
this.template.querySelector("lightning-tree").items[0].expanded = false;
```

## Design Guidelines

Use `lightning-tree` if your app has layered navigation that can’t be represented in a simple tab set. A tree helps users navigate to pages and quickly find a nested child page without loading each page.

You can use `lightning-tree` with `lightning-breadcrumbs` to further help users navigate the hierarchy.

Trees can have unlimited nesting, but we recommend flatter trees as they’re generally easier to navigate.

Not all items in the list need a corresponding page. Instead, you can group related pages together using a label header without providing an unnecessary landing page.

## Accessibility

You can use the keyboard to navigate the tree. Tab into the tree and use the
Up and Down Arrow key to focus on tree items. To collapse an expanded branch,
press the Left Arrow key. To expand a branch, press the Right Arrow key.
Pressing the Enter key or Space Bar is similar to an onclick event, and
performs the default action on the item.

## Custom Events

**`select`**

The event fired when a tree item is selected and before navigating to a given hyperlink.

The `select` event returns the following parameter.

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| name      | string | The label of the selected tree item. |

The event properties are as follows.

| Property   | Value | Description                                                                |
| ---------- | ----- | -------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                     |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched. |

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning-tree`, see the `c-wire-get-picklist-values-by-record-type` component in the LWC Recipes repo.


:::::

:::::tab
::component-specification{component="tree" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=73ddf24976fe69ec4dae9e707cc10811fa26560c1bb9aab5634a0eeee2697be0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/treeGrid/lightning-tree-grid.md -->


# Tree Grid

**`lightning-tree-grid`**

Displays a hierarchical view of data in a table.

**For Use In**

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="treeGrid" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-tree-grid` component shows hierarchical data in a table. Its
appearance resembles `lightning-datatable` since it implements `lightning-datatable` internally, with the exception that each row in the table
can be expanded to reveal a nested group of items. Rows that contain nested
data appends a chevron icon to denote that they can be expanded or collapsed.
This visual representation is useful for structured data, such as
account hierarchy or forecasting data.

Each column's formatting is determined
by its data type. For example, a phone number is presented as a hyperlink with
the `tel:` URL scheme by specifying the `phone` type. The default type is
`text`.

These `lightning-datatable` features aren't available on `lightning-tree-grid`:

- Infinite scrolling
- Inline editing
- Passing in a fixed width value to a column
- Specifying the maximum number of rows that can be selected
- Handling of `resize` event when a column is resized

Supported features include:

- Displaying and formatting of columns with appropriate data types
- Custom data types
- Header-level actions
- Row-level actions
- Resizing of columns
- Selecting of rows
- Sorting of columns by ascending and descending order
- Text wrapping and clipping
- Row numbering column
- Cell content alignment
- Appending an SLDS icon to column data
- Displaying a custom icon to expand and collapse a tree item
- Hiding the tree grid header
- Hiding the tree grid borders

## Design

`lightning-tree-grid` implements the tree grid blueprint in the Salesforce Lightning Design System (SLDS). The tree grid adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                         | SLDS 2                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Tree Grid](https://v1.lightningdesignsystem.com/components/tree-grid/)                        | [Tree Grid](https://www.lightningdesignsystem.com/components/tree-grid/)                                        |
| **For Use In** | Lightning Experience, Experience Builder sites, Lightning Out (Beta), Standalone Lightning app | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

This component provides styling for up to 20 nested levels. For tree grids that require more than 20 nested levels, we recommend that you build your own component.

A checkbox is visible by default in the first column. Set the `hide-checkbox-column` attribute to `true` to remove the checkbox.

Initialize your tree grid data by using the `data`, `columns`, and `key-field` attributes and define their values in JavaScript. Note that `key-field` is required.

This example creates a tree grid with 5 columns, where the
first column displays a checkbox for row selection. Selecting the checkbox
enables you to select the entire row of data and triggers the `onrowselection`
event handler. The `expanded-rows` attribute is optional, and expands nested
items on a row when provided. Selecting a row by using the checkbox doesn’t select
the rows nested below it.

The example includes two buttons whose handlers call `lightning-tree-grid` methods to collapse all rows and to show which rows are expanded.

<!-- prettier-ignore-start -->
```html
<template>
    <div class="slds-m-bottom_small">
        <lightning-button label="Collapse All" onclick={clickToCollapseAll}>
        </lightning-button>
    </div>

    <div class="slds-m-bottom_small">
        <lightning-button label="Get Expanded" onclick={clickToGetExpanded}>
        </lightning-button>
        <p>Expanded currently : {currentExpandedStr}</p>
    </div>

    <lightning-tree-grid
        data={data}
        columns={columns}
        key-field="name"
        expanded-rows={currentExpanded}
    >
    </lightning-tree-grid>
</template>
```
<!-- prettier-ignore-end -->

This example JavaScript creates selectable rows, with the row named 123555 having no nested
data and the row named 123556 having two levels of nested data.
The Account Owner column shows labels with an associated URL. Nested
items must be defined using the `_children` key.

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

const columns = [
  {
    type: "text",
    fieldName: "accountName",
    label: "Account Name",
  },
  {
    type: "number",
    fieldName: "employees",
    label: "Employees",
  },
  {
    type: "phone",
    fieldName: "phone",
    label: "Phone Number",
  },
  {
    type: "url",
    fieldName: "accountOwner",
    label: "Account Owner",
    typeAttributes: {
      label: { fieldName: "accountOwnerName" },
    },
  },
];

const nestedData = [
  {
    name: "123555",
    accountName: "Rewis Inc",
    employees: 3100,
    phone: "837-555-1212",
    accountOwner: "http://example.com/jane-doe",
    accountOwnerName: "Jane Doe",
  },
  {
    name: "123556",
    accountName: "Acme Corporation",
    employees: 10000,
    phone: "837-555-1212",
    accountOwner: "http://example.com/john-doe",
    accountOwnerName: "John Doe",
    _children: [
      {
        name: "123556-A",
        accountName: "Acme Corporation (Bay Area)",
        employees: 3000,
        phone: "837-555-1212",
        accountOwner: "http://example.com/john-doe",
        accountOwnerName: "John Doe",
        _children: [
          {
            name: "123556-A-A",
            accountName: "Acme Corporation (Oakland)",
            employees: 745,
            phone: "837-555-1212",
            accountOwner: "http://example.com/john-doe",
            accountOwnerName: "John Doe",
          },
          {
            name: "123556-A-B",
            accountName: "Acme Corporation (San Francisco)",
            employees: 578,
            phone: "837-555-1212",
            accountOwner: "http://example.com/jane-doe",
            accountOwnerName: "Jane Doe",
          },
        ],
      },
    ],
  },
];

export default class DemoElement extends LightningElement {}
```

This example JavaScript shows that row 123556 is expanded initially.

The `columns`, `data`, and `currentExpanded` properties are private
reactive properties, which is indicated by the `@track` decorator in the JS file.
If the values of any of these properties change, the component's template rerenders.

The `clickToGetExpanded()` function calls the `getCurrentExpandedRows()` method to retrieve
the names of the rows that are currently expanded.

```javascript
const initialExpandedRows = ["123556"];

export default class DemoElement extends LightningElement {
  @track columns = columns;
  @track data = nestedData;
  @track currentExpanded = initialExpandedRows;

  clickToGetExpanded(e) {
    const grid = this.template.querySelector("lightning-tree-grid");
    this.currentExpanded = grid.getCurrentExpandedRows();
  }

  get currentExpandedStr() {
    return this.currentExpanded.toString();
  }
}
```

Additionally, you can toggle nested items using `expandAll()` and
`collapseAll()` methods supported by `lightning-tree-grid`.

These functions show how to use the `expandAll()` and `collapseAll()` methods.
The Collapse All button in the example calls the `clickToExpandAll()` function.

```javascript
clickToExpandAll(e) {
        const grid =  this.template.querySelector('lightning-tree-grid');
        grid.expandAll();
    }

clickToCollapseAll(e) {
        const grid =  this.template.querySelector('lightning-tree-grid');
        grid.collapseAll();
    }
```

## Column Properties

Use the following column properties to customize the behavior and visual
aspects of your columns.

| Attribute      | Type    | Description                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fieldName      | string  | Required. The name that binds the columns attributes to the associated data. Each columns attribute must correspond to an item in the data array.                                                                                                                                                                            |
| label          | string  | Required. The text label displayed in the column header.                                                                                                                                                                                                                                                                     |
| type           | string  | Required. The data type to be used for data formatting. For more information, see [Data Types](#data-types).                                                                                                                                                                                                                 |
| actions        | object  | Appends a dropdown menu of actions to a column. You must pass in a list of label-name pairs.                                                                                                                                                                                                                                 |
| cellAttributes | object  | Provides additional customization by using `alignment` and `class` properties, in addition to `icon*` properties, such as for appending an icon to the output. For more information, see [Append an Icon to Column Data](#append-an-icon-to-column-data)                                                                     |
| iconName       | string  | The Lightning Design System name of the icon. Names are written in the format standard:opportunity. The icon is appended to the left of the header label.                                                                                                                                                                    |
| initialWidth   | integer | The width of the column when it's initialized, which must be within the `min-column-width` and `max-column-width` values, or within 50px and 1000px if they aren’t provided.                                                                                                                                                 |
| sortable       | boolean | Specifies whether the column can be sorted. The default is false.                                                                                                                                                                                                                                                            |
| typeAttributes | object  | Provides custom formatting with component attributes for the data type. For example, currencyCode for the currency type. For more information, see [Data Types](#data-types).                                                                                                                                                |
| wrapText       | boolean | Specifies whether text in a column is wrapped when the table renders. Wrapped text vertically expands a row to reveal its full content. Displaying a number of lines and clipping the rest using `wrap-text-max-lines` isn't supported. For more information, see [Text Wrapping and Clipping](#text-wrapping-and-clipping). |

## Data Types

The tree grid formats the data cells of a column based on the type that you
specify for the column. Each data type
is associated with a base component. For example, specifying the
`text` type renders the associated data by using a `lightning-formatted-text`
component. Some of these types allow you to pass in the attributes via the
`typeAttributes` attribute to customize your output.

The properties you pass with `typeAttributes` must be specified using the format shown here,
not the format that's used for Lightning web component attributes in your HTML template. For example,
although `lightning-formatted-number` recognizes a `currency-code` attribute, you must specify it as
`currencyCode` with the `typeAttributes` property. For supported attribute
values, refer to the component's documentation.

The first data column in the tree grid supports the following data types.

| Type        | Description                                                                     | Supported Type Attributes                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| button      | Shows a button using `lightning-button`                                         | disabled, iconName, iconPosition, label, name, title, variant                                                                                           |
| button-icon | Shows a button icon using `lightning-button-icon`                               | alternativeText, class, disabled, iconClass, iconName, name, title, variant                                                                             |
| currency    | Shows a currency using `lightning-formatted-number`                             | currencyCode, currencyDisplayAs, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits |
| date        | Shows a date and time based on the locale using `lightning-formatted-date-time` | day, era, hour, hour12, minute, month, second, timeZone, timeZoneName, weekday, year                                                                    |
| number      | Shows a number using `lightning-formatted-number`                               | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits                                  |
| percent     | Shows a percentage using `lightning-formatted-number`                           | Same as number type                                                                                                                                     |
| text        | Shows text using `lightning-formatted-text`                                     | N/A                                                                                                                                                     |
| url         | Shows a URL using `lightning-formatted-url`                                     | label, target, tooltip                                                                                                                                  |

All other columns support the following data types.

| Type        | Description                                                                                                                                                          | Supported Type Attributes                                                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action      | Shows a dropdown menu using `lightning-button-menu` with actions as menu items                                                                                       | rowActions (required), menuAlignment (defaults to right)                                                                                                |
| boolean     | Shows the icon utility:check if the value is true, and a blank value otherwise.                                                                                      | N/A                                                                                                                                                     |
| button      | Shows a button using `lightning-button`                                                                                                                              | disabled, iconName, iconPosition, label, name, title, variant                                                                                           |
| button-icon | Shows a button icon using `lightning-button-icon`                                                                                                                    | alternativeText, class, disabled, iconClass, iconName, name, title, variant                                                                             |
| currency    | Shows a currency using `lightning-formatted-number`                                                                                                                  | currencyCode, currencyDisplayAs, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits |
| date        | Shows a date and time based on the locale using `lightning-formatted-date-time`                                                                                      | day, era, hour, hour12, minute, month, second, timeZone, timeZoneName, weekday, year                                                                    |
| date-local  | Shows a simple date that is formatted based on the locale. The value passed is assumed to be in the browser local time zone and there’s no time zone transformation. | day, month, year                                                                                                                                        |
| email       | Shows an email address using `lightning-formatted-email`                                                                                                             | N/A                                                                                                                                                     |
| location    | Shows a latitude and longitude of a location using `lightning-formatted-location`                                                                                    | latitude, longitude                                                                                                                                     |
| number      | Shows a number using `lightning-formatted-number`                                                                                                                    | minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits                                  |
| percent     | Shows a percentage using `lightning-formatted-number`                                                                                                                | Same as number type                                                                                                                                     |
| phone       | Shows a phone number using `lightning-formatted-phone`                                                                                                               | N/A                                                                                                                                                     |
| text        | Shows text using `lightning-formatted-text`                                                                                                                          | linkify                                                                                                                                                 |
| url         | Shows a URL using `lightning-formatted-url`                                                                                                                          | label, target, tooltip                                                                                                                                  |

To customize the formatting based on the data type, pass in the attributes for
the corresponding base Lightning web component. For example, pass in a custom
`currencyCode` value to override the default currency code.

```javascript
var columns = [
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    typeAttributes: { currencyCode: "EUR" },
  },
  // other column data
];
```

When using currency or date and time types, the default user locale is used
when no locale formatting is provided. For more information on attributes, see
the corresponding component documentation.

For more information on creating your own data types, see [Create a Custom Data Type](https://developer.salesforce.com/docs/platform/lwc/guide/tree-grid-custom-types).

## Append an Icon to Column Data

To append an icon to your data output, use `cellAttributes` and pass in these
attributes.

| Attribute           | Description                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| iconName            | Required. The Lightning Design System name of the icon, for example, utility:down.                                      |
| iconLabel           | The label for the icon to be displayed on the right of the icon.                                                        |
| iconPosition        | The position of the icon relative to the data. Valid options include `left` and `right`. This value defaults to `left`. |
| iconAlternativeText | Descriptive text for the icon.                                                                                          |

You can add an icon with or without a label. This example defines two columns with icons.
The first column specifies the `utility:event` icon for all rows using the `iconName` cell attribute, and the icon displays to the left of the data without a label.
The second column uses computed values for the `iconName` and `iconLabel` and displays the icon to the right of the data.

```javascript
const columns = [
  // simple icon
  {
    label: "Close date",
    fieldName: "closeDate",
    type: "date",
    sortable: true,
    cellAttributes: {
      iconName: "utility:event",
      iconAlternativeText: "Close Date",
    },
  },
  // icon appended with a label
  {
    label: "Confidence",
    fieldName: "confidence",
    type: "percent",
    cellAttributes: {
      iconName: { fieldName: "confidenceDeltaIcon" },
      iconLabel: { fieldName: "confidenceDelta" },
      iconPosition: "right",
      iconAlternativeText: "Percentage Confidence",
    },
  },
  // other column data
];
```

## Add Styles To Columns

Pass Lightning Design System classes to `cellAttributes` when using standard data types.

```javascript
const columns = [
  {
    label: "Account Name",
    fieldName: "Name",
    cellAttributes: {
      class: "slds-text-color_success slds-text-title_caps",
    },
  }, // other column data
];
```

Custom classes are currently not supported. To apply custom styling on your datatable cells, create a custom data type and then apply your custom CSS classes. See [Custom Data Type Layout and Styles](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-custom-types-styling).

## Create Header-Level and Row-Level Actions

Header-level actions refer to tasks you can perform on a column of data, while
row-level actions refer to tasks you can perform on a row of data, such as
updating or deleting the row. Creating actions in `lightning-tree-grid` is
similar to creating actions in `lightning-datatable`. For more information,
see [lightning-datatable](/docs/platform/lightning-component-reference/guide/lightning-datatable.html).

## Asynchronous Loading of Nested Items

If you have a large number of nested items that would delay the loading of
your data, consider loading your nested items asynchronously. The nested items
are displayed only when you expand the particular row. To do so, initialize
your data without nested items, then add the nested items separately when the row
is expanded.

Handle asynchronous loading of nested items when a row is expanded using the
`ontoggle` action. Find the name of the row being expanded and check if data
for the nested items is already available before retrieving and displaying the
nested items.

```javascript

function getNewDataWithChildren (rowName, data, children) {

    return data.map(function(row) {
        let hasChildrenContent = false;
        if (row.hasOwnProperty('_children') && Array.isArray(row._children) && row._children.length > 0) {
            hasChildrenContent = true;
        }

        if (row.name === rowName) {
            row._children = children;
        } else if (hasChildrenContent) {
            getNewDataWithChildren(rowName, row._children, children);
        }

        return row;
    });
}

handleRowToggle(event) {

        const newChildren = [
            {
                "name": "123555-A",
                "accountName": "Rewis Inc (Oakland)",
                "employees": 345,
                "phone": "837-555-1212",
                "accountOwner": "http://example.com/john-doe",
                "accountOwnerName": "John Doe"
            },
            {
                "name": "123555-B",
                "accountName": "Rewis Inc (San Francisco)",
                "employees": 435,
                "phone": "837-555-1212",
                "accountOwner": "http://example.com/jane-doe",
                "accountOwnerName": "Jane Doe"
            }
        ];

        const rowName = event.detail.name;
        const hasChildrenContent = event.detail.hasChildrenContent;

        if (!hasChildrenContent) {
            this.data = getNewDataWithChildren(rowName, this.data, newChildren);
        }
    }
```

## Resize the Tree Grid and its Columns

The width and height of the tree grid is determined by the container element.
A scroller is appended to the tree grid body if there are more rows to display.
For example, you can restrict the height to 300px by applying CSS styling to
the container element.

<!-- prettier-ignore-start -->
```html
<div style="height: 300px;">
    <!-- lightning-tree-grid goes here -->
</div>
```
<!-- prettier-ignore-end -->

By default, columns are resizable. Users can click and drag the width to a
minimum of 50px and a maximum of 1000px. Users can also resize the column width using the keyboard. For more information, see the **Accessibility** section.

### Work with Column Widths

You can customize the column widths in many ways. To specify an initial width and enable resizing for a specific column, pass in `initialWidth` to the column property.

```javascript
const columns = [
  {
    label: "Amount",
    fieldName: "amount",
    type: "currency",
    initialWidth: 80,
  },
  // other column data
];
```

Columns have a default minimum width of 50px and maximum width of 1000px. To change the minimum and maximum width of columns, use the
`min-column-width` and `max-column-width` attributes. For example, if you want a user to be able to resize a column to a minimum of 80px, set `min-column-width="80"`.

<!-- prettier-ignore-start -->
```html
<lightning-tree-grid
    key-field="id"
    data={data}
    columns={columns}
    min-column-width="80"
></lightning-tree-grid>
```
<!-- prettier-ignore-end -->

To prevent users from resizing columns, specify `resize-column-disabled` in your markup. The table can still adjust its column widths when you resize the browser window or the width of the parent container changes.

`lightning-tree-grid` doesn't support the `resize` event and the `fixedWidth` column property.

### Manage the Resizing of Column Widths

The `column-widths-mode` attribute accepts values of `fixed` (default) or `auto`. To provide granular control on your column widths, use this attribute with the `initialWidth` column property.

Widths for the following columns are fixed and can’t be changed.

- Row Number column
- Selection (checkbox) column
- Action column

### Implement Fixed Width Mode

Render columns with equal widths using `column-widths-mode="fixed"`, which is the default setting. Any content that's too long to be displayed is clipped and appears with a trailing ellipsis. The column width is calculated by taking total available width and dividing equally among the columns.

You can specify your own widths using `initialWidth` only. The widths of the remaining columns without a specified `initialWidth` are equal.

Setting new data on the columns doesn't trigger resizing for columns, unless the new column definition specifies a change in `initialWidth` values. In `fixed` mode, the columns automatically resize and maintain equal widths when:

- The browser window is resized
- The parent container width for the datatable is changed
- The `row-number-offset` value is changed
- More or less data is passed in

When you manually resize a column to a larger width, the other columns maintain their widths, displaying a scrollbar to enable scrolling to the end of the table columns. When you manually resize to a smaller width, the other columns also maintain their widths.

You can resize manually using a mouse or a keyboard. On a keyboard, press enter in the header cell, tab to reach the resizer (column divider), and press the left or right arrow keys. On a touchscreen device, tap on the desired column resizer area, move to the desired width, and then release.

### Implement Auto Width Mode

To trigger resizing of columns according to the length or size of data in a column, set `column-widths-mode="auto"`. In `auto` width mode, the columns automatically resize when:

- Data changes in at least one row and the number of rows stays the same
- The column definition changes, such as a change in a column property or the number of columns

Pass a new reference of columns with changes for resize to take effect. The columns don't resize if there's only a change in the number of records in the data.

Column widths are calculated based on the width of the content displayed in the column and the total width of the table. Specify your own widths for particular columns using the `initialWidth` property. The widths of the columns without the `initialWidth` property are calculated based on the width of the content in the column and the remaining table width. If the columns definition is passed but no data is set yet, the columns are rendered based on the width of the column labels.

A column's width is limited by the `max-column-width` value, or 1000px by default. If a column width is calculated to be wider than the `max-column-width` value, the content is truncated and displayed with an ellipsis. If the column also specifies `wrapText: true`, the column results in a narrower width than if the column has clipped text.

A column's width is also limited by the `min-column-width` value, or 50px by default. If a column width is calculated to be narrower than the `min-column-width` value, the width is set to minimum column width and may have extra white space.

When you manually resize a column, the other columns maintain their widths. This behavior also occurs when a column is manually resized in `fixed` mode.

The columns keep their width ratios while adjusting the column widths when:

- The browser window is resized
- The parent container width for the datatable is changed
- The `rowNumberOffset` value is changed

Auto width mode is supported for containers with block display, which corresponds to the `display: block` CSS property.
`lightning-datatable` doesn't fully support containers with `display:inline-block` or flex properties.

#### Select Rows Programmatically

The `selected-rows` attribute enables you to preselect rows.

<!-- prettier-ignore -->
```html
<lightning-tree-grid
  data={dataTree}
  columns={columnsTree}
  key-field="name"
  expanded-rows={currentExpanded}
  selected-rows={selectedRowsTree}
>
</lightning-tree-grid>
```

To select a row programmatically, pass in the row `key-field` value. For example, `selectedRowsTree = ['1', '2','2a'];` where `1`, `2`, and `2a` correspond to the `name` values of the rows to be disabled.

The `max-row-selection` attribute is currently not supported.

#### Disable Rows Programmatically

Use the `disabled-rows` attribute to prevent users from changing the selection status of specified rows. Pass row identifiers into `disabled-rows` to prevent the rows from being selected. Pass row identifiers into both `disabled-rows` and `selected-rows` to prevent the rows from being deselected.

<!-- prettier-ignore -->
```html
<lightning-tree-grid
  data={dataTree}
  columns={columnsTree}
  key-field="name"
  expanded-rows={currentExpanded}
  disabled-rows={disabledRowsTree}
>
</lightning-tree-grid>
```

To disable a row programmatically, pass in the row `key-field` value to the `disabled-rows` attribute.
For example, `disabledRows = ['a', 'b'];` where `a` and `b` correspond to the `id` values of the rows to be disabled.

## Sort Data By Column

To enable sorting of row data by a column label, set `sortable` to `true` for
the column on which you want to enable sorting. Clicking a column header sorts rows by ascending order, and clicking it subsequently reverses the order. Handle the `onsort` event handler to update the table with the new column index and sort direction.

Here's an example of an `onsort` event handler.

```javascript
data = data;
columns = columns;
sortDirection = 'asc';
sortedBy;
// The method onsort event handler
handleSort(event) {
    const { fieldName: sortedByField, sortDirection } = event.detail;
    const cloneData = [...this.data];

    cloneData.sort(this.sortBy(sortedByField, sortDirection === 'asc' ? 1 : -1));
    this.data = cloneData;
    this.sortDirection = sortDirection;
    this.sortedBy = sortedByField;
}
```

The handler assigns `fieldName` to `sortedByField`, which stores the name of the field that is currently being sorted. It also retrieves `sortDirection` from the `sort` event. On first sort, `sortDirection` is `asc`.

`cloneData` creates a shallow copy of the `data` array to avoid mutating the original data. The handler passes in the comparison function `sortBy` and pass it to the [array sort() method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). It
updates the `data` property with the sorted data and `sortDirection` with the new sort direction, and `sortedBy` with the column that was sorted.

## Text Wrapping and Clipping

You can wrap or clip text within columns, which either expands the rows to
reveal more content or truncates the content to a single line within the
column.

To toggle between the two views, select **Wrap text** or **Clip text** from
the dropdown menu on the column header.

If the number of characters is more than what the column width can display,
content is clipped by default. Text wrapping is supported only for the
following data types.

- currency
- date
- email
- location
- number
- percent
- phone
- text
- url

For `text` data type, text clipping converts newline characters to spaces and condenses multiple spaces or tabs to one space. Text clipping suppresses line breaks, truncates content to fit a single line in the column, and adds a trailing ellipsis. Text wrapping breaks lines and hyphenates words as needed to fit the column.

To enable text wrapping by default, set `wrapText` to true on the `columns` property.

```javascript
columns = [
  {
    type: "text",
    fieldName: "accountName",
    label: "Account Name",
    initialWidth: 300,
    wrapText: true,
  },
  //other column data
];
```

Setting the maximum number of lines to display with text wrapping is currently not supported. Handling the header action event is currently not supported.

## Customize the Icon on the Tree Item

`lightning-tree-grid` displays a chevron icon next to tree grid items that contain nested data. By default, the icon is the `utility:chevronright` SLDS icon. To use another SLDS icon, pass in the `iconName` property with the utility icon name to the `row-toggle-icon` attribute. The icon rotates 90 degrees when the item expands.

```javascript
const rowToggleIcon = { iconName: "utility:right" };
```

To use different icons in the expanded and collapsed state, pass in an object with the `expanded.iconName` and `collapsed.iconName` property.

```javascript
const rowToggleIcon = {
  expanded: {
    iconName: "utility:add",
  },
  collapsed: {
    iconName: "utility:dash",
  },
};
```

To display a custom icon instead of an SLDS icon, use `iconSrc` to specify the path of the resource for your icon. Define a static resource in your org and upload your icon's SVG resource to it. The SVG code must include a element with an ID that you can reference. For more information on importing a static resource, see [Create and Upload a Static Resource](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources.html) in the _Lightning Web Components Developer Guide_.

To display an icon next to your column data instead, see [Append an Icon to Column Data](#append-an-icon-to-column-data).

## Accessibility

`lightning-tree-grid` renders a `<table>` element with a `treegrid` role and a polite live region that announces whether the table is in navigation mode or action mode. The label toggles the action mode when you press the Enter key or Space Bar on a cell. It toggles back to navigation mode when you press the Esc key to return focus to the cell. The component also announces the column width during a resize.

Each row header renders with an `aria-label` attribute with the labels you provide for the column definition. By default, the row number column renders with `aria-label="Row Number"` and cannot be changed. When row selection is enabled, each row renders with `aria-selected` set to true or false depending on whether the row is selected. Each cell renders with a `gridcell` role.

Use the following `aria` attributes on `lightning-tree-grid` to provide a caption or description on your table for assistive technologies. These attributes are rendered on the `<table>` element. We recommend that you use one or the other, but not both.

| Attribute       | Type              | Description                                                                                                                        |
| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| aria-label      | string            | Provides an assistive label to identify a table from other tables on a page.                                                       |
| aria-labelledby | ID reference list | Specifies the ID or list of IDs of the element or elements that contain visible descriptive text to caption or describe the table. |

You can add a `displayValue` on the dropdown arrow for a row. This `displayValue` replaces the default row `title` for the dropdown arrow's label.

```javascript
    {
        name: '125313-7j',
        accountName: 'Dach-Welch',
        displayValue: 'Display Value One',
        phone: '995-523-7024',
    }
```

### Provide an Accessible Label for the Table

Use the `aria-label` attribute to provide a more descriptive label for the table for assistive technology. The `aria-label` attribute and its value are passed down to the rendered `table` element.
On pages with multiple tables, `aria-label` helps users identify which table
they're accessing.

Set a descriptive text value to the `aria-label` attribute in `lightning-tree-grid` in your template.

<!-- prettier-ignore-start -->
```html
<lightning-tree-grid aria-label="Active Cases per Contact">
</lightning-tree-grid>
```
<!-- prettier-ignore-end -->

Change the ARIA label dynamically using the `ariaLabel` property.

```js
const treegrid = this.template.querySelector("lightning-tree-grid");
treegrid.ariaLabel = "Escalated Cases per Contact";
```

If you set `aria-label=""` in the HTML or `.ariaLabel = ""` in JavaScript, the table's `aria-label` attribute is hidden, not rendered with an empty string. An empty label string can confuse screen readers.

### Provide an Accessible Caption for the Table

If you have descriptions on an element or on multiple elements for the table, set the `aria-labelledby` value with the ID or list of IDs of the elements.

<!-- prettier-ignore-start -->
```html
<h2 id="table-desc1">Account Details by Year</h2>
<h3 id="table-desc2">EMEA Region</h3>
<lightning-tree-grid
    aria-labelledby="table-desc1 table-desc2"
    key-field="id"
    data={data}
    columns={columns}
>
</lightning-tree-grid>
```
<!-- prettier-ignore-end -->

`lightning-tree-grid` generates a unique string for the element and `aria-labelledby` value to prevent any naming conflicts with other `<table>` elements on the page. Always verify that your rendered table correctly matches the IDs of the descriptive text in the DOM with a screen reader like JAWS or VoiceOver.

When using [custom data types](https://developer.salesforce.com/docs/platform/lwc/guide/tree-grid-custom-types.html), add additional attributes to make all elements of the component accessible. To make elements focusable, pass `tabindex={internalTabIndex}` all the way down to every component or element in the custom type just like with [accessibility support for `lightning-datatable`](https://developer.salesforce.com/docs/platform/lwc/guide/data-table-a11y.html). All focusable elements also must include `data-navigation="enable"`. If you don't want the element to be focusable, use `tabindex=-1`.

### Navigate Using Arrow Keys

Although `lightning-tree-grid` implements `lightning-datatable` internally, there are differences in how keyboard navigation works. Consider these navigation guidelines.

- Tab to place focus on the tree grid. Focus is placed on the first data row the first time you place focus on the tree grid.
- When focus is on the entire data row, the row displays with a dark border across all the data cells in that row.
- To navigate between cells on a data row, use the Right and Left Arrow keys.
- To navigate between rows, use the Up and Down Arrow keys.
- To select a row using the checkbox column, navigate to the row first. Then, use the Right and Left Arrow keys to get to the checkbox column. To select the checkbox when focus is on the checkbox column, press the Space key. If the row has nested items, the first Right Arrow key press expands the nested items. Press the Right Arrow key again to place focus on the checkbox column.

### Expand and Collapse Rows

- When focus is on the entire data row, use the Right and Left Arrow keys.
- When focus is on a data cell with a chevron, press Enter or the Spacebar to activate the chevron. Press Enter or the Spacebar again to expand or collapse the row.

- When focus is on the entire data row, pressing Enter or the Spacebar has no effect on navigation or interaction.

- When focus is on a cell that contains a link, press Enter to activate the link. If the link is a URL, the browser directs you to the website. If the link is a phone number or email, your browser prompts you to open the appropriate app for the link.

### Resize Columns Using Arrow Keys

To resize a column, navigate to the header using the arrow keys first. Use any combination of Up, Down, Left, and Right keys.

- Tab to place focus on the tree grid.
- To navigate between columns, use the Right and Left Arrow keys.
- To navigate to a header column, use the Up Arrow key.

Then, press the Enter key to activate the column header. Use the Right Arrow key to get to the column divider between columns. To resize a column, you can increase or decrease its width using one of the following key combinations.

- Right and Left Arrow keys
- Up and Down Arrow keys
- Page Up and Page Down keys

When you resize a column, the new column width is announced by assistive technology. To finish resizing the column and return to navigation mode, press the Esc key.

## Custom Events

**`toggle`**

The event fired when a row is expanded or collapsed.

The `toggle` event returns the following parameters.

| Parameter          | Type    | Description                                                                                                                                                                                              |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name               | string  | The unique ID for the row that's toggled.                                                                                                                                                                |
| isExpanded         | boolean | Specifies whether the row is expanded or not.                                                                                                                                                            |
| hasChildrenContent | boolean | Specifies whether any data is available for the nested items of this row. When value is false, `_children` is null, undefined, or an empty array. When value is true, `_children` has a non-empty array. |
| row                | object  | The toggled row data.                                                                                                                                                                                    |

**`sort`**

The event fired when a column is sorted.

The `sort` event returns the following parameters.

| Parameter         | Type    | Description                                                    |
| ----------------- | ------- | -------------------------------------------------------------- |
| fieldName         | string  | The fieldName that controls the sorting.                       |
| isMultiColumnSort | boolean | Reserved for internal use. Defaults to false.                  |
| sortDirection     | string  | The sorting direction. Valid options include 'asc' and 'desc'. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`toggleall`**

The event fired when all rows are expanded or collapsed.

The `toggleall` event returns the following parameter.

| Parameter  | Type    | Description                                   |
| ---------- | ------- | --------------------------------------------- |
| isExpanded | boolean | Specifies whether the row is expanded or not. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`rowselection`**

The event fired when a row is selected.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`headeraction`**

The event fired when a header-level action is run.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |

**`rowaction`**

The event fired when a row-level action is run.

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |


:::::

:::::tab
::component-specification{component="treeGrid" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6c3541a31afe2050ebb8216fafc26819ab2e4a6222cb8018bac813a341b61748 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiAppsApi/lightning-ui-apps-api.md -->

# UI Apps API (Beta)

**`lightning/uiAppsApi`**

Get data and metadata for apps displayed in the Salesforce UI.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
**note:** `lightning/uiAppsApi` 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.

The `lightning/uiAppsApi` (Beta) module provides the `getNavItems` wire adapter.
`getNavItems` retrieves the items in the navigation menu.

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-get-nav-items).

:::::

:::::tab
::component-specification{component="uiAppsApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=c912f4fd97eafdc1ff5c6ecf61a6c114d553edbd81cbf99b9b3d061fd92c6371 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiEmbedding/lightning-ui-embedding.md -->

# UI Embedding

**`lightning-ui-embedding`**

Embeds an external web application in a sandboxed iframe and manages a secure, bidirectional bridge between the host page and the embedded app.

**For Use In**

Lightning Experience

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

`lightning-ui-embedding` creates the iframe, applies the sandbox tokens you specify, and negotiates a bootstrap handshake with the embedded document. After the handshake completes, the host and the embedded app can exchange UI state and
custom events over a `MessageChannel`. Communication uses `postMessage`, so the
embedded document can either use the Salesforce embedding SDK or send the
handshake messages directly.

For more information, see the [Salesforce Microfrontend (UI Embedding) Developer Guide](https://developer.salesforce.com/docs/platform/microfrontend/guide).


:::::

:::::tab
::component-specification{component="uiEmbedding" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a44d5809cd1b811f9c9e4d1dee6307534c6deaeec72ae04da19d1bea47b72eeb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiLayoutApi/lightning-ui-layout-api.md -->

# UI Layout API

**`lightning/uiLayoutApi`**

Get record layout metadata and data.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab
The `lightning/uiLayoutApi` module includes the `getLayout` wire adapter to get layout metadata.

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-get-layout.html).

:::::

:::::tab
::component-specification{component="uiLayoutApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=a208b0b06e61a905c00dd0e03a9b6b1a5ed80647c982770b641d308030a307f0 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiLearningPlatformApi/lightning-ui-learning-platform-api.md -->

# UI Learning Platform API

**`lightning/uiLearningPlatformApi`**

Manage data for learning items used with Enablement programs.

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiLearningPlatformApi` module provides the `evaluateLearningItem` wire adapter, which checks whether the criteria for completing a custom exercise in an Enablement program are satisfied.

**note:** Learning items are used in other contexts within Enablement programs and outside of Enablement programs, such as with Learning Paths. But, this module and wire adapter are used only with custom exercises in programs.

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-learning-platform-api).

:::::

:::::tab
::component-specification{component="uiLearningPlatformApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=4c7e9538e5b2baa4a3779ebcf04ea35741e1814d784f3bba63add3a7d44e0808 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiListApi/lightning-ui-list-api.md -->

# UI List API

**`lightning/uiListApi`**

Get the records and metadata for a list view.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiListApi` (Deprecated) module provides the `getListUi` wire adapter.
`getListUi` gets list view records and metadata for a list view by:

- List view API name
- List view ID
- API name of supported object

You can also get list view records and metadata for a most recently used list view by object. For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-list-ui).

:::::

:::::tab
::component-specification{component="uiListApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=ed26705f8d55ef0236f8dbec75abe81ee89119d013ecd23a18203230bcdce380 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiListsApi/lightning-ui-lists-api.md -->

# UI Lists API

**`lightning/uiListsApi`**

Get the metadata for a list view.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiListsApi` module includes wire adapters to execute actions on a list view using its API name, such as get a list view’s metadata and record data; create, update, and delete list views; and get and update a list view’s preferences. This module additionally includes adapters to get lists-specific metadata for a given entity using the entity’s API name. The wire adapters are:

- createListInfo
- deleteListInfo
- getListInfoByName
- getListInfosByName
- getListInfosByObjectName
- getListObjectInfo
- getListPreferences
- getListRecordsByName
- updateListInfoByName
- updateListPreferences

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-lists-ui).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/uiListsApi`, see the `c-wire-list-info-by-name` component in the LWC Recipes repo.

:::::

:::::tab
::component-specification{component="uiListsApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=8bd0210f8a53fe97c6527ad2ed8577521fdbc3d9860347923104c9925b9046cf url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiObjectInfoApi/lightning-ui-object-info-api.md -->

# UI Object Info API

**`lightning/uiObjectInfoApi`**

Get object metadata and picklist values.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiObjectInfoApi` module includes wire adapters to get object metadata and picklist values. The wire adapters are:

- getObjectInfo
- getObjectInfos
- getPicklistValues
- getPicklistValuesByRecordType

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-object-info).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/uiObjectInfoApi`, see the following components in the LWC Recipes repo.

- `c-wire-get-object-info`
- `c-wire-get-picklist-values`
- `c-wire-get-picklist-values-by-record-type`

:::::

:::::tab
::component-specification{component="uiObjectInfoApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=7c1c0e70b734d4cfd447325a39c947b3f5dd620d0caa3f8a5b5b50aae40ca2f3 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiRecordApi/lightning-ui-record-api.md -->

# UI Record API

**`lightning/uiRecordApi`**

Get record data. Also create, delete, update record data.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiRecordApi` module includes wire adapters to record data and get default values to create records. It also includes JavaScript APIs to create, delete, update, and refresh records.

The wire adapters are:

- getRecord
- getRecordCreateDefaults
- getRecordUi (Deprecated)

The JavaScript methods are:

- createRecord(recordInput)
- createRecordInputFilteredByEditedFields(recordInput, originalRecord)
- deleteRecord(recordId)
- generateRecordInputForCreate(record, objectInfo)
- generateRecordInputForUpdate(record, objectInfo)
- getFieldValue(record, field)
- getFieldDisplayValue(record, field)

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-record).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/uiRecordApi`, see the following components in the LWC Recipes repo.

- `c-wire-get-record-dynamic-contact`
- `c-wire-get-record-static-contact`
- `c-wire-get-record-user`

:::::

:::::tab
::component-specification{component="uiRecordApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=09f2ac658cfa86f2bc8a77cf8b3e9e99dc8a186e7977f99f45b7a66e812acbe9 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/uiRelatedListApi/lightning-ui-related-list-api.md -->

# UI Related List API

**`lightning/uiRelatedListApi`**

Get related list metadata and record data.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications" ]'}

:::::tab
The `lightning/uiRelatedListApi` module includes wire adapters to get related list metadata and record data. The wire adapters are:

- getRelatedListInfo
- getRelatedListsInfo
- getRelatedListRecords
- getRelatedListCount
- getRelatedListRecordsBatch
- getRelatedListInfoBatch

For this module's specification and examples, see the [Lightning Web Components Developer Guide](https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-ui-api-related-list).

## LWC Recipes

The [LWC Recipes GitHub repository](https://github.com/trailheadapps/lwc-recipes) contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses `lightning/uiRelatedListApi`, see the `c-wire-related-list` component in the LWC Recipes repo.

:::::

:::::tab
::component-specification{component="uiRelatedListApi" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=7b57da6fc490946de9626c21862c957545e46d8f4e7398e7731d10471fb4eddd url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/wave/update/wave-update.md -->

# Update

**`wave:update`**

Updates the Analytics asset with the specified filter or selection.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `wave:update` event dynamically set filters in an Analytics dashboard embedded in a Lightning page.

For more information, see the [Analytics Web SDK Dev Guide](https://developer.salesforce.com/docs/atlas.en-us.bi_dev_guide_sdk.meta/bi_dev_guide_sdk/bi_sdk_web.htm).


:::::

:::::tab
## Attributes

| Name      | Description                                                                        | Type   | Default | Required                                     |
| --------- | ---------------------------------------------------------------------------------- | ------ | ------- | -------------------------------------------- |
| `devName` | The fully qualified dev name for the Analytics Asset.                              | string |         |                                              |
| `id`      | The identifier for the Analytics asset, in the form of a standard 18-character ID. | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `type`    | The type of the Analytics asset. Currently, only dashboard is supported.           | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |
| `value`   | The JSON representing the filter or selection to be applied to the asset.          | string |         | ![Yes](https://developer.salesforce.com/media/check.png) |

:::::

::::::

<!-- document id=ca3028d325866feeb5eaf73c7a2b4edc1817e8544e4d4b1add31089baf5dbaea url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/userConsentCookie/lightning-user-consent-cookie.md -->

# User Consent Cookie

**`lightning/userConsentCookie`**

Manages cookie consent preferences on a component.

**For Use In**

Experience Builder Sites

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

The `lightning/userConsentCookie` module provides utility functions that enable you to incorporate the Cookie Consent mechanism in your components. This module abstracts all the cookie functions, such as fetching, reading, writing, and updating cookies. This component requires API version 53.0 or later.

## Understand How the `userConsentCookie` Module Works

To implement user-authorized cookie consent:

1. Enable cookie consent in Security & Privacy Settings. You can then provide users the option to allow Marketing, Preference, and Statistics cookies as well. If you don’t enable cookie consent, only Required cookies are allowed.
2. Import the `userConsentCookie` module in your cookie consent component JavaScript.
3. Add the ability for a user to consent to one or more specific cookie types (Required, Marketing, Preference, and Statistics) using HTML and JavaScript in your consent component.

Two Salesforce cookies (CookieConsentPolicy and CookieConsent) are used to put this scheme into place across your org. Client-side APIs enable you to check and set the cookie consent preferences that are persisted in the two Salesforce cookies.

## Understand How the `userConsentCookie` Cookies Interact

As mentioned above, Salesforce ePrivacy consent is managed through the interaction of two cookies, CookieConsentPolicy and CookieConsent.

- The CookieConsentPolicy cookie records whether consent is enabled. Consent is enabled by an admin in the Security & Privacy settings. See [Enable Cookie Consent in Security & Privacy](#enable-cookie-consent-in-security--privacy).

- The CookieConsent cookie records the user’s consent choices, and is used only when consent is enabled and reflected in the CookieConsentPolicy cookie. The CookieConsent cookie is set by way of ePrivacyCookie client-side functions through user choices. See [Manage Consent Options with ePrivacyCookieConsent Functions](#manage-consent-options-with-eprivacycookieconsent-functions).

## Enable Cookie Consent in Security & Privacy

An org administrator enables Cookie Consent from Settings in the Security & Privacy tab. Under _Site Cookie Usage_, turn on the _Allow only required cookies for this site_ toggle to restrict the consent to Required cookies only.

Turn on the toggle to enable consent for Required, Marketing, Preference, or Statistics cookies. Your code can then provide users with the ability to fine-tune consent for the cookie types they do and do not want to permit.

## Manage Consent Options with ePrivacyCookieConsent Functions

The ePrivacyCookieConsent component provides two JavaScript functions that enable you to manage user consent options:

- `isCategoryAllowedForCurrentConsent()` retrieves the user’s decision about a cookie category. See Check Consent With isCategoryAllowedForCurrentConsent() below.
- `setCookieConsent()` records the user’s consent. See [Set Preferences With `setCookieConsent()`](#set-preferences-with-setcookieconsent).

### Import the userConsentCookie Component Methods

To call the component's methods, you must import the `lightning/userConsentCookie` component inside your custom component. For example:

```javascript
import { setCookieConsent, isCategoryAllowedForCurrentConsent } from "lightning/userConsentCookie";
```

### Check Consent With isCategoryAllowedForCurrentConsent()

The `isCategoryAllowedForCurrentConsent` function enables you to check consent for a single cookie category. Specify the category you want to check consent for. Valid values are Required, Preference, Marketing, and Statistics.

```javascript
isCategoryAllowedForCurrentConsent(Name);
```

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| Name      | String | Cookie category to check consent for. |

To see this function called in context, see the **Example** section.

### Set Preferences With `setCookieConsent()`

This client-side method relies on the ConsentPreference JavaScript object, which contains the list of one or more cookie categories you want to grant or deny consent for.

```javascript
setCookieConsent(ConsentPreference);
```

| Parameter         | Type   | Description                               |
| ----------------- | ------ | ----------------------------------------- |
| ConsentPreference | object | Cookie categories to set preferences for. |

The ConsentPreference object structure is as follows:

```javascript
{
<<categoryName>> : boolean,
...
}
```

For example, if you wanted to grant consent for the Marketing category, but deny consent for the Preferences category, you would do something similar to the following:

```javascript
var consent = {
  Preferences: false,
  Marketing: true,
};

setCookieConsent(consent);
```

In this example, the “Statistics” category is not listed, so cookies of that type are denied consent by default.

To see this function called in context, see the **Example** section below.

### Example

This example shows a component that sets or clears the consent for four categories of cookie: Essential, Preferences, Marketing, and Statistics. Feel free to modify the UI, but don't change the defined categories, as these are standard categories used throughout the Salesforce application.

In the consent component’s JavaScript, the cookie consent methods are imported and used in the change handlers for input toggle components.

```javascript
import { LightningElement, track } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { isCategoryAllowedForCurrentConsent, setCookieConsent } from "lightning/userConsentCookie";

export default class CookieConsentToggleButton extends LightningElement {
  @track checkedEssential = true;
  @track checkedPreferences = isCategoryAllowedForCurrentConsent("Preferences");
  @track checkedMarketing = isCategoryAllowedForCurrentConsent("Marketing");
  @track checkedStatistics = isCategoryAllowedForCurrentConsent("Statistics");

  @track
  consent = {
    Preferences: this.checkedPreferences,
    Marketing: this.checkedMarketing,
    Statistics: this.checkedEssential,
  };

  changeToggleEssential(event) {
    console.log("Change toggle Essential triggered. Cannot be changed");
    this.checkedEssential = this.checkedEssential;
    this.showErrorToast();
  }

  changeTogglePreferences(event) {
    console.log("Change toggle Preference triggered");
    this.checkedPreferences = !this.checkedPreferences;
    console.log("Current setting for Preferences : " + this.checkedPreferences);
    this.setPreferences(this.checkedPreferences);
    console.log(JSON.parse(JSON.stringify(this.consent)));
    setCookieConsent(this.consent);
  }

  changeToggleMarketing(event) {
    console.log("Change toggle Marketing triggered");
    this.checkedMarketing = !this.checkedMarketing;
    console.log("Current setting for Marketing : " + this.checkedMarketing);
    this.setMarketing(this.checkedMarketing);
    console.log(JSON.parse(JSON.stringify(this.consent)));
    setCookieConsent(this.consent);
  }

  changeToggleStatistics(event) {
    console.log("Change toggle Statistics triggered");
    this.checkedStatistics = !this.checkedStatistics;
    console.log("Current setting for Statistics : " + this.checkedStatistics);
    this.setStatistics(this.checkedStatistics);
    console.log(JSON.parse(JSON.stringify(this.consent)));
    setCookieConsent(this.consent);
  }

  showErrorToast() {
    const evt = new ShowToastEvent({
      title: "Essential Cookies cannot be blocked",
      message: "These cookies are required for the app to function properly.",
      variant: "error",
      mode: "dismissable",
    });
    this.dispatchEvent(evt);
  }

  setPreferences(value) {
    this.consent.Preferences = value;
  }

  setMarketing(value) {
    this.consent.Marketing = value;
  }

  setStatistics(value) {
    this.consent.Statistics = value;
  }

  handleClickSetConsent() {
    console.log(JSON.parse(JSON.stringify(this.preferences)));
    setCookieConsent(this.consent);
  }
}
```

The component HTML template presents toggle inputs for the user to choose the types of cookies to accept and a button to set the consent value.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-card title="Consent Information" icon-name="custom:custom14">
    <div class="slds-m-around_medium">
        <div>
            <p>We use cookies to personalize contents and ads.
            Please accept/reject the categories below to set your consent.</p>
        </div>
        <br>
        <div>
            <h2><b>Essential</b></h2>
            <lightning-input
                data-id="toggleEssential" type="toggle"
                label="" checked={checkedEssential}
                onchange={changeToggleEssential} disabled=""
                message-toggle-active="" message-toggle-inactive=""
                read-only>
            </lightning-input> <br/>
            <h2><b>Preferences</b></h2>
            <lightning-input
                data-id="togglePreferences" type="toggle"
                label="" checked={checkedPreferences}
                onchange={changeTogglePreferences} message-toggle-active=""
                message-toggle-inactive="">
            </lightning-input> <br/>
            <h2><b>Marketing</b></h2>
            <lightning-input
                data-id="toggleMarketing" type="toggle"
                label="" checked={checkedMarketing}
                onchange={changeToggleMarketing} message-toggle-active=""
                message-toggle-inactive="" >
            </lightning-input> <br/>
            <h2><b>Statistics</b></h2>
            <lightning-input
                data-id="toggleStatistics" type="toggle"
                label="" checked={checkedStatistics}
                onchange={changeToggleStatistics}
                message-toggle-active="" message-toggle-inactive="" >
            </lightning-input> <br/>
        </div>
    </div>
    <div>
        <lightning-button
             class="slds-m-left_small nav-button"
             label="Set Consent"
             variant="brand"
             onclick={handleClickSetConsent}>
         </lightning-button>
     </div>
    </lightning-card>
</template>
```
<!-- prettier-ignore-end -->

## userConsentCookie Component Cookie Reference

### CookieConsentPolicy Cookie

The structure of CookieConsentPolicy value is:

SiteOptionValue:CookieConsentPermValue

with possible values of either "0:1" or "1:1".

The second bit (CookieConsentPermValue) in the cookie value is always enabled.

If the value is "0:1", only essential cookies will be enabled.
If the value is "1:1". cookies will be enabled and disabled based on the consent preferences of the customer.

### CookieConsent

The following table defines the fields of the CookieConsent cookie:

| Field             | Type    | Encoding                          | Purpose                                                                                           |
| ----------------- | ------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| Cookie Version    | String  | n/a                               | Format Sensitivity                                                                                |
| Metadata Version  | String  | n/a                               | Metadata Sensitivity                                                                              |
| Timestamp         | String  | ISO_INSTANT: YYYY-mm-DDTHH:MM:ssZ | Consent Time Sensitivity                                                                          |
| Consent           | String  | Hexadecimal or plaintext          | Array or bit-vector of consent-per-classification                                                 |
| ReconsentRequired | boolean | integer                           | Notify the consent UI that re-consent is required, without dropping existing consent preferences. |

An example of this cookie would be:

`230.6.1:20.4.0:2021-08-03T06:21:44Z:1100:0`

In this example, the Consent field of 1100 indicates that Required and Preference cookies are permitted, but Marketing and Statistics cookies are not.

## Use the Client-Side APIs

### Set Preferences With `setCookieConsent()`

This client-side method relies on the ConsentPreference JavaScript object which contains the list of one or more cookie categories you want to grant or deny consent for.

| Parameter         | Type   | Description                               |
| ----------------- | ------ | ----------------------------------------- |
| ConsentPreference | object | Cookie categories to set preferences for. |

The `ConsentPreference` object structure is as follows:

```
{
	<<categoryName>> : boolean,
	...
}
```

For example, if you plan to grant consent for the `Marketing` category, but deny consent for the `Preferences` category, you would prepare this object:

```
{
	Marketing : true,
	Preferences : false
}
```

A complete example is as follows:

```
var consent = {
    "Preferences" : true,
    "Statistics" : true,
    "Marketing" : false
}

Sfdc.Cookie.setCookieConsent(consent);
```

### Check Consent With `isCategoryAllowedForCurrentConsent()`

To check consent with this simple call, specify the category you want to check consent for.

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| Name      | String | Cookie category to check consent for. |

```
isCategoryAllowedForCurrentConsent("Marketing");
```

This check returns the consent value for the specified category. See [Enable Cookie Consent in Security & Privacy](#enable-cookie-consent-in-security--privacy).

## See Also

- [_Salesforce Help_: Experience Cloud Cookies](https://help.salesforce.com/articleView?id=sf.networks_cookies.htm&type=5)
- [Configure a Component for Experience Builder](https://developer.salesforce.com/docs/platform/lwc/guide/use-config-for-community-builder)


:::::

:::::tab
::component-specification{component="userConsentCookie" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6c118d52665b320432c070932d05dc47334562060ef5ab154aced1476221e27e url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/lightning/utilityItem/aura-utility-item.md -->

# Utility Item

**`lightning:utilityItem`**

Enables a component to be included in the utility bar.

For Aura components only. For LWC development, use [`lightning/platformUtilityBarApi`](/docs/platform/lightning-component-reference/guide/lightning-platform-utility-bar-api.html).

**For Use In**

Lightning Experience

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Implement the `lightning:utilityItem` interface to allow a component to be included in the utility bar.

Components that implement this interface are added to the app through the Select Utility Items milestone in Setup.

The provided supportsPopOut attribute can be set to false in implementing components in order to disable pop-out functionality for those components if desired.

The following example demonstrates implementing this interface and opting the component out of pop-out functionality

```html
<aura:component implements="lightning:utilityItem">
  <aura:attribute name="supportsPopOut" type="Boolean" default="false" />
</aura:component>
```


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=9f7a094b807ee1fc5d3fbe7193d0b4f37c242eb942abe35bb9b0e39f3f594abb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/ui/validationError/ui-validation-error.md -->

# Validation Error (Deprecated)

**`ui:validationError`**

Indicates that the component has validation error(s).

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when a validation error occurs on an input field. To set a handler for the `ui:validationError` event, use the `onError` attribute on a component that extends `ui:input`, such as `ui:inputText` and `ui:inputNumber`.

The following `ui:inputNumber` component displays an error message when the number entered is less than 10. It displays an alert when the error message is cleared.

```xml
<aura:component>
  <aura:attribute name="myNumber" type="integer" default="10" />
  <ui:inputNumber
    aura:id="number"
    label="Enter a number: "
    value="{!v.myNumber}"
    onError="{!c.handleError}"
  />
  <ui:button label="Validate" press="{!c.handleValidate}" />
</aura:component>
```

Here's the client-side controller that handles the input validation and handling of the validation error.

```javascript
({
  handleValidate: function (cmp, evt, helper) {
    var num = cmp.find("number");
    var val = num.get("v.value");
    if (val < 10) {
      num.set("v.errors", [{ message: "Enter a number more than 10" }]);
    } else {
      num.set("v.errors", null);
    }
  },

  handleError: function (cmp, evt, helper) {
    alert("An error was found in your input.");
  },
});
```

If you're using this event with a component other than those that extend `ui:input`, register the event first.

```xml
<aura:registerEvent
  name="onError"
  type="ui:validationError"
  description="The event fired when validation errors occur."
/>
```

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_validate_fields.htm).


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=408f0af64ad1b2bbf51c0615f62bdc034e753dad6455f5f47f136c6248fcf9a4 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/valueChange/aura-value-change.md -->

# Value Change

**`aura:valueChange`**

Indicates that a value has changed.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when an attribute value changes. Handle this event using the `aura:handler` tag. A component can have multiple `aura:handler` tags to detect changes to different attribute values.

```xml
<aura:handler name="change" value="{!v.items}" action="{!c.itemsChange}" />
```

This example updates an attribute value, which fires the `aura:valueChange` event.

```xml
<aura:component>
  <aura:attribute name="myBool" type="Boolean" default="true" />

  <!-- Handle the aura:valueChange event -->
  <aura:handler name="change" value="{!v.myBool}" action="{!c.handleValueChange}" />
  <lightning:button label="change value" onclick="{!c.changeValue}" />
</aura:component>
```

The client-side controller actions trigger the value change and handle it.

```javascript
({
  changeValue: function (component, event, helper) {
    component.set("v.myBool", false);
  },

  handleValueChange: function (component, event, helper) {
    alert("old value: " + event.getParam("oldValue"));
    alert("current value: " + event.getParam("value"));
  },
});
```

The `valueChange` event gives you access to the previous value (`oldValue`) and the current value (`value`) in the handler action. In this example, `oldValue` returns true and `value` returns false.


:::::

:::::tab
## Attributes

| Name         | Description                                                                                                                          | Type   | Default | Required |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | -------- |
| `expression` | The expression that triggered the value change.                                                                                      | string |         |          |
| `index`      | If the handler was registered through an ArrayValue or MapValue, the name/index of the changed Value in that ArrayValue or MapValue. | string |         |          |
| `oldvalue`   | The previous value that was changed.                                                                                                 | object |         |          |
| `value`      | The new value.                                                                                                                       | object |         |          |

:::::

::::::

<!-- document id=99e82aa0413c788f352b1f1a158d53034a261bf5474c5db9bf86524eeefc62c6 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/valueDestroy/aura-value-destroy.md -->

# Value Destroy

**`aura:valueDestroy`**

Indicates that a component is destroyed.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when a component is destroyed. Handle this event if you need to do custom cleanup when a component is destroyed.

```xml
<aura:handler name="destroy" value="{!this}" action="{!c.handleDestroy}" />
```

This client-side controller handles the `aura:valueDestroy` event.

```javascript
({
  handleDestroy: function (component, event, helper) {
    var val = event.getParam("value");
    // Do something else here
  },
});
```

Let’s say that you are viewing a component in the Salesforce app. The `aura:valueDestroy` event is triggered when you tap on a different menu item on the Salesforce mobile navigation menu, and your component is destroyed. In this example, the `value` parameter in the event returns the component that’s being destroyed.


:::::

:::::tab
## Attributes

| Name    | Description                      | Type   | Default | Required |
| ------- | -------------------------------- | ------ | ------- | -------- |
| `value` | The component that is destroyed. | object |         |          |

:::::

::::::

<!-- document id=cd7a55d93872a17f440de29959c02ab9b7550de12388f7d4c75f8a8c9e4a42ef url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/valueEvent/aura-value-event.md -->

# Value Event

**`aura:valueEvent`**

The root event of the event hierarchy for all events of `type="VALUE"`.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

For more information, see [Detecting Data Changes with Change Handlers](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_cb_data_change.htm) in the _Lightning Aura Components Developer Guide_.


:::::

:::::tab
![No specifications to show](https://developer.salesforce.com/media/no-specs.png)

:::::

::::::

<!-- document id=41ba4c72ba8e2f9598da0bb8eff505978d1c0e7981e0c6132bbaf36cf5a51671 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/valueInit/aura-value-init.md -->

# Value Init

**`aura:valueInit`**

Indicates that a component has been initialized.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when when an app or component is initialized, prior to rendering. Handle this event using the `aura:handler` tag.

```xml
<aura:handler name="init" value="{!this}" action="{!c.doInit}" />
```

Setting `value="{!this}"` marks this as a value event. You should always use this setting for an `init` event.

For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_cb_init_handler.htm).


:::::

:::::tab
## Attributes

| Name    | Description                       | Type   | Default | Required |
| ------- | --------------------------------- | ------ | ------- | -------- |
| `value` | The component that's initialized. | object |         |          |

:::::

::::::

<!-- document id=8bce147b8f7dc70a5dcc7da07db65099863442200fd04b3de3b070975de38308 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/valueRender/aura-value-render.md -->

# Value Render

**`aura:valueRender`**

Indicates that a component has been rendered.

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

This event is fired when when an app or component is rendered or rerendered. Handle this event using the `aura:handler` tag.

```xml
<aura:handler name="render" value="{!this}" action="{!c.onRender}" />
```

In this example, the `onRender` action in your client-side controller handles initial rendering and rerendering of the component. You can choose any name for the `action` attribute.

Setting `value="{!this}"` marks this as a value event. You should always use this setting for an `init` event.

The `render` event is fired after the `init` event, which is fired after component construction but before rendering.

For more information, see [Handle the Render Event](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_render_handler.htm) in the _Lightning Aura Components Developer Guide_.


:::::

:::::tab
## Attributes

| Name    | Description                    | Type   | Default | Required |
| ------- | ------------------------------ | ------ | ------- | -------- |
| `value` | The component that's rendered. | object |         |          |

:::::

::::::

<!-- document id=be228287653a31b2dfd0e1f1499b65fa68e130e91dc8965c294b9bfc40b5eb76 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/verticalNavigation/lightning-vertical-navigation.md -->


# Vertical Navigation

**`lightning-vertical-navigation`**

A vertical list of links that either take the user to another page or parts of the page the user is in.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="verticalNavigation" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-vertical-navigation` component represents a list of links that's only one level deep, with support for overflow sections that collapse and expand.

To create an overflow section, use `lightning-vertical-navigation-overflow`. The overflow section doesn't adjust automatically based on the view port.

## Design

`lightning-vertical-navigation` implements the vertical navigation blueprint in the Salesforce Lightning Design System (SLDS). The vertical navigation adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Vertical Navigation](https://v1.lightningdesignsystem.com/components/vertical-navigation/)                                           | [Vertical Navigation](https://www.lightningdesignsystem.com/components/vertical-navigation/)                    |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Usage

Use `lightning-vertical-navigation` together with these sub-components.

- `lightning-vertical-navigation-section`
- `lightning-vertical-navigation-item`
- `lightning-vertical-navigation-overflow`
- `lightning-vertical-navigation-item-badge`
- `lightning-vertical-navigation-item-icon`

This example creates a basic vertical navigation menu.

<!-- prettier-ignore-start -->
```html
<lightning-vertical-navigation>
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Created by Me"
            name="created"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Private Reports"
            name="private"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Public Reports"
            name="public"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
</lightning-vertical-navigation>
```
<!-- prettier-ignore-end -->

To define an active navigation item, use `selected-item="itemName"` on `lightning-vertical-navigation`, where `itemName` matches the `name` of the `lightning-vertical-navigation-item` component to be highlighted.

This example creates a navigation menu with a highlighted item and an overflow section.

<!-- prettier-ignore-start -->
```html
<lightning-vertical-navigation selected-item="recent">
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
    <lightning-vertical-navigation-overflow>
        <lightning-vertical-navigation-item
            label="Regional Sales East"
            name="east"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Regional Sales West"
            name="west"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-overflow>
</lightning-vertical-navigation>
```
<!-- prettier-ignore-end -->

## Select a Navigation Item

To determine which navigation item is selected, use the `event.detail` property on the `onselect` event handler.

<!-- prettier-ignore-start -->
```html
<lightning-vertical-navigation onselect={handleSelect} selected-item="recent">
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Created by Me"
            name="created"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
</lightning-vertical-navigation>
```
<!-- prettier-ignore-end -->

The `onselect` event handler returns the name of the navigation item that's selected.

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

export default class VerticalNavigationExample extends LightningElement {
  handleSelect(event) {
    const selectedName = event.detail.name;
  }
}
```

## Usage Considerations

If you want a navigation menu that's more than one level deep, consider using `lightning-tree` instead.

The navigation menu takes up the full width of the screen. You can specify a width by wrapping in a div and specifying width using CSS.

<!-- prettier-ignore-start -->
```html
<div style="width: 320px;">
    <lightning-vertical-navigation> ... </lightning-vertical-navigation>
</div>
```
<!-- prettier-ignore-end -->

## Accessibility

Use the Tab and Shift+Tab keys to navigate up and down the menu. To expand or collapse an overflow section, press the Enter key or Space Bar.

## Custom Events

**`beforeselect`**

The event fired before a navigation item is selected.

The `beforeselect` event returns the following parameter.

| Parameter | Type   | Description                                                                                                      |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| name      | string | The name of the item to be selected, which matches the `name` value on the `vertical-navigation-item` component. |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

**`select`**

The event fired when a navigation item is selected.

The `select` event returns the following parameter.

| Parameter | Type   | Description                                                                                                |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| name      | string | The name of the selected item, which matches the `name` value on the `vertical-navigation-item` component. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside the template in which it was dispatched.                            |


:::::

:::::tab
::component-specification{component="verticalNavigation" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=265186c05ddde20771a1a4dc4f6e22918a306c89e918c511f2a37c4520b74210 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/verticalNavigationItem/lightning-vertical-navigation-item.md -->


# Vertical Navigation Item

**`lightning-vertical-navigation-item`**

A text-only link within lightning-vertical-navigation-section or lightning-vertical-navigation-overflow.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="verticalNavigationItem" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-vertical-navigation-item` component is a navigation item within `lightning-vertical-navigation`.

For more information, see the
[lightning-vertical-navigation](/docs/platform/lightning-component-reference/guide/lightning-vertical-navigation.html) documentation.


:::::

:::::tab
::component-specification{component="verticalNavigationItem" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=49a630c32adfc6554a16595570e4419d7efc9014e8c0a6e7d1f0108c57bbe6bb url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/verticalNavigationItemBadge/lightning-vertical-navigation-item-badge.md -->


# Vertical Navigation Item Badge

**`lightning-vertical-navigation-item-badge`**

A link and badge within lightning-vertical-navigation-section or lightning-vertical-navigation-overflow.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="verticalNavigationItemBadge" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-vertical-navigation-item-badge` component is a navigation item that displays a numerical badge to the right of the item label.

Here's an example that creates a navigation menu with an item containing a badge.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-vertical-navigation selected-item="recent">
        <lightning-vertical-navigation-section label="Reports">
            <lightning-vertical-navigation-item-badge
                label="Recent"
                name="recent"
                badge-count="3"
            >
            </lightning-vertical-navigation-item-badge>
            <lightning-vertical-navigation-item
                label="Created by Me"
                name="usercreated"
            >
            </lightning-vertical-navigation-item>
            <lightning-vertical-navigation-item
                label="Private Reports"
                name="private"
            >
            </lightning-vertical-navigation-item>
            <lightning-vertical-navigation-item
                label="Public Reports"
                name="public"
            >
            </lightning-vertical-navigation-item>
            <lightning-vertical-navigation-item label="All Reports" name="all">
            </lightning-vertical-navigation-item>
        </lightning-vertical-navigation-section>
    </lightning-vertical-navigation>
</template>
```
<!-- prettier-ignore-end -->


:::::

:::::tab
::component-specification{component="verticalNavigationItemBadge" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=65024b0b6f066093ca69bef64117490f945ad47dc46f7a2ae567df31fbde8516 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/verticalNavigationItemIcon/lightning-vertical-navigation-item-icon.md -->


# Vertical Navigation Item Icon

**`lightning-vertical-navigation-item-icon`**

A link and icon within lightning-vertical-navigation-section or lightning-vertical-navigation-overflow.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="verticalNavigationItemIcon" model="lwc" namespace="lightning"}


:::::

:::::tab

A `lightning-vertical-navigation-item-icon` component is a navigation item that displays an icon to the left of the item label.

Here's an example that creates a navigation menu with icons on the navigation items.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-vertical-navigation>
        <lightning-vertical-navigation-section label="Reports">
            <lightning-vertical-navigation-item-icon
                label="Recent"
                name="recent"
                icon-name="utility:clock"
            >
            </lightning-vertical-navigation-item-icon>
            <lightning-vertical-navigation-item-icon
                label="Created by Me"
                name="created"
                icon-name="utility:user"
            >
            </lightning-vertical-navigation-item-icon>
            <lightning-vertical-navigation-item label="All Reports" name="all">
            </lightning-vertical-navigation-item>
        </lightning-vertical-navigation-section>
    </lightning-vertical-navigation>
</template>
```
<!-- prettier-ignore-end -->

Icons from the Lightning Design System are supported. Visit [https://lightningdesignsystem.com/icons](https://lightningdesignsystem.com/icons) to view available icons.

When applying Lightning Design System classes or icons, check that they are available in the
Lightning Design System release tied to your org. The latest Lightning Design System
resources become available only when the new release is available in your org.


:::::

:::::tab
::component-specification{component="verticalNavigationItemIcon" model="lwc" namespace="lightning"}

:::::

::::::

<!-- document id=6d27e9978b86c5ef0529b596f3592447f675c83d45bec53e9cfff342327c62da url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/aura/components/aura/waiting/aura-waiting.md -->

# Waiting (Deprecated)

**`aura:waiting`**

Indicates that the client-side framework is currently awaiting a response to a server request.

::::::tabset{tabs='["Develop", "Specifications"]'}

:::::tab

The `aura:waiting` event is deprecated. Execute logic after queueing an action instead of using this event. A component is waiting for a response for an action until the action’s callback is invoked. The `aura:doneWaiting` application event is fired for every server request, even for requests from other components in your app. Unless your component is running in complete isolation in a standalone app and not included in Lightning Experience or the Salesforce mobile app, the container app may trigger your event handler multiple times. This behavior makes it difficult to handle each event appropriately.

Handle the `aura:waiting` event in a client-side controller. A component can have only one `<aura:handler>` tag to handle this event.

```xml
<aura:handler event="aura:waiting" action="{!c.showSpinner}" />
```

This example shows a spinner when `aura:waiting` is fired.

```xml
<aura:component>
  <aura:handler event="aura:waiting" action="{!c.showSpinner}" />
  <!-- Other component markup here -->
  <center><ui:spinner aura:id="spinner" /></center>
</aura:component>
```

This client-side controller fires an event that displays the spinner.

```javascript
({
  showSpinner: function (component, event, helper) {
    var spinner = component.find("spinner");
    var evt = spinner.get("e.toggle");
    evt.setParams({ isVisible: true });
    evt.fire();
  },
});
```


:::::

:::::tab

![No specifications to show](https://developer.salesforce.com/media/no-specs.png)


:::::

::::::

<!-- document id=d5028dfef47b7c17b9d085c40fa2787848782aafc6e10c6f783e1611f2a57fe6 url=/developer/current/en-us/lightning-base-components/lightning-design-system/guides/base-components-reference.md -->

# What's New?

The new Component Reference adopts a similar look-and-feel of other Salesforce developer documentation. At the same time, it maintains some features of the legacy site by presenting the component information on separate tabs. The main documentation is now on a Develop tab, with the component API descriptions on a Specifications tab. The Examples tab presents running code examples along with the component code. 

The [legacy Component Reference](https://developer.salesforce.com/docs/component-library/) was available as part of the Component Library and is no longer updated.

## Differences Between the Component Reference Sites

Here are a few differences between the new Component Reference and the legacy Component Reference.

|                                             | New Component Reference                                                                                                                                                                                                                                              | Legacy Component Reference                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| View component categories                           | Use the overview pages such as [Components](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/components.md), [API Modules](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lwc/components/api.md), [Legacy Components](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/aura/components/legacy.md) to see the categories of components.                                                                    | On the Overview page, filter by categories, targets, or namespaces.                                                                                                                                                                                                                                                                              |
| View experiences that support the component | See the **For Use In** section on each component page, which describes where you can use the component. For example, in Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Standalone Lightning App, and so on.                                  | See the Target panel at the top of each component page.                                                                                                                                                                                                                                                                                          |
| Switch between Aura and LWC                   | Switch from the Aura version of a component by clicking the LWC equivalent that's presented before the **For Use In** section.                                                                                                                                       | Switch between the versions of a component by clicking the **View as Aura Component** and **View as Lightning Web Component** button.                                                                                                                                                                                                            |
| View examples                               | LWC examples render using the latest release. Some components, such as `lightning-record-form` and `lightning-input-field`, require Salesforce data. They can't be used outside an org and don't have an Example page.                                               | Examples use base components and Salesforce Lightning Design System (SLDS) from an older release, before newer components like `lightning-alert` and `lightning-modal`. Some components, such as `lightning-record-form` and `lightning-input-field`, require Salesforce data. They can't be used outside an org and don't have an Example page. |
| View documentation                          | Develop tabs display documentation with improved structure and navigation, right-side links to topics, formatted in-doc code samples with copy buttons and dark mode.                                                                                                | Documentation tabs display documentation with little formatting or navigation features.                                                                                                                                                                                                                                                          |
| View specification                          | Same as legacy Component Reference, but more reliable display for Type and Default values. The Access field is not displayed because all documented components/modules have global access. Support status is included in the documentation instead of Specification. | Specification pages display attributes, methods, slots, and events information. Display of values for Type and Default is unreliable.                                                                                                                                                                                                            |
| Modify LWC examples                         | Modifying examples isn't supported currently.                                                                                                                                                                                                                        | Modify examples and run them in real time. However, examples use an older release of base components and don't support newer components, attributes, and methods.                                                                                                                                                                                |
| View Aura examples                          | Aura examples are displayed as an image. Aura examples aren't interactive.                                                                                                                                                                                           | Aura examples are interactive.                                                                                                                                                                                                                                                                                                                   |

**note:** You can't display custom Aura component documentation for your org in the new Component Reference. The new site is only available as a web site, not an application that can run in your org. The Component Library app will continue to run in your org so you can view your custom Aura component doc there.