Configure Components for Custom Actions

Add the force:lightningQuickAction or force:lightningQuickActionWithoutHeader interface to a Lightning component to enable it to be used as a custom action in Lightning Experience or Salesforce1. You can use components that implement one of these interfaces as object-specific actions in both Lightning Experience and Salesforce1. You can use them as global actions only in Salesforce1.

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 also display and implement their own controls, but should be prepared for events from the standard controls.

Components that implement the force:lightningQuickActionWithoutHeader interface display in a panel without additional controls and are expected to provide a complete user interface for the action.

These interfaces are mutually exclusive. That is, components can implement either the force:lightningQuickAction interface or the force:lightningQuickActionWithoutHeader interface, but not both. This should make sense; a component can’t both present standard user interface elements and not present standard user interface elements.

Example Component

Here’s an example of a component that can be used for a custom action, which you can name whatever you want—perhaps “Quick Add”. (A component and an action that uses it don’t need to have matching names.) This component allows you to quickly add two numbers together.

1<!--quickAdd.cmp-->
2<aura:component implements="force:lightningQuickAction">
3
4    <!-- Very simple addition -->
5
6    <ui:inputNumber aura:id="num1"/> +
7    <ui:inputNumber aura:id="num2"/>
8
9    <br/>
10    <ui:button label="Add" press="{!c.clickAdd}"/>
11
12</aura:component>

The component markup simply presents two input fields, and an Add button.

The component’s controller does all of the real work.

1/*quickAddController.js*/
2({
3    clickAdd: function(component, event, helper) {
4
5        // Get the values from the form
6        var n1 = component.find("num1").get("v.value");
7        var n2 = component.find("num2").get("v.value");
8
9        // Display the total in a "toast" status message
10        var resultsToast = $A.get("e.force:showToast");
11        resultsToast.setParams({
12            "title": "Quick Add: " + n1 + " + " + n2,
13            "message": "The total is: " + (n1 + n2) + "."
14        });
15        resultsToast.fire();
16
17        // Close the action panel
18        var dismissActionPanel = $A.get("e.force:closeQuickAction");
19        dismissActionPanel.fire();
20    }
21
22})

Retrieving the two numbers entered by the user is straightforward, though a more robust component would check for valid inputs, and so on. The interesting part of this example is what happens to the numbers and how the custom action resolves.

The results of the add calculation are displayed in a “toast,” which is a status message that appears at the top of the page. The toast is created by firing the force:showToast event. A toast isn’t the only way you could display the results, nor are actions the only use for toasts. It’s just a handy way to show a message at the top of the screen in Lightning Experience or Salesforce1.

What’s interesting about using a toast here, though, is what happens afterward. The clickAdd controller action fires the force:closeQuickAction event, which dismisses the action panel. But, even though the action panel is closed, the toast still displays. The force:closeQuickAction event is handled by the action panel, which closes. The force:showToast event is handled by the one.app container, so it doesn’t need the panel to work.

Lightning Components Developer Guide

Configure Components for Custom Actions

Example Component

See Also: