1 | # ora [![Build Status](https://travis-ci.org/sindresorhus/ora.svg?branch=master)](https://travis-ci.org/sindresorhus/ora)
|
2 |
|
3 | > Elegant terminal spinner
|
4 |
|
5 | <img src="screenshot.gif" width="629">
|
6 |
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```
|
11 | $ npm install --save ora
|
12 | ```
|
13 |
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```js
|
18 | const ora = require('ora');
|
19 |
|
20 | const spinner = ora('Loading unicorns').start();
|
21 |
|
22 | setTimeout(() => {
|
23 | spinner.color = 'yellow';
|
24 | spinner.text = 'Loading rainbows';
|
25 | }, 1000);
|
26 | ```
|
27 |
|
28 |
|
29 | ## API
|
30 |
|
31 | It will gracefully not do anything when there's no TTY or when in a CI.
|
32 |
|
33 | ### ora([options|text])
|
34 |
|
35 | If a string is provided, it is treated as a shortcut for [`options.text`](#text).
|
36 |
|
37 | #### options
|
38 |
|
39 | Type: `object`
|
40 |
|
41 | ##### text
|
42 |
|
43 | Type: `string`
|
44 |
|
45 | Text to display after the spinner.
|
46 |
|
47 | ##### spinner
|
48 |
|
49 | Type: `string` `object`<br>
|
50 | Default: `dots` <img src="screenshot-spinner.gif" width="14">
|
51 |
|
52 | Name of one of the [provided spinners](https://github.com/sindresorhus/cli-spinners/blob/master/spinners.json). See `example.js` in this repo if you want to test out different spinners.
|
53 |
|
54 | Or an object like:
|
55 |
|
56 | ```js
|
57 | {
|
58 | interval: 80, // optional
|
59 | frames: ['-', '+', '-']
|
60 | }
|
61 | ```
|
62 |
|
63 | ##### color
|
64 |
|
65 | Type: `string`<br>
|
66 | Default: `cyan`<br>
|
67 | Values: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
|
68 |
|
69 | Color of the spinner.
|
70 |
|
71 | ##### interval
|
72 |
|
73 | Type: `number`<br>
|
74 | Default: Provided by the spinner or `100`
|
75 |
|
76 | Interval between each frame.
|
77 |
|
78 | Spinners provide their own recommended interval, so you don't really need to specify this.
|
79 |
|
80 | ##### stream
|
81 |
|
82 | Type: `WritableStream`<br>
|
83 | Default: `process.stderr`
|
84 |
|
85 | Stream to write the output.
|
86 |
|
87 | You could for example set this to `process.stdout` instead.
|
88 |
|
89 | ##### enabled
|
90 |
|
91 | Type: `boolean`<br>
|
92 | Default: `false`
|
93 |
|
94 | Force enabling of the spinner regardless of the `stream` not being run inside a TTY context and/or in a CI environment.
|
95 |
|
96 | ### Instance
|
97 |
|
98 | #### .start()
|
99 |
|
100 | Start the spinner. Returns the instance.
|
101 |
|
102 | #### .stop()
|
103 |
|
104 | Stop and clear the spinner. Returns the instance.
|
105 |
|
106 | ### .succeed()
|
107 |
|
108 | Stop the spinner, change it to a green `✔` and persist the `text`. Returns the instance. See the GIF below.
|
109 |
|
110 | ### .fail()
|
111 |
|
112 | Stop the spinner, change it to a red `✖` and persist the `text`. Returns the instance. See the GIF below.
|
113 |
|
114 | ### .stopAndPersist([symbol])
|
115 |
|
116 | Stop the spinner, change it to `symbol` (or `' '` if `symbol` is not provided) and persist the `text`. Returns the instance. See the GIF below.
|
117 |
|
118 | <img src="screenshot-2.gif" width="480">
|
119 |
|
120 | #### .clear()
|
121 |
|
122 | Clear the spinner. Returns the instance.
|
123 |
|
124 | #### .render()
|
125 |
|
126 | Manually render a new frame. Returns the instance.
|
127 |
|
128 | #### .frame()
|
129 |
|
130 | Get a new frame.
|
131 |
|
132 | #### .text
|
133 |
|
134 | Change the text.
|
135 |
|
136 | #### .color
|
137 |
|
138 | Change the spinner color.
|
139 |
|
140 | #### .promise(action, [options|text])
|
141 |
|
142 | Starts a spinner for a promise. The spinner is stopped with `.succeed()` if the promise fulfills or with `.fail()` if it rejects. Returns the spinner instance.
|
143 |
|
144 | ##### action
|
145 |
|
146 | Type: `Promise`
|
147 |
|
148 |
|
149 | ## Related
|
150 |
|
151 | - [cli-spinners](https://github.com/sindresorhus/cli-spinners) - Spinners for use in the terminal
|
152 | - [listr](https://github.com/SamVerschueren/listr) - Terminal task list
|
153 |
|
154 |
|
155 | ## License
|
156 |
|
157 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|