Hooks
usePlacement
A React hook that registers a placement so it can remotely trigger a paywall, gate feature access, and expose paywall-lifecycle state.
Purpose
Registers a placement so that, when it’s added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature while exposing the paywall lifecycle as React state.
Signature
function usePlacement(callbacks?: usePlacementCallbacks): {
/** Registers the placement and potentially presents a paywall. */
registerPlacement: (args: RegisterPlacementArgs) => Promise<void>;
/** Current paywall-lifecycle state. */
state: PaywallState;
};Parameters
Prop
Type
usePlacementCallbacks
Prop
Type
RegisterPlacementArgs
Prop
Type
Returns / State
Prop
Type
PaywallState
Prop
Type
CustomCallback
Prop
Type
CustomCallbackResult
Prop
Type
Usage
import { Button, Text } from "react-native";
import { usePlacement } from "expo-superwall";
export default function PremiumButton() {
const { registerPlacement, state } = usePlacement({
onPresent: (info) => console.log("Paywall presented:", info.name),
onDismiss: (_, result) => console.log("Paywall dismissed:", result.type),
onSkip: (reason) => console.log("Paywall skipped:", reason.type),
onError: (error) => console.error("Paywall error:", error),
onCustomCallback: async (callback) => {
// Handle custom callbacks from the paywall
console.log("Custom callback:", callback.name, callback.variables);
return { status: "success", data: { validated: true } };
},
});
const unlockFeature = async () => {
await registerPlacement({
placement: "MyFeaturePlacement",
feature: () => {
// User was allowed through without a paywall
navigateToPremiumFeature();
},
});
};
return (
<>
<Button title="Unlock Feature" onPress={unlockFeature} />
<Text>Current paywall state: {state.status}</Text>
</>
);
}See also: Present a paywall
How is this guide?