useReportingUnitDetailsQuery

---

type: Hook title: useReportingUnitDetailsQuery description: Shared TanStack Query hook for read-only reporting-unit details, keyed as ['reporting-unit','details',ruId]. tags: [frontend, react-query, hook, reporting-unit, shared] timestamp: 2026-10-01T00:00:00Z

useReportingUnitDetailsQuery

useReportingUnitDetailsQuery is a shared TanStack Query hook in frontend/src/config/react-query/hooks.ts that fetches the read-only reporting-unit details for a single reporting unit. It backs every read-only reporting-unit view, including the ReportingUnitBlockDetails page.

Rationale

Use this hook instead of calling useQuery directly. It standardizes the query key, request contract, and notification-aware error handling — the pattern copied from useDistrictVolumeTableDetailQuery in the same file. Errors are translated to user-facing notifications through a notificationTarget option, keeping that concern out of feature components.

Source References

• Source: frontend/src/config/react-query/hooks.ts (useReportingUnitDetailsQuery)
• Query key: frontend/src/config/react-query/queryKeys.ts (queryKeys.reportingUnit.details)
• Tests: covered by the ReportingUnitBlockDetails page tests

Public Interface

Signature

export const useReportingUnitDetailsQuery = <TData = ReportingUnitDto>(
  ruId: number,
  options?: Omit<
    UseQueryOptions<TData, Error, TData, ReturnType<typeof queryKeys.reportingUnit.details>>,
    'queryKey' | 'queryFn'
  > &
    QueryNotificationOptions,
) => { ... };

Parameters

Name	Type	Required	Description
ruId	number	yes	The numeric reporting unit ID used as the route param and cache key.
options	Omit<UseQueryOptions, 'queryKey' | 'queryFn'> + QueryNotificationOptions	no	Optional TanStack Query overrides plus an optional notificationTarget for the inline error notification.

Returns

The TanStack Query result containing the ReportingUnitDto — data, isLoading, isError, refetch, and the rest of the standard query result fields.

Query Key

queryKeys.reportingUnit.details(ruId) resolves to ['reporting-unit', 'details', ruId].

Behavior

• Calls API.reportingUnit.getReportingUnit(ruId) through the shared service layer.
• On error, a useEffect calls notifyProblemDetailsError(query.error, notificationTarget) when a notificationTarget is supplied, dispatching the RFC 7807 problem-details payload to the scoped notification.
• Results follow the shared QueryClient configuration (3-hour stale time, no retry).

Data Contract

frontend/src/services/reportingUnit.types.ts — reportingUnitSchema gained an optional createdAt field (z.optional(z.nullable(z.string())) on the z.looseObject schema). The change is non-breaking: existing payloads without createdAt still parse, and the field fills once the backend exposes a creation date. Follow-up tracked on issue #1250. The Block Details Summary card uses createdAt for its Created on field.

Examples

const { data, isLoading, isError } = useReportingUnitDetailsQuery(ruId, {
  notificationTarget: 'reporting-unit-block-details',
});

Known Constraints

• The hook is read-only; there is no mutation counterpart for reporting units in this hook.
• notificationTarget must match the eventTarget of the page-level PageNotification to surface inline errors.

Change Impact

• ReportingUnitBlockDetails — sole consumer.
• frontend/src/services/reportingUnit.types.ts — createdAt added to reportingUnitSchema.

See Also

• ReportingUnitBlockDetails
• React Query Integration
• Contexts and Hooks