react-distortion

A React component library for adding animated procedural distortion to other components.

Pure CSS and HTML Distortion, with animations in JS. All through inline SVGs, feTurbulence and feDisplacementMap elements, and CSS filters.

Component

DistortComponent()

Component that distorts itself and its children.

Type Parameters

| Type Parameter | Default type | Description | | ------ | ------ | ------ | | E extends ElementType | "div" | The base component type; inferred from as. |

Parameters

| Parameter | Type | | ------ | ------ | | props | Substitute<ComponentProps<E>, DistortOptions<E>> |

Remarks

The type of props is expanded to include any additional props of the component type E. For example, <DistortComponent as="a" href="..." />.

Existing properties of DistortOptions are not forwarded to the underlying component.

Options

DistortOptions<E>

Options for DistortComponent.

Type Parameters

| Type Parameter | Default type | Description | | ------ | ------ | ------ | | E extends ElementType | "div" | The base component type. Inferred from as. |

Type declaration

| Name | Type | Description | | ------ | ------ | ------ | | as? | DistortSupportedAs<E> | The react component for this to wrap. | | defaultFilter? | DistortFilterOptions | The default distortion filter settings for the element. Remarks Undefined properties are replaced with their default values. | | hoverFilter? | `${DistortAnimation}` | DistortFilterOptions | Distortion filter settings while the element is hovered. | | activeFilter? | `${DistortAnimation}` | DistortFilterOptions | Distortion filter settings while the element is active. | | focusFilter? | `${DistortAnimation}` | DistortFilterOptions | Distortion filter settings while the element is focused. | | baseSeed? | number | Starting seed for the feTurbulence noise filter. Remarks Loop animations increment from this value, while endless animations reset it. Entering a state with resetSeed = true will return to it. | | filterId? | string | A CSS ID to use for the distortion filter. | | minRefresh? | number | Minimum milliseconds between seed refreshes. | | getDistortionSeed? | () => number | A function returning an integer to pass to feTurbulence's seed | | distortChildren? | ElementType<{style: CSSProperties; } & Partial<Record<PropertyKey, unknown>>> | ReactElement<{style: CSSProperties; }> | ReactElement<{style: CSSProperties; }>[] | Child elements that are distorted even when disable = true. Remarks Useful for distorted elements of components which should otherwise remain legible, such as a distorted border on a text area. If given ReactElements, children are cloned via React.cloneElement, with the distortion filter added to style.filter. If passed as a Component, it's created as <distortChildren style={{ filter }} />. | | ref? | Ref<DistortHandle> | Component's imperative handle. | | forwardedRef? | Ref<ElementRef<DistortSupportedAs<E>>> | A Ref to pass to the wrapped component. |

Remarks

The precedence of filters in descending order is: active, focus, hover, default. Undefined filters are skipped

Any missing properties of filters will be inherited from defaultFilter, expect for disable, which always defaults to false.

Non-default filters can also be just an animation, as a shorthand for filter: { animation: "..." }.

DistortRequiredAsProps

Properties which a provided 'as' component must support

Type declaration

| Name | Type | | ------ | ------ | | children? | ReactNode | | style? | CSSProperties |

Remarks

DistortComponent works by passing additional style and children to the wrapped component, and will break if they are not supported. For example <DistortComponent as="input" /> would throw a runtime error, as input elements cannot have children.

DistortSupportedAs<T>

A wrapper which checks the passed type is a component which supports DistortRequiredAsProps. Returns never if it does not.

Type Parameters

| Type Parameter | Description | | ------ | ------ | | T | The component type to check. Inferred from as. |

DistortFilterOptions

Options for applied filters and animations.

Type declaration

| Name | Type | Description | | ------ | ------ | ------ | | animation? | `${DistortAnimation}` | The animation behavior of the distortion. | | animationInterval? | number | The milliseconds between animation seed changes. Unused when animation = 'static'. | | animationJitter? | number | () => number | Milliseconds to randomly vary animationInterval by, or a function that returns that value. | | baseFrequency? | number | The feTurbulence noise filter's base frequency. | | disable? | boolean | Disables the filter. | | numOctaves? | number | The feTurbulence noise filter's number of octaves. | | resetSeed? | boolean | If the seed should be set to baseSeed upon entering this state. Remarks Allows returning to deterministic sequences after random animations. Ignored if baseSeed is undefined. | | scale? | number | The feDisplacementMap's scale. | | steps? | number | The number of seed increments before returning to the start for loop animations. |

DistortAnimation

ReactDistortion animation types.

Remarks

This enum is provided for convenience and documentation, but the values may also be passed as strings.

Enumeration Members

| Enumeration Member | Value | Description | | ------ | ------ | ------ | | Static | "static" | Filter is applied without animation. | | Endless | "endless" | Seed is refreshed every animationInterval milliseconds. | | Loop | "loop" | Seed is incremented every animationInterval milliseconds, looping back to the original value after the given number of steps. | | AlternatingEndless | "alternating endless" | Seed is refreshed every animationInterval milliseconds while alternating between the given filter settings and the base filter. | | AlternatingLoop | "alternating loop" | Seed is incremented every animationInterval milliseconds while alternating between the given filter settings and the base filter, looping back to the original seed after the given number of steps. |

DistortHandle

DistortComponent's imperative handle.

Type declaration

| Name | Type | Description | | ------ | ------ | ------ | | refreshSeed | (seed?) => void | Refreshes the filter seed. Remarks Useful for situational animations, such as animating a range on input. Ignored if the last seed refresh was less than minRefresh milliseconds ago, including automatic animation seed refreshes. |

Utility Types

Substitute<Other, Base>

A more robust version of Omit<Other, keyof Base> & Base, giving the intersection of Other & Base with Base's properties taking precedence.

Type Parameters

| Type Parameter | | ------ | | Other extends object | | Base extends object |

ChildlessHTMLElements

HTML elements that don't accept children, as defined by the HTML spec.

NormalHTMLElements

ReactHTML elements that accept children, as defined by the HTML spec.

child-elements

A submodule of utility elements covering common use cases of DistortOptions.distortChildren. Imported from react-distortion/child-elements.

Its elements are simple divs with classes pre-applied. Importing the module will inject its CSS into the head of the document. The CSS source can be found at src/child-elements.module.css.

DistortBackground

A background overlay, for use with distortChildren.

Remarks

Background color can be set via the parent's background color or a --background-color css variable.

The parent element's background should be transparent, either with background: none or background-color: #0000, and its position should be relative.

DistortBorder

A border overlay, for use with distortChildren.

Remarks

Color can be set via the --border-color css variable or the parent element's currentcolor.

Border width should be set via a --border-width css variable, which is also used to calculate the element's position. border-width: inherit is used as a fallback, but may result in incorrect positioning. The parent element's position should be set to relative.

DistortStyles

The css classnames for this module's elements.

Type declaration

| Name | Type | Default value | Description | | ------ | ------ | ------ | ------ | | border | string | styles.border | DistortBorder's base css class. | | background | string | styles.background | DistortBackground's base css class. |