# useDocyrusDataSourceFields
URL: /docs/native/hooks/use-docyrus-data-source-fields

Lightweight schema hook for one Docyrus data source on React Native. Returns the data source and its field list (including inline enum options), served cache-first from the shared inventory so no extra request is made after the post-sign-in warm-up.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-data-source-fields
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This hook is **native-only**. Web components that only need the field list (bulk update, import wizard, dummy-data generator) take it from the much larger `useDocyrusFormView` / `useDocyrusDataViewSelect` hooks. On native, [rn-bulk-update-dialog](/docs/native/docyrus/bulk-update-dialog), [`useDocyrusDataImportWizard`](/docs/native/hooks/use-docyrus-data-import-wizard) and [`useDocyrusDummyDataGeneratorWizard`](/docs/native/hooks/use-docyrus-dummy-data-generator-wizard) use this hook instead.

It needs a `QueryClientProvider` above it. The fetch runs through `createDataSourceClient(client, { inventory: getSharedDocyrusInventory(client) })`:

1. `getBySlug(appSlug, dataSourceSlug)` is served from the [shared inventory](/docs/native/hooks/use-docyrus-inventory) with `fields` and inline enum options.
2. On a cache miss the scoped GET has no fields (system data sources), so the hook fetches again with `{ expand: 'enums' }`.

All consumers share the query key `['docyrus', 'dataSourceFields', appSlug, dataSourceSlug]` (exported as `docyrusDataSourceFieldsQueryKey`), so mounting the hook in several places causes a single request.

## Usage

```tsx
import { useDocyrusClient } from '@docyrus/signin/react-native';

import { useDocyrusDataSourceFields } from '@/hooks/docyrus-native/use-docyrus-data-source-fields';

export function TaskFieldList() {
  const client = useDocyrusClient();
  const { fields, isLoading, error } = useDocyrusDataSourceFields({
    client,
    appSlug: 'base',
    dataSourceSlug: 'task'
  });

  if (isLoading) return ;
  if (error) return ;

  return fields.map(field => );
}
```

### Gating and pre-resolved fields

```tsx
// Only fetch while a sheet is open
useDocyrusDataSourceFields({ client, appSlug, dataSourceSlug, enabled: open });

// Reuse fields you already have: the fetch is skipped entirely
useDocyrusDataSourceFields({ client, appSlug, dataSourceSlug, fields: gridFields });
```

## API Reference

### Options (`UseDocyrusDataSourceFieldsOptions`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient \| null \| undefined` | — | Authenticated REST client. The query waits while it is missing (required). |
| `appSlug` | `string` | — | App slug (required). |
| `dataSourceSlug` | `string` | — | Data source slug (required). |
| `enabled` | `boolean` | `true` | Gate the fetch (for example only while a dialog is open). |
| `fields` | `ReadonlyArray<DocyrusFieldLike>` | — | Pre-resolved fields. When set, nothing is fetched and these are returned. |
| `staleTime` | `number` | `300000` (5 minutes) | React Query stale time (ms). |

### Result (`UseDocyrusDataSourceFieldsResult`)

| Field | Type | Description |
|-------|------|-------------|
| `dataSource` | `DataSource \| null` | The data source record from `@docyrus/app-utils`. |
| `fields` | `ReadonlyArray<DocyrusFieldLike>` | Its fields, or the `fields` option. Empty while loading. |
| `isLoading` | `boolean` | First load in progress (always `false` with pre-resolved `fields`). |
| `error` | `Error \| null` | Fetch error. |
| `refetch` | `() => void` | Refetch the schema. |

### DocyrusFieldLike

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Field id. |
| `slug` | `string` | Field slug. |
| `name` | `string` | Display name. |
| `type` | `IFieldType \| string` | Field type (`field-text`, `field-select`, …). |
| `options` | `unknown` | Raw field options. |
| `enums` | `unknown` | Inline enum options. |
| `[key: string]` | `unknown` | Any other schema keys. |

## Exports

| Export | Description |
|--------|-------------|
| `useDocyrusDataSourceFields(options)` | The hook. |
| `docyrusDataSourceFieldsQueryKey(appSlug, dataSourceSlug)` | Shared query key, for example to invalidate the schema after a studio change. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataSourceFieldsOptions` | Hook options. |
| `UseDocyrusDataSourceFieldsResult` | Hook result. |