0
# Customization and Styling
1

2
Configure spinner appearance including colors, text formatting, placement options, and text animations. All properties can be modified dynamically while the spinner is running.
3

4
## Capabilities
5

6
### Text Customization
7

8
Control the text displayed alongside the spinner with dynamic updates and color formatting.
9

10
```python { .api }
11
@property
12
def text(self):
13
    """
14
    Get the current spinner text.
15
    
16
    Returns:
17
    - str: Current text value
18
    """
19

20
@text.setter
21
def text(self, text):
22
    """
23
    Set spinner text with automatic animation handling for long strings.
24
    
25
    Parameters:
26
    - text (str): New text to display
27
    """
28

29
@property  
30
def text_color(self):
31
    """
32
    Get the current text color.
33
    
34
    Returns:
35
    - str: Current text color or None
36
    """
37

38
@text_color.setter
39
def text_color(self, text_color):
40
    """
41
    Set the text color.
42
    
43
    Parameters:
44
    - text_color (str): Color name - "red", "green", "blue", "cyan", "magenta", "yellow", "white", "grey"
45
    """
46
```
47

48
**Usage Example:**
49

50
```python
51
from halo import Halo
52
import time
53

54
spinner = Halo(text='Starting process', text_color='blue')
55
spinner.start()
56

57
# Update text dynamically
58
spinner.text = 'Loading data'
59
time.sleep(1)
60

61
spinner.text = 'Processing results'  
62
spinner.text_color = 'green'
63
time.sleep(1)
64

65
spinner.stop()
66
```
67

68
### Spinner Style and Color
69

70
Customize the spinner animation and color with support for built-in spinner types and custom definitions.
71

72
```python { .api }
73
@property
74
def spinner(self):
75
    """
76
    Get current spinner configuration.
77
    
78
    Returns:
79
    - dict: Spinner definition with 'frames' and 'interval' keys
80
    """
81

82
@spinner.setter  
83
def spinner(self, spinner):
84
    """
85
    Set spinner type or custom spinner definition.
86
    
87
    Parameters:
88
    - spinner (str|dict): Spinner name or custom definition
89
      - str: Built-in spinner name (e.g., "dots", "line", "star", "arrow")
90
      - dict: Custom spinner with 'frames' (list) and 'interval' (int) keys
91
    """
92

93
@property
94
def color(self):
95
    """
96
    Get current spinner color.
97
    
98
    Returns:
99
    - str: Current spinner color
100
    """
101

102
@color.setter
103
def color(self, color):
104
    """
105
    Set spinner color.
106
    
107
    Parameters:
108
    - color (str): Color name - "cyan", "red", "green", "yellow", "blue", "magenta", "white", "grey"
109
    """
110
```
111

112
**Usage Example:**
113

114
```python
115
from halo import Halo
116
import time
117

118
# Built-in spinner types
119
spinner = Halo(text='Loading', spinner='dots', color='cyan')
120
spinner.start()
121
time.sleep(1)
122

123
# Change to different built-in spinner
124
spinner.spinner = 'star'  
125
spinner.color = 'green'
126
time.sleep(1)
127

128
# Custom spinner definition
129
custom_spinner = {
130
    'frames': ['◐', '◓', '◑', '◒'],
131
    'interval': 100
132
}
133
spinner.spinner = custom_spinner
134
spinner.color = 'red'
135
time.sleep(2)
136

137
spinner.stop()
138
```
139

140
### Placement and Layout
141

142
Control where the spinner appears relative to the text and how the overall layout is arranged.
143

144
```python { .api }
145
@property
146
def placement(self):
147
    """
148
    Get current spinner placement.
149
    
150
    Returns:
151
    - str: Current placement ("left" or "right")
152
    """
153

154
@placement.setter
155
def placement(self, placement):
156
    """
157
    Set spinner placement relative to text.
158
    
159
    Parameters:  
160
    - placement (str): Position - "left" or "right"
161
    
162
    Raises:
163
    - ValueError: If placement is not "left" or "right"
164
    """
165
```
166

167
**Usage Example:**
168

169
```python
170
from halo import Halo
171
import time
172

173
# Left placement (default)
174
spinner = Halo(text='Loading data', placement='left')
175
spinner.start()
176
time.sleep(1)
177

178
# Switch to right placement  
179
spinner.placement = 'right'
180
time.sleep(1)
181

182
spinner.stop()
183
```
184

185
### Text Animation
186

187
Handle long text with scrolling animations when text exceeds terminal width.
188

189
```python { .api }
190
@property
191
def animation(self):
192
    """
193
    Get current text animation type.
194
    
195
    Returns:
196
    - str: Current animation type or None
197
    """
198

199
@animation.setter
200
def animation(self, animation):
201
    """
202
    Set text animation for long strings.
203
    
204
    Parameters:
205
    - animation (str): Animation type - "bounce", "marquee", or None
206
      - "bounce": Text bounces back and forth within terminal width
207
      - "marquee": Text scrolls continuously like a marquee
208
      - None: Long text truncated with ellipsis
209
    """
210
```
211

212
**Usage Example:**
213

214
```python
215
from halo import Halo
216
import time
217

218
# Long text with marquee animation
219
long_text = "This is a very long text that exceeds terminal width and will scroll"
220
spinner = Halo(text=long_text, animation='marquee', spinner='dots')
221
spinner.start()
222
time.sleep(3)
223

224
# Switch to bounce animation
225
spinner.animation = 'bounce'
226
time.sleep(3)
227

228
# Disable animation (truncate with ellipsis)
229
spinner.animation = None
230
time.sleep(1)
231

232
spinner.stop()
233
```
234

235
## Built-in Spinner Types
236

237
Common spinner types available (from the `spinners` package):
238

239
```python
240
# Fast spinners
241
"dots"          # ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
242
"line"          # |/-\
243
"arrow"         # ←↖↑↗→↘↓↙
244

245
# Animated spinners  
246
"star"          # ✶✸✹✺✹✷
247
"bouncingBar"   # [    ] [=   ] [==  ] [=== ] [====]
248
"bouncingBall"  # ( ●    ) (  ●   ) (   ●  ) (    ● )
249

250
# Decorative spinners
251
"hearts"        # 💛💙💜💚❤️
252
"moon"          # 🌑🌒🌓🌔🌕🌖🌗🌘
253
"earth"         # 🌍🌎🌏
254
```
255

256
## Custom Spinner Creation
257

258
```python
259
# Define custom spinner
260
custom_spinner = {
261
    'frames': ['⚫', '⚪', '⚫', '⚪'],  # Animation frames
262
    'interval': 200                    # Milliseconds between frames
263
}
264

265
spinner = Halo(
266
    text='Custom animation',
267
    spinner=custom_spinner,
268
    color='magenta'  
269
)
270

271
with spinner:
272
    time.sleep(3)
273
```
274

275
## Dynamic Customization
276

277
```python
278
from halo import Halo
279
import time
280
import random
281

282
spinner = Halo(text='Dynamic demo', spinner='dots')
283
spinner.start()
284

285
colors = ['red', 'green', 'blue', 'cyan', 'magenta', 'yellow'] 
286
spinners = ['dots', 'line', 'star', 'arrow']
287

288
for i in range(10):
289
    # Randomly change appearance
290
    spinner.color = random.choice(colors)
291
    spinner.spinner = random.choice(spinners)
292
    spinner.text = f'Random style {i+1}'
293
    time.sleep(0.5)
294

295
spinner.stop()
296
```