Skip to Content | Skip to Navigation


dojo.create

since:V1.3

A convenient DOM creation, manipulation and placement utility shorthand.

Introduction

dojo.create() is designed to simplify the frequently used sequence of DOM manipulation:

  • create a node,
  • set attributes on it,
  • and place it in the DOM.

It can be used with existing nodes too, if you want to assign new attributes and place it afterwards.

To see this utility in context, read the DOM Quick Start first.

Since Dojo 1.7, dojo.create is exposed via the create method of the dojo/dom-construct module. An alias is kept in dojo/_base/html for backward-compatibility.

Usage

Dojo 1.7+ (AMD)

When using AMD format in a fully baseless application, create is accessed from the dojo/dom-construct module.

require(["dojo/dom-construct"], function(domConstruct){
    // create a div node
    var node = domConstruct.create("div");
});

Alternatively, you can load dojo base in AMD style and continue using dojo.create in the define or require callback:

require(["dojo"], function(dojo){
    // create a div node
    var node = dojo.create("div");
});

Dojo < 1.7

// create a div node
var node = dojo.create("div");

Examples

Create a <div>:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct"], function(domConstruct){
  var n = domConstruct.create("div");
});

// dojo < 1.7
var n = dojo.create("div");

Create a <div> with content:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct"], function(domConstruct){
  var n = domConstruct.create("div", { innerHTML: "<p>hi</p>" });
});

// dojo < 1.7
var n = dojo.create("div", { innerHTML: "<p>hi</p>" });

Append a new <div> to <body> with no attributes:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  var n = domConstruct.create("div", null, win.body());
});

// dojo < 1.7
var n = dojo.create("div", null, dojo.body());

Place a new <div> as the first child of <body> with no attributes:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  var n = domConstruct.create("div", null, win.body(), "first");
});

// dojo < 1.7
var n = dojo.create("div", null, dojo.body(), "first");

Decorate and place an existing node:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  domConstruct.create(node, { style: { color: "red" } }, win.body());
});

// dojo < 1.7
dojo.create(node, { style: { color: "red" } }, dojo.body());

Create an <ul>, and populate it with <li>’s. Place the list as the first child of a node whose id equals “someId”:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/array"], function(domConstruct, arrayUtil){
  var ul = domConstruct.create("ul", null, "someId", "first");
  var items = ["one", "two", "three", "four"];
  arrayUtil.forEach(items, function(data){
    domConstruct.create("li", { innerHTML: data }, ul);
  });
});

// dojo < 1.7
var ul = dojo.create("ul", null, "someId", "first");
var items = ["one", "two", "three", "four"];
dojo.forEach(items, function(data){
  dojo.create("li", { innerHTML: data }, ul);
});

Create an anchor, with an href. Place in <body>:

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  domConstruct.create("a", { href: "foo.html", title: "Goto FOO!", innerHTML: "link" }, win.body());
});

// dojo < 1.7
dojo.create("a", { href: "foo.html", title: "Goto FOO!", innerHTML: "link" }, dojo.body());

Alternatives

Creating and/or placing with dojo.place()

In some cases it is easier to create a node from an HTML fragment and place it, without applying any attributes, or specifying them as a part of the HTML fragment. If this is the case consider dojo.place:

// duplicating the following line with dojo.place():
// dojo.create("a", { href: "foo.html", title: "Goto FOO!", innerHTML: "link" }, dojo.body());

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  domConstruct.place("<a href='foo.html' title='Goto FOO!'>link</a>", win.body());
});

// dojo < 1.7
dojo.place("<a href='foo.html' title='Goto FOO!'>link</a>", dojo.body());
// duplicating the following line with dojo.place():
// var n = dojo.create("div", null, dojo.body());

// dojo 1.7+ (AMD)
require(["dojo/dom-construct", "dojo/_base/window"], function(domConstruct, win){
  var n = domConstruct.place("<div></div>", win.body());
});

// dojo < 1.7
var n = dojo.place("<div></div>", dojo.body());

Setting attributes with dojo.attr()

While you can use dojo.create to set attributes on the existing node without placing it, using dojo.attr is recommended:

// duplicating the following line with dojo.attr():
// var n = dojo.create(node, { innerHTML: "<p>hi</p>" });

// dojo 1.7+ (AMD)
require(["dojo/dom-attr"], function(domAttr){
  domAttr.set(node, "innerHTML", "<p>hi</p>");
});

// dojo < 1.7
dojo.attr(node, "innerHTML", "<p>hi</p>");

API Info

full API:http://dojotoolkit.org/api/dojo/create
summary:Create an element, allowing for optional attribute decoration and placement.

Parameters

Signature

dojo.create( /* DOMNode|String */ tag,  /* Object */ attrs,  /* DOMNode|String */ refNode,  /* String */ pos)

Overview

  • tag DOMNode|String

    A string of the element to create (eg: &quot;div&quot;, &quot;a&quot;, &quot;p&quot;, &quot;li&quot;, &quot;script&quot;, &quot;br&quot;), or an existing DOM node to process.

  • attrs Object

    An object-hash of attributes to set on the newly created node. Can be null, if you don’t want to set any attributes/styles. See: dojo.setAttr for a description of available attributes.

  • refNode DOMNode|String

    Optional reference node. Used by dojo.place to place the newly created node somewhere in the dom relative to refNode. Can be a DomNode reference or String ID of a node.

  • pos String

    Optional positional reference. Defaults to &quot;last&quot; by way of dojo.place, though can be set to &quot;first&quot;,&quot;after&quot;,&quot;before&quot;,&quot;last&quot;, &quot;replace&quot; or &quot;only&quot; to further control the placement of the new node relative to the refNode. ‘refNode’ is required if a ‘pos’ is specified.

Examples

Create a DIV:

var n = dojo.create("div");

Create a DIV with content:

var n = dojo.create("div", { innerHTML:"<p>hi</p>" });

Place a new DIV in the BODY, with no attributes set

var n = dojo.create("div", null, dojo.body());

Create an UL, and populate it with LI’s. Place the list as the first-child of a node with id=”someId”:

var ul = dojo.create("ul", null, "someId", "first");
var items = ["one", "two", "three", "four"];
dojo.forEach(items, function(data){
        dojo.create("li", { innerHTML: data }, ul);
});

Create an anchor, with an href. Place in BODY:

dojo.create("a", { href:"foo.html", title:"Goto FOO!" }, dojo.body());

Create a dojo.NodeList() from a new element (for syntatic sugar):

dojo.query(dojo.create('div'))
        .addClass("newDiv")
        .onclick(function(e){ console.log('clicked', e.target) })
        .place("#someNode"); // redundant, but cleaner.