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

# Release control in React

> Ask users to reload for a new deployment, require it, or show a maintenance screen in your React app, or build your own with a hook.

For what release control does and how to set rules in the dashboard, read
[Release control](https://docs.lerix.dev/modules/release-control/overview.md).

## Setup

Release control is on by default inside the `LerixProvider` from
[Installation](https://docs.lerix.dev/frameworks/react/installation.md), with the built-in screens.
Set `release` so update rules can compare versions:

```tsx main.tsx theme={"dark"}
<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
    release: '1.4.0',                         // required for update rules
    appControl: { enabled: true, ui: true },
  }}
>
  <App />
</LerixProvider>
```

| Option | Default | Description |
| - | - | - |
| `release` | none | The version this deployment ships as. Without it, update rules never apply on the web. Use a version with digits, such as `1.4.0`, not a commit SHA. |
| `appControl.enabled` | `true` | Checks for updates and maintenance. `false` turns the module off. |
| `appControl.ui` | `true` | Shows the built-in screens. `false` leaves the drawing to you. |

## What users see

* **Maintenance**: a fixed overlay above everything on the page, with **Try
  again**. The rest of the page can't be clicked or focused.
* **Required update**: the page reloads by itself to load the newest
  deployment, at most once every 5 minutes per tab. If it is still out of
  date, a full-screen message stays with a **Reload** button.
* **Optional or recommended**: a bar at the bottom of the page with
  **Update** (reloads), **Later** and, when allowed, **Skip this version**.

Web pages don't receive silent push: the SDK checks on load, when the tab is
visible again, and every minute during an emergency. See
[Delivery and offline behaviour](https://docs.lerix.dev/modules/release-control/delivery-offline.md).

## Your own screens

Set `appControl: { ui: false }` and use `useLerixAppControl()`. It returns
the whole `state`, its parts `update`, `maintenance` and `sdk` (each `null`
when nothing applies, fields in
[The state](https://docs.lerix.dev/modules/release-control/custom-ui.md#the-state)), and the helpers.
The component re-renders when the state changes.

```tsx release-gate.tsx theme={"dark"}
import { useLerixAppControl } from '@lerix-dev/lerix-react';

export function ReleaseGate({ children }: { children: React.ReactNode }) {
  const { update, maintenance, refresh, openStore, later, skip } = useLerixAppControl();

  if (maintenance) {
    return (
      <Maintenance
        title={maintenance.title}
        message={maintenance.message}
        onRetry={() => refresh()}
      />
    );
  }
  if (update?.state === 'required') {
    return <ForceUpdate message={update.message} onUpdate={() => openStore()} />;
  }
  return (
    <>
      {update && (
        <UpdateBar
          update={update}
          onUpdate={() => openStore()}
          onLater={() => later()}
          onSkip={update.allowSkip ? () => skip() : undefined}
        />
      )}
      {children}
    </>
  );
}
```

| Returned | What it is |
| - | - |
| `state` | `{ update, maintenance, sdk }` |
| `update`, `maintenance`, `sdk` | The same parts, for convenience |
| `refresh()` | Checks now and resolves the new state |
| `openStore()` | Reloads the page |
| `later()` | Hides the soft prompt for `remindAfterHours` |
| `skip()` | Hides the soft prompt until a newer version (optional updates only) |

With `ui: false` there is no automatic reload for a required update: call
`openStore()` from your own button.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.