> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.
# React
> Client-side React integration with Timeback
## Overview
The Timeback SDK provides React hooks, components, and a context provider for client-side integration.
If you are using coding agents, pair this page with [`timeback-client`](https://github.com/superbuilders/timeback-sdk-skills/tree/main/skills/timeback/timeback-client) from the [AI Skills](/beta/build-on-timeback/ai/skills) catalog.
## Installation
```bash npm theme={null}
npm install @timeback/sdk
```
```bash pnpm theme={null}
pnpm add @timeback/sdk
```
```bash yarn theme={null}
yarn add @timeback/sdk
```
```bash bun theme={null}
bun add @timeback/sdk
```
## Provider Setup
Wrap your app with `TimebackProvider`:
```tsx app/providers.tsx theme={null}
'use client'
import { TimebackProvider } from '@timeback/sdk/react'
export function Providers({ children }: { children: React.ReactNode }) {
return {children}
}
```
```tsx app/layout.tsx theme={null}
import { Providers } from './providers'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
## Hooks
### `useTimeback`
Access the Timeback client:
```tsx theme={null}
import { useTimeback } from '@timeback/sdk/react'
function MyComponent() {
const timeback = useTimeback()
// timeback is null if user is not authenticated
if (!timeback) {
return
Please sign in
}
return
Welcome!
}
```
### `useTimebackVerification`
Check authentication status:
```tsx theme={null}
import { useTimebackVerification } from '@timeback/sdk/react'
function ProtectedRoute({ children }) {
const { state, refresh } = useTimebackVerification()
if (state.status === 'loading') return
Loading...
if (state.status !== 'verified') return
return children
}
```
The `state` object has a `status` property that can be:
* `'loading'` - Verification in progress
* `'verified'` - User is verified (includes `timebackId`)
* `'unverified'` - User is not verified
* `'error'` - Verification failed (includes `message`)
### `useTimebackProfile`
Fetch user profile data:
```tsx theme={null}
import { useTimebackProfile } from '@timeback/sdk/react'
// Manual fetch
function ProfileButton() {
const { state, canFetch, fetchProfile } = useTimebackProfile()
if (state.status === 'loaded') {
return (
Welcome, {state.profile.name}
XP Today: {state.profile.xp.today}
Total XP: {state.profile.xp.all}
)
}
return (
)
}
// Auto-fetch when authenticated
function AutoProfile() {
const { state } = useTimebackProfile({ auto: true })
if (state.status === 'loading') return
)
}
```
#### Props
Button size
Button style variant
Show loading spinner on click
Show Timeback logo
Disable the button
Additional CSS classes
Inline styles
Additional click handler
Button text
## Custom Activities
The SDK supports two [activity models](/beta/about-timeback/concepts/activity-models) that capture how students spend time in your app and whether they complete what they started, producing [TimeSpentEvents](/beta/build-on-timeback/reference/events#timespentevent) and [ActivityCompletedEvents](/beta/build-on-timeback/reference/events#activitycompletedevent) that feed into dashboards, XP, and learning analytics.
### Single-session
A quiz, flashcard deck, or short lesson that a student completes in one sitting. The client tracks time and reports completion. Learn more about [single-session activities](/beta/build-on-timeback/sdk/activity-tracking/single-session).
### Stateful
A multi-part course or long-form project where students leave and come back across multiple sessions. The client tracks time per visit while the server records completion. Learn more about [stateful activities](/beta/build-on-timeback/sdk/activity-tracking/stateful).
## Next Steps
Server-side setup
Learn more about tracking