Permission Primer

Pro

Explainer screen shown before a system permission prompt, featuring a dimmed picture of what you’re asking for. Allowing brings it to life; a denial shows clear steps to turn it on in Settings.

Preview

Installation

npx @lumioui/cli add pro/permission-primer

Usage

import { PermissionPrimer } from "@/components/ui/permission-primer/permission-primer";
<PermissionPrimer />

Examples

Camera

An expense app asking for the camera the first time you tap Scan receipt.

API reference

Prop Type Default
title* string —
text* string }[] —
icon React.ReactNode

Icon shown in a tile when there is no preview.

 —
preview
React.ReactNode | ((state: PermissionPre … React.ReactNode | ((state: PermissionPreviewState) => React.ReactNode)

The feature being unlocked, shown dim until allowed. Pass a function to render its live state once granted.

 —
description string —
points { icon: IconName

Benefit rows under the description.

 —
permissionName string

What is being asked for, e.g. "Notifications". Labels the status badge and the default Settings copy.

 —
appName string

App name used in the default Settings steps.

 —
status PermissionStatus

Current system status, when you track it. A change to "granted" brightens the preview; "denied"/"blocked" shows the Settings path.

 —
onRequest
() => PermissionRequestResult … () => PermissionRequestResult | Promise<PermissionRequestResult>

Shows the system prompt and resolves with the answer. Without it, Allow counts as granted (the prompt is left to onEnable).

 —
onRecheck
() => PermissionStatus … () => PermissionStatus | Promise<PermissionStatus>

Called when the app returns to the foreground while the Settings path is showing; resolve with the fresh status.

 —
onOpenSettings () => void

Open the system settings. Default Linking.openSettings().

 —
enableLabel string

Allow button copy. Default "Enable".

 "Enable"
enabledLabel string

The button's result label once granted (e.g. "Reminders on").

 —
dismissLabel string

Dismiss copy. Default "Not now".

 "Not now"
fallbackNote string

A quiet line shown after "Not now" — where to turn it on later.

 —
settingsTitle string

Settings path title. Default "Turn on <permission> in Settings".

 —
settingsDescription string

Settings path explanation.

 —
settingsSteps string[]

Settings path steps. Default: Open Settings → app → switch on.

 —
settingsLabel string

Settings action copy. Default "Open Settings".

 "Open Settings"
onEnable () => void

Fires after the granted state has held (~700ms).

 —
onDismiss () => void —
pulse boolean

@deprecated No longer animates. Kept so existing calls still compile.

 —
className string —