Tips for Working with Lightning App Builder

Keep these guidelines in mind when creating components to expose in Lightning App Builder.

  • Make components fill 100% of the width (including margins) of the region that they display in. See Make a Component Width-Aware.
  • If components require interaction, provide an appropriate placeholder behavior in Lightning App Builder.
  • Don’t display a blank box. Think of how other sites work. For example, Facebook displays an outline of the feed before the actual feed items come back from the server. The outline improves the user’s perception of UI responsiveness.
  • If a component depends on a fired event, give it a default state that displays before the event fires.
  • Use Salesforce Design System to style components.
  • Set a friendly name for the component using the masterLabel tag in the configuration file.
  • Use the configuration file to expose properties to the Lightning App Builder.
  • We strongly recommend including supported form factor information in the configuration file for all your components.
  • Give all properties a label with a friendly display name.
  • Provide descriptions to explain the expected data and any guidelines, such as data format or expected range of values. Description text appears as a tooltip in the Lightning App Builder’s property editor.
  • Give your required properties default values. When a component that has required properties with no default values is added to the App Builder, it appears invalid, which is a poor user experience.
  • Use basic supported types (string, integer, boolean) for any exposed properties.
  • When defining a component property, make sure that it has the same type assigned (String, Integer, Boolean) in the .js file and in the configuration file. If the assigned types don’t match, the type assignment from the configuration file takes precedence.
  • Specify a min and max attribute for integer properties to control the range of accepted values.
  • String properties can provide a datasource with a set of predefined values allowing the property to expose its configuration as a picklist.
  • If a component is used on a Lightning page or in a managed package, we prevent you from making destructive changes that can break the component. Some examples of these destructive changes are:
    • Removing object tags if the component is in use on a record page for that object.
    • Removing page type support if the component is in use on that type of page.
    • Changing min or max property values if the component is in use on a Lightning page.
  • The Lightning App Builder doesn’t support the Map, Object, or java:// complex types.
  • Once a component is in use on a Lightning page, you can only increase the supported form factors for the component, not decrease them.
  • Pull to refresh doesn’t work for custom Lightning web components in the Salesforce mobile app.