gatsby-remark-image-attributes

Creates HTML image markup with style and data-* attributes from ‘image’ nodes with attributes, as parsed by remark-image-attributes.

The plugin plays nicely with other image-processing plugins like gatsby-remark-images, amending their generated markup.

markdown_html


Demo

Netlify Status source

Some examples, using MDX

Installation

npm install --save gatsby-remark-image-attributes

How to use

Add gatsby-remark-image-attributes as plugin to gatsby-transformer-remark in gatsby-config.js

plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-image-attributes`,
          options: {

            // ?Boolean=true
            //   If true (the default), all CSS
            //   property names will be recognized
            //   as styleAttribute.
            styleAttributes: true,

            // ?Boolean=false
            //   If true, all attributes that
            //   aren't styleAttributes, will be
            //   added as data-* attributes to the
            //   image.
            dataAttributes: false
          }
        }
      ]
    }
  }
],

Now you can add attribute declarations as hash value to an image’s URL:

![satisfied](https://foomoji.com/satisfied.png#lightbox=true;width=32px;height=32pxi;position=absolute;)

The resulting HTML will be:

<img
  src="https://foomoji.com/satisfied.png"
  alt="satisfied"
  style="width: 32px; height:32px; position: absolute;"
  data-lightbox="true"
  class="gatsby-img-attributes"
/>

Options

Name Type Default Description
styleAttributes Boolean true Set to false if you want to disable CSS properties being added to the images style attribute.
dataAttributes Boolean false Set to true if you want attributes not recognized as styleAttribute to be added as data- attribute to the image.

.gatsby-img-attributes

Generated markup has a CSS class gatsby-img-attributes. The plugin itself does not come with any attributes for that class; you can use it to apply default styling to all images with attributes.

styleAttributes

NOTE: options.styleAttributes used to accept an Array<String>, its items extending a default set of recognized properties, e.g. styleAttributes: ['position', 'top', 'left']. This still works, but sets styleAttributes: true, enabling all CSS properties.

The plugin uses a list of all CSS properties, as defined by the W3C, to decide whether an attribute is to be added to the image’s style or not.

dataAttributes

When options.dataAttributes is true, the plugin will add all attributes whose key isn’t a CSS property as data-* attribute to the image.

gatsby-config.js:

plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-image-attributes`,
          options: {
            dataAttributes: true
          }
        }
      ]
    }
  }
];

md:

![happy](https://foomoji.com/happy.png#tool-tip=Fancy image with tooltip;position=absolute;height=100px)

Where position and height are recognized as styleAttributes, tool-tip is not and thus applied as data- attribute:

<img
  src="https://foomoji.com/happy.png"
  alt="happy"
  style="position: absolute; height: 100px;"
  data-tool-tip="Fancy image with tooltip"
  class="gatsby-img-attributes"
/>

With options.styleAttributes === false, valid CSS properties become data- attributes:

plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-image-attributes`,
          options: {
            styleAttributes: false,
            dataAttributes: true
          }
        }
      ]
    }
  }
];
![happy](https://foomoji.com/happy.png#tool-tip=Fancy image with tooltip;position=absolute;height=100px)
<img
  src="https://foomoji.com/happy.png"
  alt="happy"
  data-tool-tip="Fancy image with tooltip"
  data-position="absolute"
  data-height="100px"
  class="gatsby-img-attributes"
/>

use with gatsby-remark-images

This plugin can handle already processed images (type: ‘html’), as long as the node object contains an attributes field and the value an <img /> tag.

So using other image processing plugins, like gatsby-remark-images, is possible:

gatsby-config.js

plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: 'gatsby-remark-images',
          options: {
            backgroundColor: 'none',
            disableBgImage: true
          }
        },
        {
          resolve: `gatsby-remark-image-attributes`,
          options: {
            dataAttributes: true
          }
        }
      ]
    }
  }
]

and

![party](./images/emojis/party.png#box-shadow=2px 2px 6px 0px;float=right;foo=bar)

generates

<span
  style="display:block; box-shadow: 2px 2px 6px 0px; float: right;"
  class="gatsby-img-attributes"
>
  <span class="gatsby-resp-image-wrapper" ...>
    <span class="gatsby-resp-image-background-image" ...></span>
    <img
      class="gatsby-resp-image-image"
      alt="party"
      title="party"
      src="/static/4d415e7127c0f88799cd9f357aabc732/b7060/party.png"
      data-foo="bar"
      ...
  /></span>
</span>

You might have noticed that styleAttributes and class="gatsby-img-attributes" have been applied to the wrapping <span> here, rather than the <img>. . See demo#positioning and this issue comment for why this is necessary.

dataAttributes, on the other hand, are always applied to the <img>.

use with gatsby-plugin-mdx

Add gatsby-remark-image-attributes to options.gatsbyRemarkPlugins of gatsby-plugin-mdx.

gatsby-config.js

{
      resolve: "gatsby-plugin-mdx",
      options: {
        extensions: [".mdx", ".md"],
        gatsbyRemarkPlugins: [
          {
            resolve: "gatsby-remark-copy-linked-files",
            options: {
              ignoreFileExtensions: ["png", "jpg", "jpeg"]
            }
          },
          {
            resolve: "gatsby-remark-images",
            options: {
              backgroundColor: "none",
              disableBgImage: true,
              linkImagesToOriginal: false
            }
          },
          {
            resolve: "gatsby-remark-image-attributes",
            options: {
              // styleAttributes: true,
              // dataAttributes: false
            }
          }
        ]
      }
    },