---
title: Provide and read records
description: Build record-aware components with RecordProvider, useRecord, and useFieldValue.
order: 10
toc:
  - id: provide-a-record
    title: Provide a record
  - id: read-a-record
    title: Read a record
  - id: read-a-field
    title: Read a field
---

## Provide a record {#provide-a-record}

Mount the provider at the boundary that owns the data. `RecordProvider` accepts a present, non-nullish record. Use `OptionalRecordProvider` when a query result may be absent.

```tsx
import { RecordProvider } from "@workspace/record"

function ProductScreen({ product }: { product: Product }) {
  return (
    <RecordProvider value={product}>
      <ProductDetails />
    </RecordProvider>
  )
}
```

```tsx
import { OptionalRecordProvider } from "@workspace/record"

;<OptionalRecordProvider value={query.data}>
  <ProductDetails />
</OptionalRecordProvider>
```

## Read a record {#read-a-record}

`useRecord` returns `undefined` when there is no provider or data has not loaded yet.

```tsx
function ProductDetails() {
  const product = useRecord<Product>()
  if (!product) return <p>Loading…</p>

  return <h2>{product.name}</h2>
}
```

A record-aware component can also accept an optional `record` prop. The explicit record takes precedence over context, making isolated previews and tests straightforward.

```tsx
function ProductTitle({ record }: { record?: Product }) {
  const product = useRecord({ record })
  return product ? <h2>{product.name}</h2> : null
}
```

## Read a field {#read-a-field}

`useFieldValue` supports direct properties, nested objects, and numeric array segments. Paths use dot notation.

```tsx
const city = useFieldValue<Customer, "address.city">({
  source: "address.city",
  defaultValue: "Unknown",
})

const firstSku = useFieldValue<Order, "items.0.sku">({
  source: "items.0.sku",
})
```