# JavaScript API

> Every JavaScript export, component lifecycle, and document behavior.

## Imports

Import from `@expressivecss/expressive` for document setup, or `@expressivecss/expressive/modular` for explicit initialization. Both entries export the same runtime names. The IIFE script exposes them on `Expressive`.

```
import { AutoInit, version } from '@expressivecss/expressive';

// Run after the markup exists.
const stop = AutoInit(document.body, {}, { watch: true });
console.log(version);

// Stop observing when the view unmounts. Existing instances keep running.
stop();
```

The `version` string is the framework package version. Type-only exports disappear at runtime. Import option and data types by name from the public entries, such as `MenuOptions`, `AutoInitOptions` and `ConfirmOptions`.

Internal `core` helpers, `Utils`, `Component`, `ModalDisplayPlugin` and `DockedDisplayPlugin` have no package export. Use the component APIs below instead of importing files from the build's internal chunks.

## Component lifecycle

Element components share `init`, `getInstance`, `defaults`, `el`, `options` and `destroy`. Each component's page documents its markup, extra methods, options and events.

```
import { Menu } from '@expressivecss/expressive/modular';

const trigger = document.querySelector('.menu-trigger');
const menu = Menu.init(trigger, { closeOnClick: false });
// Menu.getInstance(trigger) returns the same instance.
menu.open();

// When this view unmounts:
menu.destroy();
```

| API | Contract |
| --- | --- |
| `init(element, options?)` | Returns one instance. Reinitializing the same element destroys its previous instance first. |
| `init(elements, options?)` | Accepts an array, NodeList or HTMLCollection and returns an array of instances. An empty collection returns an empty array. |
| `getInstance(element)` | Returns the current instance, or `undefined` before initialization and after destruction. It does not create one. |
| `defaults` | The class's default option object. Inspect it; pass overrides to `init` rather than mutating shared defaults. |
| `el`, `options` | The element and merged initialization options. Missing `i18n` strings retain their defaults. Changing an option property does not rerun initialization. |
| `destroy()` | Removes the instance's listeners and performs its component-specific cleanup. Call before discarding a manually managed view. |

[AutoInit](/auto-init.html.md) documents selectors, markup options, watch mode and `expressive:*` events. It starts registered components only. [Snackbar](/snackbar.html.md) uses `new Snackbar(options)` and its own dismissal API. [CharacterCounter](/text-inputs.html.md#character-counter) and [Slider](/slider.html.md) require their documented initialization paths.

## Document behaviors

The root bundle installs every behavior below. The modular entry installs none. Call the required `Init()` methods once after a browser document is available. These document listeners have no per-element `destroy()` API.

```
import { Forms, Copy, Dialogs, BottomSheets } from '@expressivecss/expressive/modular';

Forms.Init();
Copy.Init();
Dialogs.Init();
BottomSheets.Init();
```

| Setup | What it enables |
| --- | --- |
| `Forms.Init()` | [Fields](/text-inputs.html.md), labels, validation, textarea resizing and file paths. |
| `Chips.Init()`, `Slider.Init()`, `Cards.Init()`, `ExpandingCard.Init()` | Initial scans for the corresponding element components. Initialize new elements explicitly or use their documented AutoInit support. |
| `Dialogs.Init()`, `BottomSheets.Init()`, `SideSheets.Init()` | Dialog dismissal and sheet dragging. Include `Dialogs.Init()` for sheet light dismissal. |
| `Copy.Init()`, `Theme.Init()` | [Copy buttons](/copy.html.md) and [theme controls](/themes.html.md). |
| `PaneResize.Init()`, `ImageCompare.Init()` | [Resizable panes](/panes.html.md) and [image comparison](/image-compare.html.md). |
| `Tour.Init()`, `Sortable.Init()`, `Lists.Init()` | [Tours](/tour.html.md), [sortable lists and actionable-row keyboard navigation](/lists.html.md). |
| `DataTables.Init()`, `TransferList.Init()` | [Data tables](/data-table.html.md) and [transfer lists](/transfer-list.html.md). |

The modular `AutoInit()` call does not replace document behavior setup. It includes the full registry, so importing it can retain more components in a bundled application. Browser APIs are required when initializing components; importing the modular entry alone is inert.

## All exports

Every runtime export links to its usage guide. This table reads the shared page catalogue; contributor checks compare it with the built bundle.

| Export | Guide |
| --- | --- |
| `AppBar` | [App bar](/navbar.html.md) |
| `Autocomplete` | [Autocomplete](/autocomplete.html.md) |
| `AutoInit` | [Auto Init](/auto-init.html.md) |
| `BackToTop` | [Back to top](/back-to-top.html.md) |
| `BarChart` | [Bar chart](/bar-chart.html.md) |
| `BottomSheets` | [Bottom sheet](/bottom-sheet.html.md) |
| `ButtonGroup` | [Button groups](/button-groups.html.md) |
| `Cards` | [Cards](/cards.html.md) |
| `Carousel` | [Carousel](/carousel.html.md) |
| `Cascader` | [Cascader](/cascader.html.md) |
| `CharacterCounter` | [Text fields](/text-inputs.html.md) |
| `Chips` | [Chips](/chips.html.md) |
| `ColorPicker` | [Color picker](/color-picker.html.md) |
| `ColumnChart` | [Column chart](/column-chart.html.md) |
| `CommandPalette` | [Command palette](/command-palette.html.md) |
| `Confetti` | [Confetti](/confetti.html.md) |
| `Copy` | [Copy to clipboard](/copy.html.md) |
| `CurrencyInput` | [Currency input](/currency-input.html.md) |
| `DataTables` | [Data table](/data-table.html.md) |
| `Datepicker` | [Date picker](/datepicker.html.md) |
| `Dialogs` | [Dialogs](/dialogs.html.md) |
| `ExpandingCard` | [Cards](/cards.html.md) |
| `FloatingActionButton` | [FAB](/floating-action-button.html.md) |
| `Forms` | [Text fields](/text-inputs.html.md) |
| `FormSelect` | [Select](/select.html.md) |
| `FunnelChart` | [Funnel chart](/funnel-chart.html.md) |
| `HeatmapChart` | [Heatmap chart](/heatmap-chart.html.md) |
| `HoverCard` | [Hover card](/hover-card.html.md) |
| `ImageCompare` | [Image compare](/image-compare.html.md) |
| `InputMask` | [Input mask](/input-mask.html.md) |
| `Keypad` | [Keypad](/keypad.html.md) |
| `Lightbox` | [Lightbox](/media.html.md) |
| `LineChart` | [Line chart](/line-chart.html.md) |
| `Lists` | [Lists](/lists.html.md) |
| `LoadingOverlay` | [Loading overlay](/loading-overlay.html.md) |
| `MapView` | [Map](/map.html.md) |
| `Menu` | [Menu](/menu.html.md) |
| `Menubar` | [Menubar](/menubar.html.md) |
| `MessageScroller` | [Message scroller](/message-scroller.html.md) |
| `MixedChart` | [Mixed chart](/mixed-chart.html.md) |
| `NavigationRail` | [Navigation rail](/navigation-rail.html.md) |
| `PaneResize` | [Panes](/panes.html.md) |
| `Particles` | [Particles](/particles.html.md) |
| `PieChart` | [Pie chart](/pie-chart.html.md) |
| `PullToRefresh` | [Pull-to-refresh](/pull-to-refresh.html.md) |
| `Questionnaire` | [Questionnaire](/questionnaire.html.md) |
| `RadarChart` | [Radar chart](/radar-chart.html.md) |
| `RadialChart` | [Radial chart](/radial-chart.html.md) |
| `RichTextEditor` | [Rich text editor](/rich-text-editor.html.md) |
| `SankeyChart` | [Sankey chart](/sankey-chart.html.md) |
| `ScatterChart` | [Scatter chart](/scatter-chart.html.md) |
| `ScrollSpy` | [Scrollspy](/scrollspy.html.md) |
| `ShowMore` | [Show more](/show-more.html.md) |
| `SideSheets` | [Side sheet](/side-sheet.html.md) |
| `Slider` | [Slider](/slider.html.md) |
| `Snackbar` | [Snackbar](/snackbar.html.md) |
| `Sortable` | [Lists](/lists.html.md) |
| `SwipeActions` | [Swipe actions](/swipe-actions.html.md) |
| `Tabs` | [Tabs](/tabs.html.md) |
| `Theme` | [Themes](/themes.html.md) |
| `Timepicker` | [Time picker](/timepicker.html.md) |
| `Tooltip` | [Tooltips](/tooltips.html.md) |
| `Tour` | [Tour](/tour.html.md) |
| `TransferList` | [Transfer list](/transfer-list.html.md) |
| `TreemapChart` | [Treemap chart](/treemap-chart.html.md) |
| `TreeSelect` | [Tree select](/tree-select.html.md) |
| `version` | [Getting started](/index.html.md) |

## CSS and Sass

CSS-only components need no JavaScript initialization. Their pages in the navigation document markup, variants and accessibility requirements.

Use [Helpers](/helpers.html.md) for layout, spacing, visibility and formatting; [Grid](/grid.html.md) for columns; [Color](/color.html.md) and [Typography](/typography.html.md) for role classes; [Elevation](/shadow.html.md), [Shapes](/shapes.html.md) and [Scroll area](/scroll-area.html.md) for their utility families.

[Design tokens](/tokens.html.md) covers runtime custom properties. The [Sass API](/sass.html.md) covers compile-time configuration, functions and mixins.