Configuration Options

🧩 Configuration Options

UCID isn’t just easy — it’s flexible too! Customize your ID like a pro 🛠️
Each option below lets you fine-tune the structure and formatting of your generated IDs.

uppercase and lowercase (booleans)

Control letter casing:

• lowercase: true by default
• uppercase: false by default

ucid({ uppercase: true });
// Result: TevajtrU-Eei8SnWa-0EZqr6NE-jMAHX0D6

ucid({ uppercase: true, lowercase: false });
// Result: FFJL9DAO-V3YPLZ2V-252L7URX-XCS3GWP5

numbers and symbols (booleans)

Toggle digits or symbols:

• numbers: true by default
• symbols: false by default

ucid({ symbols: true });
// Result: 5w55an#e-kw7bw7f3-7iomwp#o-dd79$yf1

ucid({ numbers: false });
// Result: jueldfjw-ljhiphtl-ajuptedx-rramdwne

octets (number)

Set how many segments (octets) the ID should have. Default: 4.

ucid({ octets: 3 });
// Result: 4nlwrx87-fi65iq27-43wh2s05

ucid({ octets: 6 });
// Result: hr5bg68k-ycxqfb1o-pkofgsm2-j6hnimgy-ehcxulnl-ptmvuf3j

octetLength (number)

Define how long each octet should be. Default: 8.

ucid({ octetLength: 4 });
// Result: k6ue-bvfq-fc99-oe07

ucid({ octetLength: 12 });
// Result: nz4kkg3jxxot-9v9bmx6y8ngt-x4ciymz48z9d-mqopg9mad4v2

includeOnly (string)

Use a custom character set to generate your ID:

ucid({ includeOnly: '1234567890abcdef' });
// Result: f800cdb7-0082b1b8-f0736eb3-4b16949a

timestamp (string)

Add timestamp to your ID. Either prefix or suffix.

• Aliases:
  • prefix: p, pre, pref
  • suffix: s, suf, suff

ucid({ timestamp: 'prefix' });
// Result: 20250904-k0ebaf6m-j31g7koc-b25p0p2n-u9iah5i4

ucid({ timestamp: 'suff' });
// Result: 05mdc0cp-6k6xvl9c-mgc7s9e3-t98ckh3f-20250904

timestampFormat (string)

Controls how the timestamp is formatted. Use any custom format or choose from built-ins:

• unix, epoch
• military
• iso
• utc
• rfc (rfc3339)
• filetime, winft (Windows FILETIME)

ucid({
  octets: 3,
  timestamp: 's',
  timestampFormat: 'dd-mm-yyyy-hh:mm:ss:ms',
});
// Result: gtrf9t1h-u00ycxuw-mxzhjuty-04-09-2025-12:09:00:39

ucid({
  octets: 3,
  timestamp: 'p',
  timestampFormat: 'unix',
});
// Result: 1756976740-61p0xk4r-1ad6fg3l-gxwsgpgk

octetSeparator (string)

Customize the character(s) used to separate octets. Default: "-"

ucid({ octetSeparator: '=' });
// Result: pro9mns=odvhrd3i=28e2mqzg=t3n530m9

ucid({ octetSeparator: '~' });
// Result: qm09extn~dy7s1bd1~t6fl9q2g~mv352ie4

octetFormat (string | number[])

Set the exact length of each octet individually.

ucid({ octets: 3, octetFormat: '352' });
// Result: h0c-hgkf0-k9

ucid({ octets: 4, octetFormat: [2, 4, 6, 8] });
// Result: cb-udw8-e6m4wt-i9kim7xb

ucid({ octets: 2, octetFormat: '49' });
// Result: pr3e-piis0fdy9

instances (number)

Number of IDs to generate.

ucid({ instances: 3 });
/*
Result: [
  '9v7z1v59-0v28lo6h-8g5qpnhk-dx5f6412',
  '5689u3lw-ns4wk8sc-u57bgwxz-nm9r8ydf',
  'ul7pdyya-bgubmkef-zlpp7b79-7v2oo5dq'
]
*/

ucid({
  octets: 4,
  octetFormat: [2, 4, 6, 8],
  instances: 5,
});
/*
Result: [
  'rd-c0ix-mtifus-z7ibcbip',
  'l6-gngn-1v04eg-do2yei8v',
  'kf-fprl-klp5bw-o7gcv39u',
  'tm-v4hq-8h964i-cnpswp29',
  'uq-iwcb-u44bey-yj0nvs98'
]
*/

template (string)

Use %id and %ts placeholders to inject generated values into custom strings.

ucid({
  octets: 1,
  octetLength: 8,
  includeOnly: '1234567890abcdef',
  template: 'user-%id-session-%id',
});
// Result: user-1a97ada5-session-ec64776c

ucid({
  octets: 1,
  octetLength: 8,
  includeOnly: '1234567890abcdef',
  template: 'user-%id-at-%ts',
});
// Result: user-26001cde-at-20250903

prefix and suffix (string)

Add static strings before or after your ID.

ucid({ prefix: 'ID-', suffix: '-done' });
// Result: ID-k0ebaf6m-j31g7koc-b25p0p2n-u9iah5i4-done

verbose (boolean)

Returns a full object instead of just the generated ID string.
Useful for debugging, logging, or introspection.

ucid({
  octets: 3,
  octetLength: 12,
  includeOnly: '1234567890abcdef',
  verbose: true,
});

/*
Result: {
  ucid: '795ebe1fd531-dbf06d32bd02-f512ad09e84a',
  octets: 3,
  uppercase: false,
  lowercase: true,
  octetLength: 12,
  octetFormat: '',
  numbers: true,
  octetSeparator: '-',
  symbols: false,
  includeOnly: '1234567890abcdef',
  template: null,
  prefix: '',
  suffix: '',
  verbose: true
}
*/

customize (function)

Function to customize each octet beyond built-in options.

ucid({
  octets: 2,
  octetLength: 8,
  includeOnly: '1234567890abcdef',
  customize: (octet, i) => (i % 2 ? octet.toUpperCase() : octet.toLowerCase()),
});
// Result: 80a1a368-A738C260

ucid({
  octets: 3,
  octetLength: 6,
  includeOnly: '1234567890abcdef',
  customize: (octet, i) =>
    i == 0 ? `user-${octet}` : i == 1 ? `session-${octet}` : `${i}${octet}`,
});
// Result: user-81cd0a-session-13634d-212fb85

condition (function)

Acts as a gate before UCID generation begins.
Must call resolve() to proceed or reject() to abort.

// Allow generation only in production
ucid({
  condition: (resolve, reject) =>
    process.env.NODE_ENV === 'production'
      ? resolve()
      : reject('UCID generation is disabled in non-production environments.'),
});

// Check authentication
ucid({
  condition: (resolve, reject) =>
    auth?.currentUser?.email
      ? resolve()
      : reject(new Error('User must be authenticated.')),
});

Next up → Predefined Formats