--- schema_version: "1" id: 6774cb75410a928293b3928a96c1105e205a079972f05e98c311715f62612273 title: Reference collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/analytics/bi-dev-guide-lwc-in-db/guides/reference/bi-lwc-in-db-reference.md canonical_url: https://developer.salesforce.com/docs/analytics/bi-dev-guide-lwc-in-db/guide/bi-lwc-in-db-reference.html source_site: developer.salesforce.com content_type: documentation content_hash: f61852ee6e249abbbf5dee4fa11d1d82168cf11231732841fe9a45662142ed2b products: - Lightning Web Components in CRM Analytics Dashboards - analytics --- # Reference Detailed reference for Lightning Web Components in Analytics dashboards. ## Component Configuration Description of attributes for the component `js-meta.xml` file. **`analytics__Dashboard` Target** To allow the component to be used in Analytics dashboards, add this target to the list of `targets`. ```nolang analytics__Dashboard ``` To customize how the component appears in Analytics dashboards, add a `targetConfig` to `targetConfigs`. ```nolang ``` **`` tag** In an `analytics__Dashboard` target config, you can choose to include the `true` attribute. For Lightning dashboards, the \ tag is always set to false. ```nolang true ``` This attribute indicates that your component requires a dashboard step to function as expected. With this tag, the dashboard builder UI prompts the user to attach an existing step or to create a step to an instance of the component. Components with an attached step have access to step specific API hooks like `results` and `selection`. **Measure and Dimension Attribute Data Types** Attributes specified in an `analytics__Dashboard` target config are displayed in the Analytics dashboard builder UI for configuration. In addition to the common data types, this target also supports `Measure` and `Dimension` data types for components with `true`. The dashboard builder is able to choose a column of the given data type from the results of the attached step. ```nolang true ``` ## API Hooks Overview **note:** These API hooks aren’t supported for Lightning dashboards. | Name | Description | Available for Use in LWC | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `results` | An array of objects. | Requires `true`. | | `metadata` | An object with three arrays: `groups`, `strings`, and `numbers`. Each array is the field name of each type from the associated query. | Requires `true`. | | `selectMode` | Returns the selection mode of the associated query. Valid values are:
  • `single`
  • `multi`
  • `singlerequired`
  • `multirequired`
  • `none`
| Requires `true`. | | `selection` | The current selection of the associated step. | Requires `true`. | | `setSelection` | Use this function to modify the current selection on the associated step and inform the parent dashboard. | Requires `true`. | | `getState` | Use this function to retrieve the entire parent dashboard state as a JSON document. | Always available. | | `setState` | Use this function to modify the dashboard state. | Always available | | `refresh` | Use this function to refresh the dashboard state. | Always available | ## API Hooks Details **Results** The results are rows returned by the query represented as an array of maps. ```json [ { "columnOne": "one", "columnTwo": 123 }, { "columnOne": "two", "columnTwo": 456 } ] ``` **Metadata** Metadata describes the shape of the results using lists of column developer names organized into `groups`, `numbers`, and `strings`. - `Groups` - Grouped dimensions. Typically, all grouped columns can be used together as a primary key for the row. - `Strings` - All text fields, also known as `Strings` or `Dimensions`. - `Numbers` - All numeric fields, also known as `Measures`. ```json { "groups": [], "strings": ["columnOne"], "numbers": ["columnTwo"] } ``` **`selectMode`** Returns the select mode specified for the associated step. Valid values are: - `single` - `multi` - `singlerequired` - `multirequired` - `none` ```javascript isMultiSelect() { return this.selectMode.includes('multi'); } ``` **`selection`** The current selection of the associated step as an Array of objects, with each object being one or more selected rows from `results`. Use the `setSelection` function to update the dashboard selection. ```nolang return new Map((this.selection ?? []).map((row) => [this.hash(row), row])); ``` **`setSelection`** The `setSelection` function is a callback passed in that allows the component to update the attached step's selection in Analytics. In doing so, it potentially applies filters to the rest of the dashboard's contents depending on how the queries are configured. ```javascript this.setSelection(this.isMultiSelect() ? [...selectedRowsByHash.values(), row] : [row]); ``` **`getState` and `setState`** Use `getState` to retrieve the current state of the dashboard. Use `setState` to modify the current state of the dashboard. Fetch and modify all the current selections, filters, and the currently viewed page. Use these functions to add custom logic and behavior that's not standard in the dashboard runtime. ```javascript if (!this.getState().pageId == this.targetPage) { this.priorPage = this.getState().pageId; this.setState({ ...this.getState(), pageId: this.targetPage, replaceState: true }); } ``` Learn more about selection syntax with [Filter and Selection Syntax for Embedded Dashboards](https://help.salesforce.com/articleView?id=bi_embed_filters.htm). **`refresh`** Use `refresh` to rerun either all the queries on the dashboard or a particular query. To rerun a specific query, use the `config` argument with the step id of the query. ```javascript this.refresh({ step: this.step }); ``` ## Custom Lifecycle Methods **`stateChangedCallback`** Use `stateChangedCallback`, a built-in callback method, to inform the component whenever the state of the dashboard changes. Use `stateChangedCallback` to compare the current state with the new state and then rerender if necessary. ```javascript stateChangedCallback(prevState, newState) { // perform comparison logic and set the new state to the current state to trigger a rerender of the component this.currentState = newState; } ``` For an example of this callback in action, see the [Breadcrumb](https://github.com/forcedotcom/sfdx-analytics/tree/main/quick-start/main/default/lwc/breadcrumb) javascript in the GitHub example repository. This callback method is available in v55 and later.