---
url: /posts/2023/simple-copy-button-helper-for-vitepress.md
description: >-
  A simple copy button helper for VitePress that allows you to add copy buttons
  to single backtick code blocks
---

See [vitepress-copy-helper's readme](https://github.com/Mtillmann/vitepress-copy-helper) for installation and configuration instructions.

Below are some examples of how to use the component in your vitepress markdown files.

## Examples

### Positioning Buttons relative to `code`-blocks

| markdown | html |
| --- | --- |
| `` `button at the end`<C/> `` | `button at the end`
| `` <C/>`button at the start` `` | `button at the start` |

The button is rendered on the inside of the code block in order of occurence.

You can force the button to be rendered on a specific side by setting the `position` prop to `start` or `end`:

| markdown | html |
| --- | --- |
| `` `button at the end, rendered at start`<C position="start"/> `` | `button at the end, rendered at start`
| `` <C position="end"/>`button at the start, rendered at end` `` | `button at the start, rendered at end` |

In the examples above, the natural order of the button is reversed by setting the `position` prop.

> Default behaviour can be changed globally by setting the `position` default setting to `start` or `end`.

### Selecting `code`-block targets

| markdown | html |
| --- | --- |
| `` `before` <C/> `after` `` | `before`  `after` |

The button attaches itself to the *previous* code-sibling by default.
This can be changed on a per-button basis by setting the `target` prop to `next`:

| markdown | html |
| --- | --- |
| `` `before` <C target="next"/> `after` `` | `before`  `after` |
| `` `before` <C target="next" position="end"/> `after` `` | `before`  `after` |

The button is attached to the *next* code-sibling. The first button is rendered at the start of the code block, because it uses implicit `position="auto"` and is attached from the left.

> By default, a button wedged between two code-nodes is attached to the previous code-sibling. This can be changed globally by changing the `preferSibling` default setting to `next`.

### Labels and Messages

| markdown | html |
| --- | --- |
| `` `node_nodules`<C label="copy & paste to .gitignore"/> `` | `node_nodules` |
| `` `ls -la`<C message="paste in shell">sh</C> `` | `ls -la`sh |
| `` `ls -la`<C message="内容已复制到剪贴板"/> `` | `ls -la` |
| `` `npm init -y`<C message="copied '$CONTENT'" /> `` | `npm init -y` |

The button label can be set by using the `label` prop or by using the default slot, although the `label` prop takes precedence over the default slot.

Also, using the prop does not pollute the source markdown, so it's recommended to use the `label` prop.

Labels are very useful to provide context on where to paste the copied content.

As demonstrated in the last example, you can reference the copied content by using the `$CONTENT` placeholder in the `message` prop.

> Both `label` and `message` props can be set globally by changing the `label` and `message` default settings. This is useful if you want to translate the button label and message.

### Standalone Buttons

| markdown | html |
| --- | --- |
| `No content-prop - no button <C/>` | No content-prop - no button  |
| `This will render a button <C content="yo :D"/>` | This will render a button  |
| `<C content="very good">Click here to copy!</C>` | Click here to copy! |

Standalone buttons can be created by including the `content` prop. This is useful if you want to create a button that is not attached to a code block.

If you omit the `content` prop, the button will not be rendered. `position` and `target` props have no effect on standalone buttons.
