---
icon: fa-solid:share-nodes
---
# share
Add share buttons to your site, so visitors can share pages to social platforms, by email, or as a QR code.
## Usage
```bash
npm i -D @vuepress/plugin-share@next
```
```ts title=".vuepress/config.ts"
import { sharePlugin } from '@vuepress/plugin-share'
export default {
plugins: [
sharePlugin({
// options
}),
],
}
```
The plugin registers a global `Share` component. Add it to any page:
```md
```
## Guide
### Share Services
By default, the plugin renders buttons for Twitter, Facebook, Reddit, Telegram, WhatsApp, and email.
You can choose the buttons to display on a page with the `services` prop. It accepts a comma separated string or an array of service names:
```md
```
The following built-in services are available:
| Name | Platform | Name | Platform |
| ----------- | --------- | ----------- | --------- |
| `buffer` | Buffer | `qq` | QQ |
| `douban` | Douban | `qrcode` | QR code |
| `email` | Email | `qzone` | Qzone |
| `evernote` | Evernote | `reddit` | Reddit |
| `facebook` | Facebook | `skype` | Skype |
| `flipboard` | Flipboard | `sms` | SMS |
| `line` | LINE | `snapchat` | Snapchat |
| `linkedin` | LinkedIn | `telegram` | Telegram |
| `messenger` | Messenger | `tumblr` | Tumblr |
| `pinterest` | Pinterest | `twitter` | Twitter |
| `vk` | VK | `weibo` | Weibo |
| `whatsapp` | WhatsApp | `wordpress` | WordPress |
Every built-in service is available to the component. The `services` option only decides which buttons are displayed by default, so `` works without listing `qq` in the plugin options.
### Custom Services
You can add a custom service in the `services` option:
```ts title=".vuepress/config.ts"
import { sharePlugin } from '@vuepress/plugin-share'
export default {
plugins: [
sharePlugin({
services: [
'twitter',
{
name: 'mastodon',
link: 'https://mastodon.social/share?text=[title]&url=[url]',
shape: '',
color: '#6364ff',
},
],
}),
],
}
```
A custom service requires `name`, `link`, and `shape`. It also supports `color`, `icon`, and `action`:
- `shape` is the plain icon. It can be an SVG string, an image URL, or a font icon class.
- `color` is the background color used by the colorful icon.
- `icon` overrides the icon used when `colorful` is enabled.
- `action` is the behavior of the button. See [Actions](#actions).
Custom services are only known to the client when they are provided in the plugin options. To display them by name, pass their names in the `services` prop:
```md
```
### Share Data
The link of each service can contain variables wrapped in brackets. They are replaced with the data of the current page:
| Variable | Description |
| ------------- | --------------------------- |
| `title` | Page title |
| `description` | Page description |
| `url` | Page URL |
| `excerpt` | Page excerpt |
| `summary` | Page summary |
| `tags` | Page tags, joined by commas |
| `cover` | Page cover |
| `image` | First image on the page |
`description`, `excerpt`, `summary`, `cover`, and `tags` fall back to the matching page frontmatter field, and `description` also falls back to the page meta tags:
```yaml
---
description: A page about VuePress
tag:
- vuepress
- plugin
cover: /images/cover.png
---
```
You can override the title, description, excerpt, summary, cover, and tags per page with props that receive the current page. `url` and `image` are always derived from the page:
```md
```
### Actions
A service opens its link in a popup window by default. The built-in QR code service uses `qrcode`, and the email service opens a new tab. For custom services, set `action` to one of:
- `popup`: Opens the link in a centered popup window.
- `open`: Opens the link in a new tab.
- `navigate`: Opens the link in the current tab.
- `qrcode`: Shows a QR code of the link.
A custom `qrcode` service receives its link verbatim, so it is not percent-encoded.
### Appearance
Buttons are muted and colored on hover. Use `colorful` to render the brand color:
```md
```
Use `inline` to remove the vertical margin, which is useful when the buttons are placed in a paragraph or a layout slot:
```md
```
## Options
::: fields
@`services` type=`ShareService[]`
Services to display by default. Built-in services are selected by name, and a custom service is provided as an object.
Defaults to `twitter`, `facebook`, `reddit`, `telegram`, `whatsapp`, and `email`.
See also: [Share Services](#share-services) and [Custom Services](#custom-services).
@`twitterUserName` type=string
Twitter username used by the `via` parameter of the Twitter share link.
:::
## Component Props
::: fields
@`services` type=`string | (string | ShareServiceOptions)[]`
Services to display. It can be a comma separated string or an array of names and custom service objects.
Defaults to the `services` plugin option.
@`titleGetter` type=`(page: PageData) => string`
Getter for the share title.
Defaults to the page title.
@`descriptionGetter` type=`(page: PageData) => string | null | undefined`
Getter for the share description.
Defaults to the `description` frontmatter and meta tags.
@`excerptGetter` type=`(page: PageData) => string | null | undefined`
Getter for the share excerpt.
Defaults to the page excerpt and `excerpt` frontmatter.
@`summaryGetter` type=`(page: PageData) => string | null | undefined`
Getter for the share summary.
Defaults to the page summary and `summary` frontmatter.
@`coverGetter` type=`(page: PageData) => string | null | undefined`
Getter for the share cover.
Defaults to the page cover, `cover` frontmatter, and `og:image` meta tag.
@`tagGetter` type=`(page: PageData) => string | string[] | null | undefined`
Getter for the share tags.
Defaults to the `tag` and `tags` frontmatter.
@`inline` type=boolean
Whether to display the buttons inline.
@`colorful` type=boolean
Whether to use colorful icons.
:::