Tips and Considerations for Configuring Components for Lightning Pages and the Lightning App Builder

Keep these guidelines in mind when creating components and component bundles for Lightning pages and the Lightning App Builder.
Note

Note

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 Community Builder user in another org.

Components

  • Set a friendly name for the component using the label attribute in the element in the design file, such as <design:component label="foo">.
  • Design your components to fill 100% of the width (including margins) of the region that they display in.
  • Components should provide an appropriate placeholder behavior in declarative tools if they require interaction.
  • A component should never 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. This improves the user’s perception of UI responsiveness.
  • If the component depends on a fired event, then give it a default state that displays before the event fires.
  • Style components in a manner consistent with the styling of Lightning Experience and consistent with the Salesforce Design System.

Attributes

  • Use the design file to control which attributes are exposed to the Lightning App Builder.
  • Make your attributes easy to use and understandable to an administrator. Don’t expose SOQL queries, JSON objects, or Apex class names.
  • Give your required attributes default values. When a component that has required attributes 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 attributes.
  • Specify a min and max attribute for integer attributes in the <design:attribute> element to control the range of accepted values.
  • String attributes can provide a datasource with a set of predefined values allowing the attribute to expose its configuration as a picklist.
  • Give all attributes 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 Property Editor.
  • To delete a design attribute for a component that implements the flexipage:availableForAllPageTypes or forceCommunity:availableForAllPageTypes interface, first remove the interface from the component before deleting the design attribute. Then reimplement the interface. If the component is referenced in a Lightning page, you must remove the component from the page before you can change it.

Limitations

The Lightning App Builder doesn’t support the Map, Object, or java:// complex types.