‼️ This repo is archived as of April 2023. Developers looking for source code should reference the public npm package lightning-base-components. Source code is provided as-is with no support contract. ‼️

ARCHIVED: Base Components Recipes

View examples for base components in small bites. Each recipe demonstrates a working example of the base components to build pages and apps quickly. Use and customize the base components and the recipes in your apps.

Base component recipes open up the source code for the base components shown in the Component Library. We transpiled the base components into the c namespace so that you can use the components in your projects. Explore the inner workings of the components and use the source code to build new components with your own requirements. The possibilities are endless with the source in your hands!

Only a subset of the components in the Component Library are available. For more information, see the Documentation section.

Base components implement Salesforce Lightning Design System (SLDS) and are developed using Lightning Web Components. A c namespace component can contain components in the lightning namespace.

Before You Start

Consider using base component recipes only if the base components in the lightning namespace don't work for your requirements. For example, use base component recipes if you need to customize the styles of the base components beyond supported styling mechanisms. For a list of available base components in the lightning namespace, see the Component Library.

To customize the styles on lightning namespace components, we recommend using SLDS styling hooks. For more information, see Style Components with SLDS.

Getting Started

We recommend using a scratch org to work with base component recipes on the Salesforce platform.

1. Set up your environment by following the steps in the Lightning Web Components Dev Guide, which includes:

   • Install the Salesforce CLI.
   • Install Visual Studio Code and the Salesforce Extension Pack, or your own favorite code editor.
   • Set up a Dev Hub org so you can work with Lightning web components in scratch orgs.

2. Authenticate with your Dev Hub org and provide it with an alias, as shown by mybaseorg in the following command.

sfdx force:auth:web:login -d -a mybaseorg

3. Clone the base-component-recipes repository.

git clone [email protected]:salesforce/base-components-recipes.git
cd base-components-recipes

4. Create a scratch org and provide it with an alias, as shown by base-recipes in the following command.

sfdx force:org:create -s -f config/project-scratch-def.json -a base-recipes

If you get an error "You do not have access to the [ScratchOrgInfo] object", make sure you have enabled your org as a Dev Hub org. See Enable Dev Hub in Your Org. Alternatively, sign up for a Dev Hub org at https://developer.salesforce.com/promotions/orgs/dx-signup.

5. Push the base-components-recipes code to your scratch org.

sfdx force:source:push

6. Open the scratch org.

sfdx force:org:open

7. In App Launcher, select the Base Components app. This app shows the base component recipes at base-components-recipes/example/lwc.

Use Base Components on Salesforce Platform

Create a helloWorld Lightning web component that uses a base component, c-button. We'll use Visual Studio Code in this example.

1. In Visual Studio Code, open your base-components-recipes directory.
2. Open the Command Palette by pressing Ctrl+Shift+P on Windows or Cmd+Shift+P on macOS.
3. Type SFDX.
4. Select SFDX: Create Lightning Web Component.
5. Type helloWorld for the name of the new component and press Enter.
6. Press Enter to accept the default force-app/main/default/lwc directory.
7. A helloWorld bundle is created in force-app/main/default/lwc and the helloWorld.js JavaScript file opens in the editor.
8. In helloWorld.js, replace the content with the following code. Save the file.

//helloWorld.js

import { LightningElement, api } from 'lwc';
export default class HelloWorld extends LightningElement {
    @api greeting = 'Hello World';
}

9. Open the HTML file, helloWorld.html, and replace its content with the following code. Save the file.

<!--helloWorld.html-->

<template>
    <c-button label={greeting} title="greeting"> </c-button>
</template>

10. In the XML file, helloWorld.js-meta.xml, replace the content with the following code. Save the file.

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>47.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__RecordPage</target>
        <target>lightning__HomePage</target>
  </targets>
</LightningComponentBundle>

11. Push your changes.

sfdx force:source:push

Your helloWorld component is now ready for action. You can add this component to your apps and pages via the Lightning App Builder. For more information, see the Quick Start: Lightning Web Components Trailhead project.

[Experimental] Use Base Components Outside of Salesforce Platform

Base Components in the c namespace are intended for use on the Salesforce platform. However, we realize the desire to use them in non-Salesforce scenarios. Currently, many components will work, but others will not, due to dependencies on the Salesforce platform. Our goal is to provide Base Components for non-Salesforce use cases, and we’ve created the LWC Storybook PoC to show what this might look like in the future. Please click the Watch button on the repo for updates as we move forward.

Documentation

Base components in the c namespace map to components in the lightning namespace. We transpiled the base components into the c namespace so that you can use the components in your projects. Find the base components in the c namespace in base-components-recipes/force-app/main/default/lwc/.

The components below link to documentation for components in the lightning namespace, but the usage is similar unless otherwise noted.

Localization

You can create up to 5,000 custom labels for your organization, and they can be up to 1,000 characters in length. Create custom labels that you can use in your Lightning web components.

Update Labels

To update the Custom Labels metadata, go to the force-app/main/default/labels directory. The labels are available in the lightning.labels-meta.xml file. For syntax and an example of a CustomLabels definition, see the Metadata API Dev Guide.

Add labels for your custom components in the lightning.labels-meta.xml file.

<labels>
    <categories>lightning</categories>
    <fullName>MyCard_cardTitle</fullName>
    <language>en_US</language>
    <protected>false</protected>
    <shortDescription>cardTitleLabel</shortDescription>
    <value>This is my card</value>
  </labels>

Customize Labels

To customize your labels, from Setup, type Custom Labels in the Quick Find box, then select Custom Labels. Our labels are shipped in English and can be translated to other languages. For more information, see the Translate Labels section below and Custom Labels in Salesforce Help.

Use Labels

Import the labels from the @salesforce/label scoped module. Reference your label name using the c namespace.

// myComponent.js

import cardTitleLabel from '@salesforce/label/c.MyCard_cardTitle';
import loadingLabel from '@salesforce/label/c.lightning_LightningControl_loading';
import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {
    label = {
        cardTitleLabel,
        loadingLabel
    };
}

Use your labels in a Lightning web component.

<!-- myComponent.html -->

<template>
    <c-card title={label.cardTitleLabel}>
        {label.loadingLabel}
    </c-card>
</template>

Translate Labels

Enable the Translation Workbench to support translations in your org. See Enable and Disable the Translation Workbench in Salesforce Help. Next, modify sfdx-project.json to include the path for the translation files, which are available in the optional folder.

{
    "packageDirectories": [
        {
            "path": "force-app",
            "default": true
        },
        {
            "path": "examples",
            "default": false
        },
        {
            "path": "optional"
        }
    ],
    "namespace": "",
    "sfdcLoginUrl": "https://login.salesforce.com",
    "sourceApiVersion": "46.0"
}

After updating sfdx-project.json, push the files to your scratch org.

sfdx force:source:push

Testing

We use the Jest JavaScript Testing Framework to author and run component tests. If you modify any base component recipes or add your own components, run tests to verify your changes.

For your own components, add tests to a __tests__ sub-folder of your componentName folder and name the test componentName.spec.js.

To illustrate how to test components we'll add a test to the helloWorld component created earlier.

1. Create a __tests__ subfolder in the helloWorld folder.

2. Create a file named helloWorld.spec.js in __tests__.

3. Insert this code and save the file.

//__tests__/helloWorld.spec.js

import { createElement } from 'lwc';
import Element from 'c/helloWorld';

const createComponent = (params = {}) => {
    const element = createElement('c-hello-world', { is: Element });
    Object.assign(element, params);
    document.body.appendChild(element);
    return element;
};

describe('c-hello-world', () => {
    it('button has the expected message', () => {
        const element = createComponent();
        const button = element.shadowRoot.querySelector('c-button');
        return Promise.resolve().then(() => {
            expect(button.label).toEqual('Hello World');
        });
    });
});

4. Run the helloWorld test suite from the base-components-recipe folder.

npm run test helloWorld

5. Run all base components recipes test suites.

npm run test

This runs lint and unit tests. See the package.json file for all the available tests.

Contributing

We are not accepting contributions at this time. If you have any questions about base components recipes, please use the following channels.

• Trailblazer Community - Lightning Components Development
• Salesforce Developer Forums
• Salesforce Stackexchange

FAQ

• Where can I see more examples on how to use Lightning Web Components?

  • For examples on running Lightning Web Components on Salesforce platform, visit lwc-recipes.
  • For more sample apps using Lightning Web Components, visit https://trailhead.salesforce.com/sample-gallery.
  • To experience Lightning Web Components on any platform, visit https://lwc.dev.

• How do I create a Lightning Web Component?

  See the Quick Start: Lightning Web Components Trailhead project. The Lightning Web Components Developer Guide is also a great resource.