0
# Ink Spinner
1

2
Ink Spinner is a React component that provides animated loading indicators for Ink CLI applications. It uses the extensive collection of spinners from cli-spinners, offering various animation styles like dots, lines, stars, and more to create polished command-line interfaces with visual feedback during long-running operations.
3

4
## Package Information
5

6
- **Package Name**: ink-spinner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ink-spinner`
10

11
## Core Imports
12

13
```typescript
14
import Spinner from "ink-spinner";
15
import type { SpinnerName } from "cli-spinners";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Spinner = require("ink-spinner");
22
```
23

24
## Basic Usage
25

26
```tsx
27
import React from 'react';
28
import { render, Text } from 'ink';
29
import Spinner from 'ink-spinner';
30

31
render(
32
  <Text>
33
    <Text color="green">
34
      <Spinner type="dots" />
35
    </Text>
36
    {' Loading'}
37
  </Text>
38
);
39
```
40

41
## Capabilities
42

43
### Spinner Component
44

45
A React functional component that renders animated spinner frames with configurable animation types.
46

47
```typescript { .api }
48
/**
49
 * Spinner component that displays animated loading indicators
50
 * @param props - Component props containing spinner configuration
51
 * @returns React component displaying the animated spinner
52
 */
53
function Spinner({ type = 'dots' }: Props): React.JSX.Element;
54

55
interface Props {
56
  /**
57
   * Type of spinner animation to display.
58
   * See cli-spinners for available options (dots, line, star, etc.)
59
   * @default 'dots'
60
   */
61
  type?: SpinnerName;
62
}
63
```
64

65
**Usage Examples:**
66

67
```tsx
68
import React from 'react';
69
import { Text } from 'ink';
70
import Spinner from 'ink-spinner';
71

72
// Default dots spinner
73
<Spinner />
74

75
// Line spinner
76
<Spinner type="line" />
77

78
// Star spinner  
79
<Spinner type="star" />
80

81
// Circle spinner
82
<Spinner type="circle" />
83

84
// Pipe spinner
85
<Spinner type="pipe" />
86
```
87

88
## Types
89

90
```typescript { .api }
91
/**
92
 * Type representing all available spinner names from cli-spinners library
93
 * Imported from cli-spinners package
94
 * Includes options like: 'dots', 'line', 'star', 'circle', 'pipe', 'flip', etc.
95
 */
96
type SpinnerName = import('cli-spinners').SpinnerName;
97

98
interface Props {
99
  /**
100
   * Type of spinner animation to display
101
   * @default 'dots'
102
   */
103
  type?: SpinnerName;
104
}
105
```
106

107
## Dependencies
108

109
- **cli-spinners**: ^2.7.0 - Provides spinner frame data and timing intervals
110
- **ink**: >=4.0.0 (peer dependency) - UI framework for CLI applications  
111
- **react**: >=18.0.0 (peer dependency) - React library for component rendering
112

113
## Animation Behavior
114

115
The Spinner component automatically:
116

117
- Cycles through animation frames at intervals defined by the selected spinner type
118
- Uses React hooks (useState, useEffect) for state management and timer control
119
- Starts animation on mount and cleans up timers on unmount
120
- Resets to the first frame when reaching the end of the animation sequence
121
- Updates animation timing when the spinner type changes
122

123
## Available Spinner Types
124

125
The component supports all spinner types from the cli-spinners library, including but not limited to:
126

127
- `dots` (default): Simple dot animation
128
- `line`: Horizontal line animation  
129
- `star`: Rotating star animation
130
- `circle`: Circle segments animation
131
- `pipe`: Pipe character animation
132
- `flip`: Flipping animation
133
- `hamburger`: Hamburger icon animation
134
- `growVertical`: Growing vertical bars
135
- `balloon`: Balloon animation
136
- `noise`: Random noise pattern
137
- `bounce`: Bouncing animation
138
- `boxBounce`: Box bouncing animation
139

140
For the complete list of available spinners, refer to the [cli-spinners repository](https://github.com/sindresorhus/cli-spinners).