API reference
React buttons that let readers like, share and follow with their Bluesky account. Install with npm install @skyscribe-sdk/social. See the Social buttons guide for walkthroughs.
Note
A button only works on its own Publication's website: the page it's on must be the Publication's url (with or without www.), or a SkyScribe Site showing that Publication. There's nothing to register.
LikeButtonfunction LikeButton(props: LikeButtonProps): JSX.Element
A button that records a like (a site.standard.graph.recommend record in the reader's account) for a Document. It opens a sign-in popup at social.skyscribe.app, then switches to its confirmed state.
LikeButtonProps
| Prop | Type | Required | Description |
|---|---|---|---|
documentUri | string | ✓ | AT URI of the site.standard.document record |
publicationUri | string | ✓ | AT URI of the site.standard.publication record |
title | string | ✓ | The Document's title, shown in the popup |
serviceUrl | string | — | Override the social service base URL. Defaults to "https://social.skyscribe.app" |
className | string | — | Additional CSS class appended to the base scribe-atp-like-button class |
children | ReactNode | ((isLiked: boolean) => ReactNode) | — | Custom button label. Omit to use the defaults "Like" / "Liked ✓" |
onSuccess | () => void | — | Called after a successful like |
defaultLiked | boolean | — | Starting liked state. Pass it from a server loader to avoid a flash of the wrong state |
import { LikeButton } from '@skyscribe-sdk/social';
<LikeButton
documentUri="at://did:plc:abc123/site.standard.document/3jxtctq7kqm2y"
publicationUri="at://did:plc:abc123/site.standard.publication/3mp4nd46xwr2h"
title="My Article Title"
/>
Getting the URIs: the StandardDocument from fetchDocumentBySlug (or any of the adapters) has its AT URI as document.uri, and the StandardPublication from fetchPublication has its AT URI as publication.uri.
Saved state: once liked, the result is stored in localStorage under scribe:recommended:{documentUri}, so the button shows as liked on later visits.
Accessibility: shows its state with aria-pressed, and is never disabled, so it stays in the tab order.
ShareButtonfunction ShareButton(props: ShareButtonProps): JSX.Element
A button that opens a popup for the reader to share the Document as a Bluesky post. After a successful share it shows its confirmed state for 3 seconds, then resets so the reader can share again.
ShareButtonProps
| Prop | Type | Required | Description |
|---|---|---|---|
documentUri | string | ✓ | AT URI of the site.standard.document record |
publicationUri | string | ✓ | AT URI of the site.standard.publication record |
title | string | ✓ | The Document's title, shown in the popup |
canonicalUrl | string | — | Canonical URL of the Document. Defaults to window.location.href |
serviceUrl | string | — | Override the social service base URL. Defaults to "https://social.skyscribe.app" |
className | string | — | Additional CSS class appended to the base scribe-atp-share-button class |
children | ReactNode | ((isShared: boolean) => ReactNode) | — | Custom button label. Omit to use the defaults "Share" / "Shared ✓" |
onSuccess | () => void | — | Called after a successful share |
confirm | boolean | — | true (the default) lets the reader write the post first. false posts the title and link straight after sign-in. Since 1.7.0 |
import { ShareButton } from '@skyscribe-sdk/social';
<ShareButton
documentUri="at://did:plc:abc123/site.standard.document/3jxtctq7kqm2y"
publicationUri="at://did:plc:abc123/site.standard.publication/3mp4nd46xwr2h"
title="My Article Title"
/>
Note: Unlike LikeButton and SubscribeButton, the shared state is not persisted to localStorage. The confirmed state resets after 3 seconds so the reader can share again.
SubscribeButtonfunction SubscribeButton(props: SubscribeButtonProps): JSX.Element
A button that subscribes the reader to a Publication. It opens a sign-in popup, then switches to its confirmed state. It's a toggle: when the reader is already subscribed, clicking it opens a popup to confirm unsubscribing.
SubscribeButtonProps
| Prop | Type | Required | Description |
|---|---|---|---|
publicationUri | string | ✓ | AT URI of the site.standard.publication record |
title | string | ✓ | The Publication's name, shown in the subscribe and unsubscribe popups |
serviceUrl | string | — | Override the social service base URL. Defaults to "https://social.skyscribe.app" |
className | string | — | Additional CSS class appended to the base scribe-atp-subscribe-button class |
children | ReactNode | ((isSubscribed: boolean) => ReactNode) | — | Custom button label. Omit to use the defaults "Follow" / "Following ✓" (since 1.6.0; "Subscribe" / "Subscribed ✓" before). The render prop receives isSubscribed so you can show different copy in each state |
onSuccess | () => void | — | Called after a successful subscription |
onUnsubscribe | () => void | — | Called after a confirmed unsubscription |
defaultSubscribed | boolean | — | Starting subscribed state. Pass it from a server loader to avoid a flash of the wrong state |
import { SubscribeButton } from '@skyscribe-sdk/social';
<SubscribeButton
publicationUri="at://did:plc:abc123/site.standard.publication/3mp4nd46xwr2h"
title="My Site"
/>
Getting the publicationUri: a StandardPublication from fetchPublication has it as publication.uri. resolvePublicationUri returns it without the rest of the Publication.
Saved state: stored in localStorage under scribe:subscribed:{publicationUri}, and cleared after the reader unsubscribes.
Accessibility: shows its state with aria-pressed, and is never disabled, so it stays in the tab order.
For reading or setting the saved liked and subscribed state outside the components, for example in tests or your own UI.
isRecommendedfunction isRecommended(documentUri: string): boolean
Returns true if the current user has already liked the given document.
markRecommendedfunction markRecommended(documentUri: string): void
Saves a liked state to localStorage, for example if you recorded the like through your own UI and want the button to show it.
isSubscribedfunction isSubscribed(publicationUri: string): boolean
Returns true if the current user has already subscribed to the given publication.
markSubscribedfunction markSubscribed(publicationUri: string): void
Saves a subscribed state to localStorage.
clearSubscribedfunction clearSubscribed(publicationUri: string): void
Removes a saved subscribed state from localStorage, for example after the reader unsubscribes through your own UI. SubscribeButton does this itself. Since 1.5.0.
All five are safe to call on the server: where localStorage isn't available, they return false or do nothing.
social.skyscribe.app, with the AT URI, the title and a one-time token in its URL.postMessage. If the browser blocks that, the button polls the service instead.LikeButton and SubscribeButton save it to localStorage; ShareButton resets after 3 seconds.The polling fallback runs for up to 30 seconds (20 attempts at 1.5 s intervals) before stopping.
See the Social buttons guide for full examples.