Use entities

Stateful, paginated entity feed with sorting and filtering

Overview

useFetchManyEntitiesWrapper is a stateful wrapper around useFetchManyEntities that manages pagination, sorting, and list state for you. Use it when you need a custom entity feed outside of EntityListProvider — for example, a user profile feed, a filtered search results page, or any custom list with infinite scroll.

All filters and sort options mirror those of useFetchManyEntities. Changing any sort option automatically resets the list and re-fetches from page 1.

Usage Example

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

function UserFeed({ userId }: { userId: string }) {
  const {
    entities,
    loading,
    hasMore,
    sortBy,
    setSortBy,
    loadMore,
  } = useFetchManyEntitiesWrapper({
    userId,
    limit: 15,
    defaultSortBy: "createdAt",
    include: ["user"],
  });

  return (
    <div>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="createdAt">Newest</option>
        <option value="top">Top</option>
        <option value="hot">Hot</option>
      </select>
      <ul>
        {entities.map((entity) => (
          <li key={entity.id}>{entity.title}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}

Parameters

limit · number

Number of entities per page. Default: 10.

userId · string | null

Filter to entities created by a specific user.

sourceId · string | null

Filter to entities associated with a specific source ID.

spaceId · string | null

Filter to entities in a specific space.

followedOnly · boolean

If true, return only entities from users the authenticated user follows.

include · EntityIncludeParam

Populate related fields. Accepted values: "user", "space", "topComment", "saved", "files".

defaultSortBy · EntityListSortByOptions

Initial sort field. Default: "createdAt".

defaultSortByReaction · SortByReaction

Initial reaction type to sort by when sortBy is reaction-based. Default: "upvote".

defaultSortDir · "asc" | "desc"

Initial sort direction. Default: "desc".

defaultSortType · SortType

Initial sort algorithm. Options: "auto", "numeric", "text", "boolean", "timestamp". Used when sorting by a metadata field. Default: "auto".

timeFrame · TimeFrame | null

Filter entities to a time window. Options: "day", "week", "month", "year".

keywordsFilters · KeywordsFilters | null

Filter by keywords. See Entity List Filters.

titleFilters · TitleFilters | null

Filter by title content. See Entity List Filters.

contentFilters · ContentFilters | null

Filter by body content. See Entity List Filters.

attachmentsFilters · AttachmentsFilters | null

Filter by attachments data. See Entity List Filters.

locationFilters · LocationFilters | null

Filter by geographic proximity. See Entity List Filters.

metadataFilters · MetadataFilters | null

Filter by metadata fields. See Entity List Filters.

Returns

entities · Entity[]

The current list of fetched entities. Appended to on each loadMore call.

loading · boolean

true while fetching the initial page or loading more.

hasMore · boolean

true if additional pages are available.

sortBy · EntityListSortByOptions

Current sort field.

sortByReaction · SortByReaction

Current reaction type used for reaction-based sorting.

sortDir · "asc" | "desc"

Current sort direction.

sortType · SortType

Current sort algorithm.

setSortBy · (sortBy: EntityListSortByOptions) => void

Change the sort field. Resets the list and re-fetches from page 1.

setSortByReaction · (sortByReaction: SortByReaction) => void

Change the reaction type for reaction-based sorting. Resets and re-fetches.

setSortDir · (sortDir: 'asc' | 'desc') => void

Change the sort direction. Resets the list and re-fetches from page 1.

setSortType · (sortType: SortType) => void

Change the sort algorithm. Resets the list and re-fetches from page 1.

loadMore · () => void

Load the next page of entities. Appends to the existing list.