Percy specific CSS


Covered in this doc

  • How to apply Percy-specific CSS to ignore areas from being rendered by Percy
  • Percy-specific CSS for Storybook

Percy provides a powerful way to take control of rendering to do whatever you want -- ignore regions, stabilize dynamic elements, etc.

Percy's way to do this is something we call "Percy-specific CSS", which is only applied in the Percy rendering environment. You can use any CSS and it'll only be rendered in Percy's rendering environment. This can be very helpful for ignoring regions, 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.

Snapshot options / SDK options

You can apply Percy specific CSS in most SDKs without editing your site or applications CSS files. This can be done by passing a percyCSS option via the options object. For example:

await percySnapshot('Home page', { 
  percyCSS: `iframe { display: none; }` 

You can also configure global Percy CSS via the .percy.yml file:

version: 1
  percy-css: | 
    iframe { 
      display: none; 


Percy CSS does not change specificity

Percy CSS is appended to the bottom of the </body> tag to help with order, but it's likely you will need to out-specify your applications CSS (with !important or otherwise)

Percy CSS @media query

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 CSS @media query for Storybook

When using Storybook, you can provide percyCSS along with other common options either with story percy parameters or using a Percy config file.

In order to use the Percy CSS media query with Storybook snapshots, you need to modify the Storybook's preview-head.html file to serve static CSS overrides. This is because Percy uses a content-type-based system to apply styles to HTML and CSS files, and CSS-in-JS breaks this paradigm. 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="" alt="Bom dia"/>

You can see a complete example of this technique in this pull request.

Debugging Storybook 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.