<share-button>
is a custom web component built on
the
custom element standard. The component makes it easy to add a share button to your page.
It's fully customizable, supports dark mode by default, and can be
used on nearly any platform.
Installation
There are two ways to add your share button to the page.
1. Use the CDN
Add the following script tag to your head
.
<script defer src="https://unpkg.com/@royalfig/share-button/dist/share-button.umd.js"></script>
Specify a version number in the CDN URL to speed up loading time: ...@royalfig/share-button@0.0.16...
2. Install with NPM
npm install @royalfig/share-button
Usage
There are two ways to add the share button to the page:
Custom element
Add the custom element
<share-button></share-button>
in the page
body
.
That's it!
The share button is now fully active.
Injection
It's also possible to inject the button directly onto the page, which
is helpful if you don't have access to your site's HTML.When using
this method, the button has fixed positioning, meaning that it will
float at the bottom left
, center
, or
right
of the page.
Initialize injection by adding the
data-position
attribute to the script tag along with
where you want the button to appear:
<script data-position="left" src="https://unpkg.com/@royalfig/share-button/dist/share-button.umd.js">
Customization
The share button comes with great default styles out of the box, including support for dark mode (when the user's OS preference is set to dark mode).
But it's also possible to define custom styles using attributes. For
example, to change the button's color, add the
color-button
attribute followed by a valid CSS color.
<share-button color-button="#FEBE99" color-button-text="#000" dark-mode="false"></share-button>
Below, find a list of all available custom attributes.
Note that when using the attributes via the
injection method, you must add a
data-
prefix.
Attribute | Description | Default value |
---|---|---|
color-backdrop |
The backdrop color behind the dialog | hsl(210deg 20% 98% / 50%) |
color-border |
Border color on share dialog | #e5e7eb |
color-button-text |
Button text color | #f9fafb |
color-button |
Button background color | #181b20 |
color-element |
Share dialog text and icon color | #181b20 |
color-surface |
Share dialog background color | #f9fafb |
button-text |
See button text options | "Share" |
dark-mode |
See dark mode customization for details | true |
icon |
Seven custom icons are available. | 1 |
position |
Injects the button onto the page. Learn more. | Not enabled by default. |
Button Text
To change button text, add the button-text
attribute to
the share-button
element.
<share-button button-text="Some totally different text"></share-button>
Use an empty string to omit button text altogether. Styles will update
to make the button a circle and an aria-label
will be
added to the button indicating its text.
Dark Mode Customization
By default, the share button includes default support for dark mode based on the user's OS preference. That is, when the OS is set to prefer dark mode, the share button and dialog will be in dark mode and vice versa.
However, it's possible to override this behavior by setting the
dark-mode
attribute to false
. Doing so
disables dark mode and preserves all custom colors.
Add custom dark mode styles by defining values for custom variables as a string. Variable names are the same as the custom attributes listed above.
<share-button dark-mode="--color-backdrop: #ff0; --color-border: #ff0; --color-button-text: #82b; --color-button: #333; --color-element: #010; --color-surface: #222;"></share-button>
Icon
There are seven icons available. Set the icon using the `icon` data attribute followed by a number from 1 to 7. See icons below for examples.
<share-button icon="1"></share-button>
To omit an icon altogether, set the icon attribute to
false
.
<share-button icon="false"></share-button>
FAQs
I want to add social meta platform x. (Not that X, something else...)
The share button is designed to be as lightweight as possible. It currently supports Twitter, Facebook, LinkedIn, and copying the URL to the clipboard. If you'd like to add support for another platform, please open an issue on GitHub.
Other problem, issue, feature request, or complaint?
Please file an issue on GitHub.
Happy sharing!