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

# Cards.js

> Show a cardholder their full card details in your web app, without the card data touching your DOM, your servers, or your code

<Warning>
  **Cards is available in sandbox only while we finish development.** Dakota enables Cards per
  account. The Cards endpoints are in the [API reference](/api-reference/introduction), marked
  **Sandbox only**. Endpoints, fields, and flows can still change before release.
</Warning>

`@dakota-xyz/cards-js` securely displays full card details — PAN, CVV, and expiry — directly in your web app, without the sensitive data ever touching your DOM, your servers, or your code.

Card values render inside frames served by Dakota's card-data processor. Your page positions and styles those frames but can never read them, so integrating Cards.js keeps your web front end within **PCI DSS SAQ A** scope. Your backend mints a session, and the browser consumes it once, for a bounded reveal window.

* **Framework-free core** — a small imperative client, no framework required.
* **First-class React binding** — components and hooks under `@dakota-xyz/cards-js/react`.
* **Deliberate reveal** — single-use sessions, an auto-masking reveal window, and an SDK-enforced re-mask.
* **Themeable** — a default card face you can restyle with CSS custom properties, plus per-field text styling that carries into the revealed value frames.

For how card data stays out of Dakota's REST API, and the endpoint your backend calls, see [Secure card data](/documentation/cards/secure-card-data).

## Install

```sh theme={null}
npm i @dakota-xyz/cards-js
```

React is an optional peer dependency (`react >= 18`). You only need it for the `/react` entry point.

## Quickstart — vanilla

Your backend exposes one endpoint that mints a reveal session — see the [integration guide](/documentation/cards/cards-js/integration-guide). The browser calls it through `fetchSession`:

```ts theme={null}
import { DakotaCards } from '@dakota-xyz/cards-js';
import '@dakota-xyz/cards-js/styles.css';

const cards = new DakotaCards({
  environment: 'sandbox',
  // Your backend holds the API key and mints a short-lived, single-use session.
  fetchSession: async (ctx) => {
    const res = await fetch('/api/reveal-session', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(ctx), // { sessionType, origin }
    });
    if (!res.ok) throw new Error(`session mint failed: ${res.status}`);
    return res.json(); // { session, expiresAt }
  },
});

const card = cards.cardDetails({ last4: '4242' });
await card.mount({ pan: '#pan', cvv: '#cvv', expiryMonth: '#mm', expiryYear: '#yy' });

document.querySelector('#reveal')!.addEventListener('click', () => {
  void (card.state === 'revealed' ? card.mask() : card.reveal());
});
```

The mount targets live inside the documented `.dk-card` HTML recipe — see [theming](/documentation/cards/cards-js/theming#the-dom-recipe). `mount()` only paints the masked face and never touches the network. `reveal()` is what mints a session and swaps in the processor-hosted fields.

## Quickstart — React

```tsx theme={null}
import { useMemo, useRef } from 'react';
import { DakotaCards, type FetchSession } from '@dakota-xyz/cards-js';
import { DakotaCardsProvider, CardDetails, type CardDetailsHandleRef } from '@dakota-xyz/cards-js/react';
import '@dakota-xyz/cards-js/styles.css';

const fetchSession: FetchSession = async (ctx) => {
  const res = await fetch('/api/reveal-session', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(ctx),
  });
  if (!res.ok) throw new Error(`session mint failed: ${res.status}`);
  return res.json();
};

export function CardView() {
  const client = useMemo(() => new DakotaCards({ environment: 'sandbox', fetchSession }), []);
  const ref = useRef<CardDetailsHandleRef>(null);
  return (
    <DakotaCardsProvider client={client}>
      <CardDetails ref={ref} last4="4242" />
      <button onClick={() => void ref.current?.reveal()}>Reveal</button>
      <button onClick={() => ref.current?.mask()}>Mask</button>
    </DakotaCardsProvider>
  );
}
```

`<CardDetails>` renders the `.dk-card` recipe for you. To own the markup yourself, use the `useCardDetails` hook: it returns field refs and live state, so you can render the recipe by hand.

## Styles

Import the default stylesheet once, anywhere in your app:

```ts theme={null}
import '@dakota-xyz/cards-js/styles.css';
```

It ships the Dakota card face — a black card with the DAKOTA wordmark, the card-network mark, and a textured accent — and self-hosts its fonts inside the package, so rendering the face makes no third-party requests. Restyle it with CSS custom properties or the `theme` option — see [theming](/documentation/cards/cards-js/theming).

## Browser support

| Browser | Supported |
| - | - |
| Chrome, Edge, Firefox | Current evergreen releases |
| Safari (desktop & iOS) | 16 and newer |

The page hosting a reveal must be served over **HTTPS** (a secure context), in local development too. See [Network & CSP](/documentation/cards/cards-js/network-and-csp#https-is-required).

## Privacy & telemetry

Cards.js ships no analytics or error reporting, and never logs session tokens. See [Security](/documentation/cards/cards-js/security#no-telemetry).

## Documentation

<CardGroup cols={2}>
  <Card title="Integration guide" icon="plug" href="/documentation/cards/cards-js/integration-guide">
    The `fetchSession` contract, session behaviour, error handling, and multiple cards.
  </Card>

  <Card title="API reference" icon="code" href="/documentation/cards/cards-js/api-reference">
    Every exported type, class, component, and hook.
  </Card>

  <Card title="Theming" icon="palette" href="/documentation/cards/cards-js/theming">
    The DOM recipe, custom properties, `theme`, and i18n.
  </Card>

  <Card title="Network & CSP" icon="shield-halved" href="/documentation/cards/cards-js/network-and-csp">
    The Content-Security-Policy directives to allow.
  </Card>

  <Card title="Security" icon="lock" href="/documentation/cards/cards-js/security">
    How card data stays out of your reach, and how to report a vulnerability.
  </Card>

  <Card title="Changelog" icon="clock-rotate-left" href="/documentation/cards/cards-js/changelog">
    Notable changes, per version.
  </Card>
</CardGroup>

## License

MIT © Dakota