---
title: "Consent and permissions"
description: "Ask for one permission at the moment it is needed, record what was agreed, and make refusing and withdrawing as easy as agreeing."
url: "https://opsinjs.pensievelabs.org/docs/patterns/consent-and-permissions"
source: "https://opsinjs.pensievelabs.org/docs/patterns/consent-and-permissions.md"
section: "Patterns"
kind: "pattern"
aliases: ["permission priming", "asking for consent", "permission prompt sequence", "revoking access", "data sharing prompt"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.

Consent is specific, informed, freely given, and withdrawable as easily as it was granted. A prompt that hides withdrawal in a settings sub-page is a subscription, not consent. [Consent and privacy](../health/consent-and-privacy.mdx) holds the doctrine.

## When to use it [#when-to-use-it]

Use it whenever the product wants something it cannot take: health data from the device, notifications, sharing a record with a clinician, or a secondary use such as research.

Do not use it when:

* The screen cannot exist without the permission. Say what it needs and let the reader leave, because a prompt with one real option is not a choice.
* You are telling the reader what you already hold. That is [Result disclosure](./result-disclosure.mdx).
* It is a legal notice with no choice. Accepting terms is not consent to processing.
* A question could disclose self-harm, abuse or a diagnosis. That is a distinct flow. See [High-stakes moments](../health/high-stakes-moments.mdx).

<Todo>
  A pattern for disclosure inside a questionnaire and for crisis signposting. It needs clinical review, not only design.
</Todo>

## How it works [#how-it-works]

1. Ask at the moment of need, from the surface that needs it. Never ask at first launch.
2. Explain in your own sheet first: what is collected, what it is for, who else sees it, how long it is kept, and what still works without it.
3. Trigger the operating system's dialog only after the reader agrees to yours, because most platforms cannot re-ask after a refusal. Never style your sheet to look like that dialog.
4. Ask one scope per sheet, with nothing pre-ticked. Three permissions are three sheets, each asked when it becomes useful.
5. Record what was granted, when, by whom, and which version of the wording the reader saw.
6. Deliver what the grant bought at once. After a refusal, keep the degraded but working surface, and re-offer only where it is needed.
7. Put withdrawal at the same depth as agreement. It takes effect immediately and says what happens to data already shared, because revoked and deleted are different.

Re-ask when the scope or the wording changes, never on a timer.

## Components [#components]

* [ConsentSheet](../components/consent-sheet.mdx) asks one question, with refusing exactly as easy as agreeing.
* [Sheet](../components/sheet.mdx) is the surface ConsentSheet extends.
* [Term](../components/term.mdx) explains any legal or clinical word inline.
* [DisclaimerNote](../components/disclaimer-note.mdx) says what this consent does not cover.
* [EmptyState](../components/empty-state.mdx) is the declined outcome, saying what still works and the way back.

## Ask before collecting [#ask-before-collecting]

```tsx
import { ConsentSheet } from "@/components/ui/consent-sheet"
```

```tsx
<ConsentSheet
  open={open}
  onOpenChange={setOpen}
  consentId="example-consent"
  textVersion={copy.version}
  heading={copy.question}
  purpose={copy.purpose}
  scope={copy.scope}
  withdrawalPath={copy.withdrawal}
  acceptLabel={copy.accept}
  declineLabel={copy.decline}
  onDecision={store}
/>
```

* opsinjs ships no consent wording. Every string is a prop, and `scope` takes three sentences: `collected`, `sharedWith` and `retention`.
* If any required string is missing or blank, the sheet refuses to ask and draws no controls.
* `onDecision` fires only when a control is pressed. Escape, the scrim, a drag or Close call nothing, so a dismissal is never stored as an answer.
* Store the `ConsentDecision` it returns: `granted`, `at`, `consentId`, `textVersion` and `scope`.
* Pass `consequenceOfDeclining` whenever refusing costs the reader something.

<ComponentPreview name="consent-sheet-two-questions-two-sheets" kind="example" align="start" />

## Example [#example]

<IframePreview kind="screen" name="consent-flow" />

The whole-screen flow is not built yet, so the frame shows only its placeholder. The ConsentSheet example above is the shipped specimen.

## Content [#content]

* Describe the consequence, not the mechanism: who can see what, for how long, and how to stop it. "Enable data sharing to unlock the full experience" says none of that.
* Both labels name an outcome. Never label the decline control "not now" when it means no. ConsentSheet warns about it in development.
* Never make refusal sound reckless, and never write "by continuing you agree".

## Accessibility [#accessibility]

* The explanation precedes the two controls in the DOM, so a screen reader meets the question first.
* Both answers are one component used twice: the same size, contrast and target, adjacent in the tab order. Check in greyscale, and at 200% text, where both must stay visible together.
* Focus enters the sheet, <Kbd>Escape</Kbd> closes it with no answer given, and focus returns to the opener.
* Nothing times out, auto-advances or dismisses itself.
