Components.classes is a read-only object whose properties are classes indexed by ContractID.

Introduction

Components.classes is a read-only object whose properties implement the nsIJSCID interface. Each object represents one of the classes of XPCOM components that can be constructed or accessed as an XPCOM service.

The properties of this object are indexed by the ContractID (or human-readable name) of the component class.

All of the properties and methods of the nsIJSCID and its ancestor interface nsIJSID are available for use on the objects contained in this object.

Note that Components.classes reflects only those component classes that have been previously installed and registered with the component manager using ContractIDs. If you want to use a class which was only registered with their CID, use Components.classesByID instead of Components.classes to retrieve it.

Note also that it is possible that a given add-on component with a given ContractID will be present on one machine but not have been installed on another machine. If the given element in the Components.classes object is not registered on the machine then trying to access it will generate a JavaScript warning in strict mode and the value returned will be the JavaScript value undefined. You should use the in operator to test for the element before trying to access it:

if (!("@some/bogus/class;1" in Components.classes))
  // do something...

The properties of the Components.classes object can be enumerated using a for...in loop.

Usage

In order to retrieve the object for a given ContractID, you can query the Components.classes array as follows:

var clazz0 = Components.classes["@mozilla.org/messenger;1"];

clazz0 is the class object for the ContractID @mozilla.org/messenger;1, which is not usually used by itself, but whose createInstance and getService methods can be used to create a new instance of the component or to access the singleton instance, if the contract ID represents a service.

A new XPCOM component instance can be created from the returned class object as follows:

var obj = Components.classes["@mozilla.org/supports-array;1"]
                    .createInstance(Components.interfaces.nsISupportsArray);

which is a shortcut to

var obj = Components.classes["@mozilla.org/supports-array;1"]
                    .createInstance();
obj.QueryInterface(Components.interfaces.nsISupportsArray);

If you don't provide a specific interface to createInstance(), it will return an XPConnect wrapper for the component, which only exposes the methods of the nsISupports interface (and under certain circumstances the special wrappedJSObject property).

To access a service (a singleton component, only single instance of which exists at any time), you should use getService instead of createInstance:

 var os = Components.classes["@mozilla.org/observer-service;1"]
                    .getService(Components.interfaces.nsIObserverService);

The first time anyone accesses a service, the corresponding component is created under the hood.

Shortcuts

It's a common practice to abbreviate Components.classes and Components.interfaces by storing a reference to the object as a constant:

const Cc = Components.classes, Ci = Components.interfaces;
var os = Cc["@mozilla.org/observer-service;1"]
         .getService(Ci.nsIObserverService);

A less known trick, useful when creating multiple instances of the same component, is to use the new operator on the class object:

var clazz = Components.classes["@mozilla.org/supports-array;1"];
var inst  = new clazz(Components.interfaces.nsISupportsArray);

This implicitly calls the createInstance() method for you. You still have to provide the interface name each time you create an instance, which is not necessary when using Components.Constructor.

Determining if a component has to be instantiated or used as a service

In the general case it is not possible to programmatically determine if a given component has to be instantiated or used as a service.

Often, this is stated in the documentation of the component you want to use. If this is not the case, you might want to try and find example usages of that component within MXR.