Patterns
Consent and permissions
Ask for one permission at the moment it is needed, record what was agreed, and make refusing and withdrawing as easy as agreeing.
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 holds the doctrine.
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.
- 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.
A pattern for disclosure inside a questionnaire and for crisis signposting. It needs clinical review, not only design.
How it works
- Ask at the moment of need, from the surface that needs it. Never ask at first launch.
- 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.
- 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.
- Ask one scope per sheet, with nothing pre-ticked. Three permissions are three sheets, each asked when it becomes useful.
- Record what was granted, when, by whom, and which version of the wording the reader saw.
- Deliver what the grant bought at once. After a refusal, keep the degraded but working surface, and re-offer only where it is needed.
- 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
- ConsentSheet asks one question, with refusing exactly as easy as agreeing.
- Sheet is the surface ConsentSheet extends.
- Term explains any legal or clinical word inline.
- DisclaimerNote says what this consent does not cover.
- EmptyState is the declined outcome, saying what still works and the way back.
Ask before collecting
import { ConsentSheet } from "@/components/ui/consent-sheet"<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
scopetakes three sentences:collected,sharedWithandretention. - If any required string is missing or blank, the sheet refuses to ask and draws no controls.
onDecisionfires 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
ConsentDecisionit returns:granted,at,consentId,textVersionandscope. - Pass
consequenceOfDecliningwhenever refusing costs the reader something.
consent-sheet-two-questions-two-sheets · base base · style base-lyraOpen under the product theme"use client"
import { useEffect, useRef, useState } from "react"
import { Button } from "@/components/ui/button"
import { ConsentSheet } from "@/components/ui/consent-sheet"
const FIRST_SCOPE = {
collected: "Placeholder for what the first question collects.",
sharedWith: "Placeholder for who can see it.",
retention: "Placeholder for how long it is kept.",
}
const SECOND_SCOPE = {
collected: "Placeholder for what the second question collects. This is a different thing.",
sharedWith: "Placeholder for who can see it. This is a different recipient.",
retention: "Placeholder for how long it is kept. This is a different period.",
}
export default function ConsentSheetTwoQuestionsTwoSheets() {
const [asking, setAsking] = useState<"none" | "first" | "second">("none")
const [answers, setAnswers] = useState<Record<string, string>>({})
/* A sheet opened by a control returns focus to that control on its own. This
one cannot, because by the time the last sheet closes the reader may have
been through two of them and nothing they focused opened the second. So the
return is written out. A counter rather than a boolean, because the reader
can go through this more than once and a flag already `true` would not
re-run the effect. */
const triggerRef = useRef<HTMLDivElement>(null)
const [returns, setReturns] = useState(0)
/* Whether the first sheet closed because it was answered rather than because
the reader left. It is a ref and not state, because the only reader of it is
the first sheet's `onOpenChange`, which must not trigger a render of its own,
and because it has to be set inside an event handler and read in the same
handler without a re-render between the two. */
const answeredRef = useRef(false)
useEffect(() => {
if (returns === 0) return
triggerRef.current?.querySelector("button")?.focus()
}, [returns])
return (
<div className="flex w-full flex-col items-center gap-opsin-4 p-opsin-4">
<p className="m-0 max-w-sm text-center text-opsin-footnote text-muted-foreground">
Two separate questions, asked one after the other. Answer them
differently. The point of asking twice is that the two answers do not
have to match.
</p>
{/* The trigger is read out of a wrapper rather than through a `ref` on
Button, because `ButtonProps` omits `ref`: it extends the element's
HTML attributes, and `ref` lives on `RefAttributes`. ConsentSheet
reads its decision controls out of a wrapper for the same reason. */}
<div ref={triggerRef}>
<Button onClick={() => setAsking("first")}>Ask both example questions</Button>
</div>
<ul className="m-0 flex w-full max-w-md list-none flex-col gap-opsin-1 p-0 text-opsin-caption1 text-muted-foreground">
{Object.keys(answers).length === 0 ? (
<li>No answers yet.</li>
) : (
Object.entries(answers).map(([id, verdict]) => (
<li key={id} className="wrap-break-word">
{id}: {verdict}
</li>
))
)}
</ul>
<ConsentSheet
open={asking === "first"}
onOpenChange={(nextOpen) => {
if (nextOpen) return
/* A close without an answer is not an answer, and it is not
permission to ask the next thing either, so the reader is returned
to the page. Telling "closed because it was answered" from "closed
because the reader left" must not go through a state updater:
React runs an updater twice in development StrictMode, so a
`setReturns` called from inside one would count every dismissal
twice. The answered case is recorded in a ref instead. Pressing a
control runs `onDecision` first, which sets `answeredRef` and then
`asking` to "second", thereby closing this sheet and firing
`onOpenChange(false)` with the ref already true, so this handler
consumes the flag and skips the return. A close the reader drove
leaves the ref false and returns them to the page. A reader who
wants question two can press the trigger again; in a real product
it would be asked at the moment it became relevant. */
if (answeredRef.current) {
answeredRef.current = false
return
}
setAsking("none")
setReturns((count) => count + 1)
}}
consentId="example-consent-first"
textVersion="example-wording-0"
heading="Placeholder question one. Is this the first example thing?"
purpose="Placeholder for the first purpose. In a product this sentence says what the reader gets."
scope={FIRST_SCOPE}
withdrawalPath="Placeholder for where a reader changes this first decision later."
acceptLabel="Yes, to the first example thing"
declineLabel="No, not the first example thing"
onDecision={(decision) => {
setAnswers((current) => ({
...current,
[decision.consentId]: decision.granted ? "granted" : "declined",
}))
/* Record that this close is an answer before opening the next sheet,
so the `onOpenChange` this triggers does not treat it as the reader
leaving and does not return focus while the second sheet is opening. */
answeredRef.current = true
setAsking("second")
}}
/>
<ConsentSheet
open={asking === "second"}
onOpenChange={(nextOpen) => {
if (nextOpen) return
setAsking("none")
setReturns((count) => count + 1)
}}
consentId="example-consent-second"
textVersion="example-wording-0"
heading="Placeholder question two. Is this the second example thing?"
purpose="Placeholder for the second purpose, which is a different purpose and therefore a different question."
scope={SECOND_SCOPE}
withdrawalPath="Placeholder for where a reader changes this second decision later."
consequenceOfDeclining="Placeholder for what a reader loses by saying no to this one. It is stated here, before they choose, and never raised as a confirmation afterwards."
acceptLabel="Yes, to the second example thing"
declineLabel="No, not the second example thing"
onDecision={(decision) => {
setAnswers((current) => ({
...current,
[decision.consentId]: decision.granted ? "granted" : "declined",
}))
setAsking("none")
setReturns((count) => count + 1)
}}
/>
</div>
)
}Example
NOT IMPLEMENTED. The opsinjs component `consent-flow` does not exist in any released version of opsinjs. There is no package to install, no module to import and no props interface to generate code against. Everything on this page is a specification of intended behaviour and may change without notice. Do not write code against it.
consent-flow is not built yet
/view/base/base-lyra/screen/consent-flow?mode=light, which renders under the product theme rather than the documentation chrome. There is nothing at that address yet.PlannedRoadmapWhat “planned” means
/view/base/base-lyra/screen/consent-flow?mode=lightThe whole-screen flow is not built yet, so the frame shows only its placeholder. The ConsentSheet example above is the shipped specimen.
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
- 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, Escape closes it with no answer given, and focus returns to the opener.
- Nothing times out, auto-advances or dismisses itself.