Design customization

Attention. By using the recommendation widget, you accept the risks outlined in p. 3.20 of the Offer Agreement. Before you start designing your template, make sure to read the current advertising legislation, including the requirements set for mandatory advertisement elements and their size.
The widget may have the appearance of a grid made out of ad cards or as a slider (a horizontal scrollable feed). Slider cards can be scrolled using gestures or customizable scrolling buttons.

Use the visual code designer to configure the widget's design: choose the Design section and click the Code tab. We recommend using one of the preset templates if you don't have any experience with HTML and CSS.

  1. Main widget elements
  2. CSS class styles
  3. General design settings

Main widget elements

Each element corresponds to its own HTML tag.

Here is a simple template that uses all the widget elements:

<div class="wrapper">
  <div class="headline">Recommendation widget header</div>
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
    <div class="image"><ya-unit-image /></div>
    <div class="title"><ya-unit-title /></div>
    <div class="desc"><ya-unit-desc /></div>
    <div class="domain"><ya-unit-domain /></div>
    <div class="meta">
                      <ya-unit-category class="category"/>
                      <ya-unit-date class="date"/></div>
    <ya-unit-close />
  <ya-recommendation-label />

You can use this for:

  • Change the widget's appearance from a grid (<ya-units-grid />) to a slider (<ya-units-slider />).
  • Add your own layout to the template.
  • Swap elements (don't disrupt nesting) or nest elements into other HTML tags.
  • Remove elements you don't want displayed in the widget. For example, you can remove the publication date by deleting the <ya-unit-date /> element.
Important. The template must include the element <ya-units-grid /> or <ya-units-slider />. You cannot delete these elements as they are required for the widget to work properly. Make sure to follow current advertising legislation regarding the requirements for mandatory advertisement elements the when designing your ad.

You can hide the content category and only display the “Ad” label by adding the ad-only parameter to <ya-unit-category />.

You don't need to specify the CSS class for the <ya-unit-category /> element, but you need one for the wrapper. This is done so that the "Ad" label is styled correctly when the category is missing (meaning it's not specified in the content metatags or the ad-only parameter is used).

CSS class styles

CSS classes have multiple formatting styles:
  • headline — Widget header
  • title — Cell header
  • category — Content category or the \"Ad\" label
  • wrapper — The overall appearance of the widget
  • grid — Grid
  • grid-row — Grid row
  • grid-item — Grid cell
  • ya-units-slider — Overall slider appearance
  • ya-slider-item — Card inside the slider
  • unit-wrapper — Recommendation
  • unit-image — Image used in the recommendation
  • recommendation-label — Widget label

You can also create your own CSS classes and customize their styles.

General design settings

These are the basic options for design customization. They don't require any advanced markup skills.

Customizing the widget design

The widget may have the appearance of a grid of a specific size or a slider (a horizontal scrollable feed). The grid is rendered by <ya-units-grid/> while the slider is rendered by <ya-units-slider />. You can't use both of these elements within the same template.

Setting up the grid

The <ya-units-grid> element is used to draw the grid based on parameters specified in the Grid size fields. You can only change the grid size using these fields.

Exception: if you need to display a different grids for different screen sizes, specify the corresponding values in the sizes. parameter. The ${grid_columns}x${grid_rows} valuables must be listed last. For example:
<ya-units-grid sizes="(max-width: 1024px) 2x2, (max-width: 600px) 2x1, ${grid_rows}x${grid_columns}">
Here is how grids are going to be matched to different screen sizes in this example:
  • A 2 × 1 grid will be displayed on screens less than 600 pixels wide.
  • A 2 × 2 grid will be displayed on screens between 601 and 1024 pixels wide.
  • Screens wider than 1025 pixels will display a grid based on the values set in the Grid size fields on the General tab.
Important. Keep in mind that you should set the number of displayed widget cells in HTML code. To specify the number of recommendations and ad places to load, change the values in the Grid size fields. For example, if you set the Grid size to 5 × 2 while the <ya-units-grid> element is configured to display a 2 × 2 grid for this screen size instead, then only 4 out of 10 loaded recommendations will be displayed. The opposite is also possible: if you have a 5 × 2 grid while the number of recommendations is set to 2 × 2, then the widget will display six empty cells.
The grid layout is configured via CSS classes grid, grid-row, and grid-item. For example:
.grid-row {
  margin-top: 10px; /* vertical distance between cells — 10 pixels */
.grid-item {
  margin-left: 20px; /* horizontal distance between cells — 20 pixels */
.grid {
  border: 1px solid #000; /* border around the grid: thickness — 1 pixel, border type — solid, color — black */
Setting up the slider
The slider is rendered by the element <ya-units-slider />.
Example of a slider template:
<div class="block">
  <div class="headline">Read also</div>
    <div class="unit">
      <ya-unit-close />
      <div class="image">
        <ya-unit-image ratio="0.5" />
      <div class="body">
        <div class="title">
          <ya-unit-title />
        <div class="meta">
          <span class="category">
            <ya-unit-category />
          <span class="date">
            <ya-unit-date />
  <div class="block-label">
    <div class="label">Yandex recommendations</div>
The slider design can be customized in CSS using the classes ya-units-slider (overall slider appearance) and ya-slider-item (a specific card within the slider):
.ya-units-slider {
  width: 95vw;
.ya-slider-item:not(:first-child) {
  margin-left: 1em;
You can add a recommendation scrolling button to your slider. To do this, find the element <ya-units-slider> and add the element <ya-slider-button>. The scroll direction is indicated with the direction attribute:
  • The left value sets scrolling to the left. The scroll button will be placed before the publications in the slider.
  • The right value determines scrolling to the right. The scroll button will be placed after the publications.
If <ya-slider-button> includes an element with the ya-clickable class, then scrolling will be triggered once the element is clicked on. If there is no such element, scrolling is performed by clicking on the button itself.
For example:
<ya-slider-button direction="left">Back to top</ya-slider-button>
When you scroll to the leftmost or rightmost position, the element <ya-units-slider /> receives the classes ya-slider-leftmost or ya-slider-rightmost respectively.
Note. If the scroll buttons are located above the slider cell, we don't recommend hiding them using these classes: this can lead to invalid clicks.
Customizing the overall widget appearance
Wrap the entire widget code in a tag with the wrapper class and configure the necessary parameters for this class in CSS. For example:
<div class="wrapper">
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
.wrapper {
  background: #fff; /* background color — white */
  padding: 10px; /* margins inside the border, all sides — 10 pixels */
  margin: 5px; /* margins outside the border, all sides — 5 pixels */
  border: 2px solid #000; /* border: thickness — 1 pixel, border type — solid, color — black */
  border-radius: 6px; /* round the border's corners after 6 pixels */
Restricting the number of rows displayed
May be useful for a header or a recommendation description. If you want to limit the number of rows displayed in the widget, wrap the element you need into the <ya-clamp> tag. For example:
Original header style:
<div class="title"><ya-unit-title /></div>
After limiting the number of displayed rows to two:
<ya-clamp lines="2" class="title"><ya-unit-title /></ya-clamp>
<div class="title"><ya-clamp lines="2"><ya-unit-title /></ya-clamp></div>
Text formatting
You can use CSS to format your text. Choose the class of the element you wish to configure and change its values. For example:
Setting up the font and spacing

.headline {
  font-family: Helvetica, sans-serif; /* font  */
  font-size: 18px; /* font size — 18 pixels */
  font-weight: bold; /* font thickness (weight) — bold */
  font-style: italic; /* font style — italics */
  line-height: 24px; /* line spacing — 24 pixels */
  letter-spacing: 1px; /* character spacing — 1 pixel*/
  text-decoration: underline; /* text decoration — underlined */
  text-transform: uppercase; /* text case — all uppercase */
  text-align: right; /*  text alignment — right */
  color: #373e44; /* text color — dark gray */
  background: #fff; /* background color — white */
.category {
  color: #093; /* text color — green */
  font-size: 12px; /* font size — 12 pixels */
  text-transform: uppercase; /*  text case — all uppercase */
Configuring margins

.headline {
  padding-top: 10px; /* top margin — 10 pixels */
  padding-right: 10px; /* right margin — 10 pixels */
  padding-bottom: 10px; /* bottom margin — 10 pixels */
  padding-left: 10px; /* left margin — 10 pixels */
Making a border around text

.headline {
  border: 1px solid #000; /* border: thickness — 1 pixel, border type — solid, color — black */
Configuring cell design

You can use the unit-wrapper class to configure the background color or border for each cell. For example:

.unit-wrapper {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid, color — gray */
  padding: 5px; /* margins inside cell — 5 pixels */
  border-radius: 5px; /* round the border's corners after 6 pixels */
Cells that contain content without images can have their own unique layout, which you can set using the class <unit-wrapper.unit-without-image> . For example:
.unit-wrapper.unit-without-image {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid, color — gray */
  padding: 5px; /* margins outside the border — 5 pixels */
  border-radius: 6px; /* round the border's corners after 6 pixels */
Setting up image layout inside a cell
To configure the image layout in the HTML template, use the <ya-unit-image> element. You can use it to:
  • Set the aspect ratio (the ratio parameter).
  • Display a video instead of an image.
  • Specify the path to a placeholder image (used in the widget if your content doesn't have any images to display) with the src parameter.
For example:
<ya-unit-image ratio="0.5" enable-video src="">
You can set other parameters in CSS (such as the image's maximum height or rounding corners) by changing the parameters in the unit-image class. For example:
.unit-image {
  max-height: 200px; /* maximum height — 200 pixels */
  border-radius: 4px; /* round the border's corners after 4 pixels */
Configuring the widget label
The <ya-recommendation-label> element in the HTML template is responsible for the label. If you delete the element from the template, the label won't appear in the widget. You can set your own label text using the text parameter. For example:
<ya-recommendation-label text="Recommendations" />
The label is aligned to the right and uses the color gray by default. You can change this parameters by configuring the recommendation-label CSS class. For example:
.recommendation-label {
  color: black; /* text color — black */
  text-align: left; /* align text to the left */
Setting the publication date

The publication date is specified using the <ya-unit-date /> element. You can change the date format:

<ya-unit-date format="HH:MM dd-mm-yyyy" />
Triggering a new tab to open

By default, widget recommendations open in the same browser tab, while ads open in a new one.

You can use an HTML template to set all links to open in a new tab by adding the target-blank attribute to the <ya-units-grid> or <ya-units-slider> tag. For example:

<ya-units-grid target-blank cols="${grid_columns}" rows="${grid_rows}">
Close button settings

The close button is missing from the HTML template by default. To add it to the template, use the <ya-unit-close /> element. This element must be located directly inside <ya-units-grid /> or <ya-units-slider />.

Disabling the tooltip

When you hover your mouse over the close button, a tooltip appears. You can disable it using the disableTooltip parameter: <ya-unit-close disableTooltip />. For example:

<div class="wrapper">
  <ya-units-grid cols="5">
    <ya-unit-close disableTooltip>
      <div class="super-tooltip">Close</div>
  <ya-recommendation-label />
Customizing the design of the close button and the tooltip

You can customize the appearance of the close button and the tooltip with CSS.

Use the .ya-ad-close-hovered class to make the tooltip appear as you hover the mouse over the close button.

If you want the close button to pop up when you hover the mouse over the tooltip instead, use the .ya-unit-item-hovered class. For example:

.super-tooltip {
  display: none;
/* tooltip is displayed when the close button is hovered over */
.ya-ad-close-hovered .super-tooltip {
  display: block; /* display as a block element */
  position: absolute; /* absolute position */
  width: 45%; /* width — 45% */
  height: 8%; /* height — 8% */
  top: 14%; /* position relative to top border — 14% */
  left: 20%; /* position relative to left border — 20% */
  background-color: black; /* background color — black */
  color: white; /* text color — white */
/* the close button pops up when hovering over the ad */
.ya-unit-item-hovered .ya-ad-close {
  display: block; /* display as a block element */
.ya-ad-close {
  display: none;
  /* a 7px clickable space around the close button image */
  padding: 7px; /* margins inside the border, all sides — 7 px */
  border-radius: 5px; /* round the border's corners after 5 pixels */
  background-color: red; /* background color — red */
  width: 40px; /* width — 40 px */
  height: 40px; /* height — 40 px */
  top: 10%; /* position relative to top border — 10% */
  right: 10%; /* position relative to right border — 10% */

In addition, you can change the system image for the close button: to do this, specify a link to your SVG image using the svg parameter. For example:

<ya-unit-close svg="data:image/svg+xml;base64,PD94..." />
Setting up an additional field in the feedback menu

To add a customizable field to the feedback menu, you can use the customField and customFieldUrl parameters:

<ya-unit-close customField="Super PRO" customFieldUrl="" />
Adapting your ads' appearance to fit different website designs

You can dynamically change your ad design to fit different site sections or visual themes (such as light or dark themes). To do this, add the additionalClasses parameter to the embed code and list a class array inside it. For example:

    (yaads = window.yaads || []).push({
        id: "123456-7",
        render: "div",
        additionalClasses: ["dark", "light"]

When the code is called, the following classes will be added to the root element <ya-units-grid> or <ya-units-slider>:

<ya-units-grid cols="1" rows="1"> <!-- when calling the code, classes are added to the root element -->
  <div class="image">
    <ya-unit-image ratio="1" />

Now you can set the element styles so that the rules are only applied when the added classes are included in the root element. To do this, go to the Design tab in the CSS settings and set the desired properties to the elements using the added classes. For example:

.dark .image {
  background-color: black;
.light .image {
  background-color: white;
Adding advertiser information

You can add advertiser information to your content:

The website's favicon

You can add a favicon using the <ya-unit-favicon /> element.

The favicon has a fixed size that can be set with the size parameter. The valid sizes are 16, 32, and 120 (16 by default). For example:

<ya-unit-favicon size="32" />

You can add the advertiser's logo that will be displayed on your widget's ads using the <ya-unit-logo /> element.

For cases where the publication doesn't have a logo, set a placeholder image in the src parameter. The placeholder image has zero height by default.

<ya-unit-logo src="" />
If the publication does not have a logo, it's replaced with other elements in the following order: favicon — image — placeholder. You can change this order in the disabledSubstitution parameter:
  • <ya-unit-logo disabledSubstitution="all" /> — Excludes both the favicon and the image. The logo is immediately replaced with a placeholder
  • <ya-unit-logo disabledSubstitution="favicon" /> — Excludes the favicon: the logo is replaced with an image, or a placeholder if no image is found.
  • <ya-unit-logo disabledSubstitution="image" /> — Excludes the images: the logo is replaced with a favicon or a placeholder if no favicon is found.

Added using the <ya-unit-sitelinks /> element. The number of sitelinks can be limited by the limit: parameter.

Physical address

Added using the <ya-unit-address /> element.