This library provides React utility methods that transforms element subtrees, replacing elements following the provided rules. This can be very useful in many situations where you want to either extend React functionality or modify components that you may not have access to.
yarn add react-element-replace
# or
npm install react-element-replaceThis library is a generic ste of utility functions that can be used for any situation where you want to recurse through a React element tree and do something.
Here is a small and non-exhaustive list of things you could do with this library:
- render all objects in a subtree with JSON.stringify instead of throwing an error
- replace all promises with a loading component that shows a loader until promise resolution
- inject classNames into elements or components that meet a specific criteria, in a way that can apply / switch a theme
- remove components that are slow for testing
- count the number of elements of a certain kind in a subtree
- Redact or Internationalize content
This library can enable a completely new pattern of React development, but it does violate the explicit design of the framework. An important caveat is that replacing elements does sometimes interfere with React renderer operations, causing errors when there are changes of state below the replacer node. This happens when inside your Replacer you create or destroy new non-pure components and the update does not cause a full remount from above the Replacer. Additionally, if you create new elements below the Replacer that need replacing, they won't get replaced until the Replacer node gets reevaluated. To avoid these issues, it's best to use this library as close to the target elements as possible and to maintain the relevant state, and especially any state that creates / destroys elements, above the replacing code. These are unfortunate limitations, but as far as I can tell there is no easy way around them. If you have any clues on how to make this more robust I'd appreciate it!
This library can be used as function calls, but also provides a Replacer component for convenience.
function traverseElementTree<T=any, S=any>(
node: React.ReactNode,
visitor: Visitor<T,S>,
state?: S
) : TThis function forms the core of the library. It enables you to
recurse through a given ReactNode and it's descendants
and apply the given visitor logic to it.
The optional state will get passed to each visitor invocation and
can be used to keep track of information as you go. T is the output type and S is the state type. This is the Visitor interface:
interface Visitor<T=any, S=any> {
visit(
element: React.ReactNode,
state?: S,
children?: (newState: S) => T | T[]): T;
}It provides a visit function that performs logic for each node in the tree. It is passed the given node, the state, and a function that visits
that node's children (allowing you to pass new state to the children). The children function is undefined if the given element has no children.
Let us, for example, show how this can be used to count the number of elements in a tree. We define our Visitor as so:
class TreeElementCounter implements Visitor<number,null> {
visit(
element: React.ReactNode,
state?: null,
children?: (newState: null) => number | number[]
): number {
// visit the children if they exist
let childCounts = children ? children(state) : 0;
// coerce the result into an Array
if (!Array.isArray(childCounts)) {
childCounts = [childCounts];
}
// determine if the current node is an element (vs text)
const elementCount = React.isValidElement(element) ? 1 : 0;
// add the child counts to the elementCount and return
return childCounts.reduce((count, cur) => count + cur, elementCount);
}
}Now we can use this Visitor as so:
import { traverseElementTree } from 'react-element-replace';
const elements = (
<div>1
<div>2</div>
<div>3
<div>4</div>
<div>5</div>
</div>
<div>6</div>
</div>
);
let result = traverseElementTree(elements, new TreeElementCounter(), null);
expect(result).toEqual(6);function rebuildElement(
parent: React.ReactNode,
children?: React.ReactNode | React.ReactNode[]
): React.ReactNodeThis function take a parent node and a child or children nodes (aka the result of a children() visitor invocation) and recreates the react element using React.cloneElement. This is necessary if you are modifying an element's children as part of a tree traversal. It is how the replace
method rebuilds the elements in the tree after the replace as happened.
function replaceInTree<S = any>(
node: React.ReactNode,
args: ReplacerProps<S>
): React.ReactNodeor use the Replacer component with the same ReplacerProps and node specified by the component's children.
Where the ReplacerProps type is
{
// A replacing function
replace: (value: React.ReactNode, state?: S) => React.ReactNode;
// Value and function for initializing & updating state of type <S>
updateState?: (input: React.ReactNode, state?: S) => S;
initialState?: S;
// and ONE of
// match is for matching anything
match: (value: React.ReactNode, state?: S) => boolean;
// match Element is for matching a component of a specific type or
// a DOM element of a specific name
matchElement: React.ComponentType | string;
// match Literal is for matching non-elements & non Arrays
// as in literal values like strings
matchLiteral: (value: React.ReactNode, state?: S) => boolean;
}import { Replacer } from 'react-element-replace';
<Replacer
match={x => typeof x === 'number'}
replace={x => x + 1}>
<div>
{1}
{2}
<div>{3}</div>
</div>
</Replacer>
// renders >>>>
<div>
2
3
<div>4</div>
</div><Replacer
matchLiteral={item => typeof item === "object" }
replace={item => JSON.stringify(item)} >
<div>{{ comment: "testing" }}</div>
</Replacer>
// renders >>>>>
<div>{comment: "testing" }</div>
// Note: normally this throws an error<Replacer
matchElement="div"
replace={(item: React.ReactElement) => <span {...item.props} />}>
<div>A div becomes a span</div>
</Replacer>
// renders >>>>>
<span>A div becomes a span</span>