react-stable-uniqueid

A React component that provides a stable unique ID for accessibility, SVG effects, and other purposes

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
react-stable-uniqueid
232.0.12 years ago6 years agoMinified + gzip package size for react-stable-uniqueid in KB

Readme

NPM Build Status Coverage Status
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:
import { useStableUniqueId } from 'react-stable-uniqueid';

const uniqueId = useStableUniqueId('myPrefix', {
  uniqueIdFn: myCustomUniqueIdFn,
});

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:
import { StableUniqueId } from 'react-stable-uniqueid';

<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

import { withStableUniqueId } from 'react-stable-uniqueid';

const MyComponent = ({ uniqueId }) => <div>Unique ID: {uniqueId}</div>;
const 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!