Widget / Embed
Add VIZI credit scores to any website or application with a single line of code. Our drop-in widget is fully responsive, customizable, and works as both an iframe and a native web component.
Quick Embed
The fastest way to display a VIZI Score on your site. Just include the widget script and place the custom element where you want the score to appear.
<!-- Load the VIZI widget library -->
<script src="https://cdn.vizi.com/widget.js"></script>
<!-- Place the widget wherever you want -->
<vizi-score
address="0x1234...abcd"
api-key="vizi_pk_live_your_key"
theme="light"
size="medium"
></vizi-score>Iframe Alternative
If you prefer a simple iframe, use our hosted embed URL. No JavaScript required — just set the wallet address as a query parameter.
<iframe
src="https://embed.vizi.com/score?address=0x1234...abcd&key=vizi_pk_live_your_key&theme=light"
width="320"
height="400"
frameborder="0"
style="border-radius: 12px; border: 1px solid #e5e7eb;"
></iframe>Customization
Both the web component and iframe accept the same configuration parameters, so you can match the widget to your brand.
Theme
Choose between light, dark, or auto (follows system preference). The dark theme uses a deep navy background with bright accent colors for the score gauge.
<vizi-score theme="dark" ...></vizi-score>Size
Set the widget size to small (200px), medium (320px), or large (480px). The widget is always responsive within its container.
<vizi-score size="large" ...></vizi-score>Show Factors
Display or hide the scoring factor breakdown below the gauge. Set show-factors="true" to show the full factor list with individual weights.
<vizi-score show-factors="true" ...></vizi-score>Custom Colors
Override the default gauge colors with your brand palette. Pass a JSON-encoded color map for full control over the score ranges.
<vizi-score
colors='{"excellent":"#22c55e","good":"#3b82f6","fair":"#f59e0b","poor":"#ef4444"}'
...
></vizi-score>Events API
The widget dispatches custom DOM events that let you react to user interactions and score loading states in your application.
const widget = document.querySelector('vizi-score');
widget.addEventListener('vizi:loaded', (e) => {
console.log('Score loaded:', e.detail.score); // 300-850
console.log('Grade:', e.detail.grade); // A+ through F
});
widget.addEventListener('vizi:error', (e) => {
console.error('Widget error:', e.detail.message);
});
widget.addEventListener('vizi:click', (e) => {
// User clicked the "View Details" link
window.open(`https://viziscan.com/${e.detail.address}`, '_blank');
});vizi:loaded
Fired when the score has been fetched and rendered. The detail object contains score, grade, address, and factors.
vizi:error
Fired on fetch failures. The detail object includes code and message. Handle gracefully to show a fallback UI.
Framework Integrations
The web component works natively in any framework. Here are recommended patterns for the most popular ones.
React
import { useEffect, useRef } from 'react';
function ViziScoreWidget({ address }) {
const ref = useRef(null);
useEffect(() => {
if (!document.querySelector('script[src*="vizi"]')) {
const script = document.createElement('script');
script.src = 'https://cdn.vizi.com/widget.js';
document.head.appendChild(script);
}
}, []);
return (
<vizi-score
ref={ref}
address={address}
api-key="vizi_pk_live_your_key"
theme="auto"
size="medium"
show-factors="true"
/>
);
}Vue
<template>
<vizi-score
:address="walletAddress"
api-key="vizi_pk_live_your_key"
theme="auto"
size="medium"
/>
</template>
<script setup>
import { onMounted } from 'vue';
const walletAddress = '0x1234...abcd';
onMounted(() => {
if (!document.querySelector('script[src*="vizi"]')) {
const s = document.createElement('script');
s.src = 'https://cdn.vizi.com/widget.js';
document.head.appendChild(s);
}
});
</script>Angular
// In angular.json, add to "scripts":
// "scripts": ["https://cdn.vizi.com/widget.js"]
// In your component template:
// <vizi-score [attr.address]="walletAddress" api-key="vizi_pk_live_your_key"></vizi-score>
// In app.module.ts, add CUSTOM_ELEMENTS_SCHEMA:
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@NgModule({
schemas: [CUSTOM_ELEMENTS_SCHEMA]
})Responsive Behavior
The VIZI widget is built with a fluid layout that adapts gracefully from mobile screens to large desktop monitors. On narrow screens, the gauge stacks vertically with the factor breakdown below. On wider screens, factors display in a two-column grid alongside the gauge.
The widget respects its parent container's width at all times. If you place it inside a 200px sidebar, it will scale down. If you give it a full-width section, it will fill the space up to its maximum width. No media query overrides needed on your end.
The widget uses Shadow DOM to encapsulate its styles, meaning it will never interfere with your page's CSS, and your page's CSS will never break the widget's layout. This isolation makes it safe to embed in any design system.
Security & CSP
The widget loads from cdn.vizi.com and communicates with api.vizi.com. If your site uses Content Security Policy headers, add these directives:
Content-Security-Policy:
script-src 'self' https://cdn.vizi.com;
connect-src 'self' https://api.vizi.com;
style-src 'self' 'unsafe-inline';
img-src 'self' https://cdn.vizi.com;Widget embeds use a publishable key (starts with vizi_pk_) that is safe to include in client-side code. This key can only read scores — it cannot modify data, create webhooks, or access billing information. You can restrict each publishable key to specific domains from your VIZI dashboard to prevent unauthorized usage.
Get Your Embed Key
Widget embeds use a publishable key (starts with vizi_pk_) that is safe to include in client-side code. Sign up for API access to generate your key.