Skip to main content
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

fetchEntities Signature

Filters

Sort config

List config

Each fetchEntities call sets the whole list config: a field you leave out goes back to its default (limit 10, the others unset) rather than keeping the value from the previous call, and loadMore uses the config of the last fetchEntities call.

Fetch options

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:
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.
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:

Deleting Entities From a List

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

Sorting by Metadata

You can sort by any metadata field using the metadata.fieldName syntax:
Metadata field names must contain only alphanumeric characters and underscores.