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’ 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.

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 ids in a single component.

UIDFork Component#

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)#

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.