# SecretValue

Masks a secret and adds reveal and copy buttons.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/SecretValue.tsx)

## Overview

SecretValue masks a secret behind 16 dots and adds reveal and copy buttons. A click anywhere on the block copies the value without revealing it.

## Examples

### Basic

```tsx
import { SecretValue, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <SecretValue label="API key" value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc" {...styles.value()} />
  )
}

namespace styles {
  export const value = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/Basic.tsx)

### Size

Set `size` to `small`, `medium` (default), or `large`.

```tsx
import { SecretValue, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.column()}>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <SecretValue
          key={size}
          label="API key"
          size={size}
          value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc"
        />
      ))}
    </div>
  )
}

namespace styles {
  export const column = style({
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'minmax(0, 28rem) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/Size.tsx)

### DefaultRevealed

Set `defaultRevealed` to start with the value shown.

```tsx
import { SecretValue, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <SecretValue
      defaultRevealed
      label="API key"
      value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc"
      {...styles.value()}
    />
  )
}

namespace styles {
  export const value = style({ maxWidth: '28rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/DefaultRevealed.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { SecretValue } from '@tempoxyz/ds'

<SecretValue />
```

## Guidelines

### When to Use

* Show an API key, webhook signing secret, or access key that people copy into another system.
* Show a recovery key that people must store, behind an explicit reveal.

### When Not to Use

* Use [Snippet](/docs/components/snippet) for commands and values that are not secret, such as a webhook URL.
* Use [Hex](/docs/components/hex) with `copy` for public addresses and transaction hashes.
* Use [TextInput](/docs/components/text-input) with `type="password"` when people enter a secret.

### Start Masked

Keep the value hidden until someone presses Reveal. Copy works without a reveal, and anyone near the screen or in a screen share can read a revealed value.

* **`defaultRevealed`:** Set it only on a screen that exists to show the value, such as a key creation confirmation.
* **Mask again:** Control `revealed` with `onRevealedChange` to mask the value again, such as when the tab is hidden or after a minute.

**Do:** Show the secret masked, with its name above it.

```tsx
/** Do example for "Start Masked" on the SecretValue page: show the secret masked, with its name above it. @module */
import { SecretValue, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span {...styles.label()}>Production API key</span>
      <SecretValue label="Production API key" value="tk_live_9fA2c81bE07d4c55a3e6" />
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

**Don't:** Reveal a secret by default on a page people return to, such as a key list.

```tsx
/**
 * Don't example for "Start Masked" on the SecretValue page.
 * Don't reveal a secret by default on a page people return to, such as a key list.
 * @module
 */
import { SecretValue, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span {...styles.label()}>Production API key</span>
      <SecretValue
        defaultRevealed
        label="Production API key"
        value="tk_live_9fA2c81bE07d4c55a3e6"
      />
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

### Name Every Secret

`label` sets the group's `aria-label`, which gives each button context. It is not visible. The mask is always 16 dots, so it can't tell keys apart either.

**Do:** Show what each key unlocks above it, with a creation or last used date.

```tsx
/**
 * Do example for "Name Every Secret" on the SecretValue page.
 * Show what each key unlocks above it, with a creation or last used date.
 * @module
 */
import { SecretValue, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.field()}>
        <div {...styles.header()}>
          <span {...styles.label()}>Production API key</span>
          <span {...styles.meta()}>Last used 2 hours ago</span>
        </div>
        <SecretValue label="Production API key" size="small" value="tk_live_9fA2c81bE07d4c55a3e6" />
      </div>
      <div {...styles.field()}>
        <div {...styles.header()}>
          <span {...styles.label()}>Staging API key</span>
          <span {...styles.meta()}>Created Oct 2</span>
        </div>
        <SecretValue label="Staging API key" size="small" value="tk_test_41bD7e0aC93f2d18b6c5" />
      </div>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', gap: '8' })

  export const header = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '12',
    justifyContent: 'space-between',
  })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const list = style({ display: 'grid', gap: '16', width: '100% !custom' })

  export const meta = style({ color: 'content.secondary', typography: 'body.b3' })
}
```

**Don't:** Leave people to tell keys apart by revealing them.

```tsx
/**
 * Don't example for "Name Every Secret" on the SecretValue page.
 * Don't leave people to tell keys apart by revealing them.
 * @module
 */
import { SecretValue, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <SecretValue label="Production API key" size="small" value="tk_live_9fA2c81bE07d4c55a3e6" />
      <SecretValue label="Staging API key" size="small" value="tk_test_41bD7e0aC93f2d18b6c5" />
    </div>
  )
}

namespace styles {
  export const list = style({ display: 'grid', gap: '16', width: '100% !custom' })
}
```

### Keep Each Secret on One Line

The value does not wrap, and a long revealed value scrolls horizontally.

**Do:** Give a recovery phrase of 12 or 24 words its own numbered layout, behind the same explicit
reveal.

```tsx
/**
 * Do example for "Keep Each Secret on One Line" on the SecretValue page.
 * Give a recovery phrase of 12 or 24 words its own numbered layout, behind the same explicit reveal.
 * @module
 */
import { style } from '@tempoxyz/ds'

const words = [
  'orbit',
  'maple',
  'ledger',
  'canyon',
  'velvet',
  'harbor',
  'quartz',
  'ember',
  'signal',
  'meadow',
  'falcon',
  'summit',
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span {...styles.label()}>Recovery phrase</span>
      <ol {...styles.grid()}>
        {words.map((word, index) => (
          <li key={word} {...styles.word()}>
            <span {...styles.index()}>{index + 1}</span>
            {word}
          </li>
        ))}
      </ol>
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })

  export const grid = style({
    display: 'grid',
    gap: '8',
    gridTemplateColumns: 'repeat(3, 1fr) !custom',
    listStyle: 'none',
    margin: '0',
    padding: '0',
  })

  export const index = style({ color: 'content.secondary', minWidth: '1.25rem !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const word = style({
    backgroundColor: 'container.regular',
    borderRadius: '2xs',
    color: 'content.primary',
    display: 'flex',
    gap: '4',
    padding: '8',
    typography: 'mono.m1',
  })
}
```

**Don't:** Put a recovery phrase in one scrolling line.

```tsx
/**
 * Don't example for "Keep Each Secret on One Line" on the SecretValue page.
 * Don't put a recovery phrase in one scrolling line.
 * @module
 */
import { SecretValue, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.field()}>
      <span {...styles.label()}>Recovery phrase</span>
      <SecretValue
        defaultRevealed
        label="Recovery phrase"
        value="orbit maple ledger canyon velvet harbor quartz ember signal meadow falcon summit"
      />
    </div>
  )
}

namespace styles {
  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

## Content

* **Visibility:** If a key is shown once, write Store this key now. You can't view it again.
* **Leaks:** Link to the replacement action, such as Rotate key.

## Accessibility

SecretValue renders a named `group` with a masked `<code>` value, a reveal toggle, and a copy button. Both buttons follow the [WAI-ARIA Authoring Practices button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).

### Semantics

* **Root (group):** Takes its name from the `label` prop.
* **Value (16 dots):** Screen readers read the dots, never the secret. The mask hides the length and blocks selection.
* **Reveal Button (aria-pressed):** A native button named "Reveal" that reports whether the secret is shown.
* **Copy Button (button):** A native button named "Copy". It reads "Copied" for two seconds, and a polite status region announces each copy.
* **Pointer Shortcut (click):** A click on the block copies without a reveal. Keyboard users use the copy button.

### Keyboard

* **Move Between Buttons (Tab):** Moves focus to the reveal button, then to the copy button. The value takes no focus.
* **Reveal or Copy (Enter or Space):** The reveal button shows or hides the secret. The copy button copies it. Focus stays on the pressed button.

### Your Responsibilities

* **Allow Paste (SC 3.3.8):** Do not block paste where people use the secret. [Accessible authentication](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) relies on it.

## Related

[Snippet](/docs/components/snippet)

Use for values that aren't secret.

[CopyButton](/docs/components/copy-button)

Use for copying beside your own layout.

[TextInput](/docs/components/text-input)

Use for entering a secret.

[Destructive Actions](/docs/patterns/destructive-actions)

Covers revoking and rotating keys.

[Tempo Console](/docs/products/tempo-console)

Covers API key screens.
