useSteppedBack

Location: src/hooks/useSteppedBack.js

Overview

Manages the "stepped back" feature, which allows a user to temporarily stop seeing a friend's posts without blocking or unfriending them. Unlike blocking, stepping back is private, reversible, sends no notification to the other party, and can optionally have an expiration date.

The hook fetches all stepped-back relationships on mount, auto-restores expired ones, and provides functions to step back from or restore connections with friends.

Signature

function useSteppedBack(userId: string): {
  loading: boolean,
  error: string | null,
  steppedBackFrom: Map<string, { at: Date, until: Date | null, reason: string | null }>,
  stepBackFrom: (friendId: string, options?: { until?: Date | null, reason?: string | null }) => Promise<{ success: boolean, error?: string }>,
  restoreConnection: (friendId: string, silent?: boolean) => Promise<{ success: boolean, error?: string }>,
  isSteppedBackFrom: (friendId: string) => boolean,
  getSteppedBackList: () => Array<{ friendId, at, until, reason }>,
  getSteppedBackIds: () => string[],
  updateSteppedBack: (friendId: string, options?: { until?: Date, reason?: string }) => Promise<{ success: boolean, error?: string }>,
  refetch: () => Promise<void>
}

Parameters

Parameter	Type	Required	Description
userId	string	Yes	The current user's ID

Return Value

Property	Type	Description
loading	boolean	Whether stepped-back data is being loaded
error	string | null	Error message if fetching failed
steppedBackFrom	Map<string, object>	Map of friend IDs to their stepped-back state (at, until, reason)
stepBackFrom	(friendId, options?) => Promise<Result>	Step back from a friend. Options: until (expiration date), reason (private note).
restoreConnection	(friendId, silent?) => Promise<Result>	Restore connection with a friend. If silent is true, no notifications are shown.
isSteppedBackFrom	(friendId) => boolean	Check if the user has stepped back from a specific friend
getSteppedBackList	() => Array	Get a list of all stepped-back friends with their metadata
getSteppedBackIds	() => string[]	Get an array of friend IDs the user has stepped back from (for feed filtering)
updateSteppedBack	(friendId, options?) => Promise<Result>	Update the duration or reason for an existing stepped-back relationship
refetch	() => Promise<void>	Re-fetch stepped-back state from the database

Usage

import { useSteppedBack } from '../hooks/useSteppedBack';

function FriendActions({ userId, friendId }) {
  const { isSteppedBackFrom, stepBackFrom, restoreConnection } = useSteppedBack(userId);

  if (isSteppedBackFrom(friendId)) {
    return (
      <button onClick={() => restoreConnection(friendId)}>
        Restore connection
      </button>
    );
  }

  return (
    <button onClick={() => stepBackFrom(friendId, {
      until: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 1 week
      reason: 'Need some space'
    })}>
      Step back
    </button>
  );
}

Notes

• Expired stepped-back states are automatically restored on mount and checked every hour.
• The reason field is private and only visible to the user who stepped back.
• This is different from blocking: the friendship remains intact, and the other person is not notified.
• The getSteppedBackIds function is useful for filtering posts in the feed.
• Stepped-back state is stored on the friendships table via stepped_back_by, stepped_back_at, stepped_back_until, and stepped_back_reason columns.

---

Last updated: 2026-02-07