Hooks, Components & Types
The complete exported Auth package surface, with arguments and return values.
Auth React API
Import runtime values and types from @forgewp/auth. Configuration defaults live in the theme's compiler configuration, not in a separate Auth config import.
Hooks and helpers
Export Signature and behavior useWpAuthuseWpAuth() returns actions/status listed below; it does not return useruseWpUseruseWpUser(): WpUser | nulluseWpCapabilityuseWpCapability(capability: string): booleanuseWpPageProtectuseWpPageProtect(config: WpPageConfig): void; client redirect hookstripHtmlstripHtml(text: any): string | null; removes tag-shaped text, returns null for non-strings |
|---|
stripHtml is a text-display convenience, not a complete HTML sanitizer or server-validation API. Render error/notice strings as text.
Actions returned by useWpAuth
Action Arguments Return logincredential: string, password: string, redirectUrl?: string Promise logoutnone Promise registerusername: string, email: string, password: string, metadata?: Record<string, any> Promise verifyEmailuserId: number, token: string Promise resendVerificationEmailemail: string; generated server also accepts a username Promise forgotPasswordlogin: string Promise resetPasswordlogin: string, key: string, pass: string Promise |
|---|
Status returned by useWpAuth
Property Meaning loadingAn account action is running initializingInitial session setup is running errorCurrent action error text or null noticeAccount-created instructions/feedback or null loginFieldusernameOnly, emailOnly, or usernameAndEmail emailVerificationEnabledVerification policy available to the current runtime |
|---|
Read status during rendering rather than expecting an already-captured value to update inside an async callback. A successful register() can leave the visitor signed out; logout() has no success boolean.
Components
Export Props WpAuthProviderchildren: ReactNode; loginField?: usernameOnly | emailOnly | usernameAndEmail WpAuthGatechildren: ReactNode; fallback?: ReactNode, default null WpCapabilityGateallowed: string; children: ReactNode; fallback?: ReactNode, default null WpLoginFormclassName?: string; onSuccess?: () => void WpRegisterFormclassName?: string; onSuccess?: () => void WpPasswordResetFormclassName?: string; onSuccess?: () => void; requests a recovery link |
|---|
Use one provider above related forms, user displays, and actions. The login and registration forms return no interface without a provider. The recovery form can use the standalone hook path, but the same shared-provider setup is recommended for a consistent account interface.
Context and types
WpAuthContext is the exported React.Context<WpAuthContextType | null>. WpAuthProvider is the usual way to supply it; replacing the context yourself means implementing the complete action/state contract.
Type export Fields WpUserRequired: id, username, email, displayName, roles, avatarUrl. Optional: firstName, lastName, capabilities, emailVerified, billing, shipping, metadata, meta WpAuthContextTypeuser, loading, initializing, error; optional notice/loginField/emailVerificationEnabled; all seven account actions listed above WpPageConfigprotected?: boolean, redirect?: string, allowed?: string |
|---|
billing and shipping are optional address-shaped compatibility fields, not a promise that Auth creates commerce records. billing can contain first_name, last_name, company, address_1, address_2, city, state, postcode, country, email, phone; shipping has the same address fields and phone but no email member. metadata and meta are optional arbitrary records. Available user payload fields depend on the server/integration that supplied them.
For normal UI, treat useWpUser() as profile/display state and leave authorization decisions to the server. Decoding a browser token does not validate its signature or permissions.