Skip to main content

​
Overview

The ZKScore React SDK provides pre-built components for common use cases, including score displays, identity cards, achievement lists, and leaderboards. All components are fully customizable and support both ZKS IDs and wallet addresses.
All components automatically handle ZKS ID resolution, so you can use either ZKS IDs (like alice.zks) or wallet addresses. The SDK will resolve them to the appropriate format.

​
Core Components

​
ScoreCard

Display a user’s current score with optional breakdown. 
import { ScoreCard } from '@zkscore/sdk-react';

function UserProfile({ identity }) {
  return (
    <ScoreCard
      identity={identity}
      showBreakdown={true}
      showHistory={false}
      realTime={true}
      className="custom-score-card"
      style={{ backgroundColor: '#f0f0f0' }}
    />
  );
}
Props:
  • identity (string, required): ZKS ID or wallet address
  • showBreakdown (boolean): Show detailed breakdown
  • showHistory (boolean): Show historical data
  • realTime (boolean): Enable real-time updates
  • className (string): CSS class name
  • style (object): Inline styles

​
IdentityCard

Display identity information with metadata. 
import { IdentityCard } from '@zkscore/sdk-react';

function IdentityDisplay({ identity }) {
  return (
    <IdentityCard
      identity={identity}
      showMetadata={true}
      showAvatar={true}
      showSocial={true}
      layout="horizontal"
      size="large"
    />
  );
}
Props:
  • identity (string, required): ZKS ID or wallet address
  • showMetadata (boolean): Show metadata
  • showAvatar (boolean): Show avatar image
  • showSocial (boolean): Show social links
  • layout (string): Layout type (horizontal, vertical)
  • size (string): Component size (small, medium, large)

​
AchievementList

Display a list of achievements for a user. 
import { AchievementList } from '@zkscore/sdk-react';

function AchievementsSection({ identity }) {
  return (
    <AchievementList
      identity={identity}
      category="defi"
      status="earned"
      limit={10}
      showProgress={true}
      showRarity={true}
      layout="grid"
    />
  );
}
Props:
  • identity (string, required): ZKS ID or wallet address
  • category (string): Filter by category
  • status (string): Filter by status
  • limit (number): Number of achievements to show
  • showProgress (boolean): Show progress bars
  • showRarity (boolean): Show rarity indicators
  • layout (string): Layout type (list, grid)

​
ScoreHistory

Display historical score data as a chart. 
import { ScoreHistory } from '@zkscore/sdk-react';

function ScoreChart({ identity }) {
  return (
    <ScoreHistory
      identity={identity}
      timeframe="30d"
      interval="daily"
      chartType="line"
      showTooltip={true}
      showLegend={true}
      height={300}
    />
  );
}
Props:
  • identity (string, required): ZKS ID or wallet address
  • timeframe (string): Time period (1d, 7d, 30d, 90d, 1y, all)
  • interval (string): Data interval (hourly, daily, weekly, monthly)
  • chartType (string): Chart type (line, bar, area)
  • showTooltip (boolean): Show tooltips
  • showLegend (boolean): Show legend
  • height (number): Chart height in pixels

​
Leaderboard

Display a leaderboard of users. 
import { Leaderboard } from '@zkscore/sdk-react';

function TopUsers() {
  return (
    <Leaderboard
      category="defi"
      metric="score"
      limit={20}
      timeframe="30d"
      showRank={true}
      showAvatar={true}
      showScore={true}
      layout="table"
    />
  );
}
Props:
  • category (string): Filter by category
  • metric (string): Ranking metric (score, points, achievements)
  • limit (number): Number of entries to show
  • timeframe (string): Time period for ranking
  • showRank (boolean): Show rank numbers
  • showAvatar (boolean): Show user avatars
  • showScore (boolean): Show scores
  • layout (string): Layout type (table, list, grid)

​
Advanced Components

​
TrustScore

Display trust score and attestations. 
import { TrustScore } from '@zkscore/sdk-react';

function TrustSection({ identity }) {
  return (
    <TrustScore
      identity={identity}
      showAttestations={true}
      showVerifiers={true}
      showHistory={false}
      realTime={true}
    />
  );
}

​
AchievementProgress

Display progress for a specific achievement. 
import { AchievementProgress } from '@zkscore/sdk-react';

function AchievementTracker({ identity, achievementId }) {
  return (
    <AchievementProgress
      identity={identity}
      achievementId={achievementId}
      showPercentage={true}
      showRequirements={true}
      showRewards={true}
      realTime={true}
    />
  );
}

​
ScoreBreakdown

Display detailed score breakdown. 
import { ScoreBreakdown } from '@zkscore/sdk-react';

function DetailedScore({ identity }) {
  return (
    <ScoreBreakdown
      identity={identity}
      showCategories={true}
      showPercentages={true}
      showTrends={true}
      layout="radar"
    />
  );
}

​
Layout Components

​
ProfileLayout

Complete user profile layout. 
import { ProfileLayout } from '@zkscore/sdk-react';

function UserProfile({ identity }) {
  return (
    <ProfileLayout
      identity={identity}
      sections={['identity', 'score', 'achievements', 'history']}
      layout="sidebar"
      showNavigation={true}
      showSocial={true}
    />
  );
}
Props:
  • identity (string, required): ZKS ID or wallet address
  • sections (array): Sections to include
  • layout (string): Layout type (sidebar, tabs, grid)
  • showNavigation (boolean): Show navigation
  • showSocial (boolean): Show social links

​
DashboardLayout

Dashboard layout with multiple components. 
import { DashboardLayout } from '@zkscore/sdk-react';

function UserDashboard({ identity }) {
  return (
    <DashboardLayout
      identity={identity}
      widgets={[
        { type: 'score', position: 'top-left' },
        { type: 'achievements', position: 'top-right' },
        { type: 'history', position: 'bottom-left' },
        { type: 'leaderboard', position: 'bottom-right' }
      ]}
      theme="dark"
      responsive={true}
    />
  );
}

​
Customization

​
Styling

All components support custom styling through CSS classes and inline styles. 
import { ScoreCard } from '@zkscore/sdk-react';
import './custom-styles.css';

function CustomScoreCard({ identity }) {
  return (
    <ScoreCard
      identity={identity}
      className="custom-score-card"
      style={{
        backgroundColor: '#1a1a1a',
        color: '#ffffff',
        borderRadius: '12px',
        padding: '20px'
      }}
    />
  );
}

​
CSS Custom Properties

Components use CSS custom properties for theming. 
:root {
  --zkscore-primary-color: #007bff;
  --zkscore-secondary-color: #6c757d;
  --zkscore-success-color: #28a745;
  --zkscore-warning-color: #ffc107;
  --zkscore-danger-color: #dc3545;
  --zkscore-info-color: #17a2b8;
  --zkscore-light-color: #f8f9fa;
  --zkscore-dark-color: #343a40;
  --zkscore-border-radius: 8px;
  --zkscore-box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  --zkscore-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

​
Theme Override

import { ZKScoreProvider } from '@zkscore/sdk-react';

function App() {
  return (
    <ZKScoreProvider
      apiKey="your-api-key"
      theme={{
        colors: {
          primary: '#007bff',
          secondary: '#6c757d',
          success: '#28a745',
          warning: '#ffc107',
          danger: '#dc3545'
        },
        typography: {
          fontFamily: 'Inter, sans-serif',
          fontSize: '14px'
        },
        spacing: {
          xs: '4px',
          sm: '8px',
          md: '16px',
          lg: '24px',
          xl: '32px'
        }
      }}
    >
      <YourApp />
    </ZKScoreProvider>
  );
}

​
Component Composition

​
Custom Score Display

import { useScore } from '@zkscore/sdk-react';

function CustomScoreDisplay({ identity }) {
  const { data: score, loading, error } = useScore(identity);

  if (loading) return <div className="loading">Loading score...</div>;
  if (error) return <div className="error">Error: {error.message}</div>;

  return (
    <div className="custom-score">
      <div className="score-circle">
        <div className="score-value">{score?.total || 0}</div>
        <div className="score-label">ZKScore</div>
      </div>
      <div className="score-breakdown">
        <div className="breakdown-item">
          <span>DeFi</span>
          <span>{score?.breakdown?.defi || 0}</span>
        </div>
        <div className="breakdown-item">
          <span>NFT</span>
          <span>{score?.breakdown?.nft || 0}</span>
        </div>
        <div className="breakdown-item">
          <span>Social</span>
          <span>{score?.breakdown?.social || 0}</span>
        </div>
      </div>
    </div>
  );
}

​
Custom Achievement Grid

import { useAchievements } from '@zkscore/sdk-react';

function CustomAchievementGrid({ identity }) {
  const { data: achievements, loading, error } = useAchievements(identity);

  if (loading) return <div>Loading achievements...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div className="achievement-grid">
      {achievements?.earned?.map(achievement => (
        <div key={achievement.id} className="achievement-card">
          <div className="achievement-icon">
            <img src={achievement.icon} alt={achievement.name} />
          </div>
          <div className="achievement-info">
            <h3>{achievement.name}</h3>
            <p>{achievement.description}</p>
            <div className="achievement-meta">
              <span className="rarity">{achievement.rarity}</span>
              <span className="points">{achievement.points} pts</span>
            </div>
          </div>
        </div>
      ))}
    </div>
  );
}

​
Responsive Design

​
Mobile-First Approach

import { ScoreCard } from '@zkscore/sdk-react';

function ResponsiveScoreCard({ identity }) {
  return (
    <ScoreCard
      identity={identity}
      className="responsive-score-card"
      style={{
        width: '100%',
        maxWidth: '400px',
        margin: '0 auto'
      }}
    />
  );
}

​
CSS Media Queries

.responsive-score-card {
  display: flex;
  flex-direction: column;
}

@media (min-width: 768px) {
  .responsive-score-card {
    flex-direction: row;
  }
}

@media (min-width: 1024px) {
  .responsive-score-card {
    max-width: 600px;
  }
}

​
Accessibility

​
ARIA Labels

import { ScoreCard } from '@zkscore/sdk-react';

function AccessibleScoreCard({ identity }) {
  return (
    <ScoreCard
      identity={identity}
      aria-label={`Score for ${identity}`}
      role="region"
      tabIndex={0}
    />
  );
}

​
Keyboard Navigation

import { AchievementList } from '@zkscore/sdk-react';

function KeyboardAccessibleAchievements({ identity }) {
  return (
    <AchievementList
      identity={identity}
      className="keyboard-accessible"
      onKeyDown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
          e.preventDefault();
          // Handle selection
        }
      }}
    />
  );
}

​
Performance Optimization

​
Lazy Loading

import { lazy, Suspense } from 'react';
import { ScoreCard } from '@zkscore/sdk-react';

const LazyScoreCard = lazy(() => import('@zkscore/sdk-react').then(module => ({
  default: module.ScoreCard
})));

function LazyLoadedScore({ identity }) {
  return (
    <Suspense fallback={<div>Loading score...</div>}>
      <LazyScoreCard identity={identity} />
    </Suspense>
  );
}

​
Memoization

import { memo } from 'react';
import { ScoreCard } from '@zkscore/sdk-react';

const MemoizedScoreCard = memo(ScoreCard);

function OptimizedScore({ identity }) {
  return <MemoizedScoreCard identity={identity} />;
}

​
Virtual Scrolling

import { FixedSizeList as List } from 'react-window';
import { AchievementList } from '@zkscore/sdk-react';

function VirtualizedAchievements({ identity }) {
  const { data: achievements } = useAchievements(identity);

  const Row = ({ index, style }) => (
    <div style={style}>
      <AchievementList
        identity={identity}
        startIndex={index}
        endIndex={index + 10}
      />
    </div>
  );

  return (
    <List
      height={400}
      itemCount={achievements?.earned?.length || 0}
      itemSize={80}
    >
      {Row}
    </List>
  );
}

​
Best Practices

​
1. Component Composition

import { ScoreCard, AchievementList, ScoreHistory } from '@zkscore/sdk-react';

function UserProfile({ identity }) {
  return (
    <div className="user-profile">
      <div className="profile-header">
        <ScoreCard identity={identity} />
      </div>
      <div className="profile-content">
        <div className="achievements-section">
          <AchievementList identity={identity} />
        </div>
        <div className="history-section">
          <ScoreHistory identity={identity} />
        </div>
      </div>
    </div>
  );
}

​
2. Error Boundaries

import { ErrorBoundary } from 'react-error-boundary';
import { ScoreCard } from '@zkscore/sdk-react';

function ScoreCardWithErrorBoundary({ identity }) {
  return (
    <ErrorBoundary
      fallback={<div>Failed to load score</div>}
      onError={(error) => console.error('ScoreCard error:', error)}
    >
      <ScoreCard identity={identity} />
    </ErrorBoundary>
  );
}

​
3. Loading States

import { ScoreCard } from '@zkscore/sdk-react';

function ScoreCardWithLoading({ identity }) {
  return (
    <ScoreCard
      identity={identity}
      loadingComponent={<div>Loading score...</div>}
      errorComponent={<div>Error loading score</div>}
    />
  );
}