Sign inSign up
Introduction

UI Review powered by stories

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.

UI Review

👀 Looking for Manual UI Reviews? See the documentation below.

Enable

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.

ℹ️ You must set up CI so that Chromatic is able to run builds for each commit on the PR 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

Default reviewers

If you find you’re always assigning the same reviewers, you can set default reviewers for your project. Default reviewers will be automatically assigned to new Review. You can also assign additional reviewers on a per-Review basis.

Add default reviewers on your project’s Manage page. Go to the Review section to add a default reviewer.

assign default reviewers by picking from your list of collaborators

Remove a default reviewer by clicking “Remove” beside their name. This will remove them as default reviewer but not from the project.

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.

Discussions

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.

ℹ️ Step #3 is not required if you would like to close the Review.

UI Checklist

PR check for “UI Review”

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


Manual UI Review

Manual UI Review helps you see the visual differences between any pair of branches - even if your project isn’t connected to a git provider.

Enable UI Review

Go to your project’s Manage page to enable UI Review.

Enable UI Review

Create a Review

Create Review Go to your project’s Reviews page from the sidebar. Click the “Create review” button to pick the pair of branches you want to compare.

Create review branches

If you’re familiar with creating pull or merge requests with git, this process will be very familiar:

  • Select the base branch, which is the branch that’s used as the source of truth for comparison. Typically, this will be your main branch.
  • Select the head branch, which is the branch that has changes that you want to compare with the source of truth. This is often a feature or bug fix branch you’re working on.
  • Enter a title for the Review.
  • Click the “Compare branches” button to generate your new Review

Your Review is now ready for you and your team to discuss. Follow along from to the Understanding the Review section on for more information on how to benefit the most from UI Review.

Glossary
  • 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

PR check for “UI Review”

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.

Closing a Review

Prune your completed manual UI Reviews by clicking the “Close review” menu item in the “Review now” button tooltip. Your review will be moved in the list of “Closed” Reviews on the Reviews page.

Close Review

ℹ️ Reminder: closing a Review does not merge the branches in Git.

Notes:

  • 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.
  • You can manually create a review for a linked project as well. This feature is available to all projects.

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).