transitions.md

Transitions

• Introduction
• Defaults
• Setting transitions
  • Component options
    • Example with simple transition settings
  • Scripted component options with transitions
  • Themed (using style variables)
    • Effects
  • Custom CSS
• Transient components
• Changes
  • Converting from Polythene 1.0

Introduction

Some components (such as Dialogs) are displayed only when needed. The way the component appears and disappears can be configured in different ways:

1. Simple component options
2. Scripted component options
3. Themed (using style variables)
4. Writing custom CSS

These different methods can be combined. The order of evaluation follows the listed order above. For instance, if a component option is not set, that setting will be read from the component style (if any).

See the list of transient components below.

Defaults

All transient components use CSS for their transitions (with the exception of Snackbar which uses JavaScript).

CSS is created from component style variables, located in each component's CSS vars.js file. For instance for Dialog:

// polythene-css-dialog/src/vars.js

animation_delay:                 "0s",
animation_duration:              ".220s",
animation_timing_function:       "ease-in-out",
animation_hide_css:              "opacity: 0;",
animation_show_css:              "opacity: 1;",

Any method listed above will override these defaults.

Setting transitions

Component options

Parameter	Required	Type	Default	Description
showDuration	optional	Number	.240	The show transition duration in seconds
hideDuration	optional	Number	.240	The hide transition duration in seconds
showDelay	optional	Number	0	The show delay duration in seconds
hideDelay	optional	Number	0	The hide delay duration in seconds
showTimingFunction	optional	String		The show timing function; see transition-timing-function
hideTimingFunction	optional	String		The hide timing function; see transition-timing-function
didShow	optional	Function (id: string) => undefined		Callback function that is called when the show transition is done
didHide	optional	Function (id: string) => undefined		Callback function that is called when the hide transition is done
transitions	optional	Object		Object with functions for keys show and hide; see below for an example

Example with simple transition settings

Dialog({
  // ...
  showDelay:          0,
  showDuration:       .9,
  showTimingFunction: "ease-in-out",
  hideDelay:          .3,
  hideDuration:       1.2,
  hideTimingFunction: "cubic-bezier(0.09, 0.04, 0.16, 0.87)",
})

Option transitions offers a more flexible way to script the transition, see below.

Scripted component options with transitions

Option transitions is an Object that contains the functions show and hide. Each of these 2 functions return an Object with possible keys:

• duration
• delay
• before
• transition
• after
• timingFunction

Functions show and hide receive all previously passed options, combined with references to DOM elements (usually el but sometimes other elements too - see list of transient components below).

Dialog uses a simple fade in / fade out transition. This is a good starting point to demonstrate scripted transitions. The equivalent in JavaScript using transitions would be:

Dialog({
  // ...
  transitions: {
    show: ({ el }) => ({
      duration:   .240,
      before:     () => el.style.opacity = 0,
      transition: () => el.style.opacity = 1
    }),
    hide: ({ el }) => ({
      duration:   .240,
      transition: () => el.style.opacity = 0,
    })
  }
})

Note that other options can be combined:

Dialog({
  // ...
  showDuration:   .9,
  hideDuration:   .9,
  transitions: {
    show: ({ el }) => ({
      before:     () => el.style.opacity = 0,
      transition: () => el.style.opacity = 1
    }),
    hide: ({ el }) => ({
      transition: () => el.style.opacity = 0,
    })
  }
})

Themed (using style variables)

For a general introduction to theming, see Theming.

The default component style variables can be overridden in a custom theme style:

import { DialogCSS } from "polythene-css"

DialogCSS.addStyle(".dialog-transitions", {
  animation_duration: ".8s",
  animation_delay:    ".2s"
})

//...
Dialog({
  className: "dialog-transitions",
  // ...
})

Note that CSS variables should contain a unit: "s" or "ms".

Effects

You can create extra effects by passing custom CSS declarations:

• animation_hide_css - CSS declaration at rest / when hidden
• animation_show_css - CSS declaration when shown

For example:

DialogCSS.addStyle(".dialog-transitions", {
  // ...
  animation_hide_css: "opacity: 0; transform: translate3d(0, 20px, 0);",
  animation_show_css: "opacity: 1; transform: translate3d(0, 0, 0);"
})

or:

BaseSpinnerCSS.addStyle(".spinner-transitions", {
  // ...
  animation_hide_css: "opacity: 0; transform: scale(0.1);",
  animation_show_css: "opacity: 1; transform: scale(1.0);"
})

Custom CSS

Finally you can write custom CSS to override any default style; see Custom CSS.

For example:

.my-app .pe-menu {
  transition-timing-function: ease-out;
  transition-property: opacity;
  opacity: 0;
}
.my-app .pe-menu--visible {
  opacity: 1;
}

Transient components

Component	CSS module	transition DOM elements
Dialog	DialogCSS	el, contentEl, backdropEl
Drawer	DrawerCSS	el, contentEl, backdropEl
Menu	MenuCSS	el
Notification	NotificationCSS	el, containerEl
Snackbar	SnackbarCSS	el, containerEl
BaseSpinner	BaseSpinnerCSS	el

Changes

Converting from Polythene 1.0

Option transitions has a different API for keys returned from functions show and hide. Version 1.1 creates consistency by using uniform keys.

1.0	1.1
showDelay	delay
showDuration	duration
hideDelay	delay
hideDuration	duration
beforeShow	before (for both show and hide)
afterHide	after (for both show and hide)
show	transition
hide	transition
-	timingFunction