> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Components

> Pre-built React components for ZKScore integration

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

<Tip>
  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.
</Tip>

## Core Components

### ScoreCard

Display a user's current score with optional breakdown.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```css theme={null}
: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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```css theme={null}
.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

```jsx theme={null}
import { ScoreCard } from '@zkscore/sdk-react';

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

### Keyboard Navigation

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
import { memo } from 'react';
import { ScoreCard } from '@zkscore/sdk-react';

const MemoizedScoreCard = memo(ScoreCard);

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

### Virtual Scrolling

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
import { ScoreCard } from '@zkscore/sdk-react';

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

## Related Documentation

* [Getting Started](/sdk/react/getting-started) - SDK setup and configuration
* [Hooks Reference](/sdk/react/hooks-reference) - Complete hooks API
* [Examples](/sdk/react/examples) - Complete examples
* [JavaScript SDK](/sdk/javascript/getting-started) - Core SDK documentation