Use user

Overview

useUser is the primary hook for interacting with the currently authenticated user’s profile. It provides the user’s full data (as an AuthUser), loading and error states, an updateUser action, and derived suspension state (isSuspended / activeSuspension). Updates are applied optimistically — the UI reflects changes immediately, and reverts automatically if the server request fails.

Usage Example

import { useUser } from "@sublay/react-js";

function ProfileEditor() {
  const { user, updating, updateUser } = useUser();

  const handleSave = async () => {
    await updateUser({ name: "Jane Doe", bio: "Building cool things." });
  };

  if (!user) return null;

  return (
    <div>
      <p>{user.name}</p>
      <button onClick={handleSave} disabled={updating}>
        Save
      </button>
    </div>
  );
}

Uploading an Avatar

import { useUser } from "@sublay/react-js";

function AvatarUpload({ file }: { file: File }) {
  const { updateUser } = useUser();

  const handleUpload = async () => {
    await updateUser({
      avatar: {
        file,
        options: { width: 200, height: 200, fit: "cover" },
      },
    });
  };

  return <button onClick={handleUpload}>Upload Avatar</button>;
}

Return Values

user

AuthUser | null

The authenticated user’s full profile. Returns null while loading or when no user is authenticated. See User data model.

boolean

true while the user’s profile is being fetched for the first time.

updating

boolean

true while an updateUser call is in progress.

error

string | null

Error message if an updateUser call fails. null when there is no error.

isSuspended

boolean

true while the authenticated user has an active suspension. Derived from the user’s suspensions using the same effective definition as the server.

activeSuspension

{ reason: string | null; startDate: string; endDate: string | null } | null

The user’s effective (furthest-reaching) active suspension, or null when they aren’t suspended. endDate: null means the suspension is indefinite. Bind a “suspended until X” banner or a disabled composer to this. See Suspensions.

updateUser

(update: UpdateUserParams) => Promise<AuthUser>

Updates the authenticated user’s profile. Applies optimistic updates immediately and reverts on failure.

Show UpdateUserParams fields

name

string | null

Display name. Pass null to clear.

username

string | null

Unique username. Pass null to clear. Must be available.

bio

string

Short biography. Limited to 300 characters.

birthdate

Date | null

Date of birth. Pass null to clear.

avatar

string | null | { file: File | Blob; options: UploadImageOptions }

Avatar image. Pass a URL string, a file object with upload options, or null to remove.

banner

{ file: File | Blob; options: UploadImageOptions }

Banner image. File upload only.

location

{ latitude: number; longitude: number } | null

User’s geographic location. Pass null to clear.

metadata

Record<string, any>

Arbitrary project-specific data. Limited to 10 KB. Visible to other users (embedded in entity and comment data).

secureMetadata

Record<string, any>

Private custom fields excluded from all client-facing responses, including the authenticated user’s own profile. Stored server-side only — use it for data you need to persist but never expose to any client.

clearError

() => void

Clears the current error state.

Optimistic Updates

updateUser applies changes to local state before the server responds. This makes the UI feel instant. Fields that cannot be optimistically applied (file uploads, location) wait for the server response. If the server returns an error, the hook automatically reverts the user state to its pre-update value.

File uploads (avatar as a File/Blob, and banner) are not applied optimistically because the final URL is unknown until the upload completes.

Confirm account deletion Use user actions

Overview

Auth Hooks

Current User

User Profiles

Entities

Entity Lists

Spaces

Spaces — Rules

Space Lists

Events

Comments

Reactions

Follows

Connections

Collections

App Notifications

Push Notifications

Chat — Conversations

Chat — Messages

Chat — Core

Search

Reports

Storage

Crypto

Project

Custom Tables

Overview

Usage Example

Uploading an Avatar

Return Values

Optimistic Updates

​Overview

​Usage Example

​Uploading an Avatar

​Return Values

​Optimistic Updates

Overview

Usage Example

Uploading an Avatar

Return Values

Optimistic Updates