0
# Core Widget Class
1

2
The AnyWidget class provides the fundamental building blocks for creating custom Jupyter widgets with ES modules and CSS styling. It handles the Jupyter widget protocol, communication setup, and platform-specific optimizations.
3

4
## Capabilities
5

6
### AnyWidget Base Class
7

8
The main class for creating custom Jupyter widgets that inherit from ipywidgets.DOMWidget with enhanced ES module and CSS support.
9

10
```python { .api }
11
class AnyWidget(ipywidgets.DOMWidget):
12
    """
13
    Main AnyWidget base class for creating custom Jupyter widgets.
14
    
15
    Attributes:
16
        _model_name (str): Widget model name ("AnyModel")
17
        _model_module (str): Widget model module ("anywidget") 
18
        _model_module_version (str): Widget model version
19
        _view_name (str): Widget view name ("AnyView")
20
        _view_module (str): Widget view module ("anywidget")
21
        _view_module_version (str): Widget view version
22
    """
23
    
24
    def __init__(*args, **kwargs):
25
        """
26
        Initialize the widget with ES module and CSS traits.
27
        
28
        Automatically sets up:
29
        - ES module trait from _esm class attribute
30
        - CSS trait from _css class attribute  
31
        - Unique widget ID for identification
32
        - Google Colab compatibility if needed
33
        - Command registration for custom messages
34
        
35
        Parameters:
36
            *args: Positional arguments passed to parent
37
            **kwargs: Keyword arguments passed to parent
38
        """
39
    
40
    def __init_subclass__(**kwargs):
41
        """
42
        Class method called when AnyWidget is subclassed.
43
        
44
        Automatically processes:
45
        - _esm attribute: converts file paths to FileContents objects
46
        - _css attribute: converts file paths to FileContents objects
47
        
48
        Parameters:
49
            **kwargs: Keyword arguments from class definition
50
        """
51
    
52
    def _repr_mimebundle_(**kwargs):
53
        """
54
        Generate MIME bundle representation for Jupyter display.
55
        
56
        Returns widget representation with communication channel ID
57
        for rendering in Jupyter environments.
58
        
59
        Parameters:
60
            **kwargs: Display formatting options (include/exclude)
61
            
62
        Returns:
63
            tuple[dict, dict] | None: MIME bundle data and metadata
64
        """
65
```
66

67
### Widget Traits and Attributes
68

69
Key attributes that define widget behavior and appearance.
70

71
```python { .api }
72
# Class attributes for ES module and CSS
73
_esm: str | Path | FileContents | VirtualFileContents
74
    """ES Module code or file path for widget frontend"""
75

76
_css: str | Path | FileContents | VirtualFileContents  
77
    """CSS styles or file path for widget styling"""
78

79
# Traitlets for Jupyter communication
80
_model_name: Unicode
81
    """Widget model name synced with frontend"""
82
    
83
_model_module: Unicode
84
    """Widget model module synced with frontend"""
85
    
86
_model_module_version: Unicode
87
    """Widget model version synced with frontend"""
88
    
89
_view_name: Unicode
90
    """Widget view name synced with frontend"""
91
    
92
_view_module: Unicode  
93
    """Widget view module synced with frontend"""
94
    
95
_view_module_version: Unicode
96
    """Widget view version synced with frontend"""
97
```
98

99
## Usage Examples
100

101
### Basic Widget with Inline ES Module
102

103
```python
104
import anywidget
105
import traitlets as t
106

107
class SimpleWidget(anywidget.AnyWidget):
108
    _esm = """
109
    function render({ model, el }) {
110
        el.innerHTML = "<h1>Hello, World!</h1>";
111
    }
112
    export default { render };
113
    """
114
    
115
    value = t.Unicode("Hello").tag(sync=True)
116

117
widget = SimpleWidget()
118
widget  # Displays in Jupyter
119
```
120

121
### Widget with External Files
122

123
```python
124
import anywidget
125
import traitlets as t
126

127
class FileBasedWidget(anywidget.AnyWidget):
128
    _esm = "./widget.js"      # File path to ES module
129
    _css = "./widget.css"     # File path to CSS styles
130
    
131
    data = t.List([]).tag(sync=True)
132
    
133
# Files are automatically watched for changes during development
134
widget = FileBasedWidget(data=[1, 2, 3, 4, 5])
135
```
136

137
### Interactive Widget with State Management
138

139
```python
140
import anywidget
141
import traitlets as t
142

143
class CounterWidget(anywidget.AnyWidget):
144
    _esm = """
145
    function render({ model, el }) {
146
        let count = () => model.get("value");
147
        let btn = document.createElement("button");
148
        btn.innerHTML = `Count: ${count()}`;
149
        
150
        btn.addEventListener("click", () => {
151
            model.set("value", count() + 1);
152
        });
153
        
154
        model.on("change:value", () => {
155
            btn.innerHTML = `Count: ${count()}`;
156
        });
157
        
158
        el.appendChild(btn);
159
    }
160
    export default { render };
161
    """
162
    
163
    value = t.Int(0).tag(sync=True)
164
    step = t.Int(1).tag(sync=True)
165

166
# Create widget with custom initial state
167
counter = CounterWidget(value=10, step=2)
168
```
169

170