Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2!

Percy specific CSS

Stabilizing snapshots with Percy specific CSS

Sometimes you'll want to apply CSS to a page only when it's rendered in Percy's rendering environment. This can be very helpful for hiding areas that produce false-positive visual diffs, or when you'd like more specific control over the state of UI elements like visualizations and animations.

You can do so using the @media only percy CSS media query. CSS that is nested under this media query will only apply in Percy and will not affect your normal pages outside of Percy.


For example, you might have an element that renders differently each time and you want Percy to ignore that element. You can use Percy specific styles to achieve this.

Let's say you want to apply a hide-in-percy class to elements you want hidden in Percy. Here's how you can do that:

@media only percy {
  .hide-in-percy {
    visibility: hidden;

And your page would have HTML like this:

<div class="hide-in-percy">an element we know we want to ignore in visual tests</div>

The class names don't have to be Percy specific, you can put any normal CSS selectors and rules that you want in the media query and they will only be applied when rendering in Percy.

Percy-Specific CSS for Storybook

When using Storybook, you can use a similar, but slightly modified approach. Percy uses a content-type -based system to apply styles to HTML and CSS files, and CSS-in-JS breaks this paradigm.

In order to render Percy-specific styles for Storybook snapshots, you need to modify the Storybook's preview-head.html file to serve static CSS overrides. See the storybook documentation for how to add custom head tags to your project. Here's an example of a preview-head.html file that includes a default stylesheet, and adds a .hide-in-percy class styling:

<link rel="stylesheet" type="text/css" href="default.css">

@media only percy {
  .hide-in-percy {
    visibility: hidden;

You would then add a percy-specific className attribute to your component the example show className as per React syntax:

<div className="hide-in-percy">
  <img src="https://i.giphy.com/bcKmIWkUMCjVm.gif" alt="Bom dia"/>

You can see a complete example of this technique in this Pull Request.

Debugging Percy-Specific CSS

It may be helpful to render your storybook project to a static build in order to debug any changes. See the Storybook documentation for details on how to do this. Once you have generated a static version of your app, you can remove the surrounding @media only percy block in the markup to preview your Percy-specific styles in your browser.

As always, if you have questions, we encourage you to reach out to us for support.