> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lists

## `List`

OfficeJS-shaped handle for one numbering definition.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### List properties

| Name | Type | Description |
| - | - | - |
| `id` | `number` | read-only |
| `levelExistences` | `boolean[]` | read-only |
| `levelTypes` | `ListLevelType[]` | read-only Marker kind of each of Word's nine levels; undefined levels report Word's "Number" default. |
| `paragraphs` | `ParagraphCollection<Paragraph>` | read-only |

### `fork()`

```ts theme={null}
fork(): List
```

Mint a second list instance over the same definition: identical look, its
own counters restarted at 1 — Word's "Restart numbering". Detach a list
item first, then `paragraph.attachToList(fork.id, level)`.

### `getLevelFormat()`

```ts theme={null}
getLevelFormat(level: number): ClientResult<string>
```

The resolved `w:numFmt` token of one level ("decimal", "hebrew1", ...).
Levels the definition never declares report "", like getLevelString.

### `getLevelParagraphs()`

```ts theme={null}
getLevelParagraphs(level: number): ParagraphCollection<Paragraph>
```

Paragraphs at exactly one of Word's nine list levels.

### `getLevelString()`

```ts theme={null}
getLevelString(level: number): ClientResult<string>
```

The level's marker as its first item shows it: the bullet character, or "%1.%2." at each level's start.

### `getLevelTrailingCharacter()`

```ts theme={null}
getLevelTrailingCharacter(level: number): ClientResult<string>
```

Extension: the level's `w:suff` in Office.js `TrailingCharacter` words.

### `insertParagraph()`

```ts theme={null}
insertParagraph(
  paragraphText: string,
  insertLocation: "Start" | "End" | "Before" | "After",
): Paragraph
```

Insert in or immediately outside the list, matching Word's four locations. Start/End clone the adjacent item.

### `resetLevelFont()`

```ts theme={null}
resetLevelFont(level: number, resetFontName?: boolean): void
```

Drop the level marker's run formatting; `resetFontName` drops its `w:rFonts` too.

### `setLevelAlignment()`

```ts theme={null}
setLevelAlignment(level: number, alignment: string): void
```

Marker alignment inside its own field: Left, Centered, or Right.

### `setLevelBullet()`

```ts theme={null}
setLevelBullet(
  level: number,
  listBullet: string,
  charCode?: number,
  fontName?: string,
): void
```

Turn a level into a bullet level. `charCode` is required for Custom and
rejected otherwise; `fontName` writes the marker's `w:rFonts`.

### `setLevelFont()`

```ts theme={null}
setLevelFont(level: number, options: LevelFontOptions): void
```

Extension: the marker's own character formatting, on bullet AND number
levels — this is how a clause number is bolded without touching the
paragraph text. `null` removes one property; a level left with no marker
formatting keeps no `w:rPr`. Size is in points, color "auto" or hex.

### `setLevelIndents()`

```ts theme={null}
setLevelIndents(
  level: number,
  textIndent: number,
  bulletNumberPictureIndent: number,
): void
```

Both indents in points. `bulletNumberPictureIndent` is relative to the
text indent and must be 0 or negative (it becomes the hanging indent).

### `setLevelNumbering()`

```ts theme={null}
setLevelNumbering(
  level: number,
  listNumbering: string,
  formatString?: string | (string | number)[],
): void
```

Turn a level into a numbered level. Accepts OfficeJS ListNumbering
spellings in any casing plus the other ST\_NumberFormat tokens verbatim
(decimalZero, hebrew1, chineseCounting, ...). In `formatString`, numbers are 0-based level indices (never
above `level`) and strings are literals: `["(", 1, ")"]` writes "(%2)".
A plain string is taken as the raw `w:lvlText` pattern ("%1.", 1-based).

### `setLevelStartingNumber()`

```ts theme={null}
setLevelStartingNumber(level: number, startingNumber: number): void
```

First number this level counts from.

### `setLevelTrailingCharacter()`

```ts theme={null}
setLevelTrailingCharacter(level: number, trailingCharacter: string): void
```

Extension (VBA `ListLevel.TrailingCharacter`, Office.js `ListLevel.trailingCharacter`):
what follows the marker, `w:suff`. Tab is Word's default.

**Not implemented.** These Office.js members throw: `getLevelFont`, `getLevelPicture`, `setLevelPicture`.
