Back to all snippets
Library/TypeScript/Branded Types
typescriptadvancedtypessafetypatterns

How to implement Branded Types in Typescript

Create nominal types in TypeScript

Quick Answer

Branded types add a phantom type tag to a primitive so TypeScript treats two structurally identical values as distinct types, preventing accidental mixing.

Code Snippet

1type Brand<K, T> = K & { __brand: T };
2
3type UserId = Brand<string, 'UserId'>;
4type Email = Brand<string, 'Email'>;
5
6const UserId = (id: string): UserId => id as UserId;
7const Email = (email: string): Email => email as Email;
8
9// Usage - prevents mixing different branded types
10const userId = UserId('123');
11const email = Email('user@example.com');

What is Branded Types?

TypeScript uses structural typing, which means two types with the same shape are interchangeable. Branded types add a phantom type tag to primitive values so the compiler treats them as distinct types even though they have the same underlying representation. This prevents bugs like passing a UserId where an Email is expected.

How It Works

  1. 1Define `Brand<K, T>` as `K & { __brand: T }` — the `__brand` property exists only at the type level, never at runtime.
  2. 2Create constructor functions that cast a raw string to the branded type.
  3. 3TypeScript will reject assigning a plain string or a differently branded value to a branded parameter.

Common Use Cases

  • Domain IDs - Prevent mixing UserId, OrderId, and ProductId strings
  • Validated values - Tag a string as a ValidEmail after validation
  • Units of measure - Distinguish Meters from Feet at the type level
  • Currency amounts - Prevent mixing USD and EUR numeric values

Key Benefits

  • Catches type confusion bugs at compile time with zero runtime overhead
  • Makes APIs self-documenting — parameters clearly state their expected brand
  • Works with any primitive type: string, number, symbol
  • Fully erased at runtime — no performance cost

Common Mistakes to Avoid

  • Using the same brand string for different types — brand tags must be unique across your codebase.
  • Forgetting to go through the constructor function and casting raw values directly with `as` — this defeats the purpose.
  • Exposing the `__brand` property in serialised JSON — strip it when sending data over the wire.

Quick Tips

  • Click the "Copy" button above to copy the code to your clipboard
  • This code is production-ready and can be used in your projects immediately
  • Check out related snippets below for more typescript examples

Frequently Asked Questions

Are branded types erased at runtime?

Yes. The `__brand` property only exists in the TypeScript type system. It is never present in the compiled JavaScript output, so there is zero runtime overhead.

Related Snippets

typescript
intermediate
Type Guards
Custom type guards for runtime type checking
typesguardsutilities
typescript
advanced
Utility Types
Useful TypeScript utility type definitions
typesutilitiesgenerics
typescript
intermediate
Async Function Type Helper
Extract return type from async functions
typesasyncutilities

About This Typescript Code Snippet

This free typescript code snippet for branded types is production-ready and copy-paste friendly. Whether you are building a web app, API, or frontend interface, this advanced-level example will help you implement branded types quickly and correctly.

All snippets in the Snippetly library follow typescript best practices and are tested for real-world use. You can adapt this code to work with React, Vue, Node.js, or any project that uses typescript.

Tags: types, safety, patterns  | Language: typescript  | Difficulty: advanced  | Category: TypeScript

Build Your Own Snippet Library

Organise your team's code snippets with Snippetly. Share knowledge and boost productivity across your organisation.

Get Started FreeBrowse More Snippets