Skip to Content
Api ReferenceCore Api

Last Updated: 3/9/2026

Core API

The main Nano ID function and its parameters.

nanoid()

Generates a secure, random, URL-friendly unique ID.

import { nanoid } from 'nanoid'
 
const id = nanoid()
// => "V1StGXR8_Z5jdHi6B-myT"

Default Behavior

  • Length: 21 characters
  • Alphabet: URL-friendly A-Za-z0-9_- (64 characters)
  • Randomness: Hardware random generator (crypto module)
  • Collision probability: Similar to UUID v4

For there to be a one in a billion chance of duplication, 103 trillion IDs must be generated.

nanoid(size)

Generate an ID with custom length.

import { nanoid } from 'nanoid'
 
// Short ID (10 characters)
const shortId = nanoid(10)
// => "IRFa-VaY2b"
 
// Long ID (30 characters)
const longId = nanoid(30)
// => "VfJU8x-Hq9k2L3mN5pR7tW9yB1cD4f"

Parameters

ParameterTypeDefaultDescription
sizenumber21Number of characters in the generated ID

Size Considerations

The size directly impacts collision probability:

SizeIDs needed for 1% collision probability
21~4.7 quadrillion
16~1.1 trillion
12~17 billion
10~1.1 billion
8~16 million

⚠️ Use the Collision Calculator  to determine safe sizes for your use case.

Choosing the Right Size

21 characters (default) - Maximum safety

const userId = nanoid() // For critical records

14-16 characters - Balanced

const orderId = nanoid(14) // For medium-volume systems

10-12 characters - Short URLs

const slug = nanoid(10) // For thousands of records

8 characters - Temporary IDs

const tempId = nanoid(8) // For hundreds of short-lived records

Return Value

Returns a string containing the generated ID.

const id = nanoid()
typeof id // => "string"
id.length // => 21

Alphabet

The default alphabet is URL-safe and includes:

  • Uppercase letters: A-Z (26 characters)
  • Lowercase letters: a-z (26 characters)
  • Numbers: 0-9 (10 characters)
  • Special characters: _ and - (2 characters)

Total: 64 characters

This alphabet is chosen because:

  • ✅ URL-safe (no encoding needed)
  • ✅ Filename-safe (works in all file systems)
  • ✅ HTML attribute-safe (no escaping needed)
  • ✅ Database-friendly (no special characters)
  • ✅ Double-click selectable (no spaces or special chars)

Security

Random Number Generation

Nano ID uses cryptographically strong random number generators:

Node.js:

import crypto from 'crypto'
crypto.randomBytes()

Browsers:

window.crypto.getRandomValues()

Both use hardware random generators when available, providing unpredictable, uniform randomness.

Blocking Behavior

In rare cases, nanoid() may block briefly while collecting entropy for the hardware random generator.

const id = nanoid() // May block for a few microseconds

This is normal and ensures maximum security. For non-blocking alternatives, see Async API (if needed) or Non-Secure API.

Performance

Nano ID is extremely fast:

nanoid                     3,693,964 ops/sec
crypto.randomUUID          7,619,041 ops/sec
uuid v4                    7,436,626 ops/sec

While slightly slower than native UUID, Nano ID generates shorter IDs (21 vs 36 characters) and has a smaller bundle size (118 bytes vs 423 bytes for uuid/v4).

See Performance Benchmarks for detailed comparisons.

Examples

Database Primary Keys

import { nanoid } from 'nanoid'
 
const user = {
  id: nanoid(),
  email: 'user@example.com',
  createdAt: Date.now()
}
 
await db.users.insert(user)

URL Slugs

import { nanoid } from 'nanoid'
 
function createShortUrl(longUrl) {
  const slug = nanoid(8)
  
  return {
    slug,
    url: longUrl,
    shortUrl: `https://short.link/${slug}`
  }
}

Session Tokens

import { nanoid } from 'nanoid'
 
function createSession(userId) {
  return {
    token: nanoid(32), // Extra long for security
    userId,
    expiresAt: Date.now() + 3600000 // 1 hour
  }
}

Request IDs (Logging)

import { nanoid } from 'nanoid'
 
app.use((req, res, next) => {
  req.id = nanoid()
  logger.info({ requestId: req.id, path: req.path })
  next()
})
Custom AlphabetInstallation