Use user

Access and update the authenticated user’s own profile

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, and an updateUser action.

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.

loading · 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.

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.