Uid Library
A library to generate unique IDs for use in user interfaces such as forms.
- Status
- beta
- Version
- 0.2.1
- Import from
@twilio-paste/core/uid-library
— or —@twilio-paste/uid-library
Guidelines#
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 id
collision.
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
).
Usage Guide#
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’
toimport … 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.
API#
useUID()#
This is a React Hook to generate a UID.
useUIDSeed()#
This React Hook creates a seed from which you can generate several UIDs. It's handy for when you need multiple id
s in a single component.
UIDFork 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.
uid(item, index)#
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.
A plain Javascript function to return a UID. 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.