> ## 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.

# UI Events

Layer's React components emit UI events when users interact with them. Subscribe to these events through the `onEvent` callback on `<LayerProvider>`'s `eventCallbacks` prop to power analytics, custom logging, or to react to user activity in your own application.

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

<LayerProvider
  businessId="<layer_business_id>"
  businessAccessToken="<access_token>"
  eventCallbacks={{
    onEvent: (event) => {
      console.log('Layer event:', event.type, event.payload)
    },
  }}
>
  {...}
</LayerProvider>
```

The `onEvent` callback fires when users interact with embedded Layer components. Each event includes a type, version, event-specific payload, and metadata.

## Event Structure

```tsx theme={null}
interface LayerEventEnvelope<TPayload extends object> {
  source: 'layer'
  type: LayerEventType
  version: 1
  payload: TPayload
  metadata: {
    component: LayerEventComponent
    timestamp: string
    packageVersion?: string
  }
}
```

The `LayerEventType` value, `LayerEventComponent` value, and `LayerEvent` type are exported from `@layerfi/components` for TypeScript users. `LayerEvent` is a discriminated union, so checking `event.type` narrows `event.payload` to the payload for that event.

## Supported Events

All events listed below currently use `version: 1`.

<AccordionGroup>
  <Accordion title="Tasks Events" defaultOpen>
    <ResponseField name="tasks.month_selected">
      Fired when a user selects a month in the Tasks component.

      <Expandable title="payload">
        <ResponseField name="year" type="number">
          The selected year (e.g., `2024`).
        </ResponseField>

        <ResponseField name="month" type="number">
          The selected month (1-12).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tasks.year_selected">
      Fired when a user selects a year in the Tasks component.

      <Expandable title="payload">
        <ResponseField name="year" type="number">
          The selected year (e.g., `2024`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tasks.task_clicked">
      Fired when a user clicks on a task to expand or collapse it.

      <Expandable title="payload">
        <ResponseField name="taskId" type="string">
          The ID of the clicked task.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="Bookkeeping Events" defaultOpen>
    <ResponseField name="bookkeeping.schedule_call_clicked">
      Fired when a user clicks the button to schedule a call with a bookkeeper.

      <Expandable title="payload">
        Empty object.
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="Profit and Loss Events" defaultOpen>
    <ResponseField name="profit_and_loss.month_selected">
      Fired when a user selects a month on the Profit and Loss chart.

      <Expandable title="payload">
        <ResponseField name="year" type="number">
          The selected year (e.g., `2024`).
        </ResponseField>

        <ResponseField name="month" type="number">
          The selected month (1-12).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="Transactions Events" defaultOpen>
    <ResponseField name="transactions.search_submitted">
      Fired when a user submits a search query in the Bank Transactions component.

      <Expandable title="payload">
        <ResponseField name="query" type="string">
          The search query entered by the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="transactions.download_clicked">
      Fired when a user clicks to download transactions.

      <Expandable title="payload">
        Empty object.
      </Expandable>
    </ResponseField>

    <ResponseField name="transactions.description_entered">
      Fired when a user saves a memo or description for a transaction.

      <Expandable title="payload">
        <ResponseField name="transactionId" type="string">
          The ID of the transaction.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="transactions.receipt_upload_clicked">
      Fired when a user initiates a receipt upload for a transaction.

      <Expandable title="payload">
        <ResponseField name="transactionId" type="string">
          The ID of the transaction.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="transactions.page_changed">
      Fired when a user navigates to a different page in the Bank Transactions list.

      <Expandable title="payload">
        <ResponseField name="page" type="number">
          The page number the user navigated to.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="Reports Events" defaultOpen>
    <ResponseField name="reports.navigated">
      Fired when a user navigates to a different report in the Unified Reports view.

      <Expandable title="payload">
        <ResponseField name="reportKey" type="string">
          The key identifying the selected report.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reports.download_clicked">
      Fired when a user clicks to download a report.

      <Expandable title="payload">
        <ResponseField name="reportKey" type="string">
          The key identifying the report being downloaded.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reports.section_expanded">
      Fired when a user expands or collapses a section in a report table.

      <Expandable title="payload">
        <ResponseField name="sectionKey" type="string">
          The key identifying the report section.
        </ResponseField>

        <ResponseField name="expanded" type="boolean">
          Whether the section is now expanded (`true`) or collapsed (`false`).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="Linked Accounts Events" defaultOpen>
    <ResponseField name="linked_accounts.add_account_clicked">
      Fired when a user clicks to add a new linked account.

      <Expandable title="payload">
        Empty object.
      </Expandable>
    </ResponseField>

    <ResponseField name="linked_accounts.unlink_account_clicked">
      Fired when a user confirms unlinking a bank account.

      <Expandable title="payload">
        <ResponseField name="accountId" type="string">
          The ID of the account being unlinked.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Example Usage

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

function App() {
  const handleLayerEvent = (event: LayerEvent) => {
    switch (event.type) {
      case LayerEventType.TransactionsSearchSubmitted:
        analytics.track('user_searched_transactions', {
          query: event.payload.query,
        })
        break
      case LayerEventType.TaskClicked:
        console.log('User clicked task:', event.payload.taskId)
        break
    }
  }

  return (
    <LayerProvider
      businessId="<layer_business_id>"
      businessAccessToken="<access_token>"
      eventCallbacks={{
        onEvent: handleLayerEvent,
      }}
    >
      {...}
    </LayerProvider>
  )
}
```