Skip to Content
Api ReferenceCustom Alphabet

Last Updated: 3/9/2026

Custom Alphabet

Create ID generators with custom alphabets and sizes.

customAlphabet()

Returns a function that generates IDs using your specified alphabet and default size.

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('1234567890abcdef', 10)
const id = nanoid()
// => "4f90d13a42"

Syntax

const nanoid = customAlphabet(alphabet, defaultSize)

Parameters

ParameterTypeRequiredDescription
alphabetstringYesCharacters to use in IDs (max 256)
defaultSizenumberYesDefault length of generated IDs

Returns

A function with the same signature as nanoid() that generates IDs using your custom alphabet.

const customNanoid = customAlphabet('abc', 10)
 
// Use default size
const id1 = customNanoid()
// => "abcabcabca"
 
// Override size
const id2 = customNanoid(5)
// => "bcaab"

Common Alphabets

Hexadecimal

Lowercase hex (0-9, a-f):

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789abcdef', 16)
const id = nanoid()
// => "4f90d13a42c7e1f8"

Numeric Only

Numbers only (useful for numeric IDs, PINs):

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789', 12)
const id = nanoid()
// => "382947561029"

Lowercase Alphanumeric

No uppercase (case-insensitive systems):

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('abcdefghijklmnopqrstuvwxyz0123456789', 16)
const id = nanoid()
// => "4f90d13a42c7e1kl"

Uppercase Alphanumeric

No lowercase (for readability):

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', 16)
const id = nanoid()
// => "4F90D13A42C7E1KL"

No Lookalikes

Remove similar-looking characters (0/O, 1/I/l):

import { customAlphabet } from 'nanoid'
 
// Removed: 0, O, I, l, 1
const nanoid = customAlphabet('23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz', 16)
const id = nanoid()
// => "4f9Td23a42c7eKfm"

Good for human-readable codes (support tickets, activation codes).

Pre-Made Dictionaries

The nanoid-dictionary package provides ready-to-use alphabets:

npm install nanoid-dictionary
import { customAlphabet } from 'nanoid'
import { lowercase, numbers, nolookalikes } from 'nanoid-dictionary'
 
const nanoid = customAlphabet(nolookalikes, 12)

Available dictionaries:

  • lowercase - a-z
  • uppercase - A-Z
  • numbers - 0-9
  • nolookalikes - No ambiguous characters
  • alphanumeric - a-zA-Z0-9
  • hex - 0-9a-f

Security Considerations

Alphabet Size Limit

⚠️ Maximum 256 characters

// ❌ DON'T: Too many characters
const nanoid = customAlphabet('a'.repeat(300), 10) // Insecure!

Alphabets larger than 256 characters compromise the internal random generator algorithm.

Collision Probability

Smaller alphabets = higher collision risk for the same ID length.

Example: 10-character IDs

  • Default alphabet (64 chars): ~1% collision at 1.1 billion IDs
  • Hex alphabet (16 chars): ~1% collision at 69 million IDs
  • Numeric alphabet (10 chars): ~1% collision at 17 million IDs

📊 Always use the Collision Calculator  to verify safety.

AlphabetCharactersRecommended SizeSafe For
Default6421Trillions of IDs
Alphanumeric6221Trillions of IDs
Hex1624Billions of IDs
Numeric1026Millions of IDs
No-lookalikes5622Trillions of IDs

Dynamic Size

You can override the default size when calling the generator:

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789', 12)
 
// Use default size (12)
const id1 = nanoid()
// => "382947561029"
 
// Override with custom size
const id2 = nanoid(6)
// => "492856"
 
const id3 = nanoid(20)
// => "38294756102947382019"

Non-Secure Custom Alphabet

For non-security-critical use cases, use the non-secure version:

import { customAlphabet } from 'nanoid/non-secure'
 
const nanoid = customAlphabet('0123456789', 12)
const id = nanoid()
// Faster, but not cryptographically secure

⚠️ Only use for development, testing, or non-sensitive temporary IDs.

URL Alphabet Helper

To use the default URL-friendly alphabet with a custom random generator:

import { customRandom, urlAlphabet } from 'nanoid'
 
const nanoid = customRandom(urlAlphabet, 21, customRandomFunction)

See Custom Random Generator for details.

Examples

Database Shard IDs

Hex IDs for database sharding:

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789abcdef', 16)
 
function createShardedRecord(data) {
  const id = nanoid()
  const shard = parseInt(id.substring(0, 2), 16) % 16
  
  return {
    id,
    shard,
    ...data
  }
}

Support Ticket Numbers

No confusing characters, uppercase only:

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('23456789ABCDEFGHJKLMNPQRSTUVWXYZ', 10)
 
const ticketNumber = nanoid()
// => "4F9TD23A42"

Activation Codes

Grouped numeric codes:

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789', 12)
 
function generateActivationCode() {
  const code = nanoid()
  // Format as: 1234-5678-9012
  return code.match(/.{1,4}/g).join('-')
}
 
console.log(generateActivationCode())
// => "3829-4756-1029"

Color IDs

Short hex color-like IDs:

import { customAlphabet } from 'nanoid'
 
const nanoid = customAlphabet('0123456789abcdef', 6)
 
const colorId = '#' + nanoid()
// => "#4f90d1"
Core Api