0
# JavaScript API
1

2
UIkit's JavaScript API provides a comprehensive component system with lifecycle management, global utilities, and plugin architecture for creating dynamic web interfaces.
3

4
## Capabilities
5

6
### Global UIkit Object
7

8
The main UIkit object exposed globally and as a module export.
9

10
```javascript { .api }
11
/**
12
 * Main UIkit object providing component management and utilities
13
 */
14
declare const UIkit: {
15
  /** Current UIkit version string */
16
  version: string;
17
  
18
  /** Global options object for framework-wide defaults */
19
  options: Record<string, any>;
20
  
21
  /** Utility functions collection */
22
  util: UtilityCollection;
23
  
24
  /** Global container element (default: document.body) */
25
  container: HTMLElement;
26
  
27
  /** Register or retrieve component definitions */
28
  component(name: string, definition?: ComponentDefinition): ComponentConstructor | void;
29
  
30
  /** Get component instance(s) from element */
31
  getComponent(element: HTMLElement, name?: string): ComponentInstance | Record<string, ComponentInstance>;
32
  
33
  /** Get all component instances from element */
34
  getComponents(element: HTMLElement): Record<string, ComponentInstance>;
35
  
36
  /** Update components within element */
37
  update(element?: HTMLElement, event?: Event): void;
38
  
39
  /** Install plugin */
40
  use(plugin: Plugin): typeof UIkit;
41
  
42
  /** Add mixin to component */
43
  mixin(mixin: Mixin, component?: string | ComponentConstructor): void;
44
  
45
  /** Create UIkit subclass */
46
  extend(options: ComponentOptions): ComponentConstructor;
47
};
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
// Check version
54
console.log(UIkit.version); // "3.23.12"
55

56
// Set global container
57
UIkit.container = document.getElementById('app');
58

59
// Update all components
60
UIkit.update();
61

62
// Update specific element
63
UIkit.update(document.getElementById('content'));
64
```
65

66
### Component Management
67

68
Register, retrieve, and manage component definitions.
69

70
```javascript { .api }
71
/**
72
 * Register a new component or retrieve existing component definition
73
 * @param name - Component name
74
 * @param definition - Component definition object (optional)
75
 * @returns Component constructor if retrieving, undefined if registering
76
 */
77
component(name: string, definition?: ComponentDefinition): ComponentConstructor | void;
78

79
/**
80
 * Get component instance from element
81
 * @param element - Target HTML element
82
 * @param name - Component name (optional, returns all if omitted)
83
 * @returns Component instance or all instances object
84
 */
85
getComponent(element: HTMLElement, name?: string): ComponentInstance | Record<string, ComponentInstance>;
86

87
/**
88
 * Get all component instances from element
89
 * @param element - Target HTML element
90
 * @returns Object with component names as keys and instances as values
91
 */
92
getComponents(element: HTMLElement): Record<string, ComponentInstance>;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
// Register custom component
99
UIkit.component('custom-component', {
100
  connected() {
101
    console.log('Component connected');
102
  }
103
});
104

105
// Get modal component from element
106
const modal = UIkit.getComponent(document.getElementById('my-modal'), 'modal');
107

108
// Get all components from element
109
const components = UIkit.getComponents(document.getElementById('container'));
110
```
111

112
### Component Instances
113

114
Individual component instances with lifecycle and interaction methods.
115

116
```javascript { .api }
117
interface ComponentInstance {
118
  /** Component's root element */
119
  $el: HTMLElement;
120
  
121
  /** Component configuration options */
122
  $options: Record<string, any>;
123
  
124
  /** Component's container element */
125
  $container: HTMLElement;
126
  
127
  /** Mount component to element */
128
  $mount(element: HTMLElement): void;
129
  
130
  /** Destroy component instance */
131
  $destroy(removeEl?: boolean): void;
132
  
133
  /** Create child component */
134
  $create(component: string, element: HTMLElement, options?: Record<string, any>): ComponentInstance;
135
  
136
  /** Emit component update event */
137
  $emit(event: Event): void;
138
  
139
  /** Update component */
140
  $update(element?: HTMLElement, event?: Event): void;
141
  
142
  /** Reset component state */
143
  $reset(): void;
144
  
145
  /** Get related component instance */
146
  $getComponent(name: string): ComponentInstance;
147
}
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
// Create modal instance
154
const modal = UIkit.modal('#my-modal', {
155
  keyboard: false,
156
  stack: true
157
});
158

159
// Mount to different element
160
modal.$mount(document.getElementById('new-target'));
161

162
// Destroy component
163
modal.$destroy(true); // true to remove element
164

165
// Reset component state
166
modal.$reset();
167
```
168

169
### Plugin System
170

171
Install and manage UIkit plugins and extensions.
172

173
```javascript { .api }
174
/**
175
 * Install plugin
176
 * @param plugin - Plugin function
177
 * @returns UIkit object for chaining
178
 */
179
use(plugin: Plugin): typeof UIkit;
180

181
interface Plugin {
182
  /** Installation flag to prevent double installation */
183
  installed?: boolean;
184
  /** Plugin installation function */
185
  (UIkit: typeof UIkit): void;
186
}
187
```
188

189
**Usage Examples:**
190

191
```javascript
192
// Install icons plugin
193
import Icons from 'uikit/dist/js/uikit-icons';
194
UIkit.use(Icons);
195

196
// Create custom plugin
197
const customPlugin = function(UIkit) {
198
  UIkit.component('my-component', {
199
    // Component definition
200
  });
201
};
202

203
UIkit.use(customPlugin);
204
```
205

206
### Mixin System
207

208
Add reusable functionality to components through mixins.
209

210
```javascript { .api }
211
/**
212
 * Add mixin to component(s)
213
 * @param mixin - Mixin object with reusable functionality
214
 * @param component - Target component name or constructor (optional, applies globally if omitted)
215
 */
216
mixin(mixin: Mixin, component?: string | ComponentConstructor): void;
217

218
interface Mixin {
219
  /** Mixin properties and methods */
220
  [key: string]: any;
221
}
222
```
223

224
**Usage Examples:**
225

226
```javascript
227
// Global mixin
228
UIkit.mixin({
229
  connected() {
230
    console.log('Component connected via mixin');
231
  }
232
});
233

234
// Component-specific mixin
235
UIkit.mixin({
236
  customMethod() {
237
    return 'Custom functionality';
238
  }
239
}, 'modal');
240
```
241

242
### Extension System
243

244
Create UIkit subclasses with custom functionality.
245

246
```javascript { .api }
247
/**
248
 * Create UIkit subclass
249
 * @param options - Extension options
250
 * @returns Extended UIkit constructor
251
 */
252
extend(options: ComponentOptions): ComponentConstructor;
253
```
254

255
**Usage Examples:**
256

257
```javascript
258
// Create custom UIkit subclass
259
const CustomUIkit = UIkit.extend({
260
  customOption: 'default-value',
261
  
262
  connected() {
263
    console.log('Custom UIkit connected');
264
  }
265
});
266

267
// Use custom subclass
268
const instance = new CustomUIkit({ el: '#element' });
269
```
270

271
### Update System
272

273
Manage component updates and lifecycle.
274

275
```javascript { .api }
276
/**
277
 * Update components within element tree
278
 * @param element - Root element to update (default: document.body)
279
 * @param event - Event that triggered update (optional)
280
 */
281
update(element?: HTMLElement, event?: Event): void;
282
```
283

284
**Usage Examples:**
285

286
```javascript
287
// Update all components
288
UIkit.update();
289

290
// Update specific element tree
291
UIkit.update(document.getElementById('dynamic-content'));
292

293
// Update with event context
294
UIkit.update(element, new CustomEvent('data-changed'));
295

296
// Update on DOM changes
297
const observer = new MutationObserver(() => {
298
  UIkit.update();
299
});
300
observer.observe(document.body, { childList: true, subtree: true });
301
```
302

303
### Utility Functions
304

305
Collection of utility functions available via UIkit.util.
306

307
```javascript { .api }
308
interface UtilityCollection {
309
  // DOM utilities
310
  $(selector: string | HTMLElement): HTMLElement | null;
311
  $$(selector: string): HTMLElement[];
312
  addClass(element: HTMLElement, className: string): void;
313
  removeClass(element: HTMLElement, className: string): void;
314
  hasClass(element: HTMLElement, className: string): boolean;
315
  toggleClass(element: HTMLElement, className: string): void;
316
  
317
  // Attribute utilities
318
  attr(element: HTMLElement, name: string, value?: string): string | void;
319
  removeAttr(element: HTMLElement, name: string): void;
320
  data(element: HTMLElement, key: string): any;
321
  
322
  // Style utilities
323
  css(element: HTMLElement, property: string | Record<string, string>, value?: string): string | void;
324
  
325
  // Event utilities
326
  on(element: HTMLElement, events: string, handler: Function): void;
327
  off(element: HTMLElement, events: string, handler: Function): void;
328
  once(element: HTMLElement, events: string, handler: Function): void;
329
  trigger(element: HTMLElement, event: string, detail?: any): void;
330
  
331
  // Position utilities
332
  offset(element: HTMLElement): { top: number; left: number };
333
  position(element: HTMLElement): { top: number; left: number };
334
  
335
  // Animation utilities
336
  Animation: AnimationConstructor;
337
  Transition: TransitionConstructor;
338
  
339
  // Type checking
340
  isArray(obj: any): boolean;
341
  isFunction(obj: any): boolean;
342
  isObject(obj: any): boolean;
343
  isPlainObject(obj: any): boolean;
344
  isString(obj: any): boolean;
345
  isNumber(obj: any): boolean;
346
  isWindow(obj: any): boolean;
347
  isDocument(obj: any): boolean;
348
  
349
  // Language utilities
350
  each(obj: any, callback: Function): void;
351
  includes(array: any[], item: any): boolean;
352
  startsWith(str: string, search: string): boolean;
353
  endsWith(str: string, search: string): boolean;
354
  
355
  // Object utilities
356
  assign(target: any, ...sources: any[]): any;
357
  
358
  // String utilities
359
  hyphenate(str: string): string;
360
  camelize(str: string): string;
361
  ucfirst(str: string): string;
362
}
363
```
364

365
**Usage Examples:**
366

367
```javascript
368
const { $, addClass, on, isArray } = UIkit.util;
369

370
// DOM selection
371
const element = $('#my-element');
372

373
// Class manipulation
374
addClass(element, 'uk-active');
375

376
// Event handling
377
on(element, 'click', () => {
378
  console.log('Clicked');
379
});
380

381
// Type checking
382
if (isArray(data)) {
383
  // Handle array
384
}
385
```
386

387
## Component Definition Structure
388

389
```javascript { .api }
390
interface ComponentDefinition {
391
  /** Mixins to apply to component */
392
  mixins?: Mixin[];
393
  
394
  /** Default component data */
395
  data?: Record<string, any>;
396
  
397
  /** Component properties configuration */
398
  props?: Record<string, PropDefinition>;
399
  
400
  /** Computed properties */
401
  computed?: Record<string, ComputedProperty>;
402
  
403
  /** Component methods */
404
  methods?: Record<string, Function>;
405
  
406
  /** Event definitions */
407
  events?: EventDefinition[];
408
  
409
  /** Lifecycle hooks */
410
  connected?(): void;
411
  disconnected?(): void;
412
  beforeConnect?(): void;
413
  beforeDisconnect?(): void;
414
  destroy?(): void;
415
  
416
  /** Update hooks */
417
  update?: {
418
    read?(): void;
419
    write?(): void;
420
    events?: string[];
421
  };
422
}
423

424
interface PropDefinition {
425
  /** Property type(s) */
426
  type?: string | string[];
427
  /** Default value */
428
  default?: any;
429
  /** Validation function */
430
  validator?(value: any): boolean;
431
}
432

433
interface ComputedProperty {
434
  /** Getter function */
435
  get?(): any;
436
  /** Setter function */
437
  set?(value: any): void;
438
  /** Dependencies for caching */
439
  depends?: string[];
440
}
441

442
interface EventDefinition {
443
  /** Event name(s) */
444
  name: string;
445
  /** Handler method name or function */
446
  handler: string | Function;
447
  /** Target element selector or function */
448
  el?: string | Function;
449
  /** Event delegation selector */
450
  delegate?: string;
451
  /** Filter function */
452
  filter?: Function;
453
  /** Self-only flag */
454
  self?: boolean;
455
}
456
```
457

458
**Component Definition Example:**
459

460
```javascript
461
UIkit.component('example', {
462
  mixins: [UIkit.mixin.togglable],
463
  
464
  data: {
465
    active: false,
466
    duration: 300
467
  },
468
  
469
  props: {
470
    toggle: {
471
      type: String,
472
      default: '.uk-toggle'
473
    }
474
  },
475
  
476
  computed: {
477
    toggleElement() {
478
      return UIkit.util.$(this.toggle, this.$el);
479
    }
480
  },
481
  
482
  methods: {
483
    show() {
484
      this.active = true;
485
      this.$emit('show');
486
    },
487
    
488
    hide() {
489
      this.active = false;
490
      this.$emit('hide');
491
    }
492
  },
493
  
494
  events: [
495
    {
496
      name: 'click',
497
      el: 'toggleElement',
498
      handler: 'toggle'
499
    }
500
  ],
501
  
502
  connected() {
503
    console.log('Component connected');
504
  },
505
  
506
  update: {
507
    read() {
508
      // Read DOM properties
509
    },
510
    write() {
511
      // Write DOM changes
512
    },
513
    events: ['resize']
514
  }
515
});
516
```