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

# insertPageElements

> Insert elements into the specified page in the current file.

```ts wrap theme={null}
static insertPageElements(
  elements: Element[],
  page: number,
  layer?: number | null
): Promise<APIResponse<boolean>>;
```

<Note>
  When this API operates on the current page, call [`getPageDisplaySize`](/en/api-reference/supernote-plugin/plugin-comm-api/get-page-display-size) first to get the current page display size. Do not call [`PluginFileAPI.getPageSize`](/en/api-reference/supernote-plugin/plugin-file-api/get-page-size) to get the file page size, otherwise the position data may not match.
</Note>

The `elements` you pass in typically come from [`createElement`](/en/api-reference/supernote-plugin/plugin-comm-api/create-trail) or existing elements read from elsewhere; `uuid` stays the same before and after insertion. This API requires those elements to still be present in the native cache — elements that can't be found in the cache are silently skipped instead of causing a separate error. See [Element Caching and Release](/en/plugin-base/file-op/element-op#4-element-caching-and-release) for details.

**Parameters**

| Parameter  | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `elements` | [`Element[]`](/en/api-reference/supernote-plugin/types/trail) | Elements to insert                                                                                                                                                                                                                                                                                                                                                                                     |
| `page`     | `number`                                                      | Page index, starting from `0`                                                                                                                                                                                                                                                                                                                                                                          |
| `layer`    | `number \| null`                                              | Optional layer parameter. For note files (`.note`), when omitted, the current layer is used. For recognized notes, the parameter is ignored whether you pass it or not because recognized notes have only one layer. For document files (`.pdf`, `.epub`, etc.), the parameter is ignored whether you pass it or not because document files have only one layer. When provided, valid values are `0-3` |

**Returns**

* [`APIResponse<boolean>`](/en/api-reference/supernote-plugin/types/api-response): `result === true` indicates the insertion succeeded

**Throws**

* Throws a parameter validation error when `elements` is not a valid element array
* Throws a parameter validation error when `page` is not an integer greater than or equal to `0`
* Throws a parameter validation error when `layer` is provided but is not an integer in the range `0-3`

## Example

```ts wrap theme={null}
import { PluginCommAPI, type Element } from 'sn-plugin-lib';

/**
 * Example: insert elements into a specified page in the current file.
 */
export async function exampleInsertPageElements(elements: Element[]) {
  const page = 0;
  const layer = 0;
  const res = await PluginCommAPI.insertPageElements(elements, page, layer);
  if (!res.success) {
    console.log('insertPageElements failed', res.error);
    throw new Error(res.error?.message ?? 'insertPageElements call failed');
  }
  console.log('insertPageElements result', res.result);
  return res.result;
}
```