Design customization

The widget may have the appearance of a grid made of ad cards or as a slider (a horizontal scrollable feed). Slider cards can be scrolled using gestures or customizable scrolling buttons.

You can pick and choose the elements to use in your ad in the card, such as the title, body text, image, and so on. Some elements are required by advertising law and the terms of the Yandex Advertising Network. Other elements are optional: you can use them to make the ad seamlessly blend in with your website's design and increase the widget conversion rate.

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 on the General tab if you don't have any experience with HTML and CSS. If necessary, you can go to the Code tab and add the CSS styles used on your website.

Widget template

The template determines which ad elements or recommendations will be displayed in the widget cell. 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-kebab />
  </ya-units-grid>
  <ya-recommendation-label />
</div>

You can use this to:

• 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 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.

Required ad elements

As defined by the terms of the Yandex Advertising Network, these elements must always be in the widget:

CSS class styles

CSS classes have multiple formatting styles:

• 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 — A picture or video in a recommendation.
• recommendation-label — Widget label.

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

Widget design

<ya-units-grid sizes="(max-width: 1024px) 2x2, (max-width: 600px) 2x1, ${grid_rows}x${grid_columns}">

.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 */
}

<div class="block">
  <div class="headline">See also</div>
  <ya-units-slider>
    <div class="unit">
      <ya-unit-kebab />
      <div class="image">
        <ya-unit-image ratio="0.5" />
      </div>
      <div class="body">
        <div class="title">
          <ya-unit-title />
        </div>
        <div class="meta">
          <span class="category">
            <ya-unit-category />
          </span>
          <span class="date">
            <ya-unit-date />
          </span>
        </div>
      </div>
    </div>
  </ya-units-slider>
  <div class="block-label">
    <div class="label">Yandex recommendations</div>
  </div>
</div>

.ya-units-slider {
  width: 95vw;
}
.ya-slider-item:not(:first-child) {
  margin-left: 1em;
}

<div class="block">
  <div class="headline">See also</div>
  <ya-units-slider>
    <div class="unit">
      <ya-unit-kebab />
      <div class="image">
        <ya-unit-image ratio="0.5" />
      </div>
      <div class="body">
        <div class="title">
          <ya-unit-title />
        </div>
        <div class="meta">
          <span class="category">
            <ya-unit-category />
          </span>
          <span class="date">
            <ya-unit-date />
          </span>
        </div>
      </div>
    </div>
  </ya-units-slider>
  <div class="block-label">
    <div class="label">Yandex recommendations</div>
  </div>
</div>

.ya-units-slider {
  width: 95vw;
}
.ya-slider-item:not(:first-child) {
  margin-left: 1em;
}

<div class="wrapper">
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
    ...
  </ya-units-grid>
</div>

.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 */
}

<div class="desc"><ya-unit-desc /></div>

<ya-clamp lines="2" class="desc"><ya-unit-desc /></ya-clamp>

<div class="desc"><ya-clamp lines="2"><ya-unit-desc /></ya-clamp></div>

.headline {
  font-family: Helvetica, sans-serif; /* font */
  font-size: 18px; /* font size — 18 pixels */
  font-weight: bold; /* font thickness — 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 */
}                        

.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 */
}

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

.unit-wrapper {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid, color — gray */
  padding: 5px; /* margins inside the border — 5 pixels */
  border-radius: 6px; /* round the border's corners after 6 pixels */
}

.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 inside the border — 5 pixels */
  border-radius: 6px; /* round the border's corners after 6 pixels */
}

<script>
    (yaads = window.yaads || []).push({
        id: "123456-7",
        render: "div",
        darkTheme: true
    });
</script>

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

.ya-theme-dark {
  background-color: black;
}                
.ya-theme-light {
  background-color: white;
}

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

<ya-recommendation-label text="Recommendations" />

.recommendation-label {
  color: black; /* text color — black */
  text-align: left; /* align to the left */
}

Design of individual elements in recommendations or ads

Menu icon in the ad

The user can hide or report the ad using the menu icon. The menu icon is added to the upper-right corner of the ad.

In the HTML template, the <ya-unit-kebab /> element sets the configuration of the menu icon. This element must be located directly inside <ya-units-grid /> or <ya-units-slider />.

<ya-unit-kebab class="ya-unit-kebab_dark" />

<ya-unit-kebab backgroundColor="#000000"/>

Recommendation or ad category

If you don't want to see a certain category in your recommendations, add the ad-only parameter to the <ya-unit-category /> element. Ad cells display the word "Ad" instead of a category, which can't be hidden: it's a required element.

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 recommendation metatags or the ad-only parameter is used).

Images or video in a recommendation or ad

To configure images or video in the HTML template, use the <ya-unit-image> element. If you receive multiple images from the advertiser via the <ya-unit-image> tag, they will be displayed in the ad in the form of an image carousel. If there is no image carousel, a video or picture will be displayed.

You can use this to:

• Set the aspect ratio using the ratio parameter (sets the height to width ratio).
• Enable adaptive aspect ratio for ad units with adaptive height using the ratio="adaptive" parameter. The image or video will be embedded without any restrictions and will take up at least 180 pixels but no more than 60% of the visible browser window area (without scrolling).
• Limit adaptive images and videos by height by setting a limit on the pixel count or the % of the visible browser window area. To do this, use the max-height parameter (example: max-height="140" or max-height="40vh").
• Specify the path to a placeholder image (used in ad units if your ad doesn't have any images to display) with the src parameter.
• Fit a picture or video into a specified area without cropping by using the variant="contain" attribute (example: <ya-unit-image ratio="0.5625" variant="contain" />).

Advertiser information in the ad

You can add advertiser info to your ads:

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

<ya-unit-logo src="https://example.com/image/image.png" />

<ya-unit-sitelinks limit="2" />

Action button in the ad

You can add an action button to the ad using the <ya-unit-direct-button /> element. Clicking the button will take the user to the ad link, which can significantly increase ad conversion.

The text displayed on the button is selected by the advertiser in Yandex Direct. The caption on the button can be as follows: “Learn more”, “More”, “To site”, or something else specified by the advertiser. Buttons can include domains and favicons. To make this text appear during ad rendering, set the special value {BUTTON_CAPTION} inside <ya-unit-direct-button />, such as:

<ya-unit-direct-button><div>{BUTTON_CAPTION}</div></ya-unit-direct-button>

The user's browser will render the element as <div />:

<div class="ya-unit-direct-button"><div>Get a discount</div></div>

Publication date in the recommendations

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" />

Dynamic addition

You can add a dynamic addition using the <ya-unit-line-asset> element. It will show one of the elements in the following order: price, sitelinks, callouts, or rating if they are added. For example, if the advertiser didn't add a price, but added sitelinks and callouts, then only sitelinks will be shown in the dynamic addition — as many as will fit in one row.