Button

Server component, no client JS

ImportCopy Anchor Link

import { Button } from '@nizivo/react/button';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/button.css';

Static or interactiveCopy Anchor Link

Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build mode; its code is bundled only when a client component (a 'use client' file) imports it.

onClick works as on any <button>. In a client app (a Vite or React Router single-page app, or a 'use client' file) pass it, refs and state as usual (In a client app). Only a Server Component cannot pass it, which is React's rule for every component: there, use type="submit" in a <form action={serverAction}>, render={<a href="…" />}, or a client component that owns the handler. How to choose.

PendingCopy Anchor Link

pending replaces the leading icon with a spinner, keeps the label, and keeps the button focusable with aria-disabled, swallowing clicks. The spinner turns once every 800 ms (--nz-duration-spin, Figma's duration/spin). Under Reduced motion (the OS setting, or data-nz-motion="reduce" on an ancestor) it stops, and the text "Loading…" shows in the label's place, so the wait is still visible without movement (Figma's Accessibility page: "Spinner and skeleton loops stop; a text label shows"). The text and the label share one space, so the button keeps its width when pending starts (it grows only if "Loading…" is wider than the label). Where the text does not fit, it ends in an ellipsis.

<>
  {/* Reduced motion: the spinner stops and "Loading…" replaces "Publishing" */}
  <Button pending>Publishing</Button>
  <Button pending labels={{ pending: 'Wird geladen…' }}>
    Veröffentlichen
  </Button>
</>

The label is only made transparent, so it stays in the accessible name, after the text on screen: "Loading… Publishing" (WCAG 2.5.3, the visible words are part of the name). Under default motion the text is not rendered visibly and the name is the label. Assistive technology also learns the state from aria-disabled. labels={{ pending: '' }} shows no text and keeps the label visible. The markup is the same in both motion modes; only CSS reads the preference.

Translate the text with labels.pending. It is set per instance: Button is a server component, so NizivoConfig's labels, which reach the client parts only, do not reach it. SubmitButton, its client twin, does read button.pending from them. A localised app wraps Button once and uses the wrapper everywhere (see Strings and locales):

import { Button, type ButtonProps } from '@nizivo/react/button';

const strings = { loading: 'Wird geladen…' }; // the app's own message catalogue

export function AppButton({ labels, ...props }: ButtonProps) {
  return <Button labels={{ pending: strings.loading, ...labels }} {...props} />;
}

ExamplesCopy Anchor Link

import type { ComponentPropsWithRef, JSX } from 'react';
import { Button } from '@nizivo/react/button';

/** Stands in for a router link (Next `Link`, React Router `Link`). */
function Link({ children, ...props }: ComponentPropsWithRef<'a'>): JSX.Element {
  return <a {...props}>{children}</a>;
}

export function ButtonExample(): JSX.Element {
  return (
    <div>
      <Button variant="primary">Save</Button>
      <Button>Cancel</Button>
      <Button variant="accent">Upgrade</Button>
      <Button variant="critical">Remove</Button>
      <Button size="lg">Continue</Button>
      <Button variant="critical" size="sm" disabled>
        Delete
      </Button>
      <Button variant="tertiary" pending>
        Publishing
      </Button>
      <Button render={<Link href="/orders" />} fullWidth>
        Orders
      </Button>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

ButtonLabels type

import type { ButtonLabels } from '@nizivo/react/button'

Button's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
pendingrequired	string	'Loading…'	The text a pending button shows in place of its label under Reduced motion, where the spinner stops (Figma: "Spinner and skeleton loops stop; a text label shows").

ButtonProps type

import type { ButtonProps } from '@nizivo/react/button'

The props of Button, listed above.

ButtonState type

import type { ButtonState } from '@nizivo/react/button'

The render state of Button, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-button, .nz-button-icon, .nz-button-label, .nz-button-pending-label, .nz-glyph-spinner.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• button: draws the focus outline itself on keyboard focus.

KeyboardCopy Anchor Link

Source: a native <button> (button.tsx); with render={<a />} it is a link and only Enter activates it.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:11244
• Ghost masters: Figma node 744:263