Skip to main content
Join the waitlist

ComponentDefaults

Utility provider that sets the default control size for every control below it.

import { ComponentDefaultsProvider } from "@usefragments/ui";Source

Preview

<ComponentDefaultsProvider controlSize="sm">
  <Stack direction="row" gap="sm">
    <Button variant="soft">Filter</Button>
    <Button variant="ghost">Export</Button>
  </Stack>
</ComponentDefaultsProvider>

Usage

Use when

  • A region needs every control at one size (dense table toolbars, compact sidebars, inspector panels)
  • A subtree should default to xs, sm or lg controls without repeating the size prop

Avoid when

  • Sizing a single control (pass its size prop)
  • Changing spacing or typography (use tokens, not control size)

Implementation notes

  • The one entry point for default control size: it renders no element and paints nothing
  • Nest providers to override the size for a smaller region; an omitted controlSize inherits the parent
  • An explicit size prop on a control always wins over the provider default
  • Composes with the theme scale: the provider picks the step (xs 24, sm 28, md 32, lg 40), --fui-scale multiplies every step
  • A control that draws no xs step renders sm inside an xs region

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Nested Override

A nested provider narrows the default for one region.

<ComponentDefaultsProvider controlSize="lg">
  <Button>Large by default</Button>
  <ComponentDefaultsProvider controlSize="sm">
    <Button>Small in this region</Button>
  </ComponentDefaultsProvider>
</ComponentDefaultsProvider>

Inspector

An xs region: IconButton and Button draw the 24px step.

import { Plus } from "@phosphor-icons/react";

<ComponentDefaultsProvider controlSize="xs">
  <Stack direction="row" gap="xs">
    <IconButton aria-label="Add">
      <Plus aria-hidden />

API reference

Component props
Prop
Type
Default
Description
childrenRequiredReact.ReactNodeNot setSubtree that inherits the defaults
controlSize"xs" | "sm" | "md" | "lg" | undefinedxssmmdlgNot setDefault size for controls that do not pass their own size prop. A control without the step renders its nearest one (xs falls back to sm).

Accessibility

  • xs and sm controls still meet the kit's minimum target size through the hit-area recipe

Related components

  • ThemesiblingTheme sets --fui-scale; the provider picks the step that scale multiplies
  • ButtonchildControls resolve their size through useResolvedControlSize

Next steps