0
# Composite Charts
1

2
Multi-chart layouts and complex visualizations for creating dashboards, reports, and comprehensive data presentations. These components enable combining multiple charts, creating animations, and organizing content across pages and tabs.
3

4
## Capabilities
5

6
### Grid Layouts
7

8
Combine multiple charts in a single layout with precise positioning control.
9

10
```python { .api }
11
class Grid:
12
    def __init__(self, init_opts=None, render_opts=None):
13
        """
14
        Initialize a grid layout.
15
        
16
        Args:
17
            init_opts (InitOpts, optional): Chart initialization options
18
            render_opts (RenderOpts, optional): Rendering options
19
        """
20

21
    def add(self, chart, grid_opts, grid_index=0):
22
        """
23
        Add a chart to the grid.
24
        
25
        Args:
26
            chart: Chart instance to add
27
            grid_opts (GridOpts): Grid positioning options
28
            grid_index (int): Grid index for multiple grids
29
            
30
        Returns:
31
            Grid: Self for method chaining
32
        """
33
```
34

35
**Usage Example:**
36
```python
37
from pyecharts.charts import Bar, Line, Grid
38
from pyecharts import options as opts
39

40
# Create individual charts
41
bar = (
42
    Bar()
43
    .add_xaxis(["A", "B", "C"])
44
    .add_yaxis("Series", [1, 2, 3])
45
)
46

47
line = (
48
    Line()
49
    .add_xaxis(["A", "B", "C"])
50
    .add_yaxis("Series", [3, 2, 1])
51
)
52

53
# Combine in grid
54
grid = (
55
    Grid()
56
    .add(bar, grid_opts=opts.GridOpts(pos_left="55%"))
57
    .add(line, grid_opts=opts.GridOpts(pos_right="55%"))
58
)
59
```
60

61
### Timeline Animations
62

63
Create animated charts that change over time with timeline controls.
64

65
```python { .api }
66
class Timeline:
67
    def __init__(self, init_opts=None, render_opts=None):
68
        """
69
        Initialize a timeline animation.
70
        
71
        Args:
72
            init_opts (InitOpts, optional): Chart initialization options
73
            render_opts (RenderOpts, optional): Rendering options
74
        """
75

76
    def add(self, chart, time_point):
77
        """
78
        Add a chart frame to the timeline.
79
        
80
        Args:
81
            chart: Chart instance for this time point
82
            time_point (str): Time point label
83
            
84
        Returns:
85
            Timeline: Self for method chaining
86
        """
87

88
    def add_schema(self, **kwargs):
89
        """
90
        Configure timeline settings.
91
        
92
        Args:
93
            axis_type (str): Timeline axis type ("category", "time", "value")
94
            is_auto_play (bool): Enable auto-play
95
            is_loop_play (bool): Loop animation
96
            is_rewind_play (bool): Enable rewind
97
            play_interval (int): Play interval in milliseconds
98
            is_timeline_show (bool): Show timeline control
99
            symbol (str): Timeline symbol
100
            symbol_size (int): Timeline symbol size
101
            is_inverse (bool): Inverse timeline direction
102
            pos_left (str): Left position
103
            pos_right (str): Right position
104
            pos_top (str): Top position
105
            pos_bottom (str): Bottom position
106
            width (str): Timeline width
107
            height (str): Timeline height
108
            
109
        Returns:
110
            Timeline: Self for method chaining
111
        """
112
```
113

114
### Multi-Page Documents
115

116
Create multi-page chart documents for comprehensive reports and dashboards.
117

118
```python { .api }
119
class Page:
120
    def __init__(self, page_title="Awesome-pyecharts", layout_opts=None):
121
        """
122
        Initialize a multi-page document.
123
        
124
        Args:
125
            page_title (str): Document title
126
            layout_opts (PageLayoutOpts, optional): Page layout configuration
127
        """
128

129
    def add(self, *charts):
130
        """
131
        Add charts to the page.
132
        
133
        Args:
134
            *charts: Variable number of chart instances
135
            
136
        Returns:
137
            Page: Self for method chaining
138
        """
139

140
    def render(self, path="render.html"):
141
        """
142
        Render the multi-page document.
143
        
144
        Args:
145
            path (str): Output file path
146
            
147
        Returns:
148
            str: Generated HTML content
149
        """
150

151
    def save_resize_html(self, source_path, dest_path, cfg_file=None, cfg_dict=None):
152
        """
153
        Save resized HTML version.
154
        
155
        Args:
156
            source_path (str): Source HTML file path
157
            dest_path (str): Destination file path
158
            cfg_file (str, optional): Configuration file path
159
            cfg_dict (dict, optional): Configuration dictionary
160
        """
161
```
162

163
### Tabbed Interfaces
164

165
Create tabbed chart interfaces for organized content presentation.
166

167
```python { .api }
168
class Tab:
169
    def __init__(self, page_title="Awesome-pyecharts"):
170
        """
171
        Initialize a tabbed interface.
172
        
173
        Args:
174
            page_title (str): Document title
175
        """
176

177
    def add(self, chart, tab_name):
178
        """
179
        Add a chart as a tab.
180
        
181
        Args:
182
            chart: Chart instance
183
            tab_name (str): Tab label
184
            
185
        Returns:
186
            Tab: Self for method chaining
187
        """
188

189
    def render(self, path="render.html"):
190
        """
191
        Render the tabbed interface.
192
        
193
        Args:
194
            path (str): Output file path
195
            
196
        Returns:
197
            str: Generated HTML content
198
        """
199
```
200

201
## Configuration Options
202

203
### Grid Configuration
204

205
```python { .api }
206
class GridOpts:
207
    def __init__(self, **kwargs):
208
        """
209
        Grid positioning and spacing options.
210
        
211
        Args:
212
            pos_left (str|int): Left position ("20%", 100)
213
            pos_right (str|int): Right position
214
            pos_top (str|int): Top position
215
            pos_bottom (str|int): Bottom position
216
            width (str|int): Grid width
217
            height (str|int): Grid height
218
            is_contain_label (bool): Include axis labels in grid area
219
            background_color (str): Grid background color
220
            border_color (str): Grid border color
221
            border_width (int): Grid border width
222
            shadow_blur (int): Shadow blur radius
223
            shadow_color (str): Shadow color
224
            shadow_offset_x (int): Shadow X offset
225
            shadow_offset_y (int): Shadow Y offset
226
            opacity (float): Grid opacity
227
            tooltip_opts (TooltipOpts): Grid-specific tooltip options
228
        """
229
```
230

231
### Page Layout Configuration
232

233
```python { .api }
234
class PageLayoutOpts:
235
    def __init__(self, **kwargs):
236
        """
237
        Multi-page layout configuration.
238
        
239
        Args:
240
            justify_content (str): Horizontal alignment ("center", "start", "end", "space-around", "space-between")
241
            align_items (str): Vertical alignment ("center", "start", "end")
242
            display (str): Display mode ("flex")
243
            flex_wrap (str): Flex wrap behavior ("wrap", "nowrap")
244
            margin (str): Page margins
245
            padding (str): Page padding
246
            background_color (str): Page background color
247
        """
248
```
249

250
### Timeline Configuration
251

252
```python { .api }
253
class TimelineCheckPointerStyle:
254
    def __init__(self, **kwargs):
255
        """
256
        Timeline checkpoint styling.
257
        
258
        Args:
259
            color (str): Checkpoint color
260
            border_color (str): Checkpoint border color
261
            border_width (int): Checkpoint border width
262
            symbol (str): Checkpoint symbol
263
            symbol_size (int): Checkpoint symbol size
264
            symbol_offset (list): Symbol offset [x, y]
265
            animation_duration (int): Animation duration
266
            animation_easing (str): Animation easing function
267
        """
268

269
class TimelineControlStyle:
270
    def __init__(self, **kwargs):
271
        """
272
        Timeline control button styling.
273
        
274
        Args:
275
            is_show (bool): Show control buttons
276
            show_play_button (bool): Show play button
277
            show_prev_button (bool): Show previous button
278
            show_next_button (bool): Show next button
279
            itemsize (int): Control button size
280
            itemgap (int): Gap between control buttons
281
            position (str): Control position ("left", "right", "top", "bottom")
282
            play_icon (str): Play button icon
283
            stop_icon (str): Stop button icon
284
            prev_icon (str): Previous button icon
285
            next_icon (str): Next button icon
286
            color (str): Control button color
287
            border_color (str): Control button border color
288
            border_width (int): Control button border width
289
        """
290
```
291

292
### Tab Configuration
293

294
```python { .api }
295
class TabChartGlobalOpts:
296
    def __init__(self, **kwargs):
297
        """
298
        Tab chart global options.
299
        
300
        Args:
301
            animation_opts (AnimationOpts): Animation configuration
302
            title_opts (TitleOpts): Title configuration
303
            legend_opts (LegendOpts): Legend configuration
304
            tooltip_opts (TooltipOpts): Tooltip configuration
305
            toolbox_opts (ToolboxOpts): Toolbox configuration
306
            brush_opts (BrushOpts): Brush configuration
307
            datazoom_opts (list): Data zoom controls
308
            visualmap_opts (VisualMapOpts): Visual mapping
309
            aria_opts (AriaOpts): Accessibility options
310
            dataset_opts (DatasetOpts): Dataset configuration
311
        """
312
```
313

314
## Advanced Composite Patterns
315

316
### Synchronized Charts
317

318
Create multiple charts that share interactions and data updates:
319

320
```python
321
# Example: Synchronized bar and line charts
322
from pyecharts.charts import Bar, Line, Grid
323
from pyecharts import options as opts
324

325
# Shared data
326
categories = ["Jan", "Feb", "Mar", "Apr", "May"]
327
values1 = [120, 132, 101, 134, 90]
328
values2 = [220, 182, 191, 234, 290]
329

330
# Create charts with shared x-axis
331
bar = (
332
    Bar()
333
    .add_xaxis(categories)
334
    .add_yaxis("Product A", values1)
335
    .set_global_opts(
336
        title_opts=opts.TitleOpts(title="Sales Data"),
337
        legend_opts=opts.LegendOpts(pos_top="5%"),
338
        toolbox_opts=opts.ToolboxOpts(is_show=True),
339
        brush_opts=opts.BrushOpts()  # Enable data brushing
340
    )
341
)
342

343
line = (
344
    Line()
345
    .add_xaxis(categories)
346
    .add_yaxis("Product B", values2)
347
    .set_global_opts(
348
        legend_opts=opts.LegendOpts(pos_top="5%"),
349
        toolbox_opts=opts.ToolboxOpts(is_show=True),
350
        brush_opts=opts.BrushOpts()
351
    )
352
)
353

354
# Combine with synchronized interactions
355
grid = (
356
    Grid(init_opts=opts.InitOpts(width="1200px", height="600px"))
357
    .add(bar, grid_opts=opts.GridOpts(pos_bottom="60%"))
358
    .add(line, grid_opts=opts.GridOpts(pos_top="60%"))
359
)
360
```
361

362
### Dashboard Layouts
363

364
Create comprehensive dashboards with multiple visualization types:
365

366
```python
367
# Example: Multi-chart dashboard
368
from pyecharts.charts import Bar, Pie, Line, Scatter, Page
369
from pyecharts import options as opts
370

371
# Create individual charts
372
bar_chart = Bar().add_xaxis([...]).add_yaxis("Sales", [...])
373
pie_chart = Pie().add("Market Share", [...])
374
line_chart = Line().add_xaxis([...]).add_yaxis("Trend", [...])
375
scatter_chart = Scatter().add_xaxis([...]).add_yaxis("Correlation", [...])
376

377
# Organize in dashboard
378
dashboard = (
379
    Page(page_title="Business Dashboard")
380
    .add(bar_chart, pie_chart, line_chart, scatter_chart)
381
)
382
```
383

384
### Interactive Animations
385

386
Create complex animated visualizations with timeline controls:
387

388
```python
389
# Example: Animated bubble chart over time
390
from pyecharts.charts import Scatter, Timeline
391
from pyecharts import options as opts
392

393
timeline = Timeline()
394

395
for year in range(2010, 2021):
396
    # Create scatter chart for each year
397
    scatter = (
398
        Scatter()
399
        .add_xaxis([...])  # GDP data for year
400
        .add_yaxis(f"Year {year}", [...])  # Population data
401
        .set_global_opts(
402
            title_opts=opts.TitleOpts(title=f"GDP vs Population - {year}"),
403
            visualmap_opts=opts.VisualMapOpts(max_=100)
404
        )
405
    )
406
    timeline.add(scatter, str(year))
407

408
# Configure animation
409
timeline.add_schema(
410
    is_auto_play=True,
411
    play_interval=1000,
412
    is_timeline_show=True
413
)
414
```