0
# Core Display Functions
1

2
Primary functions for rendering DataFrames as interactive tables in Jupyter environments. These functions provide the core functionality for transforming static DataFrames into interactive, sortable, filterable tables with pagination and search capabilities.
3

4
## Capabilities
5

6
### Interactive Table Display
7

8
Renders a DataFrame as an interactive datatable directly in Jupyter environments with automatic display using IPython's display system.
9

10
```python { .api }
11
def show(df, caption=None, **kwargs):
12
    """
13
    Render the given DataFrame as an interactive datatable.
14

15
    Parameters:
16
    - df: Pandas/Polars DataFrame or Series to display
17
    - caption (str, optional): Table caption text
18
    - **kwargs: ITableOptions - Configuration options (see ITableOptions type)
19

20
    Returns:
21
    None (displays table directly)
22
    """
23
```
24

25
### HTML Generation
26

27
Returns the HTML representation of a DataFrame as an interactive datatable without automatically displaying it, useful for custom rendering or saving to files.
28

29
```python { .api }
30
def to_html_datatable(df, caption=None, **kwargs):
31
    """
32
    Return the HTML representation of the given DataFrame as an interactive datatable.
33

34
    Parameters:
35
    - df: Pandas/Polars DataFrame or Series to convert
36
    - caption (str, optional): Table caption text  
37
    - **kwargs: ITableOptions - Configuration options
38

39
    Returns:
40
    str: Complete HTML representation with embedded JavaScript
41
    """
42
```
43

44
### Interactive Mode Initialization
45

46
Loads the DataTables JavaScript library and optionally activates interactive representation for all DataFrames in the notebook session.
47

48
```python { .api }
49
def init_notebook_mode(all_interactive=True, connected=None, dt_bundle=None):
50
    """
51
    Load the DataTables library and activate interactive representation.
52

53
    Parameters:
54
    - all_interactive (bool): If True, make all DataFrames interactive by default
55
    - connected (bool, optional): If True, load DataTables from CDN; if False, use offline bundle (default: auto-detected based on environment)
56
    - dt_bundle (str | Path, optional): Custom path to DataTables bundle for offline mode
57

58
    Returns:
59
    None
60
    
61
    Note: Keep cell output when connected=False, otherwise tables will stop working
62
    """
63
```
64

65
## Common Usage Examples
66

67
### Basic Interactive Display
68

69
```python
70
import pandas as pd
71
from itables import show
72

73
# Create sample data
74
df = pd.DataFrame({
75
    'Product': ['A', 'B', 'C', 'D'],
76
    'Sales': [100, 250, 300, 150],
77
    'Region': ['North', 'South', 'East', 'West']
78
})
79

80
# Display as interactive table
81
show(df, caption="Sales Data")
82
```
83

84
### Custom Configuration
85

86
```python
87
# Display with custom options
88
show(df, 
89
     pageLength=10,           # Show 10 rows per page
90
     scrollX=True,            # Enable horizontal scrolling
91
     column_filters="header", # Add column filters
92
     classes="display compact")  # Use compact styling
93
```
94

95
### HTML Export
96

97
```python
98
# Generate HTML for external use
99
html_output = to_html_datatable(df, 
100
                               caption="Exported Table",
101
                               connected=True)  # Use CDN for portability
102

103
# Save to file
104
with open('table.html', 'w') as f:
105
    f.write(html_output)
106
```
107

108
### Global Interactive Mode
109

110
```python
111
# Make all DataFrames interactive
112
init_notebook_mode(all_interactive=True, connected=False)
113

114
# Now all DataFrames display as interactive tables
115
df  # This will show as interactive table
116

117
# Polars DataFrames also supported
118
import polars as pl
119
polars_df = pl.DataFrame({'A': [1, 2, 3], 'B': ['x', 'y', 'z']})
120
polars_df  # Also displays as interactive table
121
```
122

123
### Offline Mode Setup
124

125
```python
126
from pathlib import Path
127

128
# Initialize with custom bundle path
129
init_notebook_mode(
130
    all_interactive=True,
131
    connected=False,
132
    dt_bundle=Path("custom/datatables.js")
133
)
134
```
135

136
## Configuration Options
137

138
All display functions accept configuration options through keyword arguments. Common options include:
139

140
- `pageLength`: Number of rows per page (default from options.py)
141
- `scrollX`: Enable horizontal scrolling for wide tables
142
- `column_filters`: Add column filters ("header", "footer", or False)
143
- `classes`: CSS classes for table styling
144
- `showIndex`: Control index column display ("auto", True, False)
145
- `maxRows`: Maximum rows before downsampling (0 = unlimited)
146
- `maxColumns`: Maximum columns before downsampling
147
- `allow_html`: Allow HTML content in table cells (use with caution)
148

149
See [Configuration Management](./configuration.md) for complete option details.