ArcGIS StoryMaps

Enrich your story maps with embedded web content

June 2020 update: In our latest release of ArcGIS StoryMaps we’ve added additional functionality to the embed block.  You can now get a better preview of what your embed will look like for readers on smaller screens within Embed properties. Another handy new option is the ability to see and copy the link or code for an embed if you need to re-use or adjust it.


A preview of the new embed capabilities



In my last post, I talked a bit about immersive blocks in ArcGIS StoryMaps, and how they’re powerful tools for getting readers engrossed in the story you’re telling. Well there’s another tool in your toolkit—or, more accurately, block on the block palette—that can help you create the kind of delightful and informative experiences your audience craves.

I’m talking about the embed block. With it, you can add all kinds of things to story maps: Tweets, SoundCloud tracks, Spotify playlists, interactive charts, ArcGIS apps… the list goes on and on. Embedding web content is a great way to add important context, crowdsourcing elements, or just an element of fun to your story, all of which help leave a lasting impression on anyone who comes across it.


An interactive chart is added to a story and hovered over to reveal values for each column
Adding embedded content to your story can provide delightful interaction for your readers.


The key to success with external web content, though, is creating a seamless, positive experience for your readers. That’s not always an easy task. Luckily, the StoryMaps builder does a lot of work behind the scenes to get the technical details right so you can focus on your narrative instead.

To help you become an embed master, let’s spend a little time going over all the nitty-gritty details. Those details include:

That might seem like a lot to cover, but I promise to keep it as brief as possible. I’ve also included a downloadable cheat sheet to help keep all this info fresh in your mind.

Ready? Let’s dig in.


The StoryMaps block palette with the embed block highlighted
Embedded web content can be easily added from the block palette.


Adding content with the embed block

Once you’re signed in to your account, have opened StoryMaps (at, and are in the builder, adding an embed is pretty easy. Simply open up the block palette with the green (+) and click Embed. Up pops a field where you add in your content by pasting in either a link or iframe code. Each way of adding content has its own perks, but I’ll get to those details in a bit. Either way, once you’ve pasted in the reference to your content, click Save and you’re off to the races.

Right away, the builder starts doing some behind-the-scenes decision-making to ensure that what you’re adding is delivered to your readers in the best way possible. This process takes into account a few different things, like the type of content being embedded, its appearance options, where in the story its being added, and how it will look on different screen sizes.


The modal with a single field in which to past a link or iframe code
Simply paste in a link or iframe code to bring external web content into your story.


The choices available to you as an author will vary depending on the combination of these variables, so let’s unpack each one a bit and then see how they all work together.


The four types of embedded web content

First things first, let’s look at the kinds of content you can embed in your story map. While potential web sources are many, their content can all be categorized into four core types of embeds:



These are images that are already hosted online, perhaps on Flickr or your own private server, and are added to your story via a link instead of being uploaded directly from your machine.



You know, like the ones available on YouTube, Vimeo, or Dailymotion. The story builder supports dozens of different video providers; add content from them to your story with a link or iframe code.


Rich embeds

Some trusted embed sources provide special information about their content, which the StoryMaps builder uses to optimize the display and reading experience for that embed. Twitter and SoundCloud are two examples, but there are loads more.

For the builder to gather that extra info, however, you’ll need to add this content with a link. (If the term OEmbed API means anything to you, that’s the kind of thing that’s at play here. If you read that and your response was “huh?” don’t worry, you can get by just fine without knowing what that means.)


Simple embeds

This category consists of content like ArcGIS apps, websites, and other full-page content that provides the basic embed info when referenced with a link. Non-video content you’ve added via iframe also falls into this bucket. If you’re embedding an ArcGIS app, be sure to share it publicly first.


The four types of embeds described in an infographic
There are four main types of embeds you can add to your story maps.


Ok, that’s pretty much it for embed types. Moving on…


The three different ways embedded content can be displayed

To help create a seamless reading experience, the story builder has three different ways it can display embedded content. Before we look at where these different views come into play, let’s first get an understanding of what each one is, and why it’s useful.



Cards appear as handy little link previews, pulling a title, description, and thumbnail from the embedded content. These cards are also themed, so they match the look and feel of your story.

Cards are nice way to include related resources in your story for the extra-curious individual without taking too much attention away from your main story. They’re also great for creating a list of recommending reading at the end of your story. Once clicked, the card simply opens that content in a new browser tab.

Any type of embed can be displayed as a card if you so choose—use the toolbar that appears above an embed to move between the card and live view. For some content a card may be the only available option, either for security reasons or because the content source prevents live embedding.

You can customize the appearance of a card through the embed properties panel (click the gear icon to open this up). There you can adjust the title and description for the card, upload a custom thumbnail, or reset all the information to what was originally supplied from the content’s source.


An embed card featuring the title, description and preview thumbnail of an Ops Dashboard
Cards are nice way to include related resources without taking too much attention away from your main story.


Live content

While cards simply provide a summary of the content they reference, live embeds integrate it right into your story. Readers can view the linked material alongside your text and other media, and can even interact with it all in the same space.

If the external web content you’re adding is pretty critical to your story—maybe it provides more nuance to your discussion or gives your readers a chance to explore some data you’re presenting—a live embed is likely your preferred choice.

Photo and video embeds will appear as live content automatically (though of course there’s no interactivity with a photo). Because of the behind-the-scenes optimization, rich embeds will also be added as live content.

Simple embeds will usually be added as a card at first, but will give you the option to switch to live content (minus the two exceptions noted above). When these embeds become live, you’ll notice that they require an initial click to enable interaction. That’s because the story builder doesn’t have enough information to ensure readers won’t get caught in any sticky situations—like stuck in a scroll within a scroll—if interaction is automatically enabled.


A live Operations Dashboard embed inserted into a story map
Live content appears directly in your story map, ready and waiting for your readers to engage with it.


Alternative media

While live content can be great, it doesn’t always provide the best experience on small screens and mobile devices. In these instances, the gist of an embed is conveyed through an image that you upload as alternative media. When you upload an alternative image, you also have the option to make it clickable, so that readers can tap on it to open that content in a new tab.

If you forget to upload an alternative image, the builder will provide a generic placeholder to alert your reader that there’s more to the story. This placeholder also includes a link to open the embedded content in a new tab.


A mobile phone preview showing an alternative image in place of a live embed
On mobile devices, a live embed in a sidecar media panel is replaced with an alternative image.


The three places you can add embeds (and why that matters)

Ok, time for a quick recap. So far we’ve established that you can add external web content to your story via a link or iframe code. This embedded content can fall into one of four categories (photo, video, rich, or simple), and there are three possible ways it might be displayed (card, live, or alternative media). Now let’s bring it all together by looking at where in your story maps you can add different types of embedded content, and how that placement will influence the way it appears.



Add embeds right into the body of your story, between paragraphs or other media, directly from the block palette. Photos, videos, rich embeds, and simple embeds can all be added here, and each one has the ability to be displayed as a card or live content.

Live embeds will also typically have the option to be displayed at small, medium, or large widths. The only exceptions to this are rich embeds like Tweets, where the builder has already determined the most ideal size based on the content being embedded.


A schematic of the sidecar block with the narrative panel on the left and the larger media panel on the right
A sidecar block consists of a narrow, scrolling narrative panel on one side and a large, fixed media panel on the other.


In a sidecar’s narrative panel

One of the immersive blocks in ArcGIS StoryMaps, sidecar has a long scrolling narrative panel that can include a variety of content. Open up the block palette and, sure enough, the embed block is right there waiting for you.

In the narrative panel, photos, videos, and rich embeds will appear as live content for desktop viewers (though you can change it to a card if you wish). Given the space constraints and limited information, simple embeds will always display as cards to ensure a smooth reading experience.


In a sidecar’s media panel

As part of the October 2019 release, sidecar’s media panel was enhanced to also include embedded content capabilities. Photo, video, and simple embeds are right at home here. Rich embeds are too, with a few exceptions. Tweets, for example, are a no-go for sidecar’s media panel (but they look great in the narrative panel).


A table that breaks down how different types of embeds appear on PCs depending on where they are placed in a story
The type of embed you add and where you add it will determine what appearance options are available to you.


How embedded content appears for mobile readers

While the scenarios above describe the embed appearance rules for desktop readers, things change a little on small screens. When it comes down to it, there’s just not enough space to elegantly present complicated interactives, so StoryMaps gives you some options, and makes some decisions behind the scenes, to optimize your audience’s experience. Here’s a little table to break down how each type of embed appears in each context on a mobile device:


A table that breaks down what embedded content will look like on a mobile device depending on type and placement
On mobile devices, embed display options are more restricted to ensure a seamless reading experience.


For rich or simple content that you’ve added to inline in your story, you can choose whether you’d like it to display as a card or an alternative image on small screens. To configure these settings, open up the properties panel for your embed, and adjust the card details as needed or upload an image. You can see how this will look for mobile readers by using the tablet and phone views in the story preview (access this in the story header).


A few tips to keep in mind

Now that you’ve got a sense of the fundamental workings of embedded content in story maps, let me leave you with some practical suggestions and insider tricks.


Link vs. iframe code

As I mentioned a while back, each way of adding embedded content comes with its own perks. The advantages of links are, of course, their ease of use, but also that they give the story builder the chance to detect those special optimization details that set rich embeds apart from simple embeds.

Iframes, meanwhile, give you a bit more flexibility in terms of display details. With iframes, you can add in URL parameters to adjust the look of your live content. A good example of this is using parameters to set a video to autoplay or loop.

You can also use iframe code to specify the width, height, or aspect ratio of your live content. If, for example, you’re embedding a survey into your story and want all fields visible at once, you could set the width to be 100 percent of the iframe container, and then set the height in pixels to ensure the whole form appears inline in your story.


An author pastes in a Vimeo iframe code and adds a URL parameter to the link
Adding embeds with iframe code allows you to adjust aspects of that content with URL parameters.


Use caution with embedded photos

You certainly have the option of linking to photos already hosted online, and sometimes that’s the only choice available. But ask anyone on the StoryMaps team, and we’ll tell you that, given the option, uploading your photos directly to your story is the recommended approach. The story builder has a few tricks up its digital sleeve to ensure that uploaded images are optimized for the size at which they appear in your story, but it can’t do this for linked images. That can mean longer load times for readers on mobile devices or slow internet connections.

Another risk, depending on your photo source, is the chance of a server crash or some other technical difficulty that renders your linked photos inaccessible. While popular third-party vendors like Flickr are generally reliable, that might not be the case for a small server with just a few images on it.


Don’t forget alternative text

When embedding content, be sure to open up the properties panel and add in a nice description in the alternative text field. This text is used by screen readers to help those with visual disabilities enjoy the full experience your content has to offer, making it an essential step in creating inclusive content. (Embed cards don’t require alternative text, since they already have a title and description attached to them.)


An author adds alternative text to their embed from the properties panel
Open the properties panel for a live embed to add alternative text (and media, if applicable).


Put the reader first

Finally, and most importantly, stay focused on your target audience. If you’re not sure about where to put an embed, or which appearance option is most appropriate, start by asking yourself “how essential is this for my reader, and what’s the most ideal way for them to engage with this content?” The answer to those questions will help you chart a clear path forward.

As promised, here’s a helpful cheat sheet should you need a quick reference or a refresher on everything we covered here. And if you have any reactions or ideas on how to take the embed experience even further, be sure to share them with us through our product feedback form. Now, go ahead and start putting all this new knowledge to use—happy embedding!


Note: The embed block is only available to those with subscription accounts for ArcGIS. If you don’t have a subscription account, but would like to give embeds a try, you can always sign up for a free 21-day trial of ArcGIS.


About the author

Upstate NY transplant. Content creator for Esri's StoryMaps team. Fascinated by how storytelling affects the human brain. Lover of conservation. Overly proud dog mom.


Leave a Reply

Please Login to comment
newest oldest
Mark Steger
Mark Steger

Hello and thanks for the good information on the embedding process. I have read the blog, but I am having trouble with getting a “guided tour” app put inside another App. I have practiced using another App I have to embed in the current app, but it is not seamless. I mean one has to click “Open” to bring up the App, instead of it just automatically opening and fitting into the original App.
I can send you some images if that would help to show you what I mean.

Paddy McCann
Paddy McCann

Hi Hannah, in your article you mention photographs are not interactive but I wonder if it is possible to embed 360 images via an embed code – e.g Google Tours

William Hackney
William Hackney


Good catch! Using an iframe code (which Google provides) to embed a 360-degree photo does indeed allow interactivity with that photo. See this demo story.

Liubomyr Oliinyk
Liubomyr Oliinyk

Dear Hannah,
Any chance you can help me with an embedded vimeo video? I’ve embedded it into a sidecar container with an autoplay function
. And it works perfectly fine in the editing mode – the video just starts playing automatically. However, the autoplay is not working in a published story. When I scroll to a point when the video appears there is no autoplay action and I need to press a play button in order to make it play. Any chance this can be fixed?
Thank you!

Mira Lindgren
Mira Lindgren

Hello Hannah!
Thank you for an excellent post.

I work as a tech support analyst @ Esri Sweden.

I have a customer who used this technique to embed photos and show them as cards.
But after the latest update of StoryMaps, it seems like this is not an option any more 🙁
It seems like StoryMaps recognize the URL as an image and therefor does not present the same functions as when embedding other content.
The customer really want their image to be shown as a card, but we can not find a way.
Do you have any suggestions for a solution?

Next Article

ArcGIS Maps SDK Beta 2 is available!

Read this article