Components

In-depth component reference: UI building blocks, required props, customization options, and composition patterns for the Humanity React SDK.

All components must be rendered inside a HumanityProvider.

HumanityProvider

The root context provider. Wrap your entire application with it.

import { HumanityProvider } from '@humanity-org/react-sdk';

<HumanityProvider
  clientId="hp_xxx"
  redirectUri="https://app.com/callback"
  environment="production"
  storage="memory"
  theme="system"
  onError={(err) => console.error(err)}
>
  <App />
</HumanityProvider>

Props

Prop	Type	Default	Description
clientId	string	required	Your Humanity application client ID.
redirectUri	string	required	OAuth callback URI registered in the Developer Portal.
environment	'production' 'sandbox'	'production'	Which Humanity API environment to target.
storage	'memory' 'localStorage' 'sessionStorage'	'memory'	Token storage strategy. memory is most secure — tokens are cleared on page refresh.
theme	'light' 'dark' 'system'	'system'	Controls built-in component theming. system follows the OS preference.
baseUrl	string	—	Advanced: override the API base URL (e.g. for proxies or custom environments).
onError	(error: HumanityReactError) => void	—	Global error handler called for any auth or verification error across all child components.

---

HumanityConnect

OAuth login button that handles the full authentication flow.

import { HumanityConnect } from '@humanity-org/react-sdk';

<HumanityConnect
  scopes={['openid', 'profile', 'identity:read']}
  mode="popup"
  variant="primary"
  size="md"
  label="Sign in with Humanity"
  onSuccess={(result) => handleLogin(result)}
  onError={(error) => console.error(error)}
/>

Props

Prop	Type	Default	Description
scopes	string[]	['openid', 'profile']	OAuth scopes to request.
mode	'popup' 'redirect'	'popup'	OAuth flow type. Use redirect if popups are blocked.
onSuccess	(result: AuthResult) => void	—	Called after successful authentication.
onError	(error: HumanityReactError) => void	—	Called on authentication error.
onLoading	(loading: boolean) => void	—	Called when loading state changes.
variant	'primary' 'secondary' 'outline'	'primary'	Button visual variant.
size	'sm' | 'md' | 'lg'	'md'	Button size.
label	string	'Sign in with Humanity'	Button label text.
disabled	boolean	false	Disable the button.
className	string	—	Additional CSS class.
style	React.CSSProperties	—	Inline styles.
children	React.ReactNode	—	Custom children — replaces default button content.

---

HumanityVerify

One-click verification button for a single preset.

import { HumanityVerify } from '@humanity-org/react-sdk';

<HumanityVerify
  preset="ageOver21"
  onVerified={(result) => {
    if (result.verified) grantAccess();
  }}
/>

Props

Prop	Type	Default	Description
preset	string	required	Preset key to verify (e.g. 'ageOver21', 'kycPassed').
onVerified	(result: VerificationResult) => void	—	Called after verification completes.
onError	(error: HumanityReactError) => void	—	Called on verification error.
label	string	—	Custom button label.
variant	'primary' | 'secondary' | 'outline'	'primary'	Button visual variant.
size	'sm' | 'md' | 'lg'	'md'	Button size.
autoVerify	boolean	false	Trigger verification automatically on mount.

---

HumanityGate

Conditionally renders children when a preset is verified; shows fallback otherwise.

import { HumanityGate } from '@humanity-org/react-sdk';

<HumanityGate
  preset="kycPassed"
  fallback={<CompleteKYC />}
  loadingFallback={<Spinner />}
>
  <SecureContent />
</HumanityGate>

Multi-preset gate (AND logic):

<HumanityGate
  presets={['ageOver18', 'kycPassed']}
  requireAll={true}
  fallback={<VerificationRequired />}
>
  <RestrictedContent />
</HumanityGate>

Props

Prop	Type	Default	Description
preset	string	—	Single preset key. Gate passes when verified.
presets	string[]	—	Multiple presets. Use with requireAll for AND/OR logic.
requireAll	boolean	true	true: all presets must pass. false: any one is enough.
fallback	React.ReactNode	—	Rendered when the gate condition is not met.
loadingFallback	React.ReactNode	—	Rendered while verification is in progress.

Use either preset (single) or presets (multiple), not both.

---

HumanityProfile

Displays the authenticated user's profile with optional verification badges.

import { HumanityProfile } from '@humanity-org/react-sdk';

<HumanityProfile
  variant="card"
  showAvatar={true}
  showBadges={true}
  showFields={['email', 'humanity_score']}
/>

Props

Prop	Type	Default	Description
variant	'card' | 'inline' | 'minimal'	'card'	Display variant.
showAvatar	boolean	true	Show user avatar.
showBadges	boolean	true	Show verification badges.
showFields	string[]	—	Profile fields to display.
className	string	—	Additional CSS class.

---

HumanityErrorBoundary

React error boundary for catching and displaying errors within the Humanity component tree.

import { HumanityErrorBoundary } from '@humanity-org/react-sdk';

<HumanityErrorBoundary
  fallback={(error) => <p>Something went wrong: {error.message}</p>}
  onError={(error, info) => Sentry.captureException(error)}
>
  <HumanityConnect />
</HumanityErrorBoundary>

Props

Prop	Type	Description
fallback	(error: Error) => React.ReactNode	Render function for the error state.
onError	(error: Error, info: React.ErrorInfo) => void	Called when a child component throws.
children	React.ReactNode	The component tree to protect.

Wrap authentication-critical UI with HumanityErrorBoundary as a best practice. See Error Handling for the full pattern.

---

Theming

Customize component appearance with CSS variables:

:root {
  --humanity-primary: #000000;
  --humanity-primary-hover: #222222;
  --humanity-success: #10b981;
  --humanity-error: #ef4444;
  --humanity-border-radius: 8px;
  --humanity-font-family: inherit;
}

Set theme="dark" or theme="light" on HumanityProvider to control the built-in theme. theme="system" (default) follows the OS preference.