> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use entities

> Stateful, paginated entity feed with sorting and filtering

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/v8/bundles).
</Note>

## Overview

`useFetchManyEntitiesWrapper` is a stateful wrapper around [`useFetchManyEntities`](/v8/hooks/entities/use-fetch-many-entities) 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

```tsx theme={null}
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

<ParamField body="limit" type="number" optional>
  Number of entities per page. Default: `10`.
</ParamField>

<ParamField body="userId" type="string | null" optional>
  Filter to entities created by a specific user.
</ParamField>

<ParamField body="sourceId" type="string | null" optional>
  Filter to entities associated with a specific source ID.
</ParamField>

<ParamField body="spaceId" type="string | null" optional>
  Filter to entities in a specific space.
</ParamField>

<ParamField body="followedOnly" type="boolean" optional>
  If `true`, return only entities from users the authenticated user follows.
</ParamField>

<ParamField body="include" type="EntityIncludeParam" optional>
  Populate related fields. Accepted values: `"user"`, `"space"`, `"topComments"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

<ParamField body="topCommentsLimit" type="number" optional>
  With `"topComments"` included: how many top comments per entity. Server default `1`, maximum `5`. Not sent when `include` doesn't contain `"topComments"`.
</ParamField>

<ParamField body="topCommentsSortByReaction" type="ReactionType" optional>
  With `"topComments"` included: the reaction whose raw count ranks the top comments. Server default `"upvote"`. Not sent when `include` doesn't contain `"topComments"`.
</ParamField>

<ParamField body="defaultSortBy" type="EntityListSortByOptions" optional>
  Initial sort field. Default: `"createdAt"`.
</ParamField>

<ParamField body="defaultSortByReaction" type="SortByReaction" optional>
  Initial reaction type `top` ranks by. Only sent while `sortBy` is `"top"`. Default: `"upvote"`.
</ParamField>

<ParamField body="defaultSortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;" optional>
  Initial sort direction. Default: `"desc"`.
</ParamField>

<ParamField body="defaultSortType" type="SortType" optional>
  Initial sort algorithm. Options: `"auto"`, `"numeric"`, `"text"`, `"boolean"`, `"timestamp"`. Used when sorting by a metadata field. Default: `"auto"`.
</ParamField>

<ParamField body="timeFrame" type="TimeFrame | null" optional>
  Filter entities to a time window. Options: `"day"`, `"week"`, `"month"`, `"year"`.
</ParamField>

<ParamField body="keywordsFilters" type="KeywordsFilters | null" optional>
  Filter by keywords. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

<ParamField body="titleFilters" type="TitleFilters | null" optional>
  Filter by title content. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

<ParamField body="contentFilters" type="ContentFilters | null" optional>
  Filter by body content. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

<ParamField body="attachmentsFilters" type="AttachmentsFilters | null" optional>
  Filter by attachments data. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

<ParamField body="locationFilters" type="LocationFilters | null" optional>
  Filter by geographic proximity. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

<ParamField body="metadataFilters" type="MetadataFilters | null" optional>
  Filter by metadata fields. See [Entity List Filters](/v8/sdk/entity-lists/filters).
</ParamField>

## Returns

<ResponseField name="entities" type="Entity[]">
  The current list of fetched entities. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="sortBy" type="EntityListSortByOptions">
  Current sort field.
</ResponseField>

<ResponseField name="sortByReaction" type="SortByReaction">
  Current reaction type `top` ranks by. Only sent while `sortBy` is `"top"`.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction.
</ResponseField>

<ResponseField name="sortType" type="SortType">
  Current sort algorithm.
</ResponseField>

<ResponseField name="setSortBy" type="(sortBy: EntityListSortByOptions) => void">
  Change the sort field. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="setSortByReaction" type="(sortByReaction: SortByReaction) => void">
  Change the reaction type for reaction-based sorting. Resets and re-fetches.
</ResponseField>

<ResponseField name="setSortDir" type="(sortDir: 'asc' | 'desc') => void">
  Change the sort direction. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="setSortType" type="(sortType: SortType) => void">
  Change the sort algorithm. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of entities. Appends to the existing list.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.