useBackend

useBackend returns the analytical backend provided to BackendProvider. 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

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

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.

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

Return value

• useBackend: IAnalyticalBackend | undefined
• useBackendStrict: IAnalyticalBackend (throws if unavailable)

Notes

• The backend parameter takes precedence over the context value. The hook returns backend ?? backendFromContext.
• Without a BackendProvider 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