Chrome Extension Quickstart

This guide walks you through installing the VertaaUX Chrome Extension and running your first audit. By the end, you will see accessibility and UX issues highlighted directly on a webpage.

Time required: 5 minutes

Prerequisites

• Google Chrome browser (version 120 or later)
• A VertaaUX API key (create one here)

Step 1: Install the Extension

Option A: Chrome Web Store (Recommended)

1. Open the VertaaUX Extension in Chrome Web Store
2. Click Add to Chrome
3. Click Add extension when prompted
4. You will see the VertaaUX icon in your toolbar

Option B: Manual Installation

For development builds or testing:

# Clone and build the extension
git clone https://github.com/vertaaux/extension.git
cd extension
npm install
npm run build

Then in Chrome:

1. Navigate to chrome://extensions
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked
4. Select the extension/dist folder
5. The extension icon appears in your toolbar

Step 2: Configure Your API Key

1. Click the VertaaUX extension icon in your toolbar
2. A popup appears with a text field for your API key
3. Paste your API key (starts with vx_live_ or vx_test_)
4. Click Save
5. The popup shows "API key saved" confirmation

Your API key is stored securely in Chrome's local storage and persists across browser sessions.

Step 3: Navigate to a Website

Open any website you want to audit. For this quickstart, we recommend using:

• Your own project's staging site
• A public website like https://example.com
• A local development server like http://localhost:3000

The extension works on any URL, including localhost.

Step 4: Open the Side Panel

Open the Side Panel using any of these methods:

Alternative methods:

• Click the VertaaUX extension icon and select "Open Side Panel"
• Right-click anywhere on the page and select "VertaaUX > Open Side Panel"

The Side Panel opens on the right side of your browser window.

Step 5: Run Your First Scan

In the Side Panel:

1. Click the Quick Scan button
2. Watch the progress indicator (typically completes in 2 seconds)
3. Results appear in the Side Panel's issue list

The Quick Scan runs basic accessibility checks using axe-core. For comprehensive analysis, use Full Scan (takes approximately 15 seconds).

Step 6: See Issues on the Page

Once the scan completes, issues appear as colored overlays on the page:

Overlay colors indicate severity:

Interacting with overlays:

• Hover over an overlay to see a quick summary tooltip
• Click an overlay to select it and view full details in the Side Panel
• Click elsewhere to deselect

What You Should See

After completing the scan, you should see:

1. Side Panel showing:

   • Total issues found with severity breakdown
   • Filterable issue list
   • Overall scan score

2. Page overlays showing:

   • Colored borders around elements with issues
   • Cluster badges where multiple issues are nearby
   • Tooltips on hover

3. Selected issue details showing:

   • Issue description and impact
   • WCAG reference (for accessibility issues)
   • Element selector for the affected element

Troubleshooting

No overlays appear after scan

• Verify your API key is correct (check the extension popup)
• Try a Full Scan instead of Quick Scan
• Check the browser console for errors (F12 > Console tab)

Extension icon is grayed out

• Make sure you are on an http:// or https:// page (not chrome://)
• Some internal Chrome pages block extensions

Scan takes too long

• Quick Scan should complete in under 5 seconds
• For slow pages, the extension waits for the page to stabilize
• Try refreshing the page and scanning again

API key error

• Verify the key starts with vx_live_ or vx_test_
• Check your quota at vertaaux.ai/settings/usage
• Test keys have the same functionality as live keys

Next Steps

Now that you have run your first audit:

Related

• API Authentication - API key management and security
• CLI Quickstart - Run audits from your terminal
• SDK Quickstart - Integrate audits into your application