delucis · hfournier · Apr 21, 2026 · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/.changeset/two-islands-mix.md b/.changeset/two-islands-mix.md
@@ -0,0 +1,7 @@
+---
+'@astro-community/astro-embed-integration': minor
+'@astro-community/astro-embed-soundcloud': minor
+'astro-embed': minor
+---
+
+Adds SoundCloud astro-embed component
diff --git a/demo/package.json b/demo/package.json
@@ -14,6 +14,8 @@
     "@astro-community/astro-embed-gist": "workspace:*",
     "@astro-community/astro-embed-link-preview": "workspace:*",
     "@astro-community/astro-embed-mastodon": "workspace:*",
+    "@astro-community/astro-embed-soundcloud": "workspace:*",
+    "@astro-community/astro-embed-twitter": "workspace:*",
     "@astro-community/astro-embed-vimeo": "workspace:*",
     "@astro-community/astro-embed-youtube": "workspace:*",
     "@astrojs/mdx": "^5.0.4",

diff --git a/demo/src/pages/index.astro b/demo/src/pages/index.astro
@@ -36,6 +36,11 @@ import Base from '../layouts/Base.astro';
 		<li>
 			<a href="/gist"><code>&lt;Gist/&gt;</code> component examples</a>
 		</li>
+		<li>
+			<a href="/soundcloud"
+				><code>&lt;SoundCloud/&gt;</code> component examples</a
+			>
+		</li>
 	</ul>
 	<h2>Other examples</h2>
 	<ul>

diff --git a/demo/src/pages/integration.mdx b/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://soundcloud.com/rick-astley-official/never-gonna-give-you-up
diff --git a/demo/src/pages/soundcloud.astro b/demo/src/pages/soundcloud.astro
@@ -0,0 +1,64 @@
+---
+import { SoundCloud } from '@astro-community/astro-embed-soundcloud';
+import Base from '../layouts/Base.astro';
+---
+
+<Base title="SoundCloud component examples">
+	<h2>Track</h2>
+	<p>
+		<code
+			>&lt;SoundCloud
+			id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up"
+			/&gt;</code
+		>
+	</p>
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up"
+	/>
+
+	<h2>Playlist</h2>
+	<p>
+		<code
+			>&lt;SoundCloud
+			id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44"
+			playLabel="Play the greatest hits!" params="auto_play=false&start_track=1"
+			height="450px" embedType="visual" /&gt;</code
+		>
+	</p>
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44"
+		playLabel="Play the greatest hits!"
+		params="auto_play=false&start_track=1"
+		height="600px"
+		embedType="visual"
+	/>
+
+	<h2>Artist page</h2>
+	<p>
+		<code
+			>&lt;SoundCloud id="https://soundcloud.com/rick-astley-official"
+			height="450px" embedType="visual" posterQuality="max" /&gt;</code
+		>
+	</p>
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official"
+		height="450px"
+		embedType="visual"
+		posterQuality="max"
+	/>
+
+	<h2>With a custom poster and play label</h2>
+	<p>
+		<code
+			>&lt;SoundCloud
+			id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+			playLabel="Get Rick Rolled!"
+			poster="https://picsum.photos/id/158/1280/853" /&gt;</code
+		>
+	</p>
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+		playLabel="Get Rick Rolled!"
+		poster="https://picsum.photos/id/158/1280/853"
+	/>
+</Base>
diff --git a/demo/src/pages/twitter-with-js-dark.astro b/demo/src/pages/twitter-with-js-dark.astro
@@ -1,5 +1,5 @@
 ---
-import * as Component from 'astro-embed';
+import * as Component from '@astro-community/astro-embed-twitter';
 import Base from '../layouts/Base.astro';
 ---
 

diff --git a/demo/src/pages/twitter-with-js.astro b/demo/src/pages/twitter-with-js.astro
@@ -1,5 +1,5 @@
 ---
-import * as Component from 'astro-embed';
+import * as Component from '@astro-community/astro-embed-twitter';
 import Base from '../layouts/Base.astro';
 ---
 

diff --git a/demo/src/pages/twitter.astro b/demo/src/pages/twitter.astro
@@ -1,5 +1,5 @@
 ---
-import * as Component from 'astro-embed';
+import * as Component from '@astro-community/astro-embed-twitter';
 import Base from '../layouts/Base.astro';
 ---
 

diff --git a/docs/package.json b/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-soundcloud": "workspace:*",
     "@astro-community/astro-embed-twitter": "workspace:*",
     "@astro-community/astro-embed-vimeo": "workspace:*",
     "@astro-community/astro-embed-youtube": "workspace:*",

diff --git a/docs/src/content/docs/components/soundcloud.mdx b/docs/src/content/docs/components/soundcloud.mdx
@@ -0,0 +1,244 @@
+---
+title: SoundCloud
+description: Learn how to use the Astro Embed SoundCloud component to embed SoundCloud tracks, playlists, and artist pages in your website
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { SoundCloud } from 'astro-embed';
+
+The `<SoundCloud>` component generates an embed using a lightweight custom element that will load SoundCloud’s `<iframe>` only when a user clicks play.
+
+SoundCloud embeds will always require some JavaScript, but this is one of the most minimal and performant ways to embed the SoundCloud widget in your pages.
+
+## Usage
+
+<Tabs>
+<TabItem label="Astro" icon="astro">
+```astro
+---
+import { SoundCloud } from 'astro-embed';
+---
+
+<SoundCloud id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022" />
+```
+</TabItem>
+<TabItem label="MDX" icon="seti:markdown">
+```astro
+import { SoundCloud } from 'astro-embed';
+
+<SoundCloud id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022" />
+```
+</TabItem>
+</Tabs>
+
+The above code produces the following result:
+
+<div class="not-content">
+	<SoundCloud id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022" />
+</div>
+
+:::tip
+The SoundCloud URL format for a track is `https://soundcloud.com/[ARTIST]/[TRACK]`
+:::
+
+Alternatively, you can pass in a playlist URL:
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44"
+/>
+```
+
+The above code produces the following result:
+
+<div class="not-content">
+	<SoundCloud id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44" />
+</div>
+
+:::tip
+The SoundCloud URL format for a playlist is `https://soundcloud.com/[ARTIST]/sets/[PLAYLIST]`
+:::
+
+Lastly, you can pass in an artist URL:
+
+```astro
+<SoundCloud id="https://soundcloud.com/rick-astley-official" />
+```
+
+The above code produces the following result:
+
+<div class="not-content">
+	<SoundCloud id="https://soundcloud.com/rick-astley-official" />
+</div>
+
+:::tip
+The SoundCloud URL format for an artist is `https://soundcloud.com/[ARTIST]`
+:::
+
+## Optional props
+
+In addition to the required `id` prop, the following props are available to customise how the `<SoundCloud>` component renders:
+
+### `embedType`
+
+**Type:** `'classic' | 'visual'`  
+**Default:** `'classic'`
+
+Controls the SoundCloud player style. The `'classic'` mode renders a compact player at a fixed 166px height with the track artwork shown as an inline image. The `'visual'` mode renders a taller player with the track artwork displayed as a full background.
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+	embedType="visual"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+		embedType="visual"
+	/>
+</div>
+
+### `height`
+
+**Type:** `'300px' | '450px' | '600px'`  
+**Default:** `'300px'`
+
+Sets the height of the embed. This prop only applies when `embedType="visual"` — the classic player always renders at `166px` regardless of this value.
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+	embedType="visual"
+	height="450px"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+		embedType="visual"
+		height="450px"
+	/>
+</div>
+
+### `params`
+
+You can pass a `params` prop to set the [player parameters supported by the SoundCloud Widget](https://developers.soundcloud.com/docs/api/html5-widget). This looks like a series of URL search params.
+
+For example, the following `params` value sets the widget to auto-play track 2 (zero based) in the playlist:
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44"
+	params="auto_play=true&start_track=1"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/sets/the-greatest-hits-44"
+		params="auto_play=true&start_track=1"
+	/>
+</div>
+
+:::caution
+Using the `auto_play` parameter on a playlist will only work on the first few tracks in the playlist. This is because the remaining tracks are loaded lazily as the user interacts with the widget (scrolling them into view), and the SoundCloud Widget API only supports auto-playing tracks that have been loaded.
+:::
+
+### `playLabel`
+
+**Type:** `string`  
+**Default:** Track title and artist name from SoundCloud (e.g. `Play “Never Gonna Give You Up” by Rick Astley Official`), falling back to `'Play'` if unavailable.
+
+By default, the play button in the embed has an accessible label derived from the track metadata.
+If you want to customise this, for example to match the language of your website, you can set the `playLabel` prop:
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+	playLabel="Get Rick Rolled!"
+/>
+```
+
+### `poster`
+
+**Type:** `string`
+
+You can provide an alternative poster image by passing in a URL to the `poster` prop.
+
+For example, this is the same track as the first example, but with a custom poster image:
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+	playLabel="Get Rick Rolled!"
+	poster="https://picsum.photos/id/158/1280/853"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-2022"
+		playLabel="Get Rick Rolled!"
+		poster="https://picsum.photos/id/158/1280/853"
+	/>
+</div>
+
+### `posterQuality`
+
+**Type:** `'max' | 'high' | 'default' | 'low'`  
+**Default:** `'default'`
+
+When using the default SoundCloud poster image, set the `posterQuality` to change the size of the placeholder image.
+This can be useful if displaying the embed at large or very small sizes.
+
+| `posterQuality` | resolution |
+| --------------- | ---------- |
+| `'low'`         | 67px       |
+| `'default'`     | 200px      |
+| `'high'`        | 300px      |
+| `'max'`         | 500px      |
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official"
+	posterQuality="low"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official"
+		posterQuality="low"
+	/>
+</div>
+
+```astro
+<SoundCloud
+	id="https://soundcloud.com/rick-astley-official"
+	posterQuality="max"
+/>
+```
+
+<div class="not-content">
+	<SoundCloud
+		id="https://soundcloud.com/rick-astley-official"
+		posterQuality="max"
+	/>
+</div>
+
+## Standalone installation
+
+If you only need the `<SoundCloud>` 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-soundcloud" />
+
+The `<SoundCloud>` component can then be imported as:
+
+```js
+import { SoundCloud } from '@astro-community/astro-embed-soundcloud';
+```
diff --git a/docs/src/content/docs/getting-started.mdx b/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="SoundCloud" href="/components/soundcloud/" />
 	<LinkCard title="Twitter" href="/components/twitter/" />
 	<LinkCard title="Vimeo" href="/components/vimeo/" />
 	<LinkCard title="YouTube" href="/components/youtube/" />

diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -95,4 +95,12 @@ import { Icon, Card, CardGrid } from '@astrojs/starlight/components';
 
     </Card>
 
+    <Card title="SoundCloud" icon="seti:audio">
+
+    	Load SoundCloud embeds on user interaction for faster page loads.
+
+    	[SoundCloud docs](/components/soundcloud/)
+
+    </Card>
+
 </CardGrid>
Original file line number	Diff line number	Diff line change
Expand Up		@@ -29,3 +29,5 @@ https://astro.build/blog/welcome-world/
		https://mastodon.social/@sarah11918/112937553683639459

		https://gist.github.com/vasfvitor/1f995c47ee82ae652496622db1e678ea

		https://soundcloud.com/rick-astley-official/never-gonna-give-you-up