Rich Text

By default, when you create a post, @skyware/bot parses your post’s text to identify any mentions, hashtags, and URLs. However, in some cases, you may want more control over how a post is displayed. The RichText class provides a convenient interface for constructing a post containing rich text.

Usage

To start, import the RichText class from @skyware/bot:

import { class RichText
Used to build a rich text string with facets.
@seehttps://docs.bsky.app/docs/advanced-guides/post-richtext
RichText } from "@skyware/bot";

You can then build a rich text string as follows:

const const richText: RichTextrichText = new new RichText(): RichText
Used to build a rich text string with facets.
@seehttps://docs.bsky.app/docs/advanced-guides/post-richtext
RichText()
    .RichText.text(substr: string): RichText
Append a string.
text("Hey, check out this library: ")
    .RichText.link(substr: string, uri?: string): RichText
Append a link.
You can use the uri parameter to specify a different URI than the substr.
@exampleCreate a hyperlink
new RichText().text("Go to ").link("https://bsky.app").build();@exampleCreate a hyperlink with custom text
new RichText().text("Go to ").link("Bluesky", "https://bsky.app").build();
link("https://skyware.js.org")
    .RichText.text(substr: string): RichText
Append a string.
text("! ")
    .RichText.tag(tag: string): RichText
Append a tag.
tag("#atdev");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>
Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.
post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.
text: const richText: RichTextrichText })

You’ll notice that the Bot#post method can accept either RichText or a string. Your post will look something like:

A post by user @skyware.js.org with the text "Hey, check out this library: skyware.js.org! #atdev". The link and the hashtag are highlighted blue.

Mentions

When you’re manually constructing RichText, mentioning a user requires you to know the user’s handle and DID. You can then use the mention method to add a mention to your post:

const const richText: RichTextrichText = new new RichText(): RichText
Used to build a rich text string with facets.
@seehttps://docs.bsky.app/docs/advanced-guides/post-richtext
RichText()
    .RichText.text(substr: string): RichText
Append a string.
text("Hey, ")
    .RichText.mention(handle: string, did: string): RichText
Append a mention.
mention("@skyware.js.org", "did:plc:ith6w2xyj2qy3rcvmlsem6fz")
    .RichText.text(substr: string): RichText
Append a string.
text("!");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>
Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.
post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.
text: const richText: RichTextrichText })

Note that the DID provided could differ from the mentioned handle — a mention is really just a hyperlink! Use this power for good.

Speaking of hyperlinks, mentions aren’t the only way to have text act as a link. The .link method we previously used can also take two parameters: text and a URL.

const const richText: RichTextrichText = new new RichText(): RichText
Used to build a rich text string with facets.
@seehttps://docs.bsky.app/docs/advanced-guides/post-richtext
RichText()
    .RichText.text(substr: string): RichText
Append a string.
text("Hey, check out ")
    .RichText.link(substr: string, uri?: string): RichText
Append a link.
You can use the uri parameter to specify a different URI than the substr.
@exampleCreate a hyperlink
new RichText().text("Go to ").link("https://bsky.app").build();@exampleCreate a hyperlink with custom text
new RichText().text("Go to ").link("Bluesky", "https://bsky.app").build();
link("Skyware", "https://skyware.js.org")
    .RichText.text(substr: string): RichText
Append a string.
text("!");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>
Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.
post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.
text: const richText: RichTextrichText })

A post by user @skyware.js.org with the text "Hey, check out Skyware!". The word "Skyware" is highlighted blue.

Detecting facets yourself

Alternatively, the RichText class contains a detectFacets static method that will handle detecting all mentions, links, and tags, and automatically resolve mentions to DIDs.

The post method and others such as reply and quote will automatically detect facets for you if you pass a string. However, if you want to detect facets from an existing string but exclude certain facets, the RichText.detectFacets method offers greater control.

const const text: "Hey, @skyware.js.org! #atdev"text = "Hey, @skyware.js.org! #atdev";
const const facets: Main[]facets = await class RichText
Used to build a rich text string with facets.
@seehttps://docs.bsky.app/docs/advanced-guides/post-richtext
RichText.RichText.detectFacets(text: string, bot: Bot): Promise<Main[]>
Returns a RichText instance with all facets (mentions, links, tags, etc) resolved.
@paramtext The text to detect facets in.@parambot Used to resolve mentions to DIDs.
detectFacets(const text: "Hey, @skyware.js.org! #atdev"text, const bot: Botbot);

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>
Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.
post({ PostPayload.text: string | RichText
The post text. Can be a string or a RichText instance containing facets.
text, PostPayload.facets?: (Main | Facet)[] | undefined
A facet represents a range within the post's text that has special meaning
(e.g. mentions, links, tags). Prefer to use the 
{@link 
RichText
}
 class to create
posts with facets.
This will override any facets present in the 
{@link 
text
}
 property or detected automatically.
facets });

You must pass your bot instance in to RichText.detectFacets so that it can resolve mentions. If you pass facets into post, only those facets will be used.

Moving on

You may notice that adding a link to a post doesn’t automatically add an embedded preview. Learn more about that in Embeds and Images!

A post by @skyware.js.org reading "Check out this link!". The post contains an embedded link with a title, description, and preview image.