Spatial navigation and focus management for TVs and gaming consoles done simple. Uses react-sunbeam 🌅 under the hood.
Provides three easy to use code components.
- Drag them onto your canvas
- Connect them to their content (
Framesor any other code components) - Specify the child property to update on focus for every
Focusable - Drop your
Focusables into the SunbeamScrollcomponent if you need scrolling behaviour - Run the preview of the
FramecontainingSunbeamContainer - Press arrow keys on your keyboard/gamepad/tv remote
- Enjoy spatial navigation magic happen
You can download the example Framer project that demonstrates how to setup Framer Sunbeam below. Unzip the archive and open the file in Framer X.
Creates a focus management context.
Connect it to the Frame within which you want focus to be managed
You can only have one SunbeamContainer per artboard
Allows to override the default spacial navigation keys. See the full list of available key codes here
Allows to invoke some function when a keyboard key is pressed. Can be provided via code overrides.
Allows to invoke a function when the focus is updated. An event object containing the new focusPath is passed to this callback.
Can be provided via code overrides.
Defines a component that can receive focus.
Connect it to a content component (Frame or any other code/design component).
Most of the time you want the size of the Focusable to match the size of its child content because when calculating the best candidate for receiving focus Sunbeam uses position and dimensions of the Focusable, not its content
You can nest Focusables, in this case the best candidate for the focus is first attempted to be found within the same Focusable parent.
This is useful when creating sections of the UI, e.g. Side Menu where the Focusable items are not necessarily positioned to each other closer than to the items from the Main section
Set to a randomly generated string by default.
Identifier of a Focusable. Has to be unique among the Focusable siblings
Set to false by default.
Specifies if the Focusable should receive focus when tapped/clicked
Name of the child prop that will be updated when Focusable receives/loses focus.
E.g. if you are wrapping a Frame you can find the list of the props available to you here
Type of focusProp
Focused value - focusedValueString?: string or focusedValueBoolean?: boolean or focusedValueNumber?: number or focusedValueColor?: string
Value that is passed to the child's prop when the Focusable is focused
Blurred value - blurredValueString?: string or blurredValueBoolean?: boolean or blurredValueNumber: number or blurredValueColor: string
Value that is passed to the child's prop when the Focusable is blurred
Function that is called when the Focusable receives focus. Can be provided via code overrides. Receives focusablePath which is an array of focusableKeys of all Focusables in the hierarchy from the root Focusable to the current one. Can be useful for saving the focus state or reacting to the focus updates, e.g. manual scrolling to the focused component
Mimics the behaviour of the Framer built-in Scroll component but it is aware
of the currently focused Focusable child and automatically scrolls it into view when needed.
This component is useful for creating scrollable carousels and grids of Focusable components
Specifies whether the content overflowing the Scroll viewport should be visible or not
The allowed direction of scrolling
Type of the transition to use for scrolling: Spring or Tween
Damping parameter of the Spring transition. See more here
Stiffness parameter of the Spring transition. See more here
Duration parameter of the Tween transition. See more here
Easing - easing: "linear" | "easeIn" | "easeOut" | "easeInOut" | "circIn" | "circOut" | "circInOut" | "backIn" | "backOut" | "backInOut" | "anticipate"
Easing parameter of the Tween transition. See more here
Framer Sunbeam re-exports some of the react-sunbeam 🌅 primitives and other helper functions so you can use them directly in you code to create your own custom focusable components without connecting a Focusable to another component on canvas.
You can implement your own focusable Button like this:
import * as React from "react"
import { addPropertyControls, ControlType } from "framer"
import { useFocusable } from "@framer/vladimirg.framersunbeam/code"
addPropertyControls(Button, {
focusKey: {
type: ControlType.String,
defaultValue: "CHANGE THIS TO A UNIQUE VALUE",
},
})
export function Button({ focusKey, width, height }) {
const ref = React.useRef(null)
const { focused } = useFocusable(focusKey, ref)
return (
<button
ref={ref}
style={{
width,
height,
border: focused ? "2px solid tomato" : "none",
}}
>
Go
</button>
)
}Fix Scroll fill
Expose property controls for Scroll's transition
Remove ScrollContext and useOnFocus, instead add the Scroll notification logic to useFocusable
Remove ScrollContext from module export but export it as a global variable SunbeamScrollContext
Export ScrollContext and useOnFocus
Export Focusable, useSunbeam, useFocusable and defaultGetPreferredChildOnFocusReceive so those can be used
directly in your custom code components.
Add onKeyPress and onFocusUpdate props to SunbeamContainer
Proudly introducing the new component - Scroll 🎉.
It mimics the behaviour of the Framer built-in Scroll component but it is aware of the currently focused Focusable
and automatically scrolls it into view
BREAKING CHANGE: onFocus callback now accepts an object of type { element: HTMLElement; focusablePath: string[] } as an argument, before it was a string focusablePath