Uid Library

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

Status
beta
Version
0.1.1
Sources
Github
Import from
@twilio-paste/core/uid-library — or — @twilio-paste/uid-library

Guidelines#

Why do we need unique IDs#

Unique IDs are important because:

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

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

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.