246 lines
13 KiB
Plaintext
246 lines
13 KiB
Plaintext
# Transition
|
|
|
|
<script>
|
|
import Preview from "./_Preview.svelte";
|
|
</script>
|
|
|
|
<Preview url="examples/transition" code="" class="h-[340px] bg-rose-300"/>
|
|
|
|
## About this component
|
|
|
|
One of Svelte's strengths is its great support for transitions and animations. You are welcome and even encouraged to use them with this library when possible. So why bother with the `Transition` component?
|
|
|
|
There are a few reasons you may choose to use `Transition`:
|
|
|
|
- You are converting code from Tailwind UI which uses a `Transition` component. It may be simpler to just be able to port that code directly instead of replacing it with a Svelte transition.
|
|
|
|
- You want to use CSS class-based transitions (perhaps via Tailwind CSS classes, perhaps not) instead of using Svelte's transition engine. In that case this component can help, especially by helping coordinate multiple transitions (one of the main features of the component).
|
|
|
|
Since this component works is based on CSS class, we'll be using Tailwind CSS transition classes for the examples. However, you are free to use your own transition classes, as long as they are globally available.
|
|
|
|
## Basic example
|
|
|
|
The `Transition` accepts a `show` prop that controls whether the children should be shown or hidden, and a set of lifecycle props (like `enterFrom` and `leaveTo`) that let you add CSS classes at specific phases of a transition.
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition } from "@rgossiaux/svelte-headlessui";
|
|
let show = false;
|
|
</script>
|
|
|
|
<button on:click={() => (show = !show)}> Toggle </button>
|
|
<Transition
|
|
{show}
|
|
enter="transition-opacity duration-75"
|
|
enterFrom="opacity-0"
|
|
enterTo="opacity-100"
|
|
leave="transition-opacity duration-150"
|
|
leaveFrom="opacity-100"
|
|
leaveTo="opacity-0"
|
|
>
|
|
I will fade in and out
|
|
</Transition>
|
|
```
|
|
|
|
## Showing and hiding content
|
|
|
|
Wrap the content that should be conditionally rendered in a `Transition` component, and use the `show` prop to control whether the content should be visible or hidden.
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition } from "@rgossiaux/svelte-headlessui";
|
|
let show = false;
|
|
</script>
|
|
|
|
<button on:click={() => (show = !show)}> Toggle </button>
|
|
<Transition {show}>I will appear and disappear</Transition>
|
|
```
|
|
|
|
The `Transition` component will render a `div` by default, but you can use the `as` prop to render a different element instead if needed. Any other HTML attributes (like `class` or `style`) can be added directly to the `Transition` the same way they would be for regular HTML elements.
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition } from "@rgossiaux/svelte-headlessui";
|
|
let show = false;
|
|
</script>
|
|
|
|
<button on:click={() => (show = !show)}> Toggle </button>
|
|
<Transition {show} as="a" href="/my-url" style="font-weight: 700;">
|
|
I will appear and disappear
|
|
</Transition>
|
|
```
|
|
|
|
## Animating transitions
|
|
|
|
By default, a `Transition` will enter and leave instantly, which is probably not what you're looking for if you're using this component.
|
|
|
|
To animate your enter/leave transitions, add classes that provide the styling for each phase of the transitions using these props:
|
|
|
|
- `enter`: Applied the entire time an element is entering. Usually you define your duration and what properties you want to transition here: `transition-opacity duration-75`, for example.
|
|
|
|
- `enterFrom`: The starting point to enter from, like `opacity-0` if something should fade in.
|
|
|
|
- `enterTo`: The ending point to enter to, like `opacity-100` after fading in.
|
|
|
|
- `leave`: Applied the entire time an element is leaving. Usually you define your duration and what properties you want to transition here: `transition-opacity duration-75`, for example.
|
|
|
|
- `leaveFrom`: The starting point to leave from, like `opacity-100` if something should fade out.
|
|
|
|
- `leaveTo`: The ending point to leave to, like `opacity-0` after fading out.
|
|
|
|
Here's an example:
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition } from "@rgossiaux/svelte-headlessui";
|
|
let show = false;
|
|
</script>
|
|
|
|
<button on:click={() => (show = !show)}> Toggle </button>
|
|
<Transition
|
|
{show}
|
|
enter="transition-opacity duration-75"
|
|
enterFrom="opacity-0"
|
|
enterTo="opacity-100"
|
|
leave="transition-opacity duration-150"
|
|
leaveFrom="opacity-100"
|
|
leaveTo="opacity-0"
|
|
>
|
|
I will fade in and out
|
|
</Transition>
|
|
```
|
|
|
|
In this example, the transitioning element will take 75ms to enter (that's the `duration-75` class), and will transition the opacity property during that time (that's `transition-opacity`).
|
|
|
|
It will start completely transparent before entering (that's `opacity-0` in the `enterFrom` phase), and fade in to completely opaque (`opacity-100`) when finished (that's the `enterTo` phase).
|
|
|
|
When the element is being removed (the `leave` phase), it will transition the opacity property, and spend 150ms doing it (`transition-opacity duration-150`).
|
|
|
|
It will start as completely opaque (the `opacity-100` in the `leaveFrom` phase), and finish as completely transparent (the `opacity-0` in the `leaveTo` phase).
|
|
|
|
All of these props are optional, and will default to just an empty string.
|
|
|
|
## Coordinating multiple transitions
|
|
|
|
Sometimes you need to transition multiple elements with different animations but all based on the same state. For example, say the user clicks a button to open a sidebar that slides over the screen, and you also need to fade-in a background overlay at the same time.
|
|
|
|
You can do this by wrapping the related elements with a parent `Transition` component, and wrapping each child that needs its own transition styles with a `TransitionChild` component, which will automatically communicate with the parent `Transition` and inherit the parent's `show` state.
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition, TransitionChild } from "@rgossiaux/svelte-headlessui";
|
|
export let show = false;
|
|
</script>
|
|
|
|
<!-- This `show` prop controls all nested `TransitionChild` components -->
|
|
<Transition {show}>
|
|
<!-- Background overlay -->
|
|
<TransitionChild
|
|
enter="transition-opacity ease-linear duration-300"
|
|
enterFrom="opacity-0"
|
|
enterTo="opacity-100"
|
|
leave="transition-opacity ease-linear duration-300"
|
|
leaveFrom="opacity-100"
|
|
leaveTo="opacity-0"
|
|
>
|
|
<!-- ... -->
|
|
</TransitionChild>
|
|
|
|
<!-- Sliding sidebar -->
|
|
<TransitionChild
|
|
enter="transition ease-in-out duration-300 transform"
|
|
enterFrom="-translate-x-full"
|
|
enterTo="translate-x-0"
|
|
leave="transition ease-in-out duration-300 transform"
|
|
leaveFrom="translate-x-0"
|
|
leaveTo="-translate-x-full"
|
|
>
|
|
<!-- ... -->
|
|
</TransitionChild>
|
|
</Transition>
|
|
```
|
|
|
|
The `TransitionChild` component has the exact same API as the `Transition` component, but with no `show` prop, since the `show` value is controlled by the parent.
|
|
|
|
Parent `Transition` components will always automatically wait for all children to finish transitioning before unmounting, so you don't need to manage any of that timing yourself.
|
|
|
|
## Transitioning on initial mount
|
|
|
|
If you want an element to transition the very first time it's rendered, set the `appear` prop to `true`.
|
|
|
|
This is useful if you want something to transition in on initial page load, or when its parent is conditionally rendered.
|
|
|
|
```svelte
|
|
<script>
|
|
import { Transition, TransitionChild } from "@rgossiaux/svelte-headlessui";
|
|
export let show = false;
|
|
</script>
|
|
|
|
<Transition
|
|
{show}
|
|
appear={true}
|
|
enter="transition-opacity duration-75"
|
|
enterFrom="opacity-0"
|
|
enterTo="opacity-100"
|
|
leave="transition-opacity duration-150"
|
|
leaveFrom="opacity-100"
|
|
leaveTo="opacity-0"
|
|
>
|
|
<!-- Your content goes here -->
|
|
</Transition>
|
|
```
|
|
|
|
## Component API
|
|
|
|
### Transition
|
|
|
|
This component is also exported as `TransitionRoot`, to maintain compatibility with some Tailwind UI snippets.
|
|
|
|
| Prop | Default | Type | Description |
|
|
| ----------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `show` | -- | `boolean` | Whether the children should be shown |
|
|
| `as` | `div` | `string` | The element the `Transition` should render as |
|
|
| `appear` | `false` | `boolean` | Whether the transition should run on initial mount. |
|
|
| `static` | `false` | `boolean` | Whether the element should ignore the internally managed open/closed state |
|
|
| `unmount` | `true` | `boolean` | Whether the element should be unmounted, instead of just hidden, based on the open/closed state |
|
|
| `enter` | `""` | `string` | Classes to add to the transitioning element during the entire enter phase |
|
|
| `enterFrom` | `""` | `string` | Classes to add to the transitioning element before the enter phase starts |
|
|
| `enterTo` | `""` | `string` | Classes to add to the transitioning element immediately after the enter phase starts |
|
|
| `entered` | `""` | `string` | Classes to add to the transitioning element once the transition is done. These classes will persist after that until the `leave` phase |
|
|
| `leave` | `""` | `string` | Classes to add to the transitioning element during the entire leave phase |
|
|
| `leaveFrom` | `""` | `string` | Classes to add to the transitioning element before the leave phase starts |
|
|
| `leaveTo` | `""` | `string` | Classes to add to the transitioning element immediately after the leave phase starts |
|
|
|
|
This component also dispatches the following custom events, which are listened to using the Svelte `on:` directive:
|
|
|
|
| Event name | Type of event `.detail` | Description |
|
|
| ------------- | ----------------------- | ----------------------------------------------- |
|
|
| `beforeEnter` | `null` | Dispatched before we start the enter transition |
|
|
| `afterEnter` | `null` | Dispatched after we finish the enter transition |
|
|
| `beforeLeave` | `null` | Dispatched before we start the leave transition |
|
|
| `afterLeave` | `null` | Dispatched after we finish the leave transition |
|
|
|
|
### TransitionChild
|
|
|
|
| Prop | Default | Type | Description |
|
|
| ----------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `as` | `div` | `string` | The element the `Transition` should render as |
|
|
| `static` | `false` | `boolean` | Whether the element should ignore the internally managed open/closed state |
|
|
| `unmount` | `true` | `boolean` | Whether the element should be unmounted, instead of just hidden, based on the open/closed state |
|
|
| `enter` | `""` | `string` | Classes to add to the transitioning element during the entire enter phase |
|
|
| `enterFrom` | `""` | `string` | Classes to add to the transitioning element before the enter phase starts |
|
|
| `enterTo` | `""` | `string` | Classes to add to the transitioning element immediately after the enter phase starts |
|
|
| `entered` | `""` | `string` | Classes to add to the transitioning element once the transition is done. These classes will persist after that until the `leave` phase |
|
|
| `leave` | `""` | `string` | Classes to add to the transitioning element during the entire leave phase |
|
|
| `leaveFrom` | `""` | `string` | Classes to add to the transitioning element before the leave phase starts |
|
|
| `leaveTo` | `""` | `string` | Classes to add to the transitioning element immediately after the leave phase starts |
|
|
|
|
This component also dispatches the following custom events, which are listened to using the Svelte `on:` directive:
|
|
|
|
| Event name | Type of event `.detail` | Description |
|
|
| ------------- | ----------------------- | ----------------------------------------------- |
|
|
| `beforeEnter` | `null` | Dispatched before we start the enter transition |
|
|
| `afterEnter` | `null` | Dispatched after we finish the enter transition |
|
|
| `beforeLeave` | `null` | Dispatched before we start the leave transition |
|
|
| `afterLeave` | `null` | Dispatched after we finish the leave transition |
|