Skip to main content

​
useBasic

The useBasic hook is used to access authentication, database, and other Basic features. Any of these properties can be accessed by destructuring the useBasic hook.

​
Auth State

​
isReady

​
isReady
boolean
Boolean that indicates when auth state has been determined. Use this as a loading state for your app while auth is being verified.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { isReady, isSignedIn } = useBasic()

  if (!isReady) return <div>Loading...</div>

  return (
    <div>{isSignedIn ? "User is signed in" : "User is signed out"}</div>
  )
}
isAuthReady is a deprecated alias for isReady and will be removed in a future version.

​
isSignedIn

​
isSignedIn
boolean
Boolean that checks if a user is signed in. Only use after isReady is true.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { isReady, isSignedIn } = useBasic()

  return (
    <>
      {isReady ? 
        <div>{isSignedIn ? "User is signed in" : "User is signed out"}</div> :
        <div>Loading...</div>
      }
    </>
  )
}

​
user

​
user
User | null
The current user object containing the user’s ID, email, and name. Returns null when not signed in.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { user } = useBasic()

  console.log("Fetch user ID: ", user?.id)
  console.log("Fetch user email: ", user?.email)
  console.log("Fetch user name: ", user?.name)

  return (
    <>
      {/* render items */}
    </>
  )
}
User type:
type User = {
  id?: string
  email?: string
  name?: string
  fullName?: string
  primaryEmailAddress?: { emailAddress: string }
}

​
Auth Methods

​
signIn

​
signIn
() => Promise<void>
Function to sign a user in via the Basic OAuth flow. It will redirect the user to the Basic login page, and then redirect them back to the page they were on.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signIn } = useBasic()

  return (
    <>
      <button onClick={signIn}>Sign in</button>
    </>
  )
}
signin (lowercase) is a deprecated alias for signIn and will be removed in a future version.

​
signOut

​
signOut
() => Promise<void>
Function to sign a user out. User remains on your page after signing out, but isSignedIn will be set to false until they sign in again.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signOut } = useBasic()

  return (
    <>
      <button onClick={signOut}>Sign out</button>
    </>
  )
}
signout (lowercase) is a deprecated alias for signOut and will be removed in a future version.

​
signInWithCode

​
signInWithCode
(code: string, state?: string) => Promise<AuthResult>
Function to complete authentication using an OAuth authorization code. Useful for custom OAuth flows or React Native apps where you handle the redirect manually.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { signInWithCode } = useBasic()

  const handleOAuthCallback = async (code: string, state: string) => {
    const result = await signInWithCode(code, state)
    if (result.success) {
      console.log('Signed in successfully!')
    } else {
      console.error('Sign in failed:', result.error)
    }
  }

  return <>{/* OAuth callback handling */}</>
}
AuthResult type:
type AuthResult = {
  success: boolean
  error?: string
  code?: string
}

​
getToken

​
getToken
() => Promise<string>
Fetches the user’s JWT access token. The token is automatically refreshed if expired. Use this for making authenticated API calls to your own backend.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { getToken } = useBasic()

  const fetchFromMyAPI = async () => {
    const token = await getToken()
    const response = await fetch('/api/my-endpoint', {
      headers: { 'Authorization': `Bearer ${token}` }
    })
    return response.json()
  }

  return (
    <>
      <button onClick={async () => console.log(await getToken())}>Get token</button>
    </>
  )
}

​
getSignInUrl

​
getSignInUrl
(redirectUri?: string) => Promise<string>
Returns the OAuth sign-in URL without redirecting. Useful for custom sign-in flows, React Native apps, or opening in a popup/modal.
App.tsx
import { useBasic } from '@basictech/react'

function App() {
  const { getSignInUrl } = useBasic()

  const handleCustomSignIn = async () => {
    const url = await getSignInUrl()
    // Open in popup, new tab, or handle as needed
    window.open(url, '_blank')
  }

  return <button onClick={handleCustomSignIn}>Custom Sign In</button>
}
getSignInLink is a deprecated alias for getSignInUrl and will be removed in a future version.

​
Database

​
db

​
db
BasicDB
The database object, which you can use to read, add, update, and delete items.

​
dbStatus

​
dbStatus
string
The current status of the database connection. Possible values are:
  • 'LOADING' - Database is initializing
  • 'CONNECTING' - Attempting to connect to sync server
  • 'ONLINE' - Connected and syncing
  • 'SYNCING' - Actively syncing data
  • 'OFFLINE' - No network connection (still works locally)
  • 'ERROR_WILL_RETRY' - Non-fatal error, will automatically retry
  • 'ERROR' - Fatal error occurred
    App.tsx
    import { useBasic } from '@basictech/react'

function App() {
  const { dbStatus } = useBasic()

  return (
    <div>
      Database status: {dbStatus}
      {dbStatus === 'OFFLINE' && <span> (Working offline)</span>}
    </div>
  )
}

​
dbMode

​
dbMode
'sync' | 'remote'
The current database mode. See Database Modes for details.
  • 'sync' - Local-first with IndexedDB + real-time WebSocket sync (default)
  • 'remote' - Direct REST API calls to server

​
useQuery

The useQuery hook is used to “subscribe” to data from the database, so that your component automatically re-renders when the data changes. It enables real-time sync between the local database, users’ devices, and all other users connected to the same database.
useQuery only works in sync mode. In remote mode, use regular async/await patterns instead.
We use it primarily to wrap our .get() and .getAll() functions, and it takes a function as an argument. 
import { useBasic, useQuery } from '@basictech/react'

function App() {
  const { db } = useBasic()

  // Example 1: Fetch a single item from the table
  const item = useQuery(() => db.collection('tablename').get('ID_OF_ITEM'))

  // Example 2: Fetch all items from the table
  const items = useQuery(() => db.collection('tablename').getAll())

  return (
    // render items
  )
}
The default value is an empty array [] while data is loading. This may change in a future version.