Bringing interactive examples to MDN

“This is scoped to be a pretty small change.”me, January 2017.

Over the last year and a bit, the MDN Web Docs team has been designing, building, and implementing interactive examples for our reference pages. The motivation for this was the idea that MDN should do more to help “action-oriented” users: people who like to learn by seeing and playing around with example code, rather than by reading about it.

We’ve just finished adding interactive examples for the JavaScript and CSS reference pages. This post looks back at the project to see how we got here and what we learned on the way.

First prototypes

The project was first outlined in the MDN product strategy, published at the end of 2016. We discussed some ideas on the MDN mailing list, and developed some prototypes.

The JS editor looked like this:

Early prototype of JavaScript editor

The CSS editor looked like this:

Screenshot of CSS editor after first user testing

We wanted the examples – especially the CSS examples – to show users the different kinds of syntax that an item could accept. In the early prototypes, we did this using autocomplete. When the user deleted the value assigned to a CSS property, we showed an autocomplete popup listing different syntax variations:

First round of user testing

In March 2017 Kadir Topal and I attended the first round of user testing, which was run by Mark Hurst. We learned a great deal about user testing, about our prototypes, and about what users wanted to see. We learned that users wanted examples and appreciated them being quick to find. Users liked interactive examples, too.

But autocomplete was not successful as a way to show different syntax forms. It just wasn’t discoverable, and even people who did accidentally trigger it didn’t seem to understand what it was for.

Especially for CSS, though, we still wanted a way to show readers the different kinds of syntax that an item could accept. For the CSS pages, we already had a code block in the pages that lists syntax options, like this:

transform: matrix(1.0, 2.0, 3.0, 4.0, 5.0, 6.0);
transform: translate(12px, 50%);
transform: translateX(2em);
transform: translateY(3in);
transform: scale(2, 0.5);
transform: scaleX(2);
transform: scaleY(0.5);
transform: rotate(0.5turn);
transform: skew(30deg, 20deg);

One user interaction we saw, that we really liked, was when readers would copy lines from this code block into the editor, to see the effect. So we thought of combining this block with the editor.

In this next version, you can select a line from the block underneath, and the style is applied to the element above:

Looking back at this prototype now, two things stand out: first, the basic interaction model that we would eventually ship was already in place. Second, although the changes we would make after this point were essentially about styling, they had a dramatic effect on the editor’s usability.

Building a foundation

After that not much happened for a while, because our front-end developers were busy on other projects. Stephanie Hobson helped improve the editor design, but she was also engaged in a full-scale redesign of MDN’s article pages. In June Schalk Neethling joined the team, dedicated to this project. He built a solid foundation for the editors and a whole new contribution workflow. This would be the basis of the final implementation.

In this implementation, interactive examples are maintained in the interactive-examples GitHub repository. Once an interactive example is merged to the repo, it is built automatically as a standalone web page which is then served from the “” domain. To include the example in an MDN page, we then embed the interactive example’s document using an iframe.

UX work and more user testing

At the end of June, we showed the editors to Jen Simmons and Dan Callahan, who provided us some very useful feedback. The JavaScript editor seemed pretty good, but we were still having problems with the CSS editor. At this point it looked like this:

Early prototype of CSS editor in June 2017

People didn’t understand that they could edit the CSS, or even that the left-hand side consisted of a list of separate choices rather than a single block.

Stephanie and Schalk did a full UX review of both editors. We also had an independent UX review from Julia Lopez-Mobilia from The Brigade. After all this work, the editors looked like this in static screenshots:

JS editor for the final user test

CSS editor for the final user test

Then we had another round of user testing. This time we ran remote user tests over video, with participants recruited through MDN itself. This gave us a tight feedback loop for the editors: we could quickly make and test adjustments based on user feedback.

This time user testing was very positive, and we decided we were ready for beta.

Beta testing

The beta test started at the end of August and lasted for two weeks. We embedded editors on three JavaScript and three CSS pages, added a survey, and asked for feedback. Danielle Vincent mentioned it in the Mozilla Developer Newsletter, which drove thousands of people to our Discourse announcement post.

Feedback was overwhelmingly positive: 156/159 people who took the survey voted to see the editor on more pages, and the free-form text feedback was very encouraging. We were confident that we had a good UX.

JavaScript examples and page load optimization

Now we had an editor but very few actual examples. We asked Mark Boas to write examples for the JavaScript reference pages, and in a couple of months he had written about 400 beautiful concise examples.

See the example for Array.slice().

We had another problem, though: the editors regressed page load time too much. Schalk and Stephanie worked to wring every last millisecond of performance optimization out of the architecture, and finally, in December 2017, we decided to ship.

We have some extra tricks we plan to implement this year to continue improving page load performance, the fact is we’re still not happy with current performance on interactive pages.

CSS examples

In the first three weeks of 2018, Schalk and I updated 400 JavaScript pages to include Mark’s examples, and then we turned to getting examples written for the CSS pages.

We asked for help, Jen Simmons tweeted about it, and three weeks later our community had contributed more than 150 examples, with over a hundred coming from a single volunteer, mfluehr.

See the example for rotate3d().

After that Rachel Andrew and Daniel Beck started working with us, and they took care of the rest.

See the example for clip-path.

What’s next?

Right now we’re working on implementing interactive examples for the HTML reference. We have just finished a round of user testing, with encouraging results, and hope to start writing examples soon.

As I hope this post makes clear, this project has been shaped by many people contributing a wide range of different skills. If you’d like to help out with the project, please check out the interactive-examples repo and the MDN Discourse forum, where we regularly announce updates.

About Will Bamberg

Will is a technical writer working on MDN.

More articles by Will Bamberg…


  1. Mark

    You could consider using a “sandbox=allow-scripts” attribute on each iframe to have an extra set of restrictions for the content in the iframe.

    March 20th, 2018 at 08:57

    1. Schalk Neethling

      Hey Mark,

      Thanks for your comment. Are you referring to the embedded examples on this post, or when embedded on MDN?

      March 20th, 2018 at 09:54

  2. Christoph

    I have loved the interactive examples since I first discovered them on MDN – great work!

    One minor nitpick: I still only discovered by accident that I could edit the examples as well as selecting one – however unfortunately I don’t have a suggestion how you could make that clearer (except maybe by turning off the syntax highlighting for the selected example so it looks more like a textarea – but that has its own drawbacks obviously).


    March 21st, 2018 at 00:16

    1. Will Bamberg

      Thanks Christoph, I’m very glad you like them. You’re not the only person who didn’t find it obvious that the CSS examples were editable. This is a thing we still don’t have a good answer for.

      I don’t think it matters *that* much with the CSS examples, since even just selecting different values is quite illustrative, and eventually, I think, people will usually understand that the options are editable. But we would like this to work better. One very simple thing we will do is: place the cursor at the end of the choice rather than the start, so it’s more obvious and, well, inviting.

      But we’re definitely open to improvement suggestions in this area!

      March 21st, 2018 at 06:55

      1. Kshitij Chawla

        A prominent, blinking cursor on the text, is a strong indicator that the text is editable. Can that be done? Maybe the smaller, thicker, horizontal one, blinking after the last character.

        Is it not feasible to mention ‘Click on a code block to run that line’ or something to that effect, under, for example ‘CSS Demo: Transform’ ?
        Or a small Run button next to each block?

        March 22nd, 2018 at 08:22

        1. Will Bamberg

          > A prominent, blinking cursor on the text,
          > is a strong indicator that the text is editable.
          > Can that be done?

          Yes, I think a cursor is a good way to indicate this. But we should also consider that many people aren’t going to be interested in editing the examples, and we don’t want any indicator to be annoying or distracting for these people. So there’s a balance we need to get right here.

          > Is it not feasible to mention
          > ‘Click on a code block to run that line’
          > or something to that effect, under, for example
          > ‘CSS Demo: Transform’ ?
          > Or a small Run button next to each block?

          People seem to understand easily that the blocks are _selectable_, just not that they are _editable_.

          March 22nd, 2018 at 10:08

      2. kshitij Chawla

        Instead of waiting for a click on the code line, if merely mousing over them will run it, will that make it more ‘inadvertently’ discoverable?

        Or a quick animation indicating the click/touch to run aspect on First paint.

        March 22nd, 2018 at 08:27

      3. Timon

        Hey Will!

        My suggestion would be to leave the examples themselves un-editable, and make the last option a field with just `${attribute}:`, and showing an input field next to the attribute text. Like this:

        * transform: skew (180deg);
        * transform: rotate(90deg);
        * transform:

        It obviously wouldn’t look as nice as it does now, but it would be really clear.

        March 22nd, 2018 at 08:41

        1. Will Bamberg

          This is a very interesting suggestion! I think we might look at this in the future, but it would be quite a big change to the UI, so we’d need to test it thoroughly :).

          March 22nd, 2018 at 14:57

      4. James

        One possibility is to show an “EDIT” or “Try it Myself” (or any other text to this effect) button next to the “RESET” button. On click, it then opens an extra line below the examples for users to edit and execute.

        Most users looking for a quick reference or examples won’t bother using the Edit function. However for those who desires it, since it’s initiated by users, it will be prominent with a clear purpose.

        March 22nd, 2018 at 16:47

  3. Joe Z

    MDN has become my go-to reference. Any hope for the poor, benighted SVG documentation to get the same treatment?

    March 22nd, 2018 at 07:50

    1. Will Bamberg

      You’re in luck!

      Jeremie and I talked last week about this, and we both thought SVG would be a great candidate for interactive examples. I’m pretty sure Jeremie will continue to share his progress and plans on

      March 22nd, 2018 at 08:24

  4. Will Fastie

    >>> we’re still not happy with current performance on interactive pages

    It’s only in recent months that I’ve realized what a treasure MDN is. I wish I knew enough to help. I may even retire my VisiBone book!

    So I don’t care at all about page performance. The value is in the content, not the speed. I realize you may have a practical or financial interest in keeping things light and fast, but from the end user perspective any wait is worth the education.

    March 22nd, 2018 at 08:41

    1. Will Bamberg

      That’s very nice to hear :).

      We do still care about performance. Among other reasons, poor performance hurts search engine ranking, which makes it much harder for people to find our content. Also, although performance is OK in North America, it’s considerably worse in many other parts of the world, and we’d like to fix that.

      March 22nd, 2018 at 15:01

  5. Rich

    I’ve learned so much reading Mozilla docs; in fact, it’s the way I’ve learned javascript!
    So, these interactives are just more icing on an already excellent cake!

    Even better, the editor is accessible via screen reader, which really surprised me!
    Now if that same editor could be used in the Firefox dev tools, then it might be possible to make the debugger accessible, which would be absolutely wonderful! I hope this becomes a priority; it would speed up JS development via screen reader drammatically!

    Thanx Mozilla!
    — Rich

    March 22nd, 2018 at 09:11

    1. Marijn

      > Now if that same editor could be used in the Firefox dev tools

      It appears to be a kludge of a few hundred lines ( which is very easy to break (try dragging some HTML from the surrounding page into it, for example).

      The good news is that there’s going to be a push ( happening this year to make CodeMirror, the editor in devtools, accessible.

      March 22nd, 2018 at 09:57

      1. Will Bamberg

        Of course we use CodeMirror for the JavaScript interactive examples, and will use it for the HTML ones that are in development. It’s a fantastic piece of software.

        It seemed like overkill to embed 6 CodeMirror instances in each CSS example. It would definitely provide a more robust editor than what we currently have, though.

        March 23rd, 2018 at 06:24

  6. Russell Beattie

    I was just using MDN to look up some CSS transform info the other day and used the interactive examples, so my experience as a new user is fresh in my mind. My thought is that some examples are ambiguous and need more context as to what’s happening for someone not familiar. It would be nice to be able to have a link to the entire code the example is using so you can see the line of CSS used in-place. The examples are nice to show what happens, but without the surrounding code, it can be hard to work out how to use that specific function/command/etc.

    March 22nd, 2018 at 12:42

    1. Will Bamberg

      In their current form the interactive examples are intentionally limited in scope to keep them simple to use and concise. They can introduce you to the property, or give you a reminder of its syntax if you forgot, but very often you’ll have to consult the docs at a deeper level too.

      So for the time being at least I think these examples complement, rather than replace, the existing “live samples” (e.g. – the live samples show the entire code, but are much less concise.

      Having said that, your idea of combining the two sorts of example with a link to the entire example is a very interesting idea for the future!

      March 23rd, 2018 at 06:16

  7. David Barth

    Great idea.
    Would like to see a reading list and tutorial reference for newbies like me.

    A lso I am not aware of a specific site (URL) I could go to as a start

    March 22nd, 2018 at 18:57

    1. Will Bamberg

      I’m biased of course, but the Learning Area on MDN is a great place to get started with web development:

      March 22nd, 2018 at 21:31

  8. David Nobre

    But the perspective is wrong.

    March 23rd, 2018 at 11:08

    1. Will Bamberg

      Thanks for pointing this out! If you could, please file a bug at, it will be much easier to track there than in blog comments.

      March 23rd, 2018 at 11:43

  9. Jeromie Kirchoff

    Hi! Great article big fan. I have taught myself code by reverse-engineering existing code to understand its functionality when there is “no documentation”, you know how it goes at companies.

    So, my thoughts on how to fix the text edit ability not being so obvious.

    How about a simple alert message “Did you know you can edit this?!?”

    Also, add some suggestions for the edits… Maybe a different page like a wiki? Idk.

    Anyway, just make it so the alert happens when the user clicks for the first time on the page examples.

    Have a great year all!

    March 27th, 2018 at 18:42

Comments are closed for this article.