Skip to main content
Web Stories can be embedded anywhere on your WordPress site using the dedicated embed block, shortcode, or custom PHP code.

Embedding Methods

There are three primary ways to embed Web Stories:
  1. Web Stories Embed Block - Recommended for Gutenberg editor
  2. Shortcode - Compatible with classic editor and widgets
  3. Custom Code - For theme developers and custom implementations

Using the Embed Block

Adding a Story via Block Editor

  1. Edit a post or page in the WordPress block editor
  2. Click the + button to add a new block
  3. Search for “Web Stories Embed”
  4. Select the block to insert it
  5. Choose a story from the dropdown or enter a story URL
  6. Customize display settings in the block sidebar
  7. 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:
  • 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):
<div class="wp-block-web-stories-embed web-stories-embed aligncenter">
  <div class="wp-block-embed__wrapper" style="--aspect-ratio: 0.6; --width: 360px; --height: 600px">
    <amp-story-player>
      <a href="https://example.com/web-stories/my-story/">
        <img
          src="https://example.com/poster.jpg"
          width="360"
          height="600"
          alt="Story Title"
          loading="lazy"
          decoding="async"
          data-amp-story-player-poster-img
        />
      </a>
    </amp-story-player>
  </div>
</div>

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

[web_stories_embed url="https://example.com/web-stories/my-story/"]

Shortcode Parameters

ParameterDescriptionDefaultExample
urlStory URL (required)-url="https://example.com/story/"
titleStory title”Web Story”title="My Amazing Story"
posterPoster image URLAuto-detectedposter="https://example.com/poster.jpg"
widthPlayer width in pixels360width="400"
heightPlayer height in pixels600height="640"
alignAlignmentnonealign="center"

Shortcode Examples

[web_stories_embed url="https://example.com/web-stories/travel-guide/"]
[web_stories_embed 
  url="https://example.com/web-stories/recipe/" 
  width="400" 
  height="640"
]
[web_stories_embed 
  url="https://example.com/web-stories/product-launch/" 
  poster="https://example.com/custom-poster.jpg"
  title="New Product Launch"
]
[web_stories_embed 
  url="https://example.com/web-stories/news/" 
  align="center"
]

Using Shortcode in Widgets

You can add stories to widget areas:
  1. Go to Appearance > Widgets
  2. Add a Shortcode widget
  3. Paste your shortcode
  4. Save the widget
Ensure your theme supports the Shortcode widget or use a text widget with shortcode support enabled.

Custom PHP Implementation

For theme developers, you can embed stories programmatically using the embed renderer.

Using the Embed Renderer

<?php
use Google\Web_Stories\Model\Story;
use Google\Web_Stories\Renderer\Story\Embed;

// Get story by ID or URL
$story = new Story();
$story->load_from_post(get_post(123));

// Configure embed attributes
$attributes = [
    'width'  => 360,
    'height' => 600,
    'align'  => 'center',
];

// Render the embed
$embed = new Embed($story, $assets, $context);
echo $embed->render($attributes);
?>

Template Integration

Embed stories in theme templates:
<?php
// In your theme template file (e.g., single.php, page.php)
if (function_exists('web_stories_embed_shortcode')) {
    echo do_shortcode('[web_stories_embed url="' . esc_url($story_url) . '"]');
}
?>

Custom Query Loop

Display multiple stories:
<?php
$args = [
    'post_type'      => 'web-story',
    'posts_per_page' => 3,
    'orderby'        => 'date',
    'order'          => 'DESC',
];

$stories = new WP_Query($args);

if ($stories->have_posts()) {
    while ($stories->have_posts()) {
        $stories->the_post();
        echo do_shortcode(
            sprintf(
                '[web_stories_embed url="%s" title="%s"]',
                esc_url(get_permalink()),
                esc_attr(get_the_title())
            )
        );
    }
    wp_reset_postdata();
}
?>

Embed Rendering Modes

The plugin supports different rendering modes based on context (from includes/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 previewOnly attribute to true
  • Shows only first page as static image
  • Useful for story galleries or archives
  • Reduces page weight
$attributes = [
    'previewOnly' => true,
    'width'       => 360,
    'height'      => 600,
];

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:
[web_stories_embed 
  url="https://stories.google.com/stories/example-story" 
  title="Example Story"
]
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:
.web-stories-embed {
  --aspect-ratio: 0.6; /* width / height */
  --width: 360px;
  --height: 600px;
}

.wp-block-embed__wrapper {
  max-width: var(--width);
  aspect-ratio: var(--aspect-ratio);
}
The embed maintains the correct 9:16 vertical aspect ratio across all screen sizes.

Customizing Embed Styles

Default Attributes Filter

Customize default embed settings:
add_filter('web_stories_embed_default_attributes', function($attrs) {
    $attrs['width']  = 400;  // Wider default
    $attrs['height'] = 640;  // Taller default
    $attrs['align']  = 'center';  // Center by default
    
    return $attrs;
});

Custom CSS

Add custom styles to embedded stories:
/* Customize embed container */
.web-stories-embed {
    margin: 2rem auto;
    max-width: 100%;
}

/* Add shadow effect */
.web-stories-embed amp-story-player {
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
    border-radius: 8px;
    overflow: hidden;
}

/* Adjust spacing */
.wp-block-web-stories-embed {
    padding: 1rem 0;
}

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
The plugin automatically detects the page type and renders the appropriate markup (see includes/Renderer/Story/Embed.php:114-153).

Performance Considerations

  • Poster images use loading="lazy" attribute
  • Story content loads on interaction
  • Minimal impact on initial page load
  • Optimized for mobile networks
  • Story player assets load only when needed
  • CSS automatically enqueued with embed
  • JavaScript deferred for better performance
  • No dependency on external CDNs
  • Embed markup is fully cacheable
  • Compatible with page caching plugins
  • Supports CDN caching
  • No dynamic content in embed HTML

Troubleshooting

  1. Check browser console for JavaScript errors
  2. Verify story URL is correct and accessible
  3. Ensure AMP Story Player assets are loading
  4. Check for JavaScript conflicts with other plugins
  5. Test with default theme to rule out theme issues
  1. Clear browser cache and reload editor
  2. Check that plugin is active and up to date
  3. Verify no JavaScript errors in browser console
  4. Try deactivating other plugins temporarily
  5. Ensure WordPress and Gutenberg are up to date
  1. Check width/height attributes in shortcode or block
  2. Verify CSS isn’t overriding embed dimensions
  3. Use browser DevTools to inspect computed styles
  4. Test with default theme to check for theme conflicts
  5. Ensure embed container has sufficient space
  1. Verify shortcode syntax is correct
  2. Check that plugin is active
  3. Ensure content area supports shortcodes
  4. Try using do_shortcode() in theme templates
  5. 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

Build docs developers (and LLMs) love