Components

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}
    />
  );
}

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>}
    />
  );
}

Getting Started - SDK setup and configuration
Hooks Reference - Complete hooks API
Examples - Complete examples
JavaScript SDK - Core SDK documentation

SDK Overview

JavaScript SDK

React SDK

SDK Examples

Overview

Core Components

ScoreCard

IdentityCard

AchievementList

ScoreHistory

Leaderboard

Advanced Components

TrustScore

AchievementProgress

ScoreBreakdown

Layout Components

ProfileLayout

DashboardLayout

Customization

Styling

CSS Custom Properties

Theme Override

Component Composition

Custom Score Display

Custom Achievement Grid

Responsive Design

Mobile-First Approach

CSS Media Queries

Accessibility

ARIA Labels

Keyboard Navigation

Performance Optimization

Lazy Loading

Memoization

Virtual Scrolling

Best Practices

1. Component Composition

2. Error Boundaries

3. Loading States

​Overview

​Core Components

​ScoreCard

​IdentityCard

​AchievementList

​ScoreHistory

​Leaderboard

​Advanced Components

​TrustScore

​AchievementProgress

​ScoreBreakdown

​Layout Components

​ProfileLayout

​DashboardLayout

​Customization

​Styling

​CSS Custom Properties

​Theme Override

​Component Composition

​Custom Score Display

​Custom Achievement Grid

​Responsive Design

​Mobile-First Approach

​CSS Media Queries

​Accessibility

​ARIA Labels

​Keyboard Navigation

​Performance Optimization

​Lazy Loading

​Memoization

​Virtual Scrolling

​Best Practices

​1. Component Composition

​2. Error Boundaries

​3. Loading States

​Related Documentation

Overview

Core Components

ScoreCard

IdentityCard

AchievementList

ScoreHistory

Leaderboard

Advanced Components

TrustScore

AchievementProgress

ScoreBreakdown

Layout Components

ProfileLayout

DashboardLayout

Customization

Styling

CSS Custom Properties

Theme Override

Component Composition

Custom Score Display

Custom Achievement Grid

Responsive Design

Mobile-First Approach

CSS Media Queries

Accessibility

ARIA Labels

Keyboard Navigation

Performance Optimization

Lazy Loading

Memoization

Virtual Scrolling

Best Practices

1. Component Composition

2. Error Boundaries

3. Loading States

Related Documentation