# Core widgets

Apostrophe comes with some content widgets you can use in areas right away. See below for their descriptions and options.

Common name/label	Widget reference	What is it?
Rich text	`@apostrophecms/rich-text`	A space to enter text and allow formatting (e.g., bolding, links)
Image	`@apostrophecms/image`	A single image supporting alt text and responsive behavior
Video	`@apostrophecms/video`	Embed a video from most video hosts by entering its URL
Raw HTML	`@apostrophecms/html`	Allow entering HTML directly (see security notes below)

The rich text widget provides a space for entering and editing formatted text. Editors can update its content directly in-context.

There are many text formatting features that you can configure for rich text widgets. These editor options are configured in two widget options: toolbar and styles. Add these to the widget configuration object when adding an area field.

// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
  '@apostrophecms/rich-text': {
    // 👇 Toolbar configuration
    toolbar: ['styles', 'bold', 'italic'],
    // 👇 Styles configuration
    styles: [
      {
        tag: 'p',
        label: 'Paragraph (P)'
      },
      {
        tag: 'h2',
        label: 'Heading 2 (H2)'
      }
    ]
  }
}

To add formatting tools to the rich text toolbar, add their names to the toolbar array. The available formatting options include:

Tool name	What is it?
`'styles'`	A list of text styles, allowing different HTML tags and CSS classes (see "Configuring text styles" below)
`'bold'`	Bold text
`'italic'`	Italicize text
`'strike'`	Strikethrough text
`'link'`	Add a link
`'horizontalRule'`	Add a visual horizontal rule
`'bulletList'`	Bulleted list
`'orderedList'`	Numbered list
`'blockquote'`	Block quote
`'codeBlock'`	Code block
`'alignLeft'`	Text Align Left
`'alignCenter'`	Text Align Center
`'alignRight'`	Text Align Right
`'alignJustify'`	Text Align Justify
`'undo'`	Undo the last change
`'redo'`	Redo the last undone change
`'\|'`	Add a visual separator to the toolbar (not a formatting action)

# Configuring text styles

When you add the 'styles' formatting tool, you can configure an array of text styles. These must include an HTML tag and a label for the menu interface. They may also include a CSS class.

A single style including class might look like:

{
  label: 'Centered heading',
  tag: 'h2',
  class: 'centered'
}

You can use the same tag in several styles with various CSS classes.

NOTE

Including a class with a style will not automatically apply any styles. You still need to write your own CSS for the class.

# Default rich text configuration

{
  toolbar: [
    'styles',
    'bold',
    'italic',
    'strike',
    'link',
    'bulletList',
    'orderedList',
    'blockquote'
  ],
  styles: [
    {
      tag: 'p',
      label: 'Paragraph (P)'
    },
    {
      tag: 'h2',
      label: 'Heading 2 (H2)'
    },
    {
      tag: 'h3',
      label: 'Heading 3 (H3)'
    },
    {
      tag: 'h4',
      label: 'Heading 4 (H4)'
    }
  ]
},

You can configure only one of the two sections (toolbar or styles), and use the default configuration for the other.

You can also set your own default rich text options. Avoid adding the same options repeatedly by configuring these options on the @apostrophecms/rich-text-widget module.

// modules/@apostrophecms/rich-text-widget/index.js
module.exports = {
  options: {
    defaultOptions: {
      toolbar: [
        // Your default formatting tools
      ],
      styles: [
        // Your own default styles
      ]
    }
  }
}

# Adding placeholder content

By default, the rich text widget displays placeholder content. To block this behavior, set the placeholder option to a value of false. To change the content, pass either a simple string or a string containing a namespaced i18n key, to the placeholderText option.

module.exports = {
  options: {
    placeholderText: 'myNamespace:placeholder'
  }
};

/modules/@apostrophecms/rich-text-widget/index.js

{
  "placeholder": "Add text here..."
}

/modules/@apostrophecms/rich-text-widget/i18n/myNamespace/en.json

The image widget supports displaying a single image, including its alt text. It also uses the image variants that Apostrophe generates to responsively load image files based on the active viewport width.

// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
  '@apostrophecms/image': {}
}

# Specifying a minimum size

You can specify a minimum size for any image widget:

// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
  '@apostrophecms/image': {
    minSize: [ 1000, 600 ]
  }
}

This widget won't allow the editor to select any image under 1000 pixels wide, or under 600 pixels tall. In addition, editors won't be able to crop the image smaller than that after selecting it for that particular widget.

# Specifying an aspect ratio

You can specify an aspect ratio for any image widget:

// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
  '@apostrophecms/image': {
    aspectRatio: [ 3, 2 ]
  }
}

In some designs, especially slideshow experiences involving multiple images, allowing images with different aspect ratios just doesn't look good. For these cases, you can set an appropriate aspect ratio.

When you set an aspect ratio, editors can still select differently shaped images. However, if they save that selection without manually cropping it, the image is automatically cropped to match the ratio you set. If the editor does choose to manually crop it, the cropping interface ensures the aspect ratio you chose remains in effect.

# Taking advantage of the "focal point" feature

A fixed ratio for all devices doesn't work for all designs. If your responsive design features custom CSS with different ratios at different breakpoints, consider encouraging editors to use the focal point feature as an alternative to setting minSize. The image widget emits CSS that biases the browser toward ensuring that the editor's chosen focal point remains visible, regardless of device.

# Customizing responsive image sizes

The image widget's default srcset attribute for responsive behavior assumes the image is roughly the same width as the viewport. This will help reduce download times even if the display size is smaller, but you can make responsive loading more accurate by providing the sizes attribute (opens new window) value.

This configuration is applied as a template option. In the template's area tag, include a sizes context option for the image widget. The option value should be the actual HTML attribute value.

{% area data.page, 'main' with {
  '@apostrophecms/image': {
    sizes: '(min-width: 600px) 45vw, (min-width: 1140px) 530px'
  }
} %}

See below for the image variant sizes that Apostrophe generates by default.

# Specifying the fallback size

Most browsers will use the responsive srcset attribute to find the right image file to display. Older browsers may need the static src attribute value. By default Apostrophe uses the full image variant, no larger than 1140px by 1140px, for the src value.

You can change this in the area field widget options, using another image size name.

// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
  '@apostrophecms/image': {
    size: 'one-half'
  }
}

The sizes available by default are:

Name	Maximum width	Maximum height
`max`	1600px	1600px
`full`	1140px	1140px
`two-thirds`	760px	760px
`one-half`	570px	700px
`one-third`	380px	700px
`one-sixth`	190px	350px

The final image size name is original, which delivers the original image file. This should be used carefully since it could be very large and slow to download.

# Adding a placeholder image

The image widget displays a placeholder image by default. To block this behavior, set the placeholder option to a value of false. The default image can be changed by saving the desired image in the public folder of your module, then passing the final build path for that file to the placeholderUrl option.

module.exports = {
  options: {
    // for a file named 'placeholder.png' in the module public folder
    placeholderUrl: '/modules/@apostrophecms/my-image-widget/placeholder.png'
  }
};

/modules/@apostrophecms/image-widget/index.js

NOTE

The path to the custom image is where the file will be located in the final build. If you customize the image widget at the project level, the asset module will create the my-image-widget folder to hold the contents of the /modules/@apostrophecms/image-widget/public folder. This is the location where the path to the custom image should point, not the image-widget folder.

The core video widget accepts a video URL and fetches the embed code to display it. Most major video hosts are supported by default.

# Adding a placeholder video

By default, the video widget displays a placeholder video. To block this behavior, set the placeholder option to a value of false. The default video can be changed by adding a hosted video URL string as the value of the placeholderUrl option. The video URL must be compatible with the video widget, e.g., a YouTube video page URL, Vimeo video page URL, etc.

module.exports = {
  options: {
    placeholderUrl: 'https://vimeo.com/375468729'
  }
};

/modules/@apostrophecms/video-widget/index.js

Or: How to get access to the editing interface when embedded HTML breaks it.

The HTML widget allows content editors to embed raw HTML directly into a template. This can be helpful if they may need to add third-party features (e.g., sign-up forms). This can also be very dangerous since there are no limits to what they can add. Bad JavaScript in embedded HTML can break the user interface, making it impossible to remove the bad code.

Think carefully before providing this widget option to editors and make them aware of the risks.

There is a safety mechanism in case things do go wrong. If embedded HTML breaks the Apostrophe interface, append the query parameter safemode=1 to the end of the URL. The HTML widget will not render its contents and editors will be able to edit it to remove or fix the embed.

https://example.net/broken-page?safemode=1

To do that, access the page with ?safemode=1 at the end of the URL. Then you will be able to edit the widget and remove the offending content.

# Setting a CSS class on core widgets

There are two options to set classes on core widgets. You can add a className option to either the widget module or the widget options in an area field. That value will be added to the outer-most HTML element in core widget templates. If both are set, the className property on the area configuration will be used.

Configuring on the module widget level:

// app.js
require('apostrophe') {
  modules: {
    '@apostrophecms/video-widget': {
      options: {
        className: 'project-video-class'
      }
    }
  }
};

Configuring on the area field widget options:

// modules/@apostrophecms/home-page/index.js
module.exports = {
  fields: {
    add: {
      main: {
        type: 'area',
        options: {
          widgets: {
            '@apostrophecms/video': {
              className: 'area-video-class'
            }
          }
        }
      }
    },
    // ...
  }
};

← Areas and widgets Custom widgets →

# Core widgets

# Rich text widget

# Configuring text styles

# Default rich text configuration

# Adding placeholder content

# Image widget

# Specifying a minimum size

# Specifying an aspect ratio

# Taking advantage of the "focal point" feature

# Customizing responsive image sizes

# Specifying the fallback size

# Adding a placeholder image

# Video widget

# Adding a placeholder video

# HTML widget

# Setting a CSS class on core widgets

# Core widgets

# Rich text widget

# Configuring the toolbar

# Configuring text styles

# Default rich text configuration

# Adding placeholder content

# Image widget

# Specifying a minimum size

# Specifying an aspect ratio

# Taking advantage of the "focal point" feature

# Customizing responsive image sizes

# Specifying the fallback size

# Adding a placeholder image

# Video widget

# Adding a placeholder video

# HTML widget

# Setting a CSS class on core widgets