Fetching Entities

useEntityList is the main hook for building entity feeds. Each list is identified by a listId, allowing multiple independent lists on the same page.

Basic Setup

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

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

  useEffect(() => {
    fetchEntities(
      {},                         // filters (empty = no filters)
      { sortBy: "hot" },          // sort config
      { limit: 20, include: ["user"] } // list config
    );
  }, []);

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

`fetchEntities` Signature

fetchEntities(
  filters: Partial<EntityListFilters>,
  sort?: Partial<EntityListSort>,
  config?: EntityListConfig,
  options?: EntityListFetchOptions
) => void

Filters

Param	Type	Description
`timeFrame`	`"day" \| "week" \| "month" \| "year"`	Filter by age
`userId`	`string`	Filter to a specific user’s entities
`followedOnly`	`boolean`	Only show entities from users the current user follows
`keywordsFilters`	`KeywordsFilters`	Filter by keywords
`titleFilters`	`TitleFilters`	Filter by title content
`contentFilters`	`ContentFilters`	Filter by body content
`attachmentsFilters`	`AttachmentsFilters`	Filter by attachments data
`locationFilters`	`LocationFilters`	Filter by geographic proximity
`metadataFilters`	`MetadataFilters`	Filter by metadata fields

Sort config

Param	Type	Description
`sortBy`	`"createdAt" \| "hot" \| "top" \| "controversial" \| "metadata.field"`	Sort algorithm
`sortByReaction`	`"upvote" \| "downvote" \| "like" \| "love" \| "wow" \| "sad" \| "angry" \| "funny"`	Used when `sortBy` is `"top"`
`sortDir`	`"asc" \| "desc"`	Sort direction
`sortType`	`"auto" \| "numeric" \| "text" \| "boolean" \| "timestamp"`	Type hint for metadata sorts

List config

Param	Type	Description
`limit`	`number`	Results per page. Default: `10`
`sourceId`	`string`	Filter to a specific source section
`spaceId`	`string`	Filter to a specific space
`include`	`string \| string[]`	Populate related data: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`

Fetch options

Param	Type	Description
`fetchImmediately`	`boolean`	Skip debounce and fetch right away
`clearImmediately`	`boolean`	Clear the current list before fetching
`resetFilters`	`boolean`	Reset all filters to defaults before applying new ones
`resetSort`	`boolean`	Reset sort to defaults before applying new sort

Hot Ranking

sortBy: "hot" ranks entities by a score that combines engagement and age:

Engagement. Upvotes, comments and shares raise the score; downvotes lower it. The total is weighed against the entity’s views, so an entity that draws a reaction from more of its viewers ranks higher.
Age. The whole score decays over time, so newer entities overtake older ones. Entities also get a small boost during their first 6 hours.
Ties. Entities with equal scores are ordered newest first.

Scores are recalculated when an entity is fetched, at most once every 5 minutes. An entity that hasn’t been loaded in a while is rescored on its next fetch.

Feed decay

How fast scores decay is a per-project setting: Settings → SDK → Feed Decay in the dashboard. It ranges from 6 hours to 1 month and defaults to 5 days. After one period, an entity’s score has dropped to about 37% of what it would otherwise be. Choose it based on how often new entities arrive:

New entities arrive	Suggested decay
Many per hour	6–12 hours
A few to dozens per day	5 days – 1 week
Less than one per day	2 weeks – 1 month

A decay that is too short for your posting volume makes every entity’s score drop to almost nothing within a couple of days. Engagement then stops affecting the order, and hot behaves like newest first.

Infinite Scroll

Call loadMore() to append the next page. The hook tracks pagination state internally.

<button onClick={loadMore} disabled={loading || !hasMore}>
  Load More
</button>

hasMore reflects the value returned by the server, based on the total item count.

Creating Entities Within a List

createEntity creates an entity and automatically inserts it into the list:

const { createEntity } = useEntityList({ listId: "my-feed" });

await createEntity({
  title: "New Post",
  content: "Hello!",
  insertPosition: "first", // "first" or "last"
});

Deleting Entities From a List

deleteEntity removes an entity from both the server and the local list state:

const { deleteEntity } = useEntityList({ listId: "my-feed" });

await deleteEntity({ entityId: "ent_abc123" });

Sorting by Metadata

You can sort by any metadata field using the metadata.fieldName syntax:

fetchEntities(
  {},
  { sortBy: "metadata.price", sortType: "numeric", sortDir: "asc" }
);

Metadata field names must contain only alphanumeric characters and underscores.

Setup

Authentication

Users

Entities

Entity Lists

Comments

Reactions

Reputation

Spaces

Workspaces

Events

Chat

Collections

Relationships

App Notifications

Push Notifications

Search & AI

Storage

Moderation

Custom Tables

Basic Setup

`fetchEntities` Signature

Filters

Sort config

List config

Fetch options

Hot Ranking

Feed decay

Infinite Scroll

Creating Entities Within a List

Deleting Entities From a List

Sorting by Metadata

​Basic Setup

​fetchEntities Signature

​Filters

​Sort config

​List config

​Fetch options

​Hot Ranking

​Feed decay

​Infinite Scroll

​Creating Entities Within a List

​Deleting Entities From a List

​Sorting by Metadata

Basic Setup

`fetchEntities` Signature

Filters

Sort config

List config

Fetch options

Hot Ranking

Feed decay

Infinite Scroll

Creating Entities Within a List

Deleting Entities From a List

Sorting by Metadata