/// hooks

useDensity

Reads the active UI density — "default" or "compact" — from the nearest PdsProvider. Use it to make a component’s behaviour density-aware where CSS alone cannot reach.

Signature

useDensity

function useDensity(): "default" | "compact";

Returns

Field	Type	Description
`(return)`	`"default" \| "compact"`	The active density from the nearest provider.

When to use

Adjust non-visual behaviour by density — e.g. how many rows a virtualised table shows per page, or whether a label collapses to an icon.
Choose a matching component size prop programmatically when composing controls inside a compact region.
You do not need it for spacing or control heights — those already respond to data-density through the token layer. Reach for the hook only when the decision lives in React.

Example

density-aware page size

import { useDensity } from "@protocore/pds";

function useRowsPerPage() {
  const density = useDensity();
  return density === "compact" ? 25 : 15;
}

Note

useDensity requires an ancestor <PdsProvider>. Set the density on the provider (or via data-density) — the hook reads it, it does not set it.