TypeScript Reference ยท Literal and Object Types
TypeScript index signatures
Reference for index signatures in TypeScript: string, number and symbol keys, mixing with named properties, noUncheckedIndexedAccess, Record and Map alternatives.
An index signature says "this object may have any number of properties whose keys are of this type, and whose values are of that type". You write it as [key: string]: ValueType inside an object type. It fits dictionaries, lookup tables and parsed JSON where the property names are not known in advance.
Allowed key types are string, number, symbol, template literal patterns such as `data-${string}` and unions of those. Reading any key gives the declared value type, even if the key does not exist, which is why index signatures deserve care in strict code.
interface Scores { [player: string]: number; }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ [key: string]: T }
{ [index: number]: T }
{ [key: symbol]: T }
{ [key: `prefix-${string}`]: T }
{ readonly [key: string]: T }
type Dict = Record<string, T>;
| Part | Description |
|---|---|
key |
Any identifier; it is only documentation. |
| Key type | string, number, symbol, a template literal pattern or a union of these. |
T |
The type of every value reached through that kind of key. |
readonly |
Prevents assigning through the index. |
Edge cases: a number index signature must return a type assignable to the string signature's type, because numeric keys are also strings at runtime. A string signature also covers numeric keys. Named properties in the same type must be compatible with the signature's value type (error 2411 otherwise), as the second example shows.
Usage notes
- The second example fails on purpose; widen the signature to
number | stringor move the named property into a separate intersection type. - By default
obj[key]is typed asT, notT | undefined. Turn onnoUncheckedIndexedAccessto make every index read includeundefined, which matches reality. Record<string, T>is the same thing as{ [key: string]: T }.Record<"a" | "b", T>is different: it is a fixed set of keys, not an index signature.- Prefer
Map<K, V>when keys are not strings, when you need a reliablesize, or when keys such as"__proto__"or"toString"could appear. Object.hasOwn(obj, key)orkey in objchecks presence; the index signature never does.for...ingivesstringkeys, matching a string index signature.Object.entries(obj)gives[string, T][].- Arrays and tuples have a numeric index signature, so
array[0]is typed as the element type. - Excess property checks do not fire for an object type with a string index signature, since any key is allowed.
- Use
unknownrather thananyas the value type when you are describing untrusted data.