Numeric Index Signatures and String Keys

What it is and why to use it

A numeric index signature describes values retrieved with numeric-looking keys. JavaScript object keys are strings or symbols, so ordinary numeric keys are converted to strings at runtime. TypeScript’s numeric signature is a checking rule that must remain compatible with a string signature if both are declared.

Common mistakes and limitations

If both number and string index signatures exist, the numeric value type must be compatible with the string value type. A numeric signature does not add length, iteration methods or array behaviour. Missing numeric entries are still possible.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

• index signatures
• arrays tuples

Syntax

interface Samples { [index: number]: string; title: string }

Examples

interface Samples { [index: number]: string; title: string }
const samples: Samples = { 0: "first", 1: "second", title: "Readings" };
console.log(samples[0] ?? "Missing");
console.log(Object.keys(samples).join(","));

Best practices

• If both number and string index signatures exist, the numeric value type must be compatible with the string value type. A numeric signature does not add length, iteration methods or array behaviour. Missing numeric entries are still possible.
• Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

Related TypeScript documentation

Specifications & further reading

• Official TypeScript documentation