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

# useStream

> React Hook for retrieving a stream.

Hook for retrieving a
[Stream](https://github.com/livepeer/react/blob/main/packages/core/src/types/provider.ts)
based on a unique identifier.

## Usage

<Tabs>
  <Tab title="React">
    ```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    import { useStream } from '@livepeer/react';
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    import { useStream } from '@livepeer/react-native';
    ```
  </Tab>
</Tabs>

The following examples assume a stream was created via `useCreateStream` or
directly via a provider's API/dashboard. If a falsy stream ID is provided, the
query will be skipped.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
function SomeComponent() {
  const { data: stream } = useStream(stream?.id);
}
```

## Return Value

The return value is partially based on
[Tanstack Query](https://tanstack.com/query/v4/docs/reference/useQuery), with
some return types aggregated for simplicity.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  data?: Stream,
  error?: Error,
  status: 'idle' | 'loading' | 'success' | 'error',
  isError: boolean,
  isFetched: boolean,
  isFetching: boolean,
  isIdle: boolean,
  isLoading: boolean,
  isRefetching: boolean,
  isSuccess: boolean,
  refetch: (options: RefetchOptions) => Promise<UseQueryResult>,
}
```

## Configuration

### streamId

Stream identifier. Can also be a string passed as the only parameter.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
function SomeComponent() {
  const { data: stream } = useStream({
    streamId,
  });
}
```

### UseQueryOptions

The `useStream` hook also supports any
[Tanstack Query](https://tanstack.com/query/v4/docs/reference/useQuery)
`useQuery` options, such as `refetchInterval` or `enabled`. These override any
configs passed by default by the internal hook.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
function SomeComponent() {
  const { data: stream } = useStream({
    streamId,
    refetchInterval: (stream) => (!stream?.isActive ? 5000 : false),
  });
}
```

## SSR

<Warning>
  The following section only applies to web-based use-cases - React Native has
  no concept of SSR.
</Warning>

### Next.js

The `useStream` hook also comes with a
[Tanstack Query](https://tanstack.com/query/v4/docs/guides/ssr) prefetch query,
`prefetchStream`, which makes it easy to prefetch data for server-side
rendering.

First, you add a
[`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props)
function to the page which you want to prefetch data on. The props should match
the `useStream` hook to ensure that the correct data is prefetched.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// pages/demo.tsx
import { prefetchStream, studioProvider } from "@livepeer/react";

export const getStaticProps = async () => {
  const dehydratedState = await prefetchStream(
    { streamId },
    { provider: studioProvider({ apiKey: "yourStudioApiKey" }) }
  );

  return {
    props: {
      dehydratedState,
    },
    revalidate: 600,
  };
};
```

We need to update the `_app.tsx` to pass the `dehydratedState` in `pageProps` to
the LivepeerConfig. We also move the `livepeerClient` into a useMemo hook so
that a new client is created on each request.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// pages/_app.tsx
import {
  LivepeerConfig,
  createReactClient,
  studioProvider,
} from "@livepeer/react";
import type { AppProps } from "next/app";

import { useMemo } from "react";

function App({ Component, pageProps }: AppProps<{ dehydratedState: string }>) {
  // we create a new livepeer client on each request so data is
  // not shared between users
  const livepeerClient = useMemo(
    () =>
      createReactClient({
        provider: studioProvider({
          apiKey: process.env.NEXT_PUBLIC_STUDIO_API_KEY,
        }),
      }),
    []
  );

  return (
    <LivepeerConfig
      dehydratedState={pageProps?.dehydratedState}
      client={livepeerClient}
    >
      <Component {...pageProps} />
    </LivepeerConfig>
  );
}
```

That's it! You now have data prefetching on the server, which is passed to the
browser and used to hydrate the initial query client.

### Other Frameworks

The process is very similar for other frameworks, with the exception that there
is a `clearClient` boolean which should be used to ensure that the client cache
is not reused across users.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { prefetchStream, studioProvider } from "@livepeer/react";

export const handleRequest = async (req, res) => {
  const dehydratedState = await prefetchStream(
    {
      streamId,
      clearClient: true,
    },
    { provider: studioProvider({ apiKey: "yourStudioApiKey" }) }
  );

  // sanitize the custom SSR generated data
  // https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0

  res.send(`
    <html>
      <body>
        <div id="root">${html}</div>
        <script>
          window.__REACT_QUERY_STATE__ = ${yourSanitizedDehydratedState};
        </script>
      </body>
    </html>
  `);
};
```