---
title: "Import custom nodes from .docx"
description: "Learn how to import custom nodes from DOCX (Word) files using the Import extension."
canonical_url: "https://tiptap.dev/docs/conversion/import/docx/custom-node-mapping"
---

# Import custom nodes from .docx

Learn how to import custom nodes from DOCX (Word) files using the Import extension.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Install from private registry**

  To install this frontend extensions, authenticate to Tiptap's private npm registry by following the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).

The `@tiptap-pro/extension-import-docx` extension allows you to define how custom nodes in a DOCX file should be mapped back to your Tiptap schema during import.

## Import custom nodes from .docx

> **Interactive demo:** [ImportDocxCustomNode](https://embed-pro.tiptap.dev/preview/Extensions/ImportDocxCustomNode)

When importing a DOCX file, you can define how custom nodes should be converted back to Tiptap nodes. This is done by passing an array of custom node definitions to the `import` command.

```ts
import { ImportDocx } from '@tiptap-pro/extension-import-docx'

// ... inside your Editor or useEditor setup:
ImportDocx.configure({
  appId: 'your-app-id',
  token: 'your-jwt',
  // ATTENTION: This is for demo purposes only
  endpoint: 'https://your-endpoint.com',
  imageUploadConfig: {
    url: 'https://your-endpoint.com/image-upload',
  },
  // ProseMirror custom node mapping
  prosemirrorNodes: {
    Hintbox: 'hintbox',
  },
}),
```

The latest version of the `@tiptap-pro/extension-import-docx` has available the `prosemirrorNodes` configuration option. This option allows you to map custom nodes from the DOCX to your Tiptap schema. In the example above, we are mapping the `Hintbox` custom node from the DOCX to the `hintbox` custom node in our Tiptap schema. By doing so, whenever the DOCX contains a `Hintbox` custom node, it will be converted to a `hintbox` node in Tiptap when imported.

> **DOCX, "prosemirrorNodes" and "prosemirrorMarks":**
>
> Please note that the `prosemirrorNodes` and `prosemirrorMarks` options will only work if you're importing a `.docx` file. If you're importing another type of file, eg: an `.odt` file, the `/import` endpoint will be used instead of the `/import-docx` endpoint, and the `prosemirrorNodes` and `prosemirrorMarks` options will not be available, and therefore you'd need to rely on the [custom node and mark mapping API](https://tiptap.dev/docs/conversion/import/docx/rest-api.md#custom-node-and-mark-mapping) for those endpoints.