useDensity
Reads and changes the density of the nearest DensityProvider.
import { useDensity } from "@wunderui/react"Playground
Installation
useDensity is part of WunderUI Free, in the npm package and in the free source. Import it from :
import { useDensity } from "@wunderui/react"When to use
Use useDensity for
- A settings page or a menu that lets people choose how dense the product is.
- Showing the current density somewhere, for example a checked item in a View menu.
- Adapting your own layout to the density, such as the number of rows a list shows.
Use something else for
- Density for one region of a page that should be denser or looser than the rest. It wraps its children and adds no box.
- Table for row density that only one table should follow. Set it on the table card with .
- DensityProvider for choosing the starting density, a controlled density or the storage key. The hook only reads and sets what the provider holds.
Signature
Density sets the size of controls, fields and rows: (the default, controls 32–48 px) or (36–56 px). returns the density the nearest applies and a setter for it, so a settings page can offer the switch.
useDensity(): DensityContextValueReturns
The current density and a setter. Outside a it returns and a setter that does nothing, so a component that reads it also renders without a provider.
Behavior and motion
The hook reads the provider; the provider writes `data-density` on `<html>`.
- State
- The density lives in the nearest . updates it, stores it when the provider persists and calls of a controlled provider. Every component that calls re-renders when the density changes.
- Outside a provider
- Without a provider the hook returns , the library default, and a setter that does nothing. A component that only reads the density keeps working in a test or a story.
- Document and portals
- The provider sets on , so menus, dialogs and every other portal follow it. Control heights, field heights, row padding and card padding read the density tokens, so one change resizes all of them; the page grid does not change.
- Storage and server rendering
- With the default the choice is kept in localStorage under . Nothing touches or while rendering, so the server and the first client render both show the default. Add to the document head, so a stored paints before the first frame instead of jumping after hydration.
- Cleanup
- When the provider unmounts it removes from again. Mount one provider per document: two providers write the same attribute.
- Motion
- Switching density is a layout change, not an interaction, so it does not animate. The provider pauses all transitions for one frame, which keeps controls from sliding to their new size.
- Reduced motion
- Nothing to adapt: the switch has no motion of its own, with or without .
Best practices
- Do
Offer the choice as a plain setting with two labelled options and name what changes: “Comfortable spacing”.
- Don’t
Do not switch the density on its own, for example by screen size. Let the person decide, and use responsive layout for the rest.
- Do
Add to the head when the provider persists, so a returning visitor never sees the default first.
- Don’t
Do not nest a second to scope a region. Wrap the region in instead.
- Do
Read for your own measurements, such as a row height of a virtual list, instead of hard-coding pixel values.
- Don’t
Do not store the density yourself in addition to the provider. Pass or control the provider.
Notes for AI
Give your coding assistant the page or the MCP call instead of screenshots.
get_component("useDensity")import { useDensity } from "@wunderui/react"The full library index for assistants is at /llms.txt.