Reference Data

@granit/reference-data provides framework-agnostic types for reference data entities — mirroring Granit.ReferenceData on the .NET backend. Currently covers ISO 3166-1 countries with multilingual labels.

@granit/react-reference-data wraps these into TanStack Query hooks with separate read and admin endpoints for query/mutation operations.

Peer dependencies: axios, react ^19, @tanstack/react-query ^5

Package structure

• Directory@granit/reference-data/ Country types and list params (framework-agnostic)

  • @granit/react-reference-data Query/mutation hooks for country CRUD

Package	Role	Depends on
@granit/reference-data	Country, CountriesListParams	—
@granit/react-reference-data	useCountries, useCountry, useCreateCountry, useUpdateCountry, useDeactivateCountry, useReactivateCountry	@granit/reference-data, @tanstack/react-query, axios, react

Setup

React (recommended)

import { useCountries, useCountry } from '@granit/react-reference-data';
import { api } from './api-client';

function CountrySelect() {
  const { data: countries, isLoading } = useCountries({
    client: api,
    params: { isActive: true },
  });

  // Render country options...
}

TypeScript only

import type { Country, CountriesListParams } from '@granit/reference-data';

TypeScript SDK

Types

interface Country {
  readonly code: string;           // ISO 3166-1 alpha-2
  readonly alpha3: string;         // ISO 3166-1 alpha-3
  readonly numericCode: string;    // ISO 3166-1 numeric
  readonly labelEn: string;
  readonly labelFr: string;
  readonly labelNl: string;
  readonly labelDe: string;
  readonly officialName: string;
  readonly nativeName: string;
  readonly region: string;
  readonly subRegion: string;
  readonly phoneCode: string;
  readonly sortOrder: number;
  readonly isActive: boolean;
  readonly validFrom: string | null;
  readonly validTo: string | null;
  readonly createdAt: string;
  readonly updatedAt: string;
}

interface CountriesListParams {
  readonly search?: string;
  readonly page?: number;
  readonly pageSize?: number;
  readonly sortBy?: string;
  readonly desc?: boolean;
  readonly region?: string;
  readonly isActive?: boolean;
}

React bindings

Framework-agnostic core

All types live in @granit/reference-data — pure TypeScript. The React package below wraps HTTP calls into TanStack Query hooks.

Hook options

interface ReferenceDataHookOptions {
  client: AxiosInstance;
  basePath?: string;    // default: '/api/v1/reference-data/countries'
}

interface ReferenceDataMutationOptions {
  client: AxiosInstance;
  basePath?: string;    // default: '/api/v1/admin/reference-data/countries'
}

Query hooks

useCountries(options)

Fetches countries with optional filtering, search, pagination, and sorting.

function useCountries(
  options: ReferenceDataHookOptions & { params?: CountriesListParams; enabled?: boolean }
): UseQueryResult<Country[]>;

useCountry(code, options)

Fetches a single country by ISO 3166-1 alpha-2 code.

function useCountry(
  code: string,
  options: ReferenceDataHookOptions & { enabled?: boolean }
): UseQueryResult<Country>;

Mutation hooks

All mutations invalidate the country list and detail queries on success.

useCreateCountry(options)

type CreateCountryPayload = Omit<Country, 'createdAt' | 'updatedAt'>;

function useCreateCountry(
  options: ReferenceDataMutationOptions
): UseMutationResult<Country, Error, CreateCountryPayload>;

useUpdateCountry(options)

interface UpdateCountryPayload {
  code: string;
  data: Partial<Omit<Country, 'code' | 'createdAt' | 'updatedAt'>>;
}

function useUpdateCountry(
  options: ReferenceDataMutationOptions
): UseMutationResult<Country, Error, UpdateCountryPayload>;

useDeactivateCountry(options)

Soft-deletes a country by code.

function useDeactivateCountry(
  options: ReferenceDataMutationOptions
): UseMutationResult<void, Error, string>;

useReactivateCountry(options)

Reactivates a previously deactivated country.

function useReactivateCountry(
  options: ReferenceDataMutationOptions
): UseMutationResult<Country, Error, string>;

Query keys

const countryKeys = {
  all: ['reference-data', 'countries'] as const,
  list: (params?: CountriesListParams) => [...countryKeys.all, 'list', params] as const,
  detail: (code: string) => [...countryKeys.all, 'detail', code] as const,
};

Public API summary

Category	Key exports	Package
Types	Country, CountriesListParams	@granit/reference-data
Query hooks	useCountries(), useCountry()	@granit/react-reference-data
Mutation hooks	useCreateCountry(), useUpdateCountry(), useDeactivateCountry(), useReactivateCountry()	@granit/react-reference-data
Cache keys	countryKeys	@granit/react-reference-data

See also

• Granit.ReferenceData module — .NET reference data with i18n labels and CRUD endpoints
• Localization — Country labels use the same multilingual pattern