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

# Embedded Components

> Using Layer's prebuilt React UI components.

Layer publishes pre-built UI components to npm that can be dropped into any existing React app. These components handle all integration with Layer’s API with the exception of authentication, which must be done on your backend to avoid exposing credentials in your client-side apps. See the [Embedded Components](/embedded-components) section for a full list of components and pre-built Layouts.

## React setup

<Steps>
  <Step title="Install Layer components">
    The first step of using Layer's embedded components is to install the `layerfi/components` package via npm and your preferred package manager.

    ```bash theme={null}
    npm install @layerfi/components --save
    ```

    ```bash theme={null}
    yarn install @layerfi/components
    ```
  </Step>

  <Step title="Set up LayerProvider context">
    Next, set up the `LayerProvider` context, which serves as the configuration for fetching data for an individual business. All individual UX components must be rendered within this context.

    **For local testing**, you can use your Layer sandbox credentials (`APP_ID` and `APP_SECRET`).

    ```tsx theme={null}
    import { LayerProvider } from "@layerfi/components";

      <LayerProvider
        businessId={process.env.REACT_APP_BUSINESS_ID ?? ''}
        environment={process.env.REACT_APP_ENVIRONMENT ?? ''}
        appId={process.env.REACT_APP_APP_ID ?? ''}
        appSecret={process.env.REACT_APP_APP_SECRET ?? ''}
      >
      {...}
    </LayerProvider>
    ```

    **In production**, you should use access tokens scoped to a specific business.
    See the backend configuration section below for steps to retrieve scoped tokens:

    ```tsx theme={null}
    import { LayerProvider } from "@layerfi/components";

      <LayerProvider
        businessId={process.env.REACT_APP_BUSINESS_ID ?? ''}
        environment={process.env.REACT_APP_ENVIRONMENT ?? ''}
        businessAccessToken={'<scoped business token>'}
      >
      {...}
    </LayerProvider>
    ```
  </Step>

  <Step title="Import component styles">
    You must explicitly import the Layer stylesheet into your application. We recommend importing it in the same file as your root component.

    ```ts theme={null}
    import '@layerfi/components/index.css'
    ```
  </Step>

  <Step title="Modify component styles to align with your brand">
    **Option 1: Set primary colors in theme configuration**

    You can set a dark and light theme color for all components.
    We recommend starting with simple customization like this using rgb, hsl or hex colors.

    ```tsx theme={null}
      <LayerProvider
        businessId={process.env.REACT_APP_BUSINESS_ID ?? ''}
        environment={process.env.REACT_APP_ENVIRONMENT ?? ''}
        appId={process.env.REACT_APP_APP_ID ?? ''}
        appSecret={process.env.REACT_APP_APP_SECRET ?? ''}
        theme={{
          dark: { r: '28', g: '26%', b: '11%' },
          light: { hex: '#F9A171'},
        }}
      >
      {...}
    </LayerProvider>
    ```

    **Option 2: Customize CSS variables**

    For more flexible customization, CSS variables are exposed to allow you to set colors and styles for the embedded components.
    We recommend setting these variables within a scoped container to isolate the scope to Layer components.
    In this example, we've set variables within the `.layer-container` class.

    ```css theme={null}
      body .layer-container {
        --color-black: #1a1a1a;
        --color-white: white;
        --color-neutral: #666666;
        --color-neutral-50: #fafcfc;
        --color-neutral-200: #eef0ef;
        --color-neutral-700: #636665;
        --color-red: #e46362;
        --color-info-green: #29bc9b;

        --color-primary: var(--color-black);
        --color-accent: var(--color-white);
        --color-secondary: var(--color-neutral);
        --color-success: var(--color-info-green);
        --color-danger: var(--color-red);
        --text-color-primary: var(--color-black);
        --text-color-secondary: var(--color-neutral-700);
        --bg-element-focus: var(--color-neutral-50);

        --font-family: "InterVariable", "Inter", sans-serif;
        --font-family-numeric: "InterVariable", "Inter", sans-serif;
        --text-sm: 12px;
        --text-md: 14px;
        --text-heading: 24px;
        --font-weight-normal: 460;
        --font-weight-bold: 580;
        --spacing-sm: 12px;
        --spacing-md: 16px;
        --spacing-2xl: 36px;
        --border-color: var(--color-neutral-200);
      }
    ```
  </Step>

  <Step title="Add components to your pages">
    Finally, add components to your pages as you would any React component.

    ```tsx theme={null}
    <BankTransactions />
    ```

    Some components have multiple sub components which can be optionally included for composition and layout customization.

    ```tsx theme={null}
    <ProfitAndLoss>
      <div className='profit-and-loss__chart-container'>
        <ProfitAndLoss.Chart />
      </div>
      <ProfitAndLoss.Summaries />
      <div className='profit-and-loss__date-picker-container'>
        <ProfitAndLoss.DatePicker />
      </div>
      <ProfitAndLoss.Table />
    </ProfitAndLoss>
    ```

    Type definitions are available for all components to assist with discovering options & subcomponents.
  </Step>
</Steps>

## Backend setup

To ensure an end user can only access their own data, the Layer component must be provided with a scoped access token which limits access to a specific business. This is a two step process.

<Steps>
  <Step title="Obtain your platform-wide access token">
    Use your Layer-provided `client_id` and `client_secret` to obtain a platform-wide access token. See [Authentication](/authentication) for more information on this process.
    This should be done server-side to avoid exposing your credentials in your client-side application.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://auth.layerfi.com/oauth2/token  \
        -u <client_id>:<client_secret>  \
        -H "Content-Type: application/x-www-form-urlencoded" \
        --data-urlencode "grant_type=client_credentials" \
        --data-urlencode "scope=https://sandbox.layerfi.com/sandbox" \
        --data-urlencode "client_id=<client_id>"
      ```

      ```tsx typescript theme={null}
      const clientId = "<your_client_id>";
      const clientSecret = "<your_client_secret>";

      const url = "https://auth.layerfi.com/oauth2/token";

      axios.post(url, null, {
        params: {
          grant_type: "client_credentials",
          scope: "https://sandbox.layerfi.com/sandbox",
          client_id: clientId,
        },
        auth: {
          username: clientId,
          password: clientSecret,
        },
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Retrieve a business-scope access token">
    Next, send a request to the Business Access Token endpoint, including the business ID in the `business_id` URL parameter. By default, the token's session duration is set to one hour, but you can customize this by specifying the `session_duration` parameter (in seconds) up to 24 hours.

    <CodeGroup>
      ```bash curl theme={null}
        curl -X POST https://sandbox.layerfi.com/v1/businesses/{business_id}/auth-token \
          -H "Authorization: Bearer <access_token>"
          -d '{"session_duration": 3600}'
      ```

      ```tsx typescript theme={null}
        const url = `https://sandbox.layerfi.com/v1/businesses/${businessId}/auth-token`;

        axios.post(url, {
          session_duration: 3600,
        }, {
          headers: {
            'Authorization': `Bearer ${accessToken}`
          }
        })
      ```
    </CodeGroup>

    You'll receive a new access token that can only make requests for the selected business.

    ```bash theme={null}
    {
      "access_token": "<access_token>",
      "expires_in": 3600,
      "token_type": "Bearer"
    }
    ```
  </Step>

  <Step title="Populate access token in LayerProvider context">
    Finally, send this access token to the frontend and populate it in the `businessAccessToken` field of the `LayerProvider`context:

    ```tsx theme={null}
    <LayerProvider
      businessId="<layer_business_id>"
      businessAccessToken="<access_token>"
      environment={'sandbox'}
    >
      {...}
    </LayerProvider>
    ```
  </Step>
</Steps>