Skip to content
Change the site theme

UID Library

A library to generate unique IDs for use in user interfaces such as forms.


Guidelines page anchor

Why do we need unique IDs

Why do we need unique IDs page anchor

Unique IDs are important because:

  • The HTML spec says they should be unique(link takes you to an external page) 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?

Why do we need a library? page anchor

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?

How does this library work? page anchor

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(link takes you to an external page). 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.


useUID() page anchor

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.

Information icon

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.

Warning icon

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.

Black lives matter.