SetFocus Command

SetFocus requires APL 1.1 or later. Provide an alternate experience for devices running older versions of APL.

Changes the actionable component that has focus. For details about the components that can receive and lose focus, see Focused.

Only one component has focus at a time. Setting the focus on a component automatically clears it from other components.

When SetFocus runs, the command does the following:

  1. Places the targeted component into focus and sets the focused state for the component to true.
  2. Removes focus from any component that had it before and sets that component's focused state to false.

The SetFocus command is ignored if the targeted component is disabled, not actionable, or has the inheritParentState property set to true.

Properties

The SetFocus command has the properties shown in the following table, in addition to the common command properties. Set the type property to SetFocus.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description
componentId Selector :source The component to focus.

For example, the following command sets the focus to a specific component with the id myButton:

{
  "type": "SetFocus",
  "componentId": "myButton"
}

The SetFocus command runs in fast mode, but without any delay.

componentId

A selector that identifies the target component for the command. When not provided, defaults to :source. The :source selector targets the component that issued the SetFocus command.

To open a document with a component in focus, set the document onMount property to SetFocus.

For example, to focus the component with the id myButton on document mount:

{
  "onMount": {
    "type": "SetFocus",
    "componentId": "myButton"
  }
}

SetFocus example

The following example runs SetFocus in the document onMount handler. The example defines a style called textStyleFocusable, which changes the text color and font style to indicated the component with the focus.

Was this page helpful?

Last updated: frontmatter-missing