# useHistory

The `useHistory` hook reads the channel's history backwards from the point where the channel attached, one page at a time, and keeps the deliveries it has read in one list, oldest first. It reads the first page when the transport is available, and `loadMore` reads the next older page.

<Code>

#### Javascript

```
import { useHistory } from '@ably/ai-transport/react';

function Earlier() {
  const { items, hasNext, loading, loadMore } = useHistory({ limit: 50 });

  return (
    <>
      {hasNext && <button onClick={loadMore} disabled={loading}>Load older</button>}
      <Messages deliveries={items} />
    </>
  );
}
```
</Code>

This hook must be used within a [`TransportProvider`](https://ably.com/docs/ai-transport/api/react/transport-provider.md).

Reading history attaches the channel. The list starts again when the provider creates a new transport.

## Parameters 

<Table id='UseHistoryParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| limit | required | Messages per page. A change takes effect when the provider creates a new transport. | Number |
| channelName | optional | The channel name of the provider to read. Omit it to read the nearest provider. | String |

</Table>

The hook throws an [`ErrorInfo`](https://ably.com/docs/ai-transport/api/errors.md#errorinfo) with `InvalidArgument` when no matching `TransportProvider` encloses the component.

## Returns 

<Table id='UseHistoryReturns'>

| Property | Description | Type |
| --- | --- | --- |
| items | Every delivery read so far, oldest first. Each `loadMore` adds an older page to the front. | <Table id='Delivery'/> |
| hasNext | Whether an older page exists. `true` until a page reports the end of history. | Boolean |
| loading | Whether a page is being read. | Boolean |
| error | The error the last read failed with, or `undefined`. | [`ErrorInfo`](https://ably.com/docs/ai-transport/api/errors.md#errorinfo) or `undefined` |
| loadMore | Read the next older page. | `() => Promise<void>` |

</Table>

<Table id='Delivery' >

| Property | Description | Type |
| --- | --- | --- |
| event | The decoded event, or `undefined` when the codec produced no event for the message. | `E` or `undefined` |
| message | The Ably message as delivered. | `Ably.InboundMessage` |

</Table>

## Load an older page 

`loadMore(): Promise<void>`

Read the next older page and add it to the front of `items`. The promise resolves once the page is in `items`. A call while a page is loading, or after the end of history, does nothing. A failed read sets `error`.

## Example 

A conversation view loads older messages when the user scrolls to the top.

<Code>

### Javascript

```
import { useHistory } from '@ably/ai-transport/react';

function ConversationHistory() {
  const { items, hasNext, loading, error, loadMore } = useHistory({ limit: 30 });

  const onScroll = (e) => {
    if (e.currentTarget.scrollTop === 0 && hasNext && !loading) void loadMore();
  };

  if (error) return <p>Could not load history: {error.message}</p>;

  return (
    <div onScroll={onScroll} style={{ overflowY: 'auto', height: 400 }}>
      {items.map(({ message, event }, i) => (event ? <Row key={`${message.serial}-${i}`} event={event} /> : null))}
    </div>
  );
}
```
</Code>

## Related Topics

- [TransportProvider](https://ably.com/docs/ai-transport/api/react/transport-provider.md): API reference for the AI Transport TransportProvider: create a transport for a channel and make it available to React components.
- [useTransport](https://ably.com/docs/ai-transport/api/react/use-transport.md): API reference for the AI Transport useTransport hook: read the transport from the nearest or a named TransportProvider.
- [useDeliveries](https://ably.com/docs/ai-transport/api/react/use-deliveries.md): API reference for the AI Transport useDeliveries hook: receive every delivery on the transport's channel while a component is mounted.
- [useTransportStatus](https://ably.com/docs/ai-transport/api/react/use-transport-status.md): API reference for the AI Transport useTransportStatus hook: observe the transport's discontinuities and errors.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.