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

# EntityProvider & useEntity

> Load a single entity and access its state and actions from any child component

`EntityProvider` is the standard way to load and work with a single entity. Wrap a component tree with it, then use `useEntity` in any descendant to access the entity's data and actions.

## Setting Up EntityProvider

`EntityProvider` accepts one of four mutually exclusive identifier props:

<Steps>
  <Step title="By Replyke entity ID">
    ```tsx theme={null}
    import { EntityProvider } from "@replyke/react-js";

    <EntityProvider entityId="ent_abc123">
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By foreign ID">
    Use this when your entity is linked to an item in your own system. Pass `createIfNotFound` to auto-create the entity if it doesn't exist yet.

    ```tsx theme={null}
    <EntityProvider foreignId="my-system-id-456" createIfNotFound>
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By short ID">
    Short IDs are auto-generated by Replyke and are useful for short sharing URLs.

    ```tsx theme={null}
    <EntityProvider shortId="x7k2m">
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By passing an entity object">
    If you already have the full entity object (e.g., from a list), pass it directly to skip the initial fetch.

    ```tsx theme={null}
    <EntityProvider entity={myEntity}>
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>
</Steps>

<Note>
  `EntityProvider` renders `null` if none of the identifier props are provided. Exactly one must be present.
</Note>

## Accessing Entity State with `useEntity`

Inside any child of `EntityProvider`, call `useEntity()` to access the entity and its actions:

```tsx theme={null}
import { useEntity } from "@replyke/react-js";

function EntityDetail() {
  const { entity, updateEntity, deleteEntity } = useEntity();

  if (!entity) return <p>Loading...</p>;

  return (
    <div>
      <h1>{entity.title}</h1>
      <p>{entity.content}</p>
      <button onClick={() => deleteEntity()}>Delete</button>
    </div>
  );
}
```

## `useEntity` Return Values

<ResponseField name="entity" type="Entity | null | undefined">
  The loaded entity. `undefined` while loading, `null` if not found.
</ResponseField>

<ResponseField name="setEntity" type="React.Dispatch<SetStateAction<Entity | null | undefined>>">
  Direct state setter. Use this if you need to manually update the local entity state.
</ResponseField>

<ResponseField name="updateEntity" type="(props: { update: UpdateEntityUpdate }) => Promise<Entity | undefined>">
  Updates the entity and syncs the new state locally. Accepts:

  * `title` — new title
  * `content` — new content
  * `attachments` — array of attachment objects
  * `keywords` — array of keyword strings
  * `location` — `{ latitude, longitude }`
  * `metadata` — arbitrary JSON object
  * `mentions` — array of `Mention` objects
</ResponseField>

<ResponseField name="deleteEntity" type="() => Promise<void>">
  Deletes the entity and sets local state to `undefined`.
</ResponseField>

## EntityProvider Props Reference

<ParamField path="entityId" type="string">
  Replyke entity ID. Mutually exclusive with `foreignId`, `shortId`, and `entity`.
</ParamField>

<ParamField path="foreignId" type="string">
  Your system's ID for this entity. Mutually exclusive with the others.
</ParamField>

<ParamField path="shortId" type="string">
  Auto-generated short identifier. Mutually exclusive with the others.
</ParamField>

<ParamField path="entity" type="Entity">
  A pre-fetched entity object. Pass this to avoid a redundant fetch. Mutually exclusive with the others.
</ParamField>

<ParamField path="createIfNotFound" type="boolean">
  Only valid with `foreignId`. If `true`, the entity is automatically created when it doesn't exist yet. Useful for "entity-per-resource" patterns.
</ParamField>