@vinyasa/feedback

11 feedback primitives: Spinner, ProgressBar, CircularProgress, Alert, Banner, InlineMessage, Skeleton, LoadingOverlay, EmptyState, ErrorBoundary, Toaster (+ the toast imperative API).

Installation

pnpm add @vinyasa/feedback @vinyasa/layout @vinyasa/typography @vinyasa/icons @vinyasa/button @vinyasa/tokens react react-dom

This is the one package that sits on top of every other category — it composes @vinyasa/layout (Box, Stack, Center), @vinyasa/typography (Heading, Paragraph), @vinyasa/icons (status icons), and @vinyasa/button (action slots), rather than being a peer to them. All five are peer dependencies. Rendering requires a VinyasaProvider (from @vinyasa/tokens) above these components in the tree — including <Toaster />, which renders in place (not via a portal — see its own docs below) and so must stay inside the same VinyasaProvider subtree as everything else.

This package has no root export — every component is subpath-only (import Spinner from '@vinyasa/feedback/spinner', never from '@vinyasa/feedback'). A root barrel re-exporting all 11 components would let a bundler tree-shake the unused JS down to just the ones you import, but the CSS side-effect imports the others carry are not eligible for the same tree-shaking (confirmed empirically with both esbuild and Rollup on this monorepo's other packages). Removing the root entry entirely makes that the only possible outcome, not something that depends on your bundler being clever enough to shake it out.

New tokens this package introduces

Alert/Banner/InlineMessage/Toast share one status system — four pale-background + readable-text pairs, purpose-built for status communication (distinct from primary/secondary/tertiary, which are Button's brand-hierarchy roles, and from the existing solid error/onError pair, which is built for Button's loud danger variant, not a pale alert box):

| Token | Value | Source | | ------------------- | --------- | -------------------- | | statusInfoBg | #dbeafe | existing blue[100] | | statusInfoText | #1d4ed8 | existing blue[700] | | statusSuccessBg | #dcfce7 | new green[100] | | statusSuccessText | #15803d | new green[700] | | statusWarningBg | #fef3c7 | new amber[100] | | statusWarningText | #b45309 | new amber[700] | | statusErrorBg | #fee2e2 | existing red[100] | | statusErrorText | #dc2626 | existing red[600] |

Everything else (Spinner, Skeleton, both progress components, LoadingOverlay) reuses existing tokens — primary/secondary/borderColorDefault/radiusFull/elevationOverlay/zIndexOverlay/zIndexToast.

Spacing

Every component accepts the same margin/padding props as @vinyasa/layout — see its README for the full prop and token tables.

Usage

Spinner

import Spinner from '@vinyasa/feedback/spinner';

<Spinner size="md" />;

A public, standalone spinner — distinct from the private one @vinyasa/button already uses internally for its own loading prop, not a shared dependency between the two.

ProgressBar, CircularProgress

import ProgressBar from '@vinyasa/feedback/progress-bar';
import CircularProgress from '@vinyasa/feedback/circular-progress';

<ProgressBar value={60} />
<CircularProgress value={60} />
<CircularProgress />   {/* indeterminate — omit value */}

Both expose role="progressbar" with aria-valuenow/aria-valuemin/aria-valuemax.

Alert, Banner, InlineMessage

One shared status vocabulary — status: info / success / warning / error — differing only in layout: Alert is boxed (icon + title + description), Banner is edge-to-edge (for a page/section top), InlineMessage is bare (icon + colored text, e.g. under a form field).

import Alert from '@vinyasa/feedback/alert';
import Banner from '@vinyasa/feedback/banner';
import InlineMessage from '@vinyasa/feedback/inline-message';

<Alert status="success" title="Saved" description="Your changes have been saved." />
<Banner status="warning">Scheduled maintenance tonight at 10pm.</Banner>
<InlineMessage status="error">This field is required.</InlineMessage>

Skeleton

import Skeleton from '@vinyasa/feedback/skeleton';

<Skeleton width="100%" height="1rem" />
<Skeleton circle width="3rem" height="3rem" />

LoadingOverlay

import LoadingOverlay from '@vinyasa/feedback/loading-overlay';

<LoadingOverlay visible={isLoading}>
	<Content />
</LoadingOverlay>;

EmptyState

import EmptyState from '@vinyasa/feedback/empty-state';
import Button from '@vinyasa/button/button';

<EmptyState
	icon={<InboxIcon />}
	title="No results"
	description="Try adjusting your filters."
	action={<Button>Clear filters</Button>}
/>;

ErrorBoundary

The one class component in the system — getDerivedStateFromError/componentDidCatch have no hook equivalent.

import ErrorBoundary from '@vinyasa/feedback/error-boundary';
import EmptyState from '@vinyasa/feedback/empty-state';

<ErrorBoundary fallback={<EmptyState title="Something went wrong" />}>
	<App />
</ErrorBoundary>;

Toaster + toast

An imperative API: mount one <Toaster /> inside VinyasaProvider, near the app root, then call toast.show() from anywhere.

import Toaster, { toast } from '@vinyasa/feedback/toaster';

// once, inside VinyasaProvider, near the app root
<Toaster position="bottom-right" />;

// from anywhere
toast.show({ status: 'success', title: 'Saved' });

position accepts top-left / top-center / top-right / bottom-left / bottom-center / bottom-right, defaulting to bottom-right. Mount exactly one <Toaster /> — the toast API is backed by a single global store, same as Mantine/sonner, so multiple instances would all render the same list rather than partitioning it by position.

Toaster renders in place with position: fixed, deliberately not via a portal to document.body: VinyasaProvider injects its theme as CSS custom properties on its own wrapper element rather than on :root, so anything portaled outside that subtree would lose every token (transparent backgrounds, no radius, no shadow). position: fixed already floats the toast stack above the rest of the page without leaving the themed DOM subtree.

Subpath imports

Every component is imported by its own subpath (e.g. @vinyasa/feedback/spinner) — there is no root @vinyasa/feedback entry, so import { X } from '@vinyasa/feedback' fails to resolve. See "This package has no root export" above for why.

Development

From the repository root:

pnpm --filter @vinyasa/feedback build
pnpm --filter @vinyasa/feedback test
pnpm --filter @vinyasa/feedback lint
pnpm storybook   # Feedback/*