UI Review

UI Tests protect you from accidental regressions. But, before you ship, you’ll want to invite developers, designers, and PMs to review the UI, discuss changes, and get the final sign off.

UI Review creates a changeset of the exact visual changes introduced on a new branch. You assign reviewers who can comment and request tweaks on changes that aren’t quite right. Think of it like a code review, but for your UI.

Previously, this feature was only available for accounts that linked projects with GitHub, GitLab, or Bitbucket. We are now making the feature available to all of our customers, for both linked and unlinked projects.

UI Review


Linked projects

Enable UI Review for your project on the Manage screen.

Enable UI Review

Once enabled, visit the Reviews tab in the web app sidebar. There you’ll be prompted to install the GitHub app or webhooks for GitLab/Bitbucket.

Note: For linked projects, you must set up CI so that Chromatic is able to run builds for each commit on the PR branch.

Unlinked projects

For any existing projects not already taking advantage of UI Review, you can enable it on the project’s Manage screen (see above). Any new projects will automatically have UI Review enabled.

Create a Review

Linked projects

If you have linked your project to a repository on GitHub, Bitbucket, or GitLab, enabled UI Review, and set up CI, Chromatic will run builds automatically for each commit on a PR branch. Nothing else is needed from you to create a Review.

Unlinked projects

Navigate to the Reviews link in the sidebar and click the “Create Review” button.

Create Review

  • Select the base branch, which is the branch that’s used as the source of truth for comparison.
  • Select the head branch, which is the branch that has the changes that you want to compare with the source of truth. Then, click “Continue to review.”
  • Enter a title for the Review. Then, press “Compare branches”

Create review branches


  • In order to create a Review, you will need to have at least two git branches with a build on each.

  • If you are trying to review the changes completed in a pull (merge) request, you will want to match the head and base branches of the Review with the respective branches of the pull (merge) request.

  • You can only have one open Review at a time with the same branch combination. For example, if your head branch is new-changes and your base branch is main, you cannot open another Review with new-changes as the head branch and main as the base branch.

  • While it is unlikely you would need to do so, you can manually create a review for a linked project as well.

  • Base branch: the branch you want to use as a baseline for the comparison
  • Head branch: the branch with the new changes that need to be compared against the base branch

Understanding the Review

Once a Review has been created—either manually or through CI—navigate to the Reviews tab and select the appropriate Review. You will then land on the Activity tab, which shows a timeline of builds, active discussions, and Review status. This showcases what needs to be done in the Review process.

Activity tab

Invite teammates

Invite other developers, designers, PMs, and stakeholders to help review changes. This closes the feedback loop between disciplines and helps you find the answer to “does this look right?”

If you linked your project to GitHub, Bitbucket, or GitLab, your project permissions are synced so collaborators can sign in to review immediately. If your project is unlinked, use the project invite code to add collaborators.

Assign reviewers

Use the Assign Reviewers link on the Review’s Activity screen to choose reviewers from the project’s collaborators. Reviewers will be emailed a link to the Review screen to begin their review.

assign reviewers by picking from your list of collaborators

Pull requests from forks

Chromatic supports UI Test and UI Review across forks, but there’s some caveats. First, it only works with CI integration configured to also build PR branches from forks. Secondly, you must expose your project token so that forks can use it. The easiest way to do that is to simply include it in in your package.json, for example:

  "scripts": {
    "chromatic": "chromatic --project-token <CHROMATIC_PROJECT_TOKEN>"

If you use a CI provider other than GitHub, you can still use an environment variable. Just make sure your CI is configured to also build forked branches. The project token does not grant access to the project (it can only retrieve a strict set of insensitive data), but it does allow running new builds which count against your snapshot quota.

Review the changes

The Review screen includes a Changeset tab showing a side-by-side view of all visual changes introduced on your head branch. It compares the UI on the head branch to the base branch. You’ll see each change’s component story before and after the head branch changes are applied to your base branch.

Changeset tab

Tip: To hint at what UI changed, toggle the highlighted diff (in neon green) on and off.


Reviewers can request updates to the implementation via the comment box beneath each change. Discussions are threaded and attached to the specific story represented by the change.

Changeset Comments

UI checklist

At the bottom of the Review screen’s activity tab is a list of tasks that must be completed before UI is ready to be signed off on. If changes are found, the Review will enter the 🟡 Pending state. When changes are approved and checklist items are complete, the Review will be 🟢 Passed. Here’s how to resolve these tasks:

  1. Changeset must be approved → Assign reviewers or approve yourself.
  2. Outstanding discussions must be resolved → Click ‘Resolve’ on discussions.
  3. All assigned reviewers must approve → Click ‘Approve’ in the Review screen tab bar.

Note: Step #3 is not required if you would like to close the Review.

UI Checklist

Closing a Review

Linked projects

No action is required on linked projects to close a Review. Once the PR branch is merged, the Review will be closed automatically.

Unlinked projects

Once a Review is complete, it can be closed by clicking the ‘Close review’ menu item in the ‘Review now’ button tooltip. Your review will then be displayed in the list of ‘Closed’ Reviews on the Reviews page.

Close Review

Note: closing a Review does not merge the branches in git.

PR check for “UI Review”

Linked projects

You’ll get a ‘UI Review’ status check for each PR that shows the state of the UI Checklist. Require the check in GitHub, GitLab, or Bitbucket to ensure that impactful changes are considered by the team before merging.

PR for UI Review

Unlinked projects

Manually created Reviews will not create a “UI Review” status check in GitHub, GitLab, or Bitbucket. To create a status check in your Git provider for manually created Reviews, you can use a custom webhook.

Next: Learn about documenting reusable components

Now that you’ve seen how to review the UI changeset before merging, learn how Chromatic makes sharing versioned and interactive component docs simple.

Read next chapter

Frequently asked questions

When should I ask for UI Review?

You can initiate a UI Review at any time. However, we recommend doing it later in the development cycle, once baselines have been approved and UI Tests are green. Learn more about UI review.

Can I disable UI Review if I'd prefer not to use it?

Yes. Go to the manage page for your project where you can disable UI Review. Chromatic will no longer add status checks to your PRs for UI Review once it is disabled.

What commits does Chromatic use to calculate the UI changeset?

Similar to GitHub code review, Chromatic compares between the latest commit on the PR branch and the ‘merge base’ commit, that is the commit that is the shared ancestor between the PR branch and the branch it was created from. It is important that Chromatic has run a build on both commits outlined above. If you’ve recently enabled CI and have existing PRs that you would like to review, ensure Chromatic has run in CI for both branches of that PR.

The process might look something like:

  1. Create a new PR to main adding Chromatic to CI
  2. Merge that PR when everything works well.
  3. Update your existing feature PR(s) w/ the latest from main (either merge or rebase from main).