React Stable Unique ID

A utility to generate a unique ID (using Lodash.uniqueId) that does not change on re-renders. This is useful for form inputs (ex: htmlFor), SVG effects (<defs>), and other scenarios.

NOTE: This library does not support React 18. Instead, use the built-in useId hook.

Installation

npm install --save react-stable-uniqueid

Hook Usage

As a React hook:

1import { useStableUniqueId } from 'react-stable-uniqueid';
2
3const uniqueId = useStableUniqueId('myPrefix', {
4  uniqueIdFn: myCustomUniqueIdFn,
5});

Arguments

prefix: string | undefined

Optional. If provided, adds a prefix to the generated unique ID.

Options

uniqueIdFn: () => string

Optional. If provided, uses this function instead of Lodash's to generate a unique ID. Useful for testing.

Note that this function will only be called once; if you update the prop, a new unique ID will not be generated using the new function.

Returns

A string value

Render Prop Usage

As a render prop component:

1import { StableUniqueId } from 'react-stable-uniqueid';
2
3<StableUniqueId render={({ uniqueId }) => <div>Unique ID: {uniqueId}</div>} />;

Props

render: ({ uniqueId: string }) => JSX

A fairly standard render prop. Pass it a function that returns React elements to render given a uniqueId. This function takes one argument, which is an object of type { uniqueId: string } - note the destructuring in the examples.

prefix: string

Optional. If provided, adds a prefix to the generated unique ID.

uniqueIdFn: () => string

Optional. If provided, uses this function instead of Lodash's to generate a unique ID. Useful for testing.

Note that this function will only be called once; if you update the prop, a new unique ID will not be generated using the new function.

Higher Order Component (HOC) Usage

1import { withStableUniqueId } from 'react-stable-uniqueid';
2
3const MyComponent = ({ uniqueId }) => <div>Unique ID: {uniqueId}</div>;
4const WrappedMyComponent = withStableUniqueId({ prefix: 'mycomponent' });

Added props

uniqueId: string

The generated uniqueId.

Options

prefix: string

Optional. If provided, adds a prefix to the generated unique ID.

name: string

Optional. If provided, renames the uniqueId prop added to the wrapped component.

uniqueIdFn: () => string

Optional. If provided, uses this function instead of Lodash's to generate a unique ID. Useful for testing.

Wrapped component props

_uniqueIdFn: () => string

Optional. If provided, uses this function instead of Lodash's to generate a unique ID. Useful for testing. This prop will not be consumed by the wrapper and will also be passed down to the wrapped component.

Note that this function will only be called once; if you update the prop, a new unique ID will not be generated using the new function.

Gotchas

The generated id will not change on re-renders, but it will change if a component instance is unmounted and re-mounted. It is only guaranteed to be stable or unique as long as the component is mounted.

Testing

I recommend stubbing this component or using the uniqueIdFn setting in tests, especially if you're snapshot testing or asserting on the generated, because the default function is not guaranteed to be deterministic.

Server-side rendering

This component is very likely to generate different IDs on the server vs the client. This means your rendered DOM may be mismatched when you hydrate it on the client. I haven't done much with server-side rendering; maybe this isn't much of a problem. Let me know if you try to do server-side rendering with this library so I can update these docs!