Widget Hierarchies: containers, dijit._Container, and startup()

Authors:Bill Keese

Deprecated This document is deprecated. The information contained in here maybe out of date.

Often developers will build a hierarchy of widgets. For example, a dijit.Menu will contain dijit.MenuItem‘s, or a dijit.layout.BorderContainer will contain multiple dijit.layout.ContentPane‘s, each of which contains some other widgets like dijit.form.TextBox and dijit.form.Button.

Widgets that are meant to contain other widgets must:

  • define a containerNode attribute pointing to the DOMNode containing the child widgets (either to the widget’s root node or a descendant)
  • call startup() on the child widgets (when startup() is called on the widget)

Note that “other widgets” here refers to widgets added by the user (ie, by the calling code), rather than an internal widgets which are hidden from the user, and appear to be part of the main widget. Examples are dijit/layout/ContentPane and dijit/Toolbar. A widget that is not considered a container is dijit/InlineEditBox, because even though it contains button widgets, they appear to be part of the InlineEditBox and are not listed by getChildren().

Since widgets are required to call startup() on their children, the parser (dojo.parser) will *not* call startup on those widgets. This allows the parent widget to do processing both before and after the child widget is started. Therefore, when adding child widgets to a parent widget, be sure to use the proper API, so that the parent knows the child exists.


dijit/_Container is a mixin for widgets with child widgets, especially for widgets that contain nothing but an ordered list of child widgets, like a dijit.Menu. It implements the contract for containers listed above, and goes farther.

In particular, dijit/_Container implements the addChild() and removeChild() API.

All of the widgets named ***Container (ex: dijit.layout.TabContainer) extend dijit/_Container.


dijit/_Contained is the counterpart to dijit/_Container. It represents a widget that has a dijit._Container as a parent. However, dijit/_Container can contain any widget, regardless of whether it extends dijit/_Contained, so this class is generally not used.

Error in the documentation? Can’t find what you are looking for? Let us know!