> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# useBackend

> Retrieve the analytical backend from BackendProvider context, with an optional prop override or strict variant.

API reference: [useBackend()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.usebackend/index.md) (function), [useBackendStrict()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.usebackendstrict/index.md) (function)

`useBackend` returns the analytical backend provided to [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md). If you pass a backend, the hook returns it instead, so a component can accept a `backend` prop that wins over the context. `useBackendStrict` does the same but throws when no backend is available.

## [Basic usage](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#basic-usage)

```tsx
import { useBackend } from "@gooddata/sdk-ui";

function MyComponent({ backend: backendProp }) {
    // Uses backendProp if defined, otherwise falls back to context value
    const backend = useBackend(backendProp);

    // backend may be undefined if neither prop nor context is set
    if (!backend) {
        return <div>No backend configured</div>;
    }

    // Use backend to interact with GoodData
    // ...
}
```

### [Require a backend](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#require-a-backend)

`useBackendStrict` throws an invariant error when neither the parameter nor the context supplies a backend. Use it when a backend is required and you want a clear error instead of handling `undefined`.

```tsx
import { useBackendStrict } from "@gooddata/sdk-ui";

function MyComponent({ backend: backendProp }) {
    // Throws if no backend is available
    const backend = useBackendStrict(backendProp);

    // backend is always defined here
    const workspaces = backend.workspaces();
    // ...
}
```

## [Parameters](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#parameters)

| Parameter | Type | Description |
|-----------|------|-------------|
| `backend` | `IAnalyticalBackend \| undefined` | Optional backend override. If provided, returned directly instead of context value. |

## [Return value](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#return-value)

- `useBackend`: `IAnalyticalBackend | undefined`
- `useBackendStrict`: [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) (throws if unavailable)

## [Notes](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#notes)

- The `backend` parameter takes precedence over the context value. The hook returns `backend ?? backendFromContext`.
- Without a [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) up the tree and without the `backend` parameter, `useBackend` returns `undefined`. It doesn't throw.
- `useBackendStrict` accepts a second, optional `context: string` parameter (default `"useBackendStrict"`). It prefixes the invariant error message, so you can pass the name of the calling hook or component.
- When no backend is available, `useBackendStrict` raises an invariant error with this message: `<context>: IAnalyticalBackend must be defined. Either pass it as a parameter or make sure there is a BackendProvider up the component tree.`

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/hooks/use-backend/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`authenticate`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendauthenticate) | `(force?: boolean) => Promise<`[`IAuthenticatedPrincipal`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iauthenticatedprincipal/index.md)`>` | Yes | Triggers authentication process against the backend. | — |
| [`capabilities`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendcapabilities) | [`IBackendCapabilities`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ibackendcapabilities/index.md) | Yes | Capabilities available on this backend. | — |
| [`config`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendconfig) | [`IAnalyticalBackendConfig`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackendconfig/index.md) | Yes | Configuration used for communication with this backend. | — |
| [`currentUser`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendcurrentuser) | `() =>` [`IUserService`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iuserservice/index.md) | Yes | Returns a service for interacting with the currently authenticated user. | — |
| [`dataSources`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackenddatasources) | `() =>` [`IDataSourcesService`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.idatasourcesservice/index.md) | Yes | Returns service that can be used to work with data sources. | — |
| [`deauthenticate`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackenddeauthenticate) | `(returnTo?: string) => Promise<void>` | Yes | Triggers deauthentication process against the backend. | — |
| [`entitlements`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendentitlements) | `() =>` [`IEntitlements`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ientitlements/index.md) | Yes | Returns service that can be used to obtain license entitlements. | — |
| [`geo`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendgeo) | `() =>` [`IGeoService`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.igeoservice/index.md) | Yes | Returns service that can be used to load geo location assets. | — |
| [`isAuthenticated`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendisauthenticated) | `() => Promise<`[`IAuthenticatedPrincipal`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iauthenticatedprincipal/index.md) `\| null>` | Yes | Tests authentication against this backend. | — |
| [`onHostname`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendonhostname) | `(hostname: string) =>` [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | Yes | Creates new instance of backend on the provided hostname. | — |
| [`organization`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendorganization) | `(organizationId: string) =>` [`IOrganization`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iorganization/index.md) | Yes | Returns an organization available on the backend. | — |
| [`organizations`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendorganizations) | `() =>` [`IOrganizations`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iorganizations/index.md) | Yes | Returns a service that can be obtained to obtain organizations. | — |
| [`withAuthentication`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendwithauthentication) | `(provider:` [`IAuthenticationProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iauthenticationprovider/index.md)`) =>` [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | Yes | Sets authentication provider to be used when backend discovers current session is not authenticated. | — |
| [`withCorrelation`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendwithcorrelation) | `(correlationMetadata:` [`IRequestCorrelationMetadata`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.irequestcorrelationmetadata/index.md)`) =>` [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | Yes | Sets request correlation metadata that will be included in HTTP requests to the backend. If the IAnalyticalBackend instance already has correlation metadata set, the new metadata will be merged with the existing one. This method provides more flexibility than withTelemetry by allowing arbitrary key-value pairs to be sent. | — |
| [`withTelemetry`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendwithtelemetry) | `(componentName: string, props: object) =>` [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | Yes | Sets telemetry information that SHOULD be sent to backend to track component usage. | — |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendworkspace) | `(id: string) =>` [`IAnalyticalWorkspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalworkspace/index.md) | Yes | Returns an analytical workspace available on this backend. | — |
| [`workspaces`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md#ianalyticalbackendworkspaces) | `() =>` [`IWorkspacesQueryFactory`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iworkspacesqueryfactory/index.md) | Yes | Returns service that can be used to obtain available workspaces. | — |