useCollapseTransition
function useCollapseTransition<E extends HTMLElement>(
options: CollapseTransitionHookOptions<E>
): CollapseTransitionHookReturnValue<E>;
This useCollapseTransition
hook is used to create a transition to collapse
and expand an element inline with other content like an accordion by
animating the max-height
, padding-top
, and padding-bottom
CSS properties.
The default behavior is to hide the element completely while collapsed, but
providing the minHeight
, minPaddingTop
, and minPaddingBottom
options can
make this work like a "See More"/"Preview" type of element
Example Usage
See the Collapse demos for examples.
Parameters
options
- An object with the following definition:
export interface CollapseTransitionHookOptions<E extends HTMLElement>
extends Omit<PreconfiguredCSSTransitionOptions<E>, "exitedHidden">,
CollapseConfigurationStyle {
/**
* An optional style to merge with the required collapse transition styles.
*
* If any keys from the {@link CollapseStyle} are included in this object,
* these styles will override and possibly break the collapse transition.
*/
style?: CSSProperties;
/**
*
* @see {@link DEFAULT_COLLAPSE_TIMEOUT}
* @defaultValue `DEFAULT_COLLAPSE_TIMEOUT`
*/
timeout?: TransitionTimeout;
/**
*
* @defaultValue `minHeight === 0 && minPaddingTop === 0 && minPaddingBottom === 0`
*/
temporary?: boolean;
}
export interface CollapseConfigurationStyle {
/**
* The minimum height that the collapsed element can be which defaults to `0`.
* This can either be a number of pixels or a string CSS height value.
*
* Setting this value to any non-zero value will allow for the element to
* shrink to the defined min-height, and then expand to the full height once
* no longer collapsed.
*
* Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
* are all set to `0` (default), the child will be removed from the DOM while
* collapsed.
*
* @defaultValue `0`
*/
minHeight?: number | string;
/**
* The minimum padding-top that the collapsed element can be which defaults to
* `0`. This can either be a number of pixels or a string CSS `padding-top`
* value.
*
* Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
* are all set to `0` (default), the child will be removed from the DOM while
* collapsed.
*
* @defaultValue `0`
*/
minPaddingTop?: number | string;
/**
* The minimum padding-bottom that the collapsed element can be which defaults
* to `0`. This can either be a number of pixels or a string CSS
* `padding-bottom` value.
*
* Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
* are all set to `0` (default), the child will be removed from the DOM while
* collapsed.
*
* @defaultValue `0`
*/
minPaddingBottom?: number | string;
}
Returns
An object with the following definition:
export interface CollapseTransitionHookReturnValue<E extends HTMLElement>
extends CSSTransitionHookReturnValue<E>,
CollapseElementProps<E> {
/**
* This is just a convenience object so that you don't need to destructure as
* many variables to pass to an element.
*
* @example Simple Usage
* ```tsx
* const { elementProps, rendered } = useCollapseTransition({
* // ...options
* transitionIn,
* });
*
* if (!rendered) {
* return null
* }
*
* return <div {...elementProps}>{children}</div>;
*
* // This is the long-hand version
* const { ref, style, className, hidden, rendered } = useCollapseTransition({
* // ...options
* transitionIn,
* });
*
* if (!rendered) {
* return null
* }
*
* return (
* <div
* ref={ref}
* style={style}
* className={className}
* hidden={hidden}
* >
* {children}
* </div>
* );
* ```
*/
elementProps: Readonly<CollapseElementProps<E>>;
}
export interface CollapseElementProps<E extends HTMLElement>
extends CSSTransitionElementProps<E> {
/**
* A merged styled object required for the collapse transition to work.
*
* @see {@link CollapseStyle}
* @see {@link CollapseTransitionHookOptions.style}
*/
style: CSSProperties;
}