Generate UUID in JavaScript

Step-by-Step Guide

Follow these four steps to generate, extend, and safely store UUIDs in any JavaScript runtime.

1. 1

   Verify your environment

   In browsers, crypto.randomUUID() requires a secure context (HTTPS or localhost). In Node.js, use version 19+ for the global API, or import { randomUUID } from 'node:crypto' on 14.17+.

   javascriptCopy

   function canGenerateUUID() {
     return typeof crypto !== 'undefined'
       && typeof crypto.randomUUID === 'function';
   }

2. 2

   Generate a UUID v4

   Call crypto.randomUUID() anywhere you have access to the Web Crypto API. Each call is independent and thread-safe.

   javascriptCopy

   const sessionId = crypto.randomUUID();
   const batch = Array.from({ length: 10 }, () => crypto.randomUUID());

3. 3

   Install uuid for v7 or v5

   Native APIs only produce v4. Install uuid when you need sortable v7 or deterministic v5 identifiers.

   bashCopy

   npm install uuid

4. 4

   Validate and store

   Validate external UUIDs at API boundaries. Store as lowercase strings in JavaScript; use binary UUID columns in your database when possible.

   javascriptCopy

   const id = crypto.randomUUID().toLowerCase();
   if (!isUUID(incomingId)) throw new Error('Invalid UUID');

Quick Reference

Choose the right UUID version and method for your use case.

Environment Compatibility

crypto.randomUUID() availability across JavaScript runtimes.

All UUID Versions

// 122 bits of CSPRNG randomness, RFC 4122 compliant
const id = crypto.randomUUID();
// → "550e8400-e29b-41d4-a716-446655440000"

import { v7 as uuidv7 } from 'uuid';

const id = uuidv7();
// → "018e8f6a-1b2c-7d3e-9f4a-5b6c7d8e9f0a"
// Later IDs sort after earlier ones (RFC 9562)

import { v5 as uuidv5 } from 'uuid';

const id = uuidv5('example.com', uuidv5.DNS);
// → always "cfbff0d1-9375-5685-968c-48ce8b15ae17"

import { v1 as uuidv1, v3 as uuidv3, v6 as uuidv6 } from 'uuid';

uuidv1(); // timestamp + MAC-based node
uuidv3('hello', uuidv3.URL); // MD5 namespace hash
uuidv6(); // reordered v1 for better DB locality (RFC 9562)

Validate and Parse UUIDs

TypeScript types do not validate runtime input. Always check UUIDs from HTTP requests, query params, and user input.

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

function isUUID(value) {
  return typeof value === 'string' && UUID_RE.test(value);
}

function normalizeUUID(value) {
  if (!isUUID(value)) throw new TypeError('Invalid UUID');
  return value.toLowerCase();
}

// v5 inputs: use stable lowercase names; URLs should be canonical
const name = 'example.com';
const id = uuidv5(name, uuidv5.DNS);

Real-World Use Cases

function addTodoOptimistically(text, setTodos) {
  const tempId = crypto.randomUUID();
  setTodos((prev) => [...prev, { id: tempId, text, status: 'pending' }]);
  fetch('/api/todos', {
    method: 'POST',
    body: JSON.stringify({ id: tempId, text }),
  });
}

async function chargeCard(amount, cardToken) {
  const key = crypto.randomUUID();
  sessionStorage.setItem('payment_idempotency_key', key);
  return fetch('/api/payments', {
    method: 'POST',
    headers: { 'Idempotency-Key': key },
    body: JSON.stringify({ amount, cardToken }),
  });
}

function getDeviceId() {
  const key = 'device_id';
  let id = localStorage.getItem(key);
  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem(key, id);
  }
  return id;
}

const ws = new WebSocket('wss://api.example.com/ws');
const connectionId = crypto.randomUUID();
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({ type: 'hello', connectionId }));
});

async function saveDraft(db, content) {
  const id = crypto.randomUUID();
  const tx = db.transaction('drafts', 'readwrite');
  tx.objectStore('drafts').put({ id, content, updatedAt: Date.now() });
  await tx.done;
  return id;
}

const correlationId = crypto.randomUUID();
console.info(JSON.stringify({
  level: 'info',
  correlationId,
  message: 'Order created',
  orderId: crypto.randomUUID(),
}));

UUID v4 vs v7 Decision Guide

Use v4 by default. Switch to v7 when insert order and index locality matter at database scale.

• →UUID v7 Generator - interactive v7 generation and export.
• →Format comparison - v4 vs v7 vs ULID vs NanoID.
• →TypeScript guide - branded UUID types and Zod validation.

How UUID v4 Works

crypto.randomUUID() fills 122 bits from the OS CSPRNG. Six bits are fixed: four encode version 4 (0100) and two encode the RFC 4122 variant (10).

With 2^122 possible values, collision risk is negligible for any practical application. The birthday bound for a 50% collision chance requires generating roughly 2.6 billion billion UUIDs.

Common Mistakes

Best Practices, Performance, and Security

Installation

# No installation needed

npm install uuid
# or: pnpm add uuid / yarn add uuid / bun add uuid

// ESM
import { v7 as uuidv7 } from 'uuid';
// CommonJS
const { v4: uuidv4 } = require('uuid');

Frequently Asked Questions

Related Guides