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

# React SDK

> React components and hooks for integrating Hey Chocolate sustainability data.

The React SDK provides pre-built components and hooks for displaying sustainability data in React applications.

## Installation

```bash theme={null}
npm install @heychocolate/react
```

## Provider setup

Wrap your app with the `HeyChocolateProvider`:

```tsx theme={null}
import { HeyChocolateProvider } from '@heychocolate/react';

function App() {
  return (
    <HeyChocolateProvider apiKey={process.env.NEXT_PUBLIC_HC_API_KEY}>
      <YourApp />
    </HeyChocolateProvider>
  );
}
```

<Warning>
  For client-side usage, use a restricted API key with read-only permissions. Sensitive operations should go through your backend.
</Warning>

## Hooks

### useProduct

```tsx theme={null}
import { useProduct } from '@heychocolate/react';

function ProductPage({ productId }: { productId: string }) {
  const { product, loading, error } = useProduct(productId);

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

  return (
    <div>
      <h1>{product.name}</h1>
      <p>CO2: {product.impactScore.co2Equivalent} kg</p>
      <p>MKI: {product.impactScore.mkiScore} EUR</p>
    </div>
  );
}
```

### useImpactCalculation

```tsx theme={null}
import { useImpactCalculation } from '@heychocolate/react';

function Calculator({ productId }: { productId: string }) {
  const { calculate, result, loading } = useImpactCalculation();

  return (
    <div>
      <button onClick={() => calculate({
        productId,
        quantity: 100,
        transportMethod: 'TRUCK',
      })}>
        Calculate Impact
      </button>

      {result && (
        <p>{result.equivalency.description}: {result.equivalency.value}</p>
      )}
    </div>
  );
}
```

### useCartImpact

```tsx theme={null}
import { useCartImpact } from '@heychocolate/react';

function CartSummary({ items }) {
  const { cartImpact, loading } = useCartImpact({
    sessionId: 'session_abc',
    items,
    shippingMethod: 'STANDARD',
    shippingAddress: { country: 'NL' },
  });

  if (loading) return <p>Calculating impact...</p>;

  return (
    <div>
      <p>Cart footprint: {cartImpact.totalCo2Equivalent} kg CO2e</p>
      <p>{cartImpact.equivalency.description}: {cartImpact.equivalency.value}</p>
    </div>
  );
}
```

## Components

### CarbonBadge

```tsx theme={null}
import { CarbonBadge } from '@heychocolate/react';

<CarbonBadge productId="prod_abc123" variant="compact" theme="light" />
```

### ComparisonTable

```tsx theme={null}
import { ComparisonTable } from '@heychocolate/react';

<ComparisonTable
  productIds={["prod_abc123", "prod_def456", "prod_ghi789"]}
  metrics={["CO2_EQUIVALENT", "MKI_SCORE", "WATER_FOOTPRINT"]}
/>
```

### ImpactBreakdown

```tsx theme={null}
import { ImpactBreakdown } from '@heychocolate/react';

<ImpactBreakdown productId="prod_abc123" animated={true} />
```

### SupplyChainViewer

```tsx theme={null}
import { SupplyChainViewer } from '@heychocolate/react';

<SupplyChainViewer productId="prod_abc123" maxTier={3} interactive={true} />
```

## Styling

All components accept `className` and `style` props. Default styles can be overridden with CSS variables:

```css theme={null}
:root {
  --hc-primary: #F83B00;
  --hc-success: #4CAF50;
  --hc-warning: #FF9800;
  --hc-danger: #F44336;
  --hc-font-family: inherit;
  --hc-border-radius: 8px;
}
```