Use entity list

Manage a paginated entity feed with filtering, sorting, and infinite scroll

Overview

useEntityList is the primary hook for building entity feeds. Each call receives a unique listId that namespaces its Redux state, so multiple independent lists can coexist on the same page.

See Fetching Entities for a full guide on using this hook.

Usage Example

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

function Feed() {
  const {
    entities,
    loading,
    hasMore,
    fetchEntities,
    loadMore,
  } = useEntityList({ listId: "main-feed" });

  useEffect(() => {
    fetchEntities({}, { sortBy: "hot" }, { limit: 20, include: ["user"] });
  }, []);

  return (
    <>
      {entities.map((e) => <div key={e.id}>{e.title}</div>)}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}

Props

listId · string · required

Unique identifier for this list. Used to namespace Redux state. Must be stable across renders.

infuseData · (foreignId: string) => Promise<Record<string, any> | null>

Optional. A function called for each entity with a foreignId. Its result is merged into the entity under an infusion key. See Infusing Data.

Reputation

The config object passed to fetchEntities accepts two optional reputation fields that opt each row’s embedded author into an added spaceReputation number. See Reputation.

config.spaceReputationId · string

Resolves each row’s embedded author reputation into a spaceReputation number. Accepts a space <uuid>, "none" (project-general bucket), or "context" (server-derived per row from the request context — useful for mixed-space feeds). Empty string, "general", and null are rejected.

config.spaceReputationDescendants · boolean

When true, spaceReputation is the subtree sum (the space plus all its descendants). Only honored when spaceReputationId is an explicit <uuid>.

Return Values

entities · Entity[]

The current list of loaded entities.

infusedEntities · (Entity & { infusion: Record<string, any> })[]

Entities merged with data from infuseData. Empty array if infuseData was not provided.

loading · boolean

true while a fetch or load-more is in progress.

hasMore · boolean

true when there are more pages to load.

fetchEntities · (filters, sort?, config?, options?) => void

Loads the first page with the given filters, sort, and config. Debounced by default (800ms). See Fetching Entities for the full parameter reference.

loadMore · () => void

Appends the next page of results. Must be called after fetchEntities has been invoked at least once.

createEntity · (props: EntityListCreateEntityProps) => Promise<Entity | undefined>

Creates a new entity and inserts it into the list. Accepts the same fields as useCreateEntity, plus insertPosition: "first" | "last".

deleteEntity · (props: { entityId: string }) => Promise<void>

Deletes an entity and removes it from the local list state.

sortBy · "createdAt" | "hot" | "top" | "controversial" | "metadata.field" | null

Current sort algorithm.

sortByReaction · "upvote" | "downvote" | "like" | "love" | "wow" | "sad" | "angry" | "funny" | null

Current reaction sort type (used when sortBy is "top").

sortDir · "asc" | "desc" | null

Current sort direction.

sortType · "auto" | "numeric" | "text" | "boolean" | "timestamp" | null

Current sort type hint for metadata sorts.

timeFrame · "day" | "week" | "month" | "year" | null

Active time frame filter.

sourceId · string | null

Active source ID filter (from config).

userId · string | null

Active user ID filter.

followedOnly · boolean

Whether the followed-only filter is active.

keywordsFilters · KeywordsFilters | null

Active keywords filter.

titleFilters · TitleFilters | null

Active title filter.

contentFilters · ContentFilters | null

Active content filter.

attachmentsFilters · AttachmentsFilters | null

Active attachments filter.

locationFilters · LocationFilters | null

Active location filter.

metadataFilters · MetadataFilters | null

Active metadata filter.