useAutoDensity

Pro

The value for data-density on the app's root (or any container): "spacious" or "compact", or undefined for the default density. With "auto" (the default), a coarse primary pointer (a finger on a phone or tablet) gives "spacious", so controls are big enough to touch, and a fine one gives the default; it follows the pointer when it changes, as when a tablet's keyboard and trackpad are attached. Any other choice is the person's and wins over the pointer, so offer the choice in your settings with "Automatic" first.

On the server and while the page hydrates it returns undefined (the default density), so the server's markup and the first render agree; the pointer is read just after. window isn't touched when the module is imported.

const density = useAutoDensity(settings.density)
return <div data-density={density}>…</div>

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0 and 4.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/use-auto-density

Brings in: tokens

Usage

TSX · The example above

"use client"

import * as React from "react"
import { useAutoDensity } from "@/lib/candor/use-auto-density"
import { ToggleGroup, ToggleGroupItem } from "@/components/candor/ui/toggle-group"
import { TooltipProvider } from "@/components/candor/ui/tooltip"
import { Button } from "@/components/candor/ui/button"

type Choice = "auto" | "compact" | "default" | "spacious"
const choices: readonly Choice[] = ["auto", "compact", "default", "spacious"]
const isChoice = (value: string): value is Choice => (choices as readonly string[]).includes(value)

export default function Example() {
  // The person's setting, kept with their other preferences. "Automatic" follows the pointer: spacious for a finger.
  const [choice, setChoice] = React.useState<Choice>("auto")
  const density = useAutoDensity(choice)
  return (
    <TooltipProvider>
      {/* In an app, data-density goes on the root (<html> or the layout's outer element). */}
      <div data-density={density} className="flex flex-col items-start gap-4">
        <ToggleGroup type="single" variant="outline" value={choice} onValueChange={(value) => isChoice(value) && setChoice(value)} aria-label="Density">
          <ToggleGroupItem value="auto">Automatic</ToggleGroupItem>
          <ToggleGroupItem value="compact">Compact</ToggleGroupItem>
          <ToggleGroupItem value="default">Default</ToggleGroupItem>
          <ToggleGroupItem value="spacious">Spacious</ToggleGroupItem>
        </ToggleGroup>
        <div className="flex gap-2">
          <Button size="sm">Approve</Button>
          <Button size="sm" variant="outline">
            Ask for changes
          </Button>
        </div>
        <p className="text-xs text-muted-foreground">Density now: {density ?? "default"}</p>
      </div>
    </TooltipProvider>
  )
}

Functions

useAutoDensity(choice: "auto" | "compact" | "default" | "spacious" | undefined = "auto")