events.md

@property {Object} can-component.prototype.events events @parent can-component.prototype

Listen to events on elements and observables.

@option {Object.<can-control.eventDescription,can-control.eventHandler>} An object of event names and methods that handle the event. For example:

import Component from "can-component";

Component.extend( {
	ViewModel: {
		limit: "number",
		offset: "number",
		next: function() {
			this.offset = this.offset + this.limit;
		}
	},
	events: {
		".next click": function() {
			this.viewModel.next();
		},
		"{viewModel} limit": function( viewModel, ev, newValue ) {
			console.log( "limit is now", newValue );
		}
	}
} );

A component’s events object is used as the prototype of a [can-control]. The control gets created on the component’s element.

The component’s [can-component.prototype.ViewModel] instance is available within event handlers as this.viewModel.

The component element is available as this.element.

@body

Use

[can-component]’s events object allows you to provide low-level [can-control]-like abilities to a Component while still accessing the Component’s [can-component::ViewModel]. The following example listens to clicks on elements with className="next" and calls .next() on the component’s viewModel.

@demo demos/can-component/paginate_events_next.html @codepen

The events object can also listen to objects or properties on the component’s [can-component::ViewModel] instance. For instance, instead of using live-binding, we could listen to when offset changes and update the page manually:

@demo demos/can-component/paginate_events_next_update_page.html @codepen

Special events: inserted and removed

In previous versions of CanJS, components had the ability to bind to special inserted and removed events that were called when a component’s element had been inserted into or removed from the page:

{
	events: {
		"inserted": function() {

			// called when the component’s tag is inserted into the DOM
		},
		"removed": function() {

			// called when the component’s tag is removed from the DOM
		}
	}
}

You can still bind to these special events by using the can-3-4-compat package, but this is deprecated in favor of the new [can-component/connectedCallback] API. See more information about migrating away from the inserted and removed events in the [migrate-4] guide.

High performance view rendering

While [can-stache-bindings] conveniently allows you to call a [can-component::ViewModel] method from a view like:

<input on:change="doSomething()"/>

This has the effect of binding an event handler directly to this element. Every element that has a on:click or similar attribute has an event handler bound to it. For a large grid or list, this could have a performance penalty.

By contrast, events bound using [can-component]’s events object use event delegation, which is useful for high performance view rendering. In a large grid or list, event delegation only binds a single event handler rather than one per row.