A library to generate unique IDs for use in user interfaces such as forms.
- Import from
@twilio-paste/core/uid-library— or —
Why do we need unique IDs#
Unique IDs are important because:
- The HTML spec says they should be unique and strange bugs might occur otherwise.
- You need them to correctly pair form elements together for better UX.
- You need them to provide additional information for screenreaders, such as to provide a text hint to icons.
Here's what could happen without unique IDs:
Why do we need a library?#
Anytime a software product needs unique identifiers, the likelyhood of
id collisions increases the larger the project and team becomes.
Furthermore, the way React has transformed the traditional process of page-based development to componened-based development leads to more situations where an
id can clash.
For example, if one page renders the same
DeleteIcon component twice and that icon has
id="delete-icon" hardcoded, then we now have an
It is very difficult to predict the exact circumstances where a component will be used, so any time a component needs an
id the risk of a collision is present.
How does this library work?#
This library maintains a sequential count, so that everytime a component mounts and needs an ID, it will fetch the next value (
count += 1).
This package is a wrapper around react-uid. If you’re wondering why we wrapped that package into our own, we reasoned that it would be best for our consumers’ developer experience. For example:
- We can control which APIs we expose and how to expose them. For example, in this package export only some of the source package's exports.
- If we want to migrate the underlying nuts and bolts in the future, Twilio products that
depend on this primitive would need to replace all occurrences of
import … from ‘@react-uid’to
import … from ‘@some-new/package’. By wrapping it in
@twilio-paste/uid-library, this refactor can be avoided. The only change would be a version bump in the package.json file.
- We can more strictly enforce semver and backwards compatibility than some of our dependencies.
- We can control when to provide an update and which versions we allow, to help reduce potential bugs our consumers may face.
This package has 4 exports, described below.
This is a React Hook to generate a UID.
This React Hook creates a seed from which you can generate several UIDs. It's handy for when you need multiple
ids in a single component.
This is only needed for lazy-loaded or code-split chunks.
This React Component pivots the global singleton
count to read a counter from React Context.
If your app has code-splitting or lazy-loading, you want to wrap every entrypoint with
<UIDFork> in order
to garantee there isn't any collisions.
Don't use this API in React Components
Prefer using the other React Hooks (useUID or useUIDSeed) in React components. They are Server Side Rendering (SSR) compatible and the recommended future-proof API.
item should be an object (in JS, this could mean a function, an array, etc.). If
item isn't an object
, provide the second argument
index. This API is not SSR friendly.
We provide this export for quick UID generation in utility files.