Adds an embed component for TikTok

.changeset/odd-jeans-repair.md

@@ -0,0 +1,7 @@
+---
+'@astro-community/astro-embed-integration': minor
+'@astro-community/astro-embed-tiktok': minor
+'astro-embed': minor
+---
+
+Adds TikTok astro-embed component

demo/package.json

@@ -14,6 +14,7 @@
     "@astro-community/astro-embed-gist": "workspace:*",
     "@astro-community/astro-embed-link-preview": "workspace:*",
     "@astro-community/astro-embed-mastodon": "workspace:*",
+    "@astro-community/astro-embed-tiktok": "workspace:*",
     "@astro-community/astro-embed-vimeo": "workspace:*",
     "@astro-community/astro-embed-youtube": "workspace:*",
     "@astrojs/mdx": "^5.0.4",

demo/src/pages/index.astro

@@ -36,6 +36,9 @@ import Base from '../layouts/Base.astro';
 		<li>
 			<a href="/gist"><code>&lt;Gist/&gt;</code> component examples</a>
 		</li>
+		<li>
+			<a href="/tiktok"><code>&lt;TikTok/&gt;</code> component examples</a>
+		</li>
 	</ul>
 	<h2>Other examples</h2>
 	<ul>

demo/src/pages/integration.mdx

@@ -29,3 +29,5 @@ https://astro.build/blog/welcome-world/
 https://mastodon.social/@sarah11918/112937553683639459
 
 https://gist.github.com/vasfvitor/1f995c47ee82ae652496622db1e678ea
+
+https://www.tiktok.com/@rickastleyofficial/video/7512867562258992406

demo/src/pages/tiktok.astro

@@ -0,0 +1,74 @@
+---
+import { TikTok } from '@astro-community/astro-embed-tiktok';
+import Base from '../layouts/Base.astro';
+---
+
+<Base title="TikTok component examples">
+	<h2>With just the video ID</h2>
+	<p>
+		<code>&lt;TikTok id="7512867562258992406" /&gt;</code>
+	</p>
+	<TikTok id="7512867562258992406" />
+
+	<h2>With a full tiktok.com URL</h2>
+	<p>
+		<code
+			>&lt;TikTok
+			id="https://www.tiktok.com/@rickastleyofficial/video/7512867562258992406"
+			/&gt;</code
+		>
+	</p>
+	<TikTok
+		id="https://www.tiktok.com/@rickastleyofficial/video/7512867562258992406"
+	/>
+
+	<h2>Displaying as a video instead of a player</h2>
+	<p>
+		<code
+			>&lt;TikTok id="7512867562258992406" embedType="video" maxWidth="418px"
+			/&gt;</code
+		>
+	</p>
+	<TikTok id="7512867562258992406" embedType="video" maxWidth="418px" />
+
+	<h2>With a custom poster image</h2>
+	<p>
+		<code
+			>&lt;TikTok id="7512867562258992406"
+			poster="https://picsum.photos/id/158/1280/853" /&gt;</code
+		>
+	</p>
+	<TikTok
+		id="7512867562258992406"
+		poster="https://picsum.photos/id/158/1280/853"
+	/>
+
+	<h2>With custom params</h2>
+	<p>
+		<code
+			>&lt;TikTok id="7512867562258992406"
+			params="music_info=1&description=1&autoplay=0&loop=1" /&gt;</code
+		>
+	</p>
+	<TikTok
+		id="7512867562258992406"
+		params="music_info=1&description=1&autoplay=0&loop=1"
+	/>
+
+	<h2>With a custom play label</h2>
+	<p>
+		<code
+			>&lt;TikTok id="7512867562258992406" playLabel="Play the TikTok video"
+			/&gt;</code
+		>
+	</p>
+	<TikTok id="7512867562258992406" playLabel="Play the TikTok video" />
+
+	<h2>With a 16:9 aspect ratio override</h2>
+	<p>
+		<code
+			>&lt;TikTok id="7512867562258992406" orientation="landscape" /&gt;</code
+		>
+	</p>
+	<TikTok id="7512867562258992406" orientation="landscape" />
+</Base>

docs/package.json

@@ -16,6 +16,7 @@
     "@astro-community/astro-embed-gist": "workspace:*",
     "@astro-community/astro-embed-link-preview": "workspace:*",
     "@astro-community/astro-embed-mastodon": "workspace:*",
+    "@astro-community/astro-embed-tiktok": "workspace:*",
     "@astro-community/astro-embed-twitter": "workspace:*",
     "@astro-community/astro-embed-vimeo": "workspace:*",
     "@astro-community/astro-embed-youtube": "workspace:*",

docs/src/content/docs/components/tiktok.mdx

@@ -0,0 +1,173 @@
+---
+title: TikTok
+description: Learn how to use the Astro Embed TikTok component to embed TikTok videos in your website
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { TikTok } from '@astro-community/astro-embed-tiktok';
+
+The `<TikTok>` component generates an embed using a lightweight custom element that will load TikTok's `<iframe>` only when a user clicks play.
+
+TikTok embeds will always require some JavaScript, but this is one of the most minimal and performant ways to embed a TikTok video while protecting your visitors' privacy until they choose to interact.
+
+## Usage
+
+<Tabs>
+<TabItem label="Astro" icon="astro">
+```astro
+---
+import { TikTok } from 'astro-embed';
+---
+
+<TikTok id="7512867562258992406" />
+```
+</TabItem>
+<TabItem label="MDX" icon="seti:markdown">
+```astro
+import { TikTok } from 'astro-embed';
+
+<TikTok id="7512867562258992406" />
+```
+</TabItem>
+</Tabs>
+
+## Optional props
+
+In addition to the required `id` prop, the following props are available to customise how the `<TikTok>` component renders:
+
+### `autoplay`
+
+**Type:** `boolean`  
+**Default:** `true`
+
+If `autoplay` is set to `true`, the video will automatically start when the `<iframe>` is loaded. However, since the `<iframe>` is only loaded when a user clicks play, this prop can safely be set to `true` without worrying about unwanted autoplay behavior on page load.
+
+```astro
+<TikTok id="7512867562258992406" autoplay="false" />
+```
+
+### `embedType`
+
+**Type:** `'post' | 'video'`  
+**Default:** `'post'`
+
+The `embedType` prop controls the type of TikTok embed to generate. The default `'post'` type includes the full video player with caption and user info and more control via the optional `params` prop. The `'video'` type generates a self-contained video player with no additional controls.
+
+```astro
+<TikTok id="7512867562258992406" />
+```
+
+<TikTok id="7512867562258992406" />
+
+```astro
+<TikTok id="7512867562258992406" embedType="video" maxWidth="418px" />
+```
+
+<TikTok id="7512867562258992406" embedType="video" maxWidth="418px" />
+
+:::note
+Since the component displays with a `9:16` aspect ratio by default, setting a `maxWidth` will also adjust the height proportionally to maintain the aspect ratio. If you are using the `'video'` `embedType` and need a slightly shorter/taller player to avoid scrolling that added content, simply set the `maxWidth` to decrease/increase the overall size of the embed.
+:::
+
+### `id`
+
+**Type:** `string`
+
+The `<TikTok>` component requires a `id` prop to identify the video to embed. The `id` prop accepts any of the following formats:
+
+| Format                    | Example                                                                |
+| ------------------------- | ---------------------------------------------------------------------- |
+| Numeric video ID          | `7512867562258992406`                                                  |
+| Full video URL            | `https://www.tiktok.com/@rickastleyofficial/video/7512867562258992406` |
+| `vm.tiktok.com` short URL | `https://vm.tiktok.com/ZMkABCDEF/`                                     |
+| `tiktok.com/t/` short URL | `https://www.tiktok.com/t/ZMkABCDEF/`                                  |
+
+### `orientation`
+
+**Type:** `'portrait' | 'landscape'`  
+**Default:** `'portrait'`
+
+TikTok content is predominantly vertical, so the component defaults to a `'portrait'` orientation with an aspect ratio of 9:16. You can override this by passing in the `orientation` prop with the `'landscape'` value:
+
+```astro
+<TikTok id="7512867562258992406" orientation="landscape" />
+```
+
+### `maxWidth`
+
+**Type:** `string`  
+**Default:** `'425px'`
+
+The `maxWidth` prop allows you to set a maximum width for the embed. This can be useful for ensuring that the embed fits well within your page layout. The value should be a valid CSS length unit, such as `px`, `rem`, `vw`, or `%`.
+
+```astro
+<TikTok id="7512867562258992406" maxWidth="400px" />
+```
+
+### `params`
+
+You can pass a `params` prop to set [TikTok embed player parameters](https://developers.tiktok.com/doc/embed-player#customize_the_player_). This looks like a series of URL search params.
+
+For example, the following `params` value enables looping as well as showing the music info and description overlays:
+
+```astro
+<TikTok id="7512867562258992406" params="music_info=1&description=1&loop=1" />
+```
+
+:::note
+The `params` prop is only compatible with the default `'post'` `embedType`, which includes the full TikTok player. The `'video'` `embedType` generates a simplified player that does not support these parameters.
+:::
+
+### `playLabel`
+
+**Type:** `string`  
+**Default:** `'Play'`
+
+By default, the play button in the embed has an accessible label set to "Play".
+If you want to customise this, for example to match the language of your website, you can set the `playLabel` prop:
+
+```astro
+<TikTok id="7512867562258992406" playLabel="Play the TikTok video" />
+```
+
+### `poster`
+
+**Type:** `string`
+
+You can provide an alternative poster image by passing in a URL to the `poster` prop. If not provided, the component will automatically fetch the thumbnail from TikTok's oEmbed API.
+
+```astro
+<TikTok
+	id="7512867562258992406"
+	poster="https://picsum.photos/id/158/1280/853"
+/>
+```
+
+<TikTok
+	id="7512867562258992406"
+	poster="https://picsum.photos/id/158/1280/853"
+/>
+
+### `title`
+
+**Type:** `string`
+
+The video title is automatically fetched from TikTok's oEmbed API and displayed as an overlay on the poster image. You can override this with a custom title:
+
+```astro
+<TikTok id="7512867562258992406" title="My custom title" />
+```
+
+## Standalone installation
+
+If you only need the `<TikTok>` component, you can install the package directly instead of the main `astro-embed` package:
+
+import { PackageManagers } from 'starlight-package-managers';
+
+<PackageManagers pkg="@astro-community/astro-embed-tiktok" />
+
+The `<TikTok>` component can then be imported as:
+
+```js
+import { TikTok } from '@astro-community/astro-embed-tiktok';
+```

docs/src/content/docs/getting-started.mdx

@@ -77,6 +77,7 @@ Astro Embed currently supports the following services:
 	<LinkCard title="GitHub Gist" href="/components/gist/" />
 	<LinkCard title="Mastodon" href="/components/mastodon/" />
 	<LinkCard title="Open Graph" href="/components/link-preview/" />
+	<LinkCard title="TikTok" href="/components/tiktok/" />
 	<LinkCard title="Twitter" href="/components/twitter/" />
 	<LinkCard title="Vimeo" href="/components/vimeo/" />
 	<LinkCard title="YouTube" href="/components/youtube/" />

docs/src/content/docs/index.mdx

@@ -95,4 +95,12 @@ import { Icon, Card, CardGrid } from '@astrojs/starlight/components';
 
     </Card>
 
+    <Card title="TikTok" icon="tiktok">
+
+    	Load TikTok embeds on user interaction for faster page loads.
+
+    	[TikTok docs](/components/tiktok/)
+
+    </Card>
+
 </CardGrid>

packages/astro-embed-integration/package.json

@@ -25,6 +25,7 @@
     "@astro-community/astro-embed-bluesky": "^0.2.0",
     "@astro-community/astro-embed-gist": "^0.1.0",
     "@astro-community/astro-embed-link-preview": "^0.3.1",
+    "@astro-community/astro-embed-tiktok": "^0.1.0",
     "@astro-community/astro-embed-mastodon": "^0.1.1",
     "@astro-community/astro-embed-twitter": "^0.5.11",
     "@astro-community/astro-embed-vimeo": "^0.3.12",

packages/astro-embed-integration/remark-plugin.ts

@@ -1,6 +1,7 @@
 import { type Node, select, selectAll } from 'unist-util-select';
 import blueskyMatcher from '@astro-community/astro-embed-bluesky/matcher';
 import gistMatcher from '@astro-community/astro-embed-gist/matcher';
+import tiktokMatcher from '@astro-community/astro-embed-tiktok/matcher';
 import twitterMatcher from '@astro-community/astro-embed-twitter/matcher';
 import vimeoMatcher from '@astro-community/astro-embed-vimeo/matcher';
 import youtubeMatcher from '@astro-community/astro-embed-youtube/matcher';
@@ -10,6 +11,7 @@ import mastodonMatcher from '@astro-community/astro-embed-mastodon/matcher';
 const matchers = [
 	[blueskyMatcher, 'BlueskyPost'],
 	[gistMatcher, 'Gist'],
+	[tiktokMatcher, 'TikTok'],
 	[twitterMatcher, 'Tweet'],
 	[vimeoMatcher, 'Vimeo'],
 	[youtubeMatcher, 'YouTube'],

packages/astro-embed-tiktok/README.md

@@ -0,0 +1,5 @@
+# `@astro-community/astro-embed-tiktok`
+
+This package contains a component for embedding TikTok videos in Astro projects.
+
+[Read the `<TikTok>` component docs](https://astro-embed.netlify.app/components/tiktok/).