SecretValueField

Masked display for API keys, tokens, and webhook secrets with accessible copy action.

Overview

SecretValueField renders a secret credential in masked form by default, with a one-click copy action and an optional reveal toggle. It is designed for settings pages and API key management screens where you need to:

• Show a newly-created secret exactly once (use initiallyRevealed).
• Display an existing key masked, with only safe metadata (prefix/suffix) visible.
• Let users copy the value without it appearing in accessible labels, titles, or data attributes.

Security contract: The value prop is never written to any passive attribute. The copy announcement says only "Copied" and never contains the value. Reveal is opt-in and off by default.

Usage

<script lang="ts">
  import { SecretValueField } from '@lostgradient/cinder/secret-value-field';
</script>

<!-- Newly-created API key: show once, prompt to copy -->
<SecretValueField
  value="example_live_abc123xyz"
  label="API Key"
  prefix="example_live_"
  initiallyRevealed={true}
/>

<!-- Existing masked key with last-4 suffix for identification -->
<SecretValueField
  value="example_live_abc123xyz"
  label="API Key"
  prefix="example_live_"
  suffix="xyz"
/>

<!-- Allow the user to reveal the full value on demand -->
<SecretValueField value="example_whsec_abc123xyz" label="Webhook Secret" revealAllowed={true} />

Accessibility

SecretValueField keeps the secret out of all accessible attributes. See secret-value-field.a11y.md for the full accessibility contract.

• The value display has an aria-label that names the field and its state ("masked" or "revealed") without including the value itself.
• Copy success is announced by a role="status" aria-live="polite" region with aria-atomic="true". The announcement says "Copied" (or your custom copiedLabel), never the value.
• The reveal toggle uses aria-pressed to communicate its state, and its aria-label flips between "Reveal {label}" and "Hide {label}".
• Prefix and suffix elements carry aria-hidden="true" to prevent double-reading; the value region's aria-label already describes the field.
• The row of controls is wrapped in role="group" labelled via aria-labelledby pointing to the field label.