Skip to Content
getting-startedQuick Start

Last Updated: 3/9/2026

Quick Start

Get started with Nano ID in under 5 minutes.

Basic Usage

Generate a unique ID with the default settings:

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

That’s it! You now have a 21-character, URL-safe, cryptographically random ID.

Custom Size

Adjust the ID length by passing a size parameter:

import { nanoid } from 'nanoid'
 
// Shorter ID (higher collision risk)
const shortId = nanoid(10)
console.log(shortId) //=> "IRFa-VaY2b"
 
// Longer ID (lower collision risk)
const longId = nanoid(32)
console.log(longId) //=> "gB7pQr2nJ8vK4fW9xZ1mT5hL3cN6dY8u"

⚠️ Important: Shorter IDs increase collision probability. Always check safety using the collision calculator .

Use CaseSizeCollision Risk
URLs, slugs21 (default)Similar to UUID
Short codes10-12Moderate (check calculator)
High-security tokens32+Extremely low
Human-readable codes6-8High (use custom alphabet)

Common Use Cases

Database Primary Keys

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

URL Slugs

import { nanoid } from 'nanoid'
 
const article = {
  slug: nanoid(),
  title: 'Getting Started with Nano ID',
  url: `https://example.com/articles/${nanoid()}`
}

API Tokens

import { nanoid } from 'nanoid'
 
const apiKey = nanoid(32) // Longer for security
const sessionId = nanoid()
 
res.cookie('sessionId', sessionId, { httpOnly: true })

File Names

import { nanoid } from 'nanoid'
import fs from 'fs'
 
const filename = `upload-${nanoid()}.jpg`
fs.writeFileSync(filename, buffer)

TypeScript

Nano ID includes TypeScript definitions out of the box:

import { nanoid } from 'nanoid'
 
const id: string = nanoid()
 
// With size parameter
const shortId: string = nanoid(10)

Opaque Types

Create branded types for type safety:

import { nanoid } from 'nanoid'
 
declare const userIdBrand: unique symbol
type UserId = string & { [userIdBrand]: true }
 
interface User {
  id: UserId
  name: string
}
 
const user: User = {
  id: nanoid<UserId>(), // Type-safe ID generation
  name: 'Alice'
}

See TypeScript guide for advanced patterns.

Non-Secure IDs (Optional)

For non-critical use cases where security isn’t a concern, use the faster non-secure variant:

import { nanoid } from 'nanoid/non-secure'
 
const id = nanoid() //=> "Uakgb_J5m9g-0JDMbcJqLJ"

⚠️ Warning: This uses Math.random() instead of cryptographic random generation. Only use for:

  • Development/testing
  • Non-sensitive temporary IDs
  • Environments without crypto support

Never use for:

  • Security tokens
  • Session IDs
  • API keys
  • Primary keys in production databases

See Non-Secure API for details.

Custom Alphabet

Generate IDs with a custom character set:

import { customAlphabet } from 'nanoid'
 
// Numbers only
const nanoid = customAlphabet('1234567890', 10)
console.log(nanoid()) //=> "4926581703"
 
// Lowercase hex
const hexId = customAlphabet('0123456789abcdef', 16)
console.log(hexId()) //=> "4f90d13a42b8c7e1"
 
// No ambiguous characters (for human-readable codes)
const nanoid = customAlphabet('346789ABCDEFGHJKLMNPQRTUVWXY', 8)
console.log(nanoid()) //=> "6RTUVWXY"

⚠️ Alphabet must be ≤256 characters for security guarantees.

See Custom Alphabets for best practices.

React Usage

❌ Don’t use Nano ID for React keys:

// WRONG: Generates new ID on every render
function Todos({ todos }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={nanoid()}> {/* ❌ DON'T DO THIS */}
          {todo.text}
        </li>
      ))}
    </ul>
  )
}

✅ Use stable IDs from your data:

// CORRECT: Use existing ID from data
function Todos({ todos }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}> {/* ✅ Stable ID */}
          {todo.text}
        </li>
      ))}
    </ul>
  )
}

✅ Or use React’s useId for linking elements:

import { useId } from 'react'
 
function FormField({ label }) {
  const id = useId() // React 18+
  
  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </>
  )
}

See React guide for proper usage patterns.

Next Steps

Now that you’ve generated your first IDs, explore:

IntroductionInstallation