3.1.1.2.16 image

Include artwork or images in a DITA topic by using the <image> element. The <image> element has optional attributes that indicate whether the placement of the included graphic or artwork should be inline (like a button or icon) or on a separate line for a larger image. There are also optional attributes that indicate the size to which the included graphic or artwork should be scaled. An image element must specify an href attribute, a keyref attribute, or both. When both keyref and href are specified, the href is used as a fallback when the key reference cannot be resolved. The image addressed by the keyref or href is brought into the main flow of the content as rendered. To make the intent of the image more accessible for users using screen readers or text-only readers, authors should include a description of the image's content in the alt element.

Contains

Doctype

Content model

topic, map, concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap, classifyMap, subjectScheme, machineryTask, learningAssessment, learningBookmap, learningContent, learningMap, learningOverview, learningPlan, learningSummary

( (alt) (optional) then (longdescref) (optional) )

Contained by

Doctype

Content model

topic (base)

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, imagemap

map (base), classifyMap, subjectScheme, learningMap

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, imagemap

topic (technical content)

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, imagemap, uicontrol, pt, pd

map (technical content)

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, imagemap, uicontrol, pt, pd

concept

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, conbody, imagemap, uicontrol, pt, pd

ditabase

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, conbody, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, glossterm, glossdef, glossProperty, glossUsage, glossScopeNote, imagemap, uicontrol, pt, pd

glossary, glossentry, glossgroup

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, conbody, glossterm, glossdef, glossProperty, glossUsage, glossScopeNote, imagemap, uicontrol, pt, pd

reference

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, imagemap, uicontrol, pt, pd

task (strict), task (general)

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, imagemap, uicontrol, pt, pd

bookmap

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, booklibrary, mainbooktitle, booktitlealt, organizationname, imagemap, uicontrol, pt, pd

machineryTask

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, reqcond, reqcontp, personnel, perscat, perskill, esttime, supequi, supply, spare, safecond, imagemap, uicontrol

learningAssessment, learningOverview, learningSummary

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, imagemap, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcAsset, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcHotspotMap

learningBookmap

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, booklibrary, mainbooktitle, booktitlealt, organizationname, imagemap

learningContent

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, conbody, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, imagemap, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcAsset, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcHotspotMap

learningPlan

data, title, shortdesc, desc, p, note, lq, sli, li, itemgroup, dthd, ddhd, dt, dd, fig, figgroup, ph, stentry, draft-comment, fn, xref, entry, abstract, body, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, lcClient, lcPlanTitle, lcCIN, lcModDate, lcDelivDate, lcPlanSubject, lcPlanDescrip, lcPlanPrereqs, lcGeneralDescription, lcGoals, lcNeeds, lcValues, lcOrgConstraints, lcEdLevel, lcAge, lcBackground, lcSkills, lcKnowledge, lcMotivation, lcSpecChars, lcWorkEnvDescription, lcPlanResources, lcProcesses, lcTaskItem, lcAttitude, lcPlanObjective, lcJtaItem, lcGapItemDelta, lcLearnStrat, lcAssessment, lcDelivery, lcLMS, lcNoLMS, lcHandouts, lcClassroom, lcOJT, lcConstraints, lcW3C, lcPlayers, lcGraphics, lcViewers, lcResolution, lcFileSizeLimitations, lcDownloadTime, lcSecurity, imagemap, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcAsset, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcHotspotMap

Inheritance

- topic/image

Example
<image href="bike.gif" placement="break">
  <alt>Two-wheeled bicycle</alt>
</image>
Attributes

Name

Description

Data Type

Default Value

Required?

href

Provides a reference to the image. See 3.4.2.1 The href attribute for detailed information on supported values and processing implications.

CDATA

#IMPLIED

No

scope

The scope attribute identifies the closeness of the relationship between the current document and the target resource. See 3.4.2.10 The scope attribute for more information on values.

(local | peer | external | -dita-use-​conref-​target)

#IMPLIED

No

height

Indicates the vertical dimension for the resulting image display. If necessary, the image is scaled to the specified size. The value of this attribute is a real number optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a height value is specified and no width value is specified, the width will be scaled by the same factor as the height. If both a height value and width value are specified, some implementations may not be able to scale the two directions by a different factor and may therefore ignore one of the two values.

NMTOKEN

#IMPLIED

No

width

Indicates the horizontal dimension for the resulting image display. If necessary, the image is scaled to the specified size. If a width value is specified and no height value is specified, the height will be scaled by the same factor as the width.

NMTOKEN

#IMPLIED

No

align

Controls the horizontal alignment of an image when placement is specified as "break." Common values include left, right, and center.

CDATA

#IMPLIED

No

scale

Specifies a percentage by which to scale the image in the absence of any specified image height or width; a value of 100 implies that the image should be presented at its intrinsic size. If a value has been specified for this image's height or width attribute (or both), the scale attribute is ignored.

It is an error if the value of this attribute is not an unsigned integer. In this case, the implementation may (but need not) give an error message and may (but need not) recover by ignoring this attribute.

NMTOKEN

#IMPLIED

No

scalefit

Allow an image to be scaled to fit within available space. If, for a given image, any one of height, width, or scale is specified, those attributes determine the graphic size, and any setting of scalefit is ignored. If none of those attributes are specified and scalefit="yes", then the image is scaled (the same factor in both dimensions) so that the graphic will just fit within the available height or width (whichever is more constraining). The available width would be the prevailing column (or table cell) width--that is, the width a paragraph of text would have if the graphic were a paragraph instead. The available height is implementation dependent, but if feasible, it is suggested to be the page (or table cell) height or some other reasonable value.

(yes | no | -dita-use-​conref-​target)

#IMPLIED

No

placement

Indicates whether an image should be displayed inline or separated from the surrounding text. The processing default is inline. Allowable values are: inline or break. See 3.4.2.4.1 Using the -dita-use-conref-target value for more information on the -dita-use-​conref-​target value.

(inline | break | -dita-use-​conref-​target)

inline

No

alt (deprecated)

Alternative text that describes the image to provide accessibility to page readers or provides a text description when an image cannot be displayed by the user's software. The alt attribute is deprecated; use the alt element instead.

CDATA

#IMPLIED

No

longdescref (deprecated)

A reference to a textual description of the graphic or object. This attribute supports creating accessible content. See 3.4.2.1 The href attribute for detailed information on supported values and processing implications. For examples of how this attribute is used in output, see this this topic on long descriptions. NOTE: This attribute is deprecated in favor of the longdescref subelement to this element.

CDATA

#IMPLIED

No

univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)

A set of related attributes, described in 3.4.1.3 univ-atts attribute group

     

global-atts attribute group (xtrf, xtrc)

A set of related attributes, described in 3.4.1.2 global-atts attribute group

     

class, outputclass, keyref

Class and outputclass are described in 3.4.1.9 Other common DITA attributes

     

Previous Topic:  3.1.1.2.15 fn

Next Topic:  3.1.1.2.17 keyword

Parent Topic:  3.1.1.2 Body elements

Sibling Topics:

3.1.1.2.1 alt

3.1.1.2.2 cite

3.1.1.2.3 dd

3.1.1.2.4 desc

3.1.1.2.5 ddhd

3.1.1.2.6 dl

3.1.1.2.7 dlentry

3.1.1.2.8 dlhead

3.1.1.2.9 dt

3.1.1.2.10 draft-comment

3.1.1.2.11 dthd

3.1.1.2.12 example

3.1.1.2.13 fig

3.1.1.2.14 figgroup

3.1.1.2.15 fn

3.1.1.2.17 keyword

3.1.1.2.18 li

3.1.1.2.19 lines

3.1.1.2.20 longdescref

3.1.1.2.21 longquoteref

3.1.1.2.22 lq

3.1.1.2.23 object

3.1.1.2.24 note

3.1.1.2.25 ol

3.1.1.2.26 p

3.1.1.2.27 param

3.1.1.2.28 ph

3.1.1.2.29 pre

3.1.1.2.30 q

3.1.1.2.31 section

3.1.1.2.32 sectiondiv

3.1.1.2.33 sl

3.1.1.2.34 sli

3.1.1.2.35 term

3.1.1.2.36 text

3.1.1.2.37 tm

3.1.1.2.38 ul

3.1.1.2.39 xref