---json
{
    "description": "Combostrap supports raster and vector images. This page shows you how to add an image with syntax and examples.",
    "images": [
        { "path": ":docs:block:stock_image_surfer_in_the_see.png" }
    ],
    "page_id": "y0sap72kyohtclmlce7xt",
    "title": "How to use the image tag in ComboStrap"
}
---
====== Image Link ======

===== About =====
''image'' is a [[docs:content:content|inline component]] that permits to show [[docs:content:raster|raster]] or [[docs:content:svg|svg]] images from your media library in your pages.




===== Features =====


All images:
  * are [[docs:performance:lazy|lazy loaded]] by default to enhance [[docs:performance:performance|performance]]
  * are ''automatically reduced in size'' and ''responsive''
      * for [[docs:content:svg|svg images]], we set extra responsive properties.
      * for [[docs:content:raster|raster images]],  a small screen will receive a small image while a big screen will receive the biggest image. For more information, see [[docs:content:raster#automatic_responsive_resizing|Raster - Automatic Resizing]]
  * support scaling on ''width'', ''height'' or both
  * are cached permanently by the server and the browser until the physical file has changed.

===== Supported Image Type =====
''ComboStrap'' supports:
  * [[docs:content:raster|raster image]] (jpg, png, ...)
  * and [[docs:content:svg|svg image]]


===== Syntax =====

ComboStrap uses:
  * the same syntax than [[doku>wiki:syntax#media_files|Dokuwiki]]
  * extended with the possibility to define a ''ratio''
  * extended with the [[docs:styling:styling|styling attributes]]

<code dw>
{{[ ]path?WxH&ratio=w:h&nolink&att=value[ ]}}
</code>
where:
  * ''path'' is:
      * for an internal image: the internal path of the dokuwiki
      * for an external image: the URL.
  * ''W'' is the width  (Optional, 0 if you want to set only the height)
  * ''H'' is the height (Optional)
  * ''ratio'' is the image ratio (''21:9'', ''16:9'', ''4:3'', ''1:1'' or any other custom ratio).
  * ''[ ]'' are optional spaces that indicates the alignement of the image (left, center, or right [[docs:styling:float|float]])
  * ''nolink'' will not add a [[#imagedefaultlinking|link to the image itself]].
  * ''lazy=(none|html|lozad)'' controls the [[:docs:performance:lazy|lazy method]]
  * ''att=value'' is one or more [[docs:styling:styling|styling attributes]]



===== Example =====

==== Resize to a given width ====


To resize to a given width, add a number.

Example of an image resized to ''400px''
<webcode>
<code dw>
{{:docs:block:stock_image_surfer_in_the_see.png?400|}}
</code>
</webcode>


<note>
Raster images are automatically resized below the screen size. For more information, see the [[docs:content:raster#automatic_responsive_resizing|Raster - Automatic Resizing feature]]
</note>

==== Resize to a given height ====


To resize to a given height, set a width to ''0'' followed by the height.

Example of an image resized to ''250px'' height
<webcode name="Default" frameborder="0">
<code dw>
{{:docs:block:stock_image_surfer_in_the_see.png?0x250|}}
</code>
</webcode>


==== Cropping ====


''cropping'' can be defined by setting the following properties:
  * a width and an height
  * a ratio and a width 
  * a ratio and a height
  * a ratio

''cropping'' works on:
  * [[docs:content:svg|svg]] ([[docs:content:icon|icon]] included)
  * and [[docs:content:raster|raster image]]

First, the image is scaled down by height and is then cropped on the width towards the center.

Example: 
  * [[docs:content:raster|raster image]] cropped to ''200x200px'' with the definition of a ''200'' width and ''200'' height 
<webcode name="Default" frameborder="0">
<code dw>
{{:docs:block:stock_image_surfer_in_the_see.png?200x200|}}
</code>
</webcode>
  * [[docs:content:raster|raster image]] cropped to ''200x200px'' with the definition of the ratio ''1:1'' and a ''200'' width
<webcode name="Default" frameborder="0">
<code dw>
{{:docs:block:stock_image_surfer_in_the_see.png?200&ratio=1:1|}}
</code>
</webcode>
  * [[docs:content:raster|raster image]] cropped to ''4:3'' with the definition of the ratio at the natural width
<webcode name="Default" frameborder="0">
<code dw>
{{:docs:block:stock_image_surfer_in_the_see.png?ratio=4:3|}}
</code>
</webcode>
  * [[docs:content:svg|svg image]] cropped to ''16:9'' with ''200'' height <inote>We have added an height because [[docs:content:svg|svg]] expands to the available space and will take the whole page width, while a raster image expands only to its intrinsic width</inote>
<webcode name="Default" frameborder="0">
<code dw>
{{:undraw_content_creator.svg?0x200&ratio=16:9|}}
</code>
</webcode>
==== Position ====

  * To position the image to the left, let no space, this is the default
  * To position the image to the center with a [[docs:styling:align#center|center block]], let a space at the left and at the right
  * To position the image to the right with a [[docs:styling:float#right|right float]], let a space at the left

Example: position the image to the right with:
  * a width of 300
  * a [[docs:styling:color|background-color of white]]
  * and a padding of 3 (''p-3'') with [[docs:styling:spacing|spacing]]
<webcode name="Default" frameborder="0">
<code dw>
{{ :docs:block:stock_image_surfer_in_the_see.png?300&spacing=p-3&background-color=white|}}
</code>
</webcode>

<note>
If you want more control on position, we advise you to use the [[docs:layout:component:grid|grid]] and its cells.
</note>


==== Styling Attributes ====

You can style even further your image with [[docs:styling:styling|styling element]]:
  * with a [[docs:styling:shadow|shadow elevation through styling]].
  * with a [[docs:animation:hover|hover float effect]]

For instance, to elevate this photography with a surfer, you could use this syntax.

<webcode name="Default" frameborder=0>
<code dw>
{{ :docs:block:stock_image_surfer_in_the_see.png?400&onHover=float&shadow=lg |}}
</code>
</webcode>

==== Background ====

You can also use the image as [[docs:styling:background|background]].
<webcode name="Default" frameborder="0">
<code dw>
<slide color="steelblue" align="text-center" >
   <background opacity="0.3">{{:docs:block:stock_image_surfer_in_the_see.png|}}</background>
    <heading d2>A background image</heading>
    <text lead font-size="h3">A background image will emphasise a short message.</text>
</slide>
</code>
</webcode>

==== Gallery ====

With the [[docs:layout:component:carrousel|carroussel component]], you can create an image gallery

<webcode name="Default" frameborder="0" >
  * The cards:
<code dw>
<carrousel>
{{ :woman-yoga-sunset.jpg?0x600&ratio=16:9 |}}
{{ :page_speed_performance.png?0x600&ratio=16:9 |}}
{{ :undraw_content_creator.svg?0x600&ratio=16:9 |}}
</carrousel>
</code>
  * The output:
</webcode>
===== Support =====





===== Configuration =====
==== imageEnable ====
This [[docs:app:configuration|configuration]] permits to disable completely this component. It will also disable:
  * the [[docs:content:raster|raster image]]
  * and [[docs:content:svg|svg]] component

==== imageDefaultLinking ====

This [[docs:app:configuration|configuration]] permits setting the link type to the image.

^ Value ^ Behavior ^
| ''default'' | The default value is ''direct'' |
| ''direct'' | Direct link to the image in a [[..:utility:lightbox|lightbox]] |
| ''detail'' | Link to a web page with image details |
| ''linkonly'' | Only the link is displayed, not the image |
| ''nolink'' | No link is added around the image |


===== Metadata Image =====
You can also add [[release:deprecated:images-meta|image in the metadata]] in order to add/set illustrations for social cards or templates.