tinky-spinner

Animated CLI spinner component for React-based terminal applications.

✨ Features

• 100+ Spinner Types - Powered by cli-spinners
• Custom Labels - Add descriptive text alongside your spinner
• TypeScript Support - Fully typed with comprehensive type definitions
• Theming - Customizable through tinky-theme integration
• Lightweight - Minimal dependencies, efficient rendering

📦 Installation

# npm
npm install tinky-spinner

# yarn
yarn add tinky-spinner

# pnpm
pnpm add tinky-spinner

# bun
bun add tinky-spinner

Peer Dependencies

This package requires the following peer dependencies:

npm install react tinky tinky-theme cli-spinners

🚀 Quick Start

Basic Usage

import { Spinner } from "tinky-spinner";

function App() {
  return <Spinner />;
}

Output:

⠋

With Label

import { Spinner } from "tinky-spinner";

function App() {
  return <Spinner label="Loading..." />;
}

Output:

⠋ Loading...

Different Spinner Types

import { Spinner } from "tinky-spinner";

function App() {
  return (
    <>
      <Spinner type="dots" label="Classic" />
      <Spinner type="arrow3" label="Arrows" />
      <Spinner type="line" label="Simple" />
    </>
  );
}

📋 API Reference

Component

The main component for rendering animated CLI spinners.

Props

| Prop | Type | Default | Description | | ------- | ------------- | ----------- | --------------------------------------------------------------------------------------------- | | label | string | undefined | Optional text displayed next to the spinner | | type | SpinnerName | "dots" | The spinner animation type (see cli-spinners) |

Example

<Spinner type="arrow3" label="Processing..." />

useSpinner() Hook

A custom hook for managing spinner animation state directly.

Parameters

| Parameter | Type | Default | Description | | --------- | ------------- | -------- | -------------------------- | | type | SpinnerName | "dots" | The spinner animation type |

Returns

| Property | Type | Description | | -------- | -------- | -------------------------------------- | | frame | string | The current animation frame to display |

Example

import { useSpinner } from "tinky-spinner";
import { Text } from "tinky";

function CustomSpinner() {
  const { frame } = useSpinner({ type: "dots" });
  return <Text>{frame} Loading...</Text>;
}

SpinnerTheme

The theme configuration type for customizing Spinner appearance.

type SpinnerTheme = {
  styles: {
    container: () => BoxProps;
    frame: () => TextProps;
    label: () => TextProps;
  };
};

Type Exports

| Type | Description | | ------------------ | ----------------------------------------------------------- | | SpinnerProps | Props interface for the Spinner component | | UseSpinnerProps | Props interface for the useSpinner hook | | UseSpinnerResult | Return type of the useSpinner hook | | SpinnerName | Union type of all available spinner names from cli-spinners | | SpinnerTheme | Theme configuration type for the Spinner component |

🎨 Theming

Custom Theme Example

import { ThemeProvider, extendTheme } from "tinky-theme";
import { Spinner, spinnerTheme } from "tinky-spinner";

const customTheme = extendTheme(spinnerTheme, {
  styles: {
    frame: () => ({
      color: "magenta",
      bold: true,
    }),
    label: () => ({
      color: "gray",
      italic: true,
    }),
  },
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <Spinner label="Custom themed spinner" />
    </ThemeProvider>
  );
}

🧪 Testing

Run the test suite:

# Run all tests
bun test

# Run tests with coverage
bun test --coverage

# Run tests in watch mode
bun test --watch

🔧 Development

# Install dependencies
bun install

# Build the project
bun run build

# Run linter
bun run lint

# Generate documentation
bun run docs

# Prepare for publishing
bun run prepublish

📄 License

MIT © ByteLand Technology

🔗 Related Packages

• tinky - React for CLIs
• tinky-theme - Theming system for Tinky
• cli-spinners - 100+ spinner types for CLI applications