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

# Record widget

> Record Widgets are a way to show information on record pages.

<img className="dark:hidden" width="720" height="440" noZoom src="https://mintcdn.com/attio/2EyaTyByKNPeSVcd/images/text-widget.png?fit=max&auto=format&n=2EyaTyByKNPeSVcd&q=85&s=905d99548719a1fe3fa5ed50327194c4" data-path="images/text-widget.png" />

<img className="hidden dark:block" width="720" height="440" noZoom src="https://mintcdn.com/attio/2EyaTyByKNPeSVcd/images/text-widget-dark.png?fit=max&auto=format&n=2EyaTyByKNPeSVcd&q=85&s=effd70a15c784e18ba183266c5b0dc5a" data-path="images/text-widget-dark.png" />

```ts theme={"system"}
import type {App} from "attio"
```

Register a record widget by creating an `App.Record.Widget` and adding it to the
`record.widgets` array of your [`app.ts`](./app-ts) file.

<Note>
  Before your record widget will appear on a record page, you will need to go to "Configure page",
  click on "Add Widget", and select your widget.
</Note>

## Example

```tsx arr-widget.ts theme={"system"}
import React from "react"
import type {App} from "attio"
import {Widget} from "attio/client"
import {useMyArrQuery} from "your-code-somewhere.ts"

const ArrWidgetComponent = ({recordId}: {recordId: string}) => {
  const {arr, delta} = useMyArrQuery(recordId) // may suspend!
  return (
    <Widget.TextWidget>
      <Widget.Title>ARR</Widget.Title>
      <Widget.Text.Primary>{arr}</Widget.Text.Primary>
      <Widget.Badge text={delta} color={delta < 0 ? "red" : "green"} />
    </Widget.TextWidget>
  )
}

export const arrWidget: App.Record.Widget = {
  id: "company-arr",
  label: "ARR",
  Widget: ({recordId}) => {
    return (
      <React.Suspense fallback={<Widget.Loading />}>
        <ArrWidgetComponent recordId={recordId} />
      </React.Suspense>
    )
  },
  objects: "companies", // only show on company records
}
```

```tsx app.ts theme={"system"}
import type {App} from "attio"

import {arrWidget} from "./arr-widget"

export const app: App = {
  record: {
    widgets: [arrWidget],
    // ...
  },
  // ...
}
```

<Note>
  The widget will always display your app's icon, which you set in the [Developer
  dashboard](https://build.attio.com).
</Note>

## Arguments

<ParamField path="id" type="string" required>
  The unique identifier for this widget.

  It is only used internally; never shown to the user.
</ParamField>

<ParamField path="label" type="string" required>
  A human-readable label of the widget that will be shown to the user in the widget picker.
</ParamField>

<ParamField path="color" type="string">
  The base hexadecimal color of the gradient displayed in the background of the widget.
</ParamField>

<ParamField path="Widget" type="(props: { recordId: string, object: ObjectSlug }) => React.ReactNode" required>
  A React component that will render the widget.

  It can suspend while loading data.

  Must return a one of the following components as the root element:

  * [`Widget.Loading`](../components/widgets/loading)
  * [`Widget.TextWidget`](../components/widgets/text-widget)
</ParamField>

<ParamField path="objects" type="ObjectSlug | Array<ObjectSlug>">
  A single slug or an array of slugs to select which types of record the record widget will apply to.

  Defaults to `undefined`, which will cause the widget to show on ***all*** types of records.

  The built-in slugs are

  * [`"companies"`](../../docs/standard-objects/standard-objects-companies)
  * [`"people"`](../../docs/standard-objects/standard-objects-people)
  * [`"deals"`](../../docs/standard-objects/standard-objects-deals)
  * [`"users"`](../../docs/standard-objects/standard-objects-users)
  * [`"workspaces"`](../../docs/standard-objects/standard-objects-workspaces)
</ParamField>