CSS Transition
This is a mechanism to trigger CSS transitions when property values change.
cssTransition
The cssTransition function creates a function that invokes a CSS transition. The created function can be used as a callback for property update monitoring.
const transition = cssTransition("transition")
const show = (state) => ({
".modal": {
"class-is-open": state.modalIsOpen,
"&class-is-open": transition
}
})
.modal.is-open {
display: block;
opacity: 1;
}
.modal.transition-enter { /* when modal open */
opacity: 0;
display: block;
}
.modal.transition-enter-active {
transition: opacity 0.2s;
opacity: 1;
}
.modal.transition-exit { /* when modal close */
display: block;
}
.modal.transition-exit-active {
transition: opacity 0.2s;
opacity: 0;
}
Parameters
name | type | default | description |
---|---|---|---|
name | string | mandatory | The base string of the CSS class to be assigned. For example, if this string is "transition", the CSS class name would be "transition-enter", "transition-exit", etc. |
options | object | "size" | "details" | "dropdown" | {} |
Specify options by object that extend the behavior of the CSS transitions. You can also specify a string, in which case you specify the built-in behavior (called a "preset"). There are three presets: "size", "details" and "dropdown". See below. |
options.target | string | ":scope" | Specify a CSS selector for the DOM element to which the CSS class is to be assigned. The default is the DOM element itself that is under update monitoring. The extraction of DOM elements by the selector starts from the DOM element that is the target of the update monitoring. |
options.timeout | number | 10000 | Specifies the time in milliseconds (1/1000 of a second) before the CSS transition is forced to end. Default is 10 seconds. Normally, CSS transitions are terminated when the transitionend event is received. However, in case this does not happen for some reason, there is a force termination mechanism. You can specify here how many seconds to wait for the forced termination. |
options.onstart | function | null |
A callback called just before starting a CSS transition. The parameters and return values of the callback are the same as those of the update monitoring. |
options.onfinish | function | null |
A callback called just before the end of a CSS transition. The parameters and return values of the callback are the same as those of the update monitor. |
Return Value
name | type | description |
---|---|---|
fn | function | Function that, when called, activates CSS transitions. Can be used as a callback for update monitoring. |
How CSS transitions work
The CSS transition mechanism of batonjs is built in reference to React Transition Group.
The cssTransition function performs CSS class operations on DOM elements in the following steps. Define the appropriate CSS for each class so that the transition will be executed.
- Add
transition-enter-before
After this, the onstart callback is called. - Remove
transition-enter-before
, Addtransition-enter
After this, a small amount of time is reserved to make the browser render the DOM element. - Add
transition-enter-active
At this point, the CSS transition begins, and when thetransitionend
event is received, proceeds to the next step. - Remove
transition-enter-active
andtransition-enter
After this, the onfinish callback is called.
You can use each class as follows.
In the transition-enter
class, define the style at the start of the transition. In the case of a modal or other DOM element with a display
property of none
, this is where you change it to block
.
In the transition-enter-active
class, define the style for when the transition ends. In conjunction with the previous step, transition-enter-active
is added after transition-enter
. By adding the classes in this order, batonjs activates the CSS transition.
It is here that you define the transition
property.
The transition-enter-before
class is a class that is added in the preparatory stage before starting a transition. In some UIs, it is necessary to change the style for a moment before starting a transition, and then do some processing with that style. transition-enter-before
is a class provided for such situations.
The class name given, such as "transition-enter", varies depending on the argument.
The "transition" part is the string passed as the first argument to the cssTransition function.
The "enter" part becomes "enter" when the third argument (newValue) of the update monitoring callback is true (truthy) and "exit" when it is false (falsy). For example, if the property to be monitored is open, "enter" will be given if the open property is true, and "exit" will be given if it is false.
Thus, the class name also changes depending on how the property value has changed, so that a different animation can be used for each.
size preset
The trouble with CSS transitions is when you want to change the height or width, because you have to measure the size of the DOM element in advance with javascript and then make the transition.
With the size preset, this can be automated.
The size preset will measure the size of the DOM element when it is displayed and set it to the style property as CSS custom properties.
The size preset defines following two CSS custom properties.
--width
- Width of the target DOM element
--height
- Height of the target DOM element
The size preset measures the size of the DOM element in the onstart
callback. The user should ensure that the DOM element is visible when the onstart
callback is called.
To do so, use the transition-enter-before
class.
const transition = cssTransition("transition", "size") // specifies size preset
const show = (state) => ({
".modal": {
"class-is-open": state.modalIsOpen,
"&class-is-open": transition
}
})
.modal.is-open,
.modal.transition-enter-before { /* We need this line to measure the size. */
display: block;
opacity: 1;
}
.modal.transition-enter { /* on modal open */
opacity: 0;
height: 0;
display: block;
}
.modal.transition-enter-active {
transition: opacity 0.2s, height 0.2s;
opacity: 1;
height: var(--height); /* using --height */
}
.modal.transition-exit { /* on modal close */
display: block;
height: var(--height); /* using --height */
}
.modal.transition-exit-active {
transition: opacity 0.2s, height 0.2s;
opacity: 0;
height: 0;
}
details preset
The details preset is used to animate the opening and closing of details/summary element.
The element to be animated is the second child of the details element; since the first child is a summary, the second is the body part that will be invisible when closed.
The details preset defines custom properties by measuring the size of the body part, just like the size preset. Therefore, users of the details preset need to define CSS transitions for the body part.
An example of the use of the details preset can be found in Sample "jQuery's slideUp/Down".
dropdown preset
A dropdown preset is a preset for defining a style of dropdown.
It will decide where to display the dropdown, measure the size, and set it to a custom property.
An example of the use of the dropdown preset can be found in Sample "Dropdown".