# General Translation Platform: formatList
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/formatting/format-list.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format an array into a locale-aware list string on a GT instance. API reference for formatList.

General Translation uses the built-in `Intl.ListFormat` API to join items with the correct separators and conjunction ("and") or disjunction ("or") wording for each locale.

## Overview [#overview]

Call `formatList` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with an array and an optional options object. It returns a flat string with the items joined for the resolved locale.

```typescript
const gt = new GT({ targetLocale: 'en' });

const list = gt.formatList(['apple', 'banana', 'orange']);
// "apple, banana, and orange"
```

Signature:

```typescript
formatList(
  array: Array<string | number>,
  options?: { locales?: string | string[] } & Intl.ListFormatOptions
): string
```

*Note: `formatList` returns a flat `string`. To keep the original item types (for mixed-type or JSX arrays), use [`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) instead. For formatting without a `GT` instance, see the standalone [`formatList`](/docs/platform/core/reference/utility-functions/formatting/format-list).*

## How it works [#how-it-works]

- **Intl-backed.** Formatting is delegated to [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat).
- **Locale resolution.** By default the method formats for the instance's target locale, falling back to the source locale and then the library default (`en`) — not the `locales` config array. Pass `locales` in the options to override.
- **List type.** `type: 'conjunction'` produces "and" lists, `'disjunction'` produces "or" lists, and `'unit'` produces unit-style lists.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`array`](#array) | The list of items to format. | `Array<string \| number>` | No | — |
| [`options`](#options) | Formatting configuration, extending `Intl.ListFormatOptions` with a `locales` override. | `object` | Yes | — |

### `array` [#array]

**Type** `Array<string | number>` · **Required**

The list of items to join into a single string.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.ListFormatOptions` · **Optional**

Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. (See the [`Intl.ListFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#options) for supplemental standard and runtime-specific details).

| Name | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` |
| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` |
| `type` | List formatting type. | `'conjunction' \| 'disjunction' \| 'unit'` | Yes | `'conjunction'` |
| `style` | List formatting style. | `'long' \| 'short' \| 'narrow'` | Yes | `'long'` |

## Returns [#returns]

**Type** `string`

The items joined into a single locale-aware list string.

## Examples [#examples]

```typescript
import { GT } from 'generaltranslation';

const gt = new GT({ targetLocale: 'en' });

// Conjunction (default) — "and" list
console.log(gt.formatList(['A', 'B', 'C']));
// Output: "A, B, and C"

// Disjunction — "or" list
console.log(gt.formatList(['A', 'B', 'C'], { type: 'disjunction' }));
// Output: "A, B, or C"

// Spanish disjunction
console.log(gt.formatList(['red', 'green', 'blue'], {
  locales: ['es'],
  type: 'disjunction',
}));
// Output: "red, green o blue"
```

## Notes [#notes]

- Returns a flat `string`; use [`formatListToParts`](/docs/platform/core/reference/gt-class-methods/formatting/format-list-to-parts) when you need to preserve non-string item types.
- The method uses browser-native `Intl.ListFormat` under the hood.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
