# FDocumentListItem

- Human documentation: [https://docs.univer.ai/reference/facade/document-list-item](https://docs.univer.ai/reference/facade/document-list-item)

- Agent Markdown: [https://docs.univer.ai/reference/facade/document-list-item.md](https://docs.univer.ai/reference/facade/document-list-item.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/document-list-item.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/document-list-item.mdx)

---

Facade object for a single docs list item.

## Access

Access through:

* [`FDocument.getListItems()`](https://docs.univer.ai/reference/facade/document.md#getlistitems)
* [`FDocument.getListItem()`](https://docs.univer.ai/reference/facade/document.md#getlistitem)
* [`FDocument.getListItemAt()`](https://docs.univer.ai/reference/facade/document.md#getlistitemat)
* [`FDocument.findListItemByText()`](https://docs.univer.ai/reference/facade/document.md#findlistitembytext)
* [`FDocument.findListItems()`](https://docs.univer.ai/reference/facade/document.md#findlistitems)
* [`FDocumentList.getItems()`](https://docs.univer.ai/reference/facade/document-list.md#getitems)

## Example

```ts
const fDocument = univerAPI.getActiveDocument()

const item = fDocument.findListItemByText('Ship API')
item?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, {
  mode: univerAPI.Enum.DocsListSelectionMode.Level,
})
item?.demote()
```

## Setup

Register [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/docs-list/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/docs/getting-started/facade.md).

## `@univerjs-pro/docs-list`

### `FDocumentListItem.continueNumbering`

Continues numbering from the previous same-level ordered list segment.

```typescript
continueNumbering(): boolean
```

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Start a new list segment that continues numbering from the previous segment.
const item = fDocument.findListItemByText('New Segment')
item?.continueNumbering()
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.demote`

Demotes this item, level, or whole list by one nesting level.

`mode: Item` only changes this item's nesting level. It works for both ordered and
unordered list items. Demoting an item that is already at the maximum nesting level is
a no-op, so it may succeed without a visible change.

```typescript
demote(options?: IDocsListOperationOptions): boolean
```

**Parameters**

* `options` — Optional. Default: `{}`. Scope options. Defaults to `mode: 'list'` in command behavior.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Demote the whole list.
const item = fDocument.findListItemByText('Todo')
item?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.List })

// Demote the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
item2?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.Level })

// Demote just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
item3?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.Item })
```

**Types:** [`IDocsListOperationOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.describe`

Returns an agent-friendly description of this list item.

```typescript
describe(): IDocsListItemInfo | null
```

**Returns**

The list item info, or `null` if the paragraph is no longer a list item.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Ship API')
console.log(item?.describe())
```

**Types:** [`IDocsListItemInfo`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.getParagraphStartIndex`

Returns the paragraph start index that identifies this list item.

```typescript
getParagraphStartIndex(): number
```

**Returns**

The paragraph start index.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Ship API')
console.log(item?.getParagraphStartIndex())
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.getSegmentId`

Get the segment id of this list item.
The main body list item have an empty string segment id.
The header and footer list item have a non-empty string segment id.

```typescript
getSegmentId(): string
```

**Returns**

The segment id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Ship API')
console.log(item?.getSegmentId())
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.getText`

Returns plain text in this list item.

```typescript
getText(): string
```

**Returns**

The list item text.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Ship API')
console.log(item?.getText())
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.isOrdered`

Returns whether this list item is rendered as an ordered marker.

This is the recommended guard before calling ordered-list-only APIs such as
`setPrefixSuffix()` or `setStartNumber()`.

```typescript
isOrdered(): boolean
```

**Returns**

`true` when this item uses an ordered marker.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Step 1')

if (item?.isOrdered()) {
  item.setPrefixSuffix('Step ', ':')
}
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.isUnordered`

Returns whether this list item is rendered as an unordered bullet marker.

This is the recommended guard before calling bullet-list-oriented APIs such as
`setGlyphSymbol()`.

```typescript
isUnordered(): boolean
```

**Returns**

`true` when this item exists and uses an unordered marker.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const item = fDocument.findListItemByText('Todo')

if (item?.isUnordered()) {
  item.setGlyphSymbol('•')
}
```

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.promote`

Promotes this item, level, or whole list by one nesting level.

`mode: Item` only changes this item's nesting level. It works for both ordered and
unordered list items. Promoting an item that is already at the top level is a no-op,
so it may succeed without a visible change.

```typescript
promote(options?: IDocsListOperationOptions): boolean
```

**Parameters**

* `options` — Optional. Default: `{}`. Scope options. Defaults to `mode: 'list'` in command behavior.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Promote the whole list.
const item = fDocument.findListItemByText('Todo')
item?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.List })

// Promote the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
item2?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.Level })

// Promote just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
item3?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.Item })
```

**Types:** [`IDocsListOperationOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.select`

Selects this item, its current level, or its whole list.

```typescript
select(mode?: DocsListSelectionMode): boolean
```

**Parameters**

* `mode` — Optional. Default: `DocsListSelectionMode.Item`. Selection scope. Defaults to `item`.

**Returns**

Whether the selection command succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Select just the item.
const item = fDocument.findListItemByText('Ship API')
item?.select()

// Select the whole list.
const item2 = fDocument.findListItemByText('Todo')
item2?.select(univerAPI.Enum.DocsListSelectionMode.List)

// Select the current level.
const item3 = fDocument.findListItemByText('Subtask 1')
item3?.select(univerAPI.Enum.DocsListSelectionMode.Level)
```

**Types:** [`DocsListSelectionMode`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/common/type.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.setGlyphSymbol`

Changes the bullet symbol for this item, level, or whole list.

```typescript
setGlyphSymbol(symbol: string, options?: IDocsListOperationOptions): boolean
```

**Parameters**

* `symbol` — Required. The bullet symbol to apply.
* `options` — Optional. Default: `{}`. Scope options. Defaults to `mode: 'list'` in command behavior.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Change bullet symbol for the whole list.
const item = fDocument.findListItemByText('Todo')
item?.setGlyphSymbol('•', { mode: univerAPI.Enum.DocsListSelectionMode.List })

// Change bullet symbol for the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
item2?.setGlyphSymbol('◦', { mode: univerAPI.Enum.DocsListSelectionMode.Level })

// Change bullet symbol for just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
item3?.setGlyphSymbol('▪', { mode: univerAPI.Enum.DocsListSelectionMode.Item })
```

**Types:** [`IDocsListOperationOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.setGlyphType`

Changes the list marker glyph type for this item, level, or whole list.

`glyphType` controls the marker value style, such as decimal numbers, upper-case letters,
lower-case letters, or Roman numerals. It does not change marker punctuation or wrapping;
use `setPrefixSuffix()` to change formats such as `1.`, `(1)`, or `Step 1:`.

For unordered bullet lists, setting an ordered glyph type such as `DECIMAL` removes the
bullet symbol and renders the marker as an ordered value. For ordered lists, setting the
same glyph type as the current level may succeed without a visible change. For example,
the default first level of `PresetListType.ORDER_LIST` is already `DECIMAL`.

```typescript
setGlyphType(glyphType: ListGlyphType, options?: IDocsListOperationOptions): boolean
```

**Parameters**

* `glyphType` — Required. The marker glyph type to apply.
* `options` — Optional. Default: `{}`. Scope options. Defaults to `mode: 'list'` in command behavior.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Change glyph type for the whole list.
const item = fDocument.findListItemByText('Todo')
item?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, {
  mode: univerAPI.Enum.DocsListSelectionMode.List,
})

// Change glyph type for the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
item2?.setGlyphType(univerAPI.Enum.ListGlyphType.LOWER_ROMAN, {
  mode: univerAPI.Enum.DocsListSelectionMode.Level,
})

// Change glyph type for just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
item3?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, {
  mode: univerAPI.Enum.DocsListSelectionMode.Item,
})
```

**Types:** [`ListGlyphType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts) · [`IDocsListOperationOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.setPrefixSuffix`

Sets ordered-list prefix and suffix for this item, level, or whole list.

This changes the ordered marker format around the number placeholder. For example,
`prefix: '('` and `suffix: ')'` renders markers like `(1)`, while `prefix: 'Step '`
and `suffix: ':'` renders markers like `Step 1:`.

In `mode: Item`, the item receives a custom list definition, but it keeps the same
`listId` so ordered-list numbering stays continuous with the surrounding list. Because
ordered marker rendering also depends on that shared numbering context, prefix/suffix
changes may appear to affect adjacent items in the same continuous list. Use `mode: Level`
or `mode: List` when formatting ordered-list markers for a stable visual result.
No-op for unordered bullet lists.

```typescript
setPrefixSuffix(prefix: string, suffix: string, options?: IDocsListOperationOptions): boolean
```

**Parameters**

* `prefix` — Required. Prefix before the number token.
* `suffix` — Required. Suffix after the number token.
* `options` — Optional. Default: `{}`. Scope options. Defaults to `mode: 'list'` in command behavior.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Set prefix/suffix for the whole list.
const item = fDocument.findListItemByText('Todo')
if (item?.isOrdered()) {
  item.setPrefixSuffix('(', ')', { mode: univerAPI.Enum.DocsListSelectionMode.List })
}

// Set prefix/suffix for the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
if (item2?.isOrdered()) {
  item2.setPrefixSuffix('<', '>', { mode: univerAPI.Enum.DocsListSelectionMode.Level })
}

// Set prefix/suffix for just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
if (item3?.isOrdered()) {
  item3.setPrefixSuffix('[', ']', { mode: univerAPI.Enum.DocsListSelectionMode.Item })
}
```

**Types:** [`IDocsListOperationOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)

### `FDocumentListItem.setStartNumber`

Starts ordered-list numbering from the provided number at this item.

This only applies to ordered list items. Calling it on an unordered bullet list is a no-op.
The current implementation restarts numbering from this item and may affect following
continuous ordered-list items, regardless of `mode`.

```typescript
setStartNumber(startNumber: number, options?: IDocsListStartNumberOptions): boolean
```

**Parameters**

* `startNumber` — Required. The visible number to start from.
* `options` — Optional. Default: `{}`. Scope and restart options.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Start numbering from 5 for the whole list.
const item = fDocument.findListItemByText('Todo')
if (item?.isOrdered()) {
  item.setStartNumber(5, { mode: univerAPI.Enum.DocsListSelectionMode.List })
}

// Start numbering from 3 for the current level.
const item2 = fDocument.findListItemByText('Subtask 1')
if (item2?.isOrdered()) {
  item2.setStartNumber(3, { mode: univerAPI.Enum.DocsListSelectionMode.Level })
}

// Start numbering from 10 for just the item.
const item3 = fDocument.findListItemByText('Subtask 1')
if (item3?.isOrdered()) {
  item3.setStartNumber(10, { mode: univerAPI.Enum.DocsListSelectionMode.Item })
}
```

**Types:** [`IDocsListStartNumberOptions`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list-item.d.ts)