---
title: "Elements hooks"
description: "Hand-written shim. Generated CRUD hooks via ./elements.gen
(`useListElements`, `useCreateElement`, `useRetrieveElement`, `useUpdateElement`,
`useDeleteElement`, `useRestoreElement`). Hooks below cover the build
action, the preview-session lifecycle, and the per-version file ops —
none of which fit the manifest's standard CRUD kinds."
section: "Libraries"
group: "React hooks"
order: 415
---

## Usage

```tsx
import Aeontel from "@aeontel/sdk";
import { AeontelProvider, useListElements } from "@aeontel/react";

const client = new Aeontel(import.meta.env.VITE_AEONTEL_API_KEY);

function App() {
  return (
    <AeontelProvider client={client}>
      <ElementsList workspaceId="wsp_abc123" />
    </AeontelProvider>
  );
}

function ElementsList({ workspaceId }: { workspaceId: string }) {
  const { data, isLoading } = useListElements({ workspace_id: workspaceId });
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {data?.data.map((e) => (
        <li key={e.id}>{e.name}</li>
      ))}
    </ul>
  );
}
```

## Hooks

### `useBuildElement` `composite`

Trigger a build for an element version.

```ts
useBuildElement(options?: MutationOpts<Build, BuildElementParams>)
```

**Types:** [Build](/types/build) · [BuildElementParams](/types/build-element-params)

### `useCreateElement` `mutation`

Create a new element.

```ts
useCreateElement(options?: MutationOpts<Element, CreateElementParams>)
```

**Types:** [Element](/types/element) · [CreateElementParams](/types/create-element-params)

### `useCreateElementVersionFile` `mutation`

Create a file in a specific element version.

```ts
useCreateElementVersionFile(options?: MutationOpts<SuccessResponse, CreateElementVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [CreateElementVersionFileParams](/types/create-element-version-file-params)

### `useDeleteElement` `mutation`

Soft-delete an element.

```ts
useDeleteElement(options?: MutationOpts<SuccessResponse, string>)
```

**Types:** [SuccessResponse](/types/success-response)

### `useDeleteElementVersionFile` `mutation`

Delete a file from a specific element version.

```ts
useDeleteElementVersionFile(options?: MutationOpts<SuccessResponse, DeleteElementVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [DeleteElementVersionFileParams](/types/delete-element-version-file-params)

### `useGetElementPreview` `query`

Poll a preview session by id. Pass a null id to pause.

```ts
useGetElementPreview(sessionId: string | null, options?: QueryOpts<ElementPreviewSession>)
```

### `useKeepaliveElementPreview` `composite`

Heartbeat a preview session so the idle reaper doesn't tear it down.

```ts
useKeepaliveElementPreview(options?: MutationOpts<{ id: string; status: string; }, { sessionId: string; }>)
```

### `useListElementFiles` `query`

List files in an element's default version (default-version shortcut).

```ts
useListElementFiles(elementId: string, params?: { path?: string; }, options?: QueryOpts<AppFileListResponse>)
```

**Types:** [AppFileListResponse](/types/app-file-list-response)

```ts
const { data } = useListElementFiles("elm_abc123", { path: "src" });
```

### `useListElements` `query`

List elements.

```ts
useListElements(params?: Omit<ListElementsParams, | > & { filter?: ElementFilter; orderBy?: ElementOrderBy[]; } & ElementShorthands, options?: QueryOpts<Page<Element>>)
```

**Types:** [ListElementsParams](/types/list-elements-params) · [ElementFilter](/types/element-filter) · [ElementOrderBy](/types/element-order-by) · [ElementShorthands](/types/element-shorthands) · [Page](/types/page) · [Element](/types/element)

### `useListElementVersionFiles` `query`

List files in a specific element version. Manifest-driven SDK method.

```ts
useListElementVersionFiles(versionId: string, params?: { path?: string; }, options?: QueryOpts<AppFileListResponse>)
```

**Types:** [AppFileListResponse](/types/app-file-list-response)

```ts
const { data } = useListElementVersionFiles("elmver_def456");
```

### `usePurgeElement` `composite`

Permanently delete a soft-deleted element.

```ts
usePurgeElement(options?: MutationOpts<SuccessResponse, PurgeElementParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [PurgeElementParams](/types/purge-element-params)

### `useRestoreElement` `composite`

Restore a soft-deleted element.

```ts
useRestoreElement(options?: MutationOpts<Element, string>)
```

**Types:** [Element](/types/element)

### `useRetrieveElement` `query`

Get a single element.

```ts
useRetrieveElement(id: string, options?: QueryOpts<Element>)
```

**Types:** [Element](/types/element)

### `useStartElementPreview` `composite`

Start a preview session for an element version.

```ts
useStartElementPreview(options?: MutationOpts<ElementPreviewSession, { id: string; versionId: string; }>)
```

### `useStopElementPreview` `composite`

Stop a preview session.

```ts
useStopElementPreview(options?: MutationOpts<SuccessResponse, { sessionId: string; }>)
```

**Types:** [SuccessResponse](/types/success-response)

### `useUpdateElement` `mutation`

Update an element.

```ts
useUpdateElement(options?: MutationOpts<Element, UpdateElementParams>)
```

**Types:** [Element](/types/element) · [UpdateElementParams](/types/update-element-params)

### `useUpdateElementVersionFile` `mutation`

Update a file in a specific element version.

```ts
useUpdateElementVersionFile(options?: MutationOpts<SuccessResponse, UpdateElementVersionFileParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [UpdateElementVersionFileParams](/types/update-element-version-file-params)