# Library blocks and embedded blocks

*Choose between a block you can reuse in any prompt and a block that belongs to one prompt only, and edit either from the Build screen.*

Online version: https://promptmason.ai/docs/embedded-blocks

A dynamic prompt can use two kinds of block:

- **Library blocks** live on the Blocks screen. You can use one in any number of prompts, and changing it changes every prompt that uses it.
- **Embedded blocks** belong to one prompt. They're for text that only that prompt needs. They aren't on the Blocks screen, in search or in the Build screen's block list, and changing one changes only its prompt.

On the Build screen, an embedded block has an **Embedded** badge. A library block has no **Embedded** badge.

![The Build canvas with two library blocks and one block carrying an Embedded badge.](https://promptmason.ai/images/docs/embedded-blocks-embedded-badge-on-canvas.webp)

## How they compare

| | Library block | Embedded block |
|---|---|---|
| Where it's listed | Blocks screen, search, the Build screen's block list | Only inside its prompt |
| Used by | Any number of prompts | One prompt |
| Editing it changes | Every prompt that uses it | Only its prompt |
| When an edit is saved | Straight away | When you save the prompt |
| Version history | Its own | Part of the prompt's history |
| Counts toward the Free plan's 25 blocks | Yes | No |
| When its prompt is deleted | Stays in your library | Deleted with the prompt, and restored with it |

## Add an embedded block

1. Open the prompt on the Build screen ([Build a prompt](https://promptmason.ai/docs/build-prompt)).
2. Click **Embedded Block**, above the canvas. A new block with a **New** badge appears at the end of the prompt.

    ![A new embedded block card at the bottom of the canvas, with a name box, a Type menu, a text box and a Save to Block Library checkbox.](https://promptmason.ai/images/docs/embedded-blocks-embedded-block-card.webp)

3. Type a name for the block.
4. Choose its type in the box next to the name.
5. Write the block's text. The toolbar and the `{{` variable picker work as they do on the Blocks screen.
6. Tick **Include Name** or **Include Type** if you want a header above it ([block headers](https://promptmason.ai/docs/text-formatting#block-headers)).
7. Leave **Save to Block Library** unticked.
8. Save the prompt (**Save as Dynamic**, **Update Prompt** or **Apply**).

The block becomes a real embedded block when you save the prompt. The Save buttons stay grayed out until every new block has a name, a type and some text.

To get rid of a new block before you save, click its X. **Undo** may not bring back an unsaved block you removed, so copy its text first if you might want it.

## Add a new library block from Build

Follow the steps in [Add an embedded block](#add-an-embedded-block), but tick **Save to Block Library** at step 7. A **Tags** box appears for the block's tags (when the Tags feature is on).

When you save the prompt, the block is added to the Blocks screen like any other library block, and you can use it in other prompts. On the Free plan it counts toward your 25 blocks. If there isn't room, the **Free plan limit** window opens and nothing is saved ([Plans and limits](https://promptmason.ai/docs/plans)).

## Edit a block from Build

Click the pencil (**Edit block**) on a block's card. The **Edit block** window opens with its **Name**, **Type** and text, and what happens next depends on the kind of block.

### An embedded block

The window says **This block is embedded in this prompt only. Your changes are saved when you save the prompt.**

1. Make your changes.
2. Click **Done**.
3. Save the prompt.

If you leave Build without saving the prompt, the changes are lost. When you save, the changes go into the prompt's [version history](https://promptmason.ai/docs/version-history).

### A library block

The window says **This block is saved in your Block Library.**, with a warning: **Saving changes this block everywhere it's used**, followed by the saved prompts that use it (the first five, then "and N more").

![The Edit block window for a library block, with a warning that saving changes the block everywhere it is used.](https://promptmason.ai/images/docs/embedded-blocks-edit-block-window.webp)

1. Make your changes. When the Tags feature is on, you can change its **Tags** here too.
2. Click **Save block**.

The block is saved **straight away**, for every prompt that uses it, even if you then leave Build without saving this prompt. To change it for this prompt only, click **Cancel** and use [Convert to embedded block](#change-a-library-block-for-this-prompt-only) instead.

## Change a library block for this prompt only

When you want different wording in this prompt, but don't want to change the block in your other prompts:

1. On the block's card, click the **Convert to embedded block** button (between the pencil and the X).

    ![A library block's card with its pencil, Convert to embedded block and remove buttons.](https://promptmason.ai/images/docs/embedded-blocks-card-buttons.webp)

2. The card is replaced, in the same place, by a new embedded block with the same name, type, text, tags and header choices.
3. Change the text.
4. Save the prompt.

The library block isn't changed, and your other prompts keep using it.

## Turn an embedded block into a library block

You can make one of this prompt's embedded blocks into a library block from the Code view:

1. On the Build screen, click **Code** above the canvas, then **Edit**.
2. Find the block (its `"saveToBlocksLibrary"` is `false`) and change it to `true`.
3. Save the prompt.

The block then shows on the Blocks screen, and counts toward the Free plan's 25 blocks. See [Edit a prompt as code](https://promptmason.ai/docs/code-view).

You can't turn a library block into an embedded block this way. Use [Convert to embedded block](#change-a-library-block-for-this-prompt-only), which makes an embedded copy.

## Copying a prompt

When you duplicate a prompt (right-click it on the Prompts screen and choose **Copy**):

- The copy uses the **same library blocks** as the original. Changing one of them changes both prompts.
- The copy gets **its own copies of the embedded blocks**. Changing an embedded block in one prompt doesn't change the other.

See [Folders, moving and copying](https://promptmason.ai/docs/folders).

## Want a hand?

Paste this prompt into Claude, ChatGPT or another AI assistant, together with this guide, to be walked through it step by step:

> I'm building a prompt in PromptMason and need some text that only this prompt uses. Explain library blocks and embedded blocks, and walk me through adding an embedded block and changing a library block for this prompt only.