Embedding Methods
There are three primary ways to embed Web Stories:- Web Stories Embed Block - Recommended for Gutenberg editor
- Shortcode - Compatible with classic editor and widgets
- Custom Code - For theme developers and custom implementations
Using the Embed Block
Adding a Story via Block Editor
- Edit a post or page in the WordPress block editor
- Click the + button to add a new block
- Search for “Web Stories Embed”
- Select the block to insert it
- Choose a story from the dropdown or enter a story URL
- Customize display settings in the block sidebar
- Publish or update your post
The Web Stories Embed block is registered automatically and appears in the block inserter under the “Web Stories” category.
Block Settings
Customize embed appearance using block settings:Display Options
Display Options
- Width: Story player width (default: 360px)
- Height: Story player height (default: 600px)
- Alignment: Left, center, right, wide, or full width
- Poster Image: Custom poster image URL
Example Block Output
The block renders using<amp-story-player> (from includes/Renderer/Story/Embed.php:87-191):
Using the Shortcode
The[web_stories_embed] shortcode provides a flexible way to embed stories in any content area (from includes/Shortcode/Embed_Shortcode.php:40-72).
Basic Shortcode Usage
Shortcode Parameters
| Parameter | Description | Default | Example |
|---|---|---|---|
url | Story URL (required) | - | url="https://example.com/story/" |
title | Story title | ”Web Story” | title="My Amazing Story" |
poster | Poster image URL | Auto-detected | poster="https://example.com/poster.jpg" |
width | Player width in pixels | 360 | width="400" |
height | Player height in pixels | 600 | height="640" |
align | Alignment | none | align="center" |
Shortcode Examples
Basic Embed
Basic Embed
Custom Size
Custom Size
With Custom Poster
With Custom Poster
Centered Alignment
Centered Alignment
Using Shortcode in Widgets
You can add stories to widget areas:- Go to Appearance > Widgets
- Add a Shortcode widget
- Paste your shortcode
- Save the widget
Custom PHP Implementation
For theme developers, you can embed stories programmatically using the embed renderer.Using the Embed Renderer
Template Integration
Embed stories in theme templates:Custom Query Loop
Display multiple stories:Embed Rendering Modes
The plugin supports different rendering modes based on context (fromincludes/Embed_Base.php:151-161):
Standard Embed Mode
Default mode using<amp-story-player>:
- Interactive story player
- Supports navigation and gestures
- Loads story content dynamically
- Best for most use cases
Preview Mode
Single-page preview using static image:- Set
previewOnlyattribute totrue - Shows only first page as static image
- Useful for story galleries or archives
- Reduces page weight
Feed Mode
Simplified rendering for RSS feeds:- Automatically detected in feed context
- Renders as static image with link
- Ensures feed compatibility
- Fallback for feed readers
Embedding External Stories
You can embed stories from other websites that support Web Stories:External stories must be valid AMP stories and publicly accessible for embedding to work correctly.
Responsive Embeds
Embeds automatically adapt to container width while maintaining aspect ratio:Customizing Embed Styles
Default Attributes Filter
Customize default embed settings:Custom CSS
Add custom styles to embedded stories:AMP Compatibility
Embeds work on both AMP and non-AMP pages:Non-AMP Pages
Uses<amp-story-player> web component:
- Requires JavaScript
- Full interactive features
- Lazy loads story content
- Better performance
AMP Pages
Uses AMP-compatible<amp-story-player> with restrictions:
- Includes
layout="intrinsic"attribute - Works with AMP validation
- Compatible with AMP caching
- Optimized for AMP performance
includes/Renderer/Story/Embed.php:114-153).
Performance Considerations
Lazy Loading
Lazy Loading
- Poster images use
loading="lazy"attribute - Story content loads on interaction
- Minimal impact on initial page load
- Optimized for mobile networks
Asset Management
Asset Management
- Story player assets load only when needed
- CSS automatically enqueued with embed
- JavaScript deferred for better performance
- No dependency on external CDNs
Caching
Caching
- Embed markup is fully cacheable
- Compatible with page caching plugins
- Supports CDN caching
- No dynamic content in embed HTML
Troubleshooting
Story player not appearing
Story player not appearing
- Check browser console for JavaScript errors
- Verify story URL is correct and accessible
- Ensure AMP Story Player assets are loading
- Check for JavaScript conflicts with other plugins
- Test with default theme to rule out theme issues
Embed block not showing in editor
Embed block not showing in editor
- Clear browser cache and reload editor
- Check that plugin is active and up to date
- Verify no JavaScript errors in browser console
- Try deactivating other plugins temporarily
- Ensure WordPress and Gutenberg are up to date
Incorrect embed sizing
Incorrect embed sizing
- Check width/height attributes in shortcode or block
- Verify CSS isn’t overriding embed dimensions
- Use browser DevTools to inspect computed styles
- Test with default theme to check for theme conflicts
- Ensure embed container has sufficient space
Shortcode rendering as plain text
Shortcode rendering as plain text
- Verify shortcode syntax is correct
- Check that plugin is active
- Ensure content area supports shortcodes
- Try using
do_shortcode()in theme templates - Check for shortcode conflicts with other plugins
Best Practices
Placement
- Place embeds in prominent content areas
- Avoid embedding too many stories on one page
- Consider story relevance to surrounding content
- Use preview mode for story galleries
Performance
- Limit number of embeds per page (3-5 maximum)
- Use lazy loading for below-the-fold embeds
- Optimize poster images for fast loading
- Consider preview mode for story archives
User Experience
- Ensure adequate spacing around embeds
- Provide context about story content
- Use descriptive titles and alt text
- Test on mobile devices