Check for Chromatic

The isChromatic method allows you to control how your Storybook tests run in the Chromatic environment. Use it to configure what features and behaviors are available when testing.

Global configuration

If you’re working with a framework-specific feature or library that prevents it from running in your tests, you can adjust your configuration file (i.e.,.storybook/preview.js|ts) and add the isChromatic helper function, enabling you to configure how your tests run in Chromatic across your entire project. For example:

import isChromatic from "chromatic/isChromatic";

// Disables animation in Chromatic
if (isChromatic()) {
  // The exact method depends on your animation techniques.
  AnimationLibrary.disable = true;
}

// Disables lazyloading
LazyLoad.disabled = isChromatic();

Test-specific configuration

If you need more granular control over how your tests run in Chromatic, you can add the isChromatic helper function and set the available options accordingly. For example:

// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";

import isChromatic from "chromatic/isChromatic";

import { MyComponent } from "./MyComponent";

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  title: "MyComponent",
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const Default: Story = {
  args: {
    label: isChromatic() ? "I'm in Chromatic" : "Not in Chromatic",
  },
};

Environment variables

If you’re running Storybook tests with version 7.6 or higher, you can also use the IS_CHROMATIC environment variable to control how your tests run in Chromatic. To do so, adjust your chromatic script in your package.json file to include the environment variable as follows:

{
  "scripts": {
    "chromatic": "IS_CHROMATIC=true chromatic"
 }
}

Then, in your tests, you can check for the IS_CHROMATIC environment variable and set the available options accordingly (e.g., args, parameters).

// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";

import { MyComponent } from "./MyComponent";

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  title: "MyComponent",
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const Default: Story = {
  args: {
    label: process.env.IS_CHROMATIC ? "I'm in Chromatic" : "Not in Chromatic",
  },
};

Using isChromatic in your application

Under specific circumstances, your components may require different behavior when running in Chromatic (e.g., disabling animations, lazy loading). In these cases, you can use isChromatic directly in your components to control their behavior when tested. However, this approach can lead to unexpected behavior. We recommend using isChromatic only in your tests or via configuration to ensure a clear separation of concerns and make the code agnostic to the environment in which it’s running.