spotlight/SpotlightContainerDecorator

A component for managing groups of spottable components.

Interactive Demo

Members

SpotlightContainerDecorator Higher-Order Component

Constructs a higher-order component that allows Spotlight focus to be passed to its own configurable hierarchy of spottable child controls.

Note: This HoC passes a number of props to the wrapped component that should be passed to the main DOM node.

Example:

const Component = ({myProp, ...rest}) => (
	<div {...rest}>{myProp}</div>
);
...
const DefaultContainer = SpotlightContainerDecorator(Component);
const FocusDefaultContainer = SpotlightContainerDecorator({enterTo: 'default-element'}, Component);

To specify a default element to spot in a container, utilize the spotlightDefaultClass.

Example:

import Spotlight from '@enact/spotlight';
import SpotlightContainerDecorator from '@enact/spotlight/SpotlightContainerDecorator';
const ContainerComponent = SpotlightContainerDecorator(Component);
const View = kind({
	render: () => {
		<ContainerComponent>
			<SpottableComponent>foo</SpottableComponent>
			<SpottableComponent className={spotlightDefaultClass}>spot me first</SpottableComponent>
		</ContainerComponent>
	}
});

Configuration

continue5WayHold

Boolean

When true, allows focus to move outside the container to the next spottable element when holding 5 way keys.

Default: false

defaultElement

StringArray(String)

The selector for the default spottable element within the container. When an array of selectors is provided, the first selector that successfully matches a node is used.

Default: '.spottable-default'

enterTo

String

Directs which element receives focus when gaining focus from another container. If 'default-element', the default focused item will be selected. If 'last-focused', the container will focus the last focused item; if the container has never had focus, the default element will receive focus. If null, the default 5-way behavior will be applied.

Default: null

leaveFor

Object

Directs which element receives focus when the focus is leaving from the current container using 5-way direction keys. If {down: '#left'}, the focus moves to the DOM element whose id value is left when pressing the 5-way down. If {left: '', right: ''}, the focus cannot leave the current container with 5-way left and right. If null, the default 5-way behavior will be applied.

Default: null

navigableFilter

Function

Filter the navigable elements.

preserveId

Boolean

Whether the container will preserve the specified spotlightId when it unmounts.

Default: false

restrict

String

Restricts or prioritizes navigation when focus attempts to leave the container. It can be either 'none', 'self-first', or 'self-only'. Specifying 'self-first' indicates that elements within the container will have a higher likelihood to be chosen as the next navigable element. Specifying 'self-only' indicates that elements in other containers cannot be navigated to by using 5-way navigation - however, elements in other containers can still receive focus by calling Spotlight.focus(elem) explicitly. Specifying 'none' indicates there should be no restrictions when 5-way navigating the container.

Default: 'self-first'

Properties added to wrapped component

spotlightDisabled

Boolean

When true, controls in the container cannot be navigated.

Default: false

spotlightId

String

Used to identify this component within the Spotlight system.

If the value is null, an id will be generated. To keep the container information for restoring focus, it is required to specify a unique identifier.

spotlightMuted

Boolean

Whether or not the container is in muted mode.

In muted mode, :focus CSS styles will not be applied to the Spottable controls giving them the appearance of not having focus while they still have focus.

Default: false

spotlightRestrict

String

Default: 'self-first'

spotlightDefaultClass string

The class name to apply to the default component to focus in a container.