Suggest an edit

Improve this article

Refine the answer for “What is an index signature in an interface?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## 1. What is an index signature

> An **index signature** is a special syntax in an interface (or type)
> that tells TypeScript:
> "this object can have **any number of properties** with a defined key type and value type".

---

### Example

```javascript
interface Dictionary {
  [key: string]: string;
}

const colors: Dictionary = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};
```

> Here `[key: string]: string` is the **index signature**.
>
> It means:
>
> - keys can be any strings (`string`);
> - values for all these keys must be strings (`string`).

---

## 2. General syntax

```javascript
interface SomeInterface {
  [key: KeyType]: ValueType;
}
```

| Element | What it means |
| --- | --- |
| `key` | the variable name (can be anything) |
| `KeyType` | the key type (`string`, `number`, `symbol`) |
| `ValueType` | the value type |

---

### Example with numbers

```javascript
interface NumericIndex {
  [index: number]: string;
}

const arr: NumericIndex = ["one", "two", "three"];
```

> In this case TypeScript checks that **all values at numeric indexes are strings**.
> That is, `arr[0]`, `arr[1]`, and so on are `string`.

---

## 3. Combining with regular properties

You can combine **specific fields** with dynamic keys:

```javascript
interface ProductInfo {
  id: number;
  name: string;
  [extra: string]: string | number; // index signature
}

const p: ProductInfo = {
  id: 10,
  name: "Shirt",
  color: "white",
  price: 49,
};
```

> Everything is correct, because both the specific properties (`id`, `name`) and the dynamic ones (`color`, `price`)
> match the `string | number` type.

---

## 4. Important: the index signature sets a **constraint for all properties**

If an interface has `[key: string]: string`,
then **all properties** of that interface must be compatible with `string`.

```javascript
interface BadExample {
  id: number;             // Error
  [key: string]: string;  // because number is not compatible with string
}
```

To fix it, both types need to be included:

```javascript
interface GoodExample {
  id: number;
  [key: string]: string | number;
}
```

---

## 5. Key types: `string`, `number`, `symbol`

| Key type | When it's used | Example |
| --- | --- | --- |
| `string` | for regular objects | `[key: string]: number` |
| `number` | for array-like structures | `[index: number]: string` |
| `symbol` | rarely, for unique keys | `[key: symbol]: boolean` |

> `[key: string]` is usually used,
> because most objects in JS use string keys.

---

## 6. Difference between index signature and `Record`

| Feature | `index signature` | `Record<K, T>` |
| --- | --- | --- |
| Syntax | `[key: string]: T` | `Record<string, T>` |
| Flexibility (fields can be added) | Yes | Limited |
| Suitable for interfaces | Yes | More often in `type` |
| Can be combined with specific properties | Yes | Not always convenient |
| Key checking via union | No | Yes |

---

## 7. Real-world usage example

### Translations dictionary

```javascript
interface Translations {
  [locale: string]: string;
}

const messages: Translations = {
  en: "Hello",
  fr: "Bonjour",
  de: "Hallo",
};
```

---

### Users map

```javascript
interface UsersMap {
  [id: number]: { name: string; age: number };
}

const users: UsersMap = {
  1: { name: "Tim", age: 25 },
  2: { name: "Max", age: 30 },
};
```

---

## Summary

> An **index signature** is a way to describe an object with **unpredictable (dynamic)** keys in TypeScript.
>
> Syntax:
>
> ```javascript
> interface Example {
>   [key: string]: ValueType;
> }
> ```
>
> It allows you to:
>
> - describe dictionaries and tables (`Record`-like objects),
> - combine fixed and arbitrary fields,
> - control the value type for any keys.
>
> It is often used for:
>
> - dictionaries (`Dictionary`),
> - configurations (`Config`),
> - caches (`Cache`),
> - localizations (`Translations`).

Markdown · drag & drop images · ⌘B / ⌘I shortcuts658 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.