search

tisho / Switch.framerfx

Utility component for Framer X that lets you switch between different states of an element
31 stars 4 forks source link

readme

Switch

Switch is a utility component that lets you switch between different states of an element on the canvas using animated transitions. It comes with an additional SwitchToStateAction component, which acts as a hotspot that can change the current state of a Switch without writing any code.

→ View documentation on GitHub

→ File an issue on GitHub

Latest Release

3/26/2021

3/24/2021

→ See past releases

Examples

→ See examples in Framer Web (requires free account)

→ Download examples (.framerx file)

Bottom Sheet

Bottom Sheet Example

Tabs

Tabs Example

Carousel

Carousel Example

Tooltip

Tooltip

Toggle

Toggle

Usage

Interactive Switch

Interactive Switches can manage their own state. Use them when you need to have a Switch change its own state when it's tapped / hovered over. Here are a few examples of components that are a good fit for an interactive Switch:

Creating an Interactive Switch

  1. Drag and drop a Switch component onto the canvas.

  1. Connect it to the states you want to switch between.

  1. In the properties panel, set "Interactive" to "Yes".

  1. Choose the trigger for the state change, and the target action.

  1. Customize the transition to use when switching between states.

  1. Preview your prototype.

Controlled Switch

Controlled Switches rely on other elements to set their state. Here are a few use cases that are a good fit for a controlled Switch:

Creating a Controlled Switch

  1. Drag and drop a Switch component onto the canvas.

  1. Connect it to the states you want to switch between.

  1. Choose a unique name for your switch. This name will let other SwitchToStateAction hotspots control the state of your switch.

  1. Drag and drop a SwitchToStateAction component onto the canvas. This component will act as a hotspot that changes the state of a Switch component when the user interacts with it.

  1. Change the name of the target Switch to the name you used in step 3, then pick a trigger, and a target state.

  1. Customize the transition to use when switching between states.

  1. Preview your prototype.

Auto-Animating Between States

The "Auto-Animate" transition works differently from the other available state transitions. When triggered, elements shared between two states will animate their properties smoothly between each state. If there are elements in the next state that don't exist in the current one, they'll fade in, and elements that should no longer be shown will fade out.

How Element Matching Works

Before an auto-animate transition begins, the Switch component looks for matching elements between the current and the next state. To figure out if an element matches another element, it looks at:

Note: Names of Graphic layers are currently not recognized properly. To transition between Graphic layers, wrap them in a Frame and name the Frame.

Supported Transitions Between Matching Elements

If an element is found to be matching another element, we'll create an animated transition for the following properties:

If the two matching elements are of a different type (e.g. a transition between a Frame and a Graphic), or are of a type where a smooth transition isn't possible (e.g. transitions between two Text layers), the two elements will be animated using a cross-dissolve.

Customizing Auto-Animation Transition Timing

Each auto-animate transition groups transitioning elements in 3 categories:

Each group can have different transition timing. Morphing elements always use the timing options defined right below the "Transition" property when it's set to "Auto-Animate". The Enter and Exit transitions will have their own options right below (by default, they're set to a 0.3s dissolve).

Additionally, auto-animate lets you take advantage of Framer Motion's ability to stagger or delay animations of nested elements.

Auto-Animations Between Code Components

Since code components can render arbitrary HTML, it's hard for Switch to figure out if content rendered by the code component should also be auto-animated. To get around this issue, whenever it encounters a Code Component, the Switch will only animate its position and size. It will then determine if any of the component's props have changed between the different states, and if they have, it will pass the new props to the component.

Matching code components will not get unmounted and remounted between states, just passed new props. This is especially powerful with components that are expensive to fully re-render, like maps and videos.

If this behavior doesn't match what you expect, you can set the morphCodeComponentPropsOnly prop on a Switch instance to false through an Override, and we'll fall back to a cross-dissolve between the two states of the code component.

Using Switch in Code

Use these in Overrides, or when you use the Switch component from code.

Switch Overrides

Prop Type Description
autoAssignIdentifier boolean When true, the Switch instance will get its own random identifier automatically. Default: false
identifier string The name of the Switch instance. Make sure this is unique.
initialState number The index of the initial state of the Switch. Default: 0
overflow boolean Whether content outside the bounds of the container will be shown or not. Default: true
onSwitch function A callback function that will be called whenever the Switch component switches its state. The function is passed in the current state index, the previous state index, and the identifier of the Switch component in this order.
shouldTrigger function A callback function that will be called right before a trigger is fired. Returning false from this callback will stop the trigger from firing. All original arguments to the trigger will be passed down to the function (e.g. event)
transition enum The transition to use when switching states. Can be one of: instant, autoanimate, dissolve, zoom, zoomout, zoomin, swapup, swapdown, swapleft, swapright, slidehorizontal, slidevertical, slideup, slidedown, slideleft, slideright, pushhorizontal, pushvertical, pushup, pushdown, pushleft, pushright.

SwitchToStateAction Overrides

Prop Type Description
targetType enum Defines whether the SwitchToStateAction will target the closest switch, or target a specifically named Switch. Possible values are: closest, named. Default is named.
target string The name of the Switch instance to target. Make sure this is unique and matches the name of an existing Switch. Only used when targetType is set to named.
shouldTrigger function A callback function that will be called right before a trigger is fired. Returning false from this callback will stop the trigger from firing. All original arguments to the trigger will be passed down to the function (e.g. event)

Controlling Switches with the useSwitch Hook

To control Switches from code, first import the useSwitch hook at the top of your file:

import { useSwitch } from "@framer/tishogeorgiev.switch/code"

Note on Framer Web: Sometimes Web will throw an error in the in-app preview saying it can't find useSwitch. This is because it hasn't had time to reload all of its dependencies. When this happens, refresh your browser and it should be fine.

Note: You will likely get a red underline under @framer/tishogeorgiev.switch/code, with an error message like "Cannot find module '@framer/tishogeorgiev.switch/code'". You can safely ignore this error, as the code will work anyway. If it bothers you, import useSwitch like this, instead:

// @ts-ignore
import { useSwitch } from "@framer/tishogeorgiev.switch/code"

Then call the useSwitch() hook in your code component or override:

export function SwitchButton(): Override {
    const controls = useSwitch()

    return {
        onTap: () => {
            controls.setSwitchState("sharedSwitch", 1)
        },
    }
}

Note: you can only call this hook from inside a React component or override. Calling it from a different place in your code could result in unexpected behavior. Read more about the rules of hook usage.

The useSwitch hook will return a controls object with the following functions:

Past Releases

12/17/2020

10/30/2020

10/07/2020

9/08/2020

9/01/2020

7/17/2020

5/29/2020

5/26/2020

5/14/2020

4/6/2020

3/24/2020

3/23/2020

2/13/2020

2/5/2020

2/4/2020

1/31/2020

1/10/2020

1/8/2020

1/2/2020

12/15/2019

12/8/2019

11/28/2019

11/27/2019

11/26/2019

11/21/2019

Get In Touch