TypeScript Record Type: Record<K, V> Explained with Examples

Record<K, V> is a built-in utility type for an object whose keys have type K and whose values all have type V. With string keys it describes a dictionary; with a union of literal keys it describes an object that must have exactly those keys.

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record exists only in the type system. At runtime both objects are plain JavaScript objects, so they work with object literals, spread, JSON.stringify and everything else that takes an object.

Syntax and Definition

Record<Keys, Value>

Keys must be something that can be an object key: string, number, symbol, a union of string or number literals, or a template literal type. Value can be any type. The whole definition in TypeScript's standard library is one line, a mapped type:

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any is string | number | symbol, the set of all possible key types. [P in K]: T creates one property of type T for each member of K. That explains both behaviors below: a wide K like string produces an index signature (any key), and a union K produces one required property per member.

Union Keys: Every Key Is Required

When the keys are a union of literals, a Record must list every one of them, and no others. This turns the compiler into a checklist:

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

Add "cancelled" to Status and both objects stop compiling until you give the new status a label and a color. Leaving a key out, or adding one that is not in the union, is a compile error:

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

The same works with a string enum as the key type: Record<Color, string> requires one entry per enum member.

Record<string, T> and the Missing Key

With string keys, any key is allowed, and TypeScript types every lookup as T, even for a key that is not there. At runtime a missing key gives undefined:

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

This is the most common Record bug. Three ways to handle it: check with in or Object.hasOwn before reading, declare the value as V | undefined, or turn on the noUncheckedIndexedAccess compiler option, which adds | undefined to every index-signature read in the project. A Record with union keys does not have this problem, because every key is guaranteed to exist.

Partial<Record<K, V>>: Only Some Keys

To use a union of keys but not require all of them, wrap the Record in Partial. Reads then return V | undefined, which is honest:

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

A misspelled key such as jp is still an error, which is the advantage over Record<string, string>.

Iterating over a Record

Object.keys, Object.values and Object.entries all work. The catch is the key type: Object.keys returns string[] and Object.entries returns [string, V][], never your union of keys:

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

TypeScript keeps the keys as string on purpose: an object can have more properties at runtime than its type lists, so promising Plan[] would be unsafe in general. For an object you created from a literal, like seats, the cast is safe.

Building a Record from Data

Records are the usual result of grouping or indexing an array. Start from an empty object with the Record type and fill it:

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

Book["genre"] reuses the union from the interface as the key type, so adding a genre to Book makes byGenre demand a new entry.

Record<string, unknown> and Interfaces

Record<string, unknown> is a common type for "some object with string keys". It accepts object literals and values typed with a type alias, but an interface is rejected:

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

Interfaces can be extended by declaration merging, so TypeScript does not assume they fit an index signature; type aliases cannot be reopened, so a type User = { name: string } would pass. The usual fixes are to accept object instead (you can still call Object.keys on it), make the function generic (<T extends object>(obj: T)), or declare User with type (the interface vs type page covers the other differences).

Record vs Index Signature vs Map

Pick Record with union keys whenever the set of keys is known: it is the only option that checks every key is present. For open-ended string keys, Record<string, V> and an index signature are interchangeable, and many codebases prefer Record for readability. Reach for a Map when keys are added and removed at runtime, when keys are not strings, or when you need the size and insertion order without extra work.