Design customization

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

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

Widget design

Widget format

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:

HTML

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

The grid layout is configured via CSS classes grid, grid-row, and grid-item. For example:

CSS

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

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 2 × 2, then the widget will display six empty cells.

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

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 cells in the slider.
• The right value determines scrolling to the right. The scroll button will be located after the slider cells.

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.

Widget appearance

To customize the widget's overall appearance (such as the text background color or margins), you need to wrap all of the ad unit's code in tags, set the class (for example, wrapper), and set up parameters for that class in CSS.

HTML

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

CSS

.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

If you want to limit the number of rows displayed in the widget, wrap the element you need in the <ya-clamp> tag.

Attention. Do not limit the number of lines displayed in the title: it must be displayed in full according to advertising law.

HTML

Original header style:

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

After limiting the number of displayed rows to two:

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

Or

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

Text format

You can use CSS to format your text. Choose the class of the element you wish to configure and change its values.

Setting up the font and spacing

CSS

.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

CSS

.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

CSS

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

Cell appearance

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

CSS

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

Cells that contain recommendations or ads without images can have their own unique layout, which you can set using the <unit-wrapper.unit-without-image> class. For example:

CSS

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

Adapting your ads' appearance to fit your website design

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 darkTheme: true parameter to the embed code, for example:

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

When the code is called, the <ya-units-grid> or <ya-units-slider> root elements will receive the ya-theme-dark or ya-theme-light classes:

<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" />
  </div>
</ya-units-grid>

Each ad unit can store one design layout with two color themes. To do this, go to the Code tab in the CSS settings and set the desired properties using these classes.

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

The ad menu will also change depending on the theme. We don't recommend using media queries for your ad designs, because this method won't let the menu change to match the theme changes.

Note. We would normally use the additionalClasses and nativeAdditionalClasses parameters to make ads fit the website design. However, they will no longer be supported in the future.

Open recommendations in a new tab

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

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:

HTML

<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:

CSS

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

Edit the menu icon

The default menu icon is white with a semi-transparent sublayer. For rendering on a white background, you can change the icon color to black and remove the sublayer: to do this, use the ya-unit-kebab_dark class.

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

You can set any other color for the icon using the backgroundColor parameter:

<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:

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. Acceptable sizes: 32 × 32 and 120 × 120 pixels. The default size is 32 × 32.

If the favicon can't be displayed, you can display the ad image instead. To do this, specify the allowImageFallback attribute.

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

Logo

You can add the advertiser's logo to the widget's ads using the <ya-unit-logo /> element.

For cases where the ad 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="https://example.com/image/image.png" />

If the ad doesn't 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.

Callouts

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

Callouts list the advantages of a certain product or service, inform users of special offers, and describe the advantages of partnering with a specific advertiser.

The advertiser can add multiple callouts to a single ad. The number of callouts can be limited using the limit parameter. Callouts are not clickable.

Sitelinks

You can add sitelinks using the <ya-unit-sitelinks /> element. An ad can display up to 8 links at a time, but you can limit their number via the limit parameter.

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

Physical address

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

Action button in the ad

You can add an action button to your ad that will act as the ad link for the user. To do this, add the element <ya-unit-direct-button />.

The text on the button is chosen by the advertiser in Yandex Direct. To make this text appear during ad rendering, specify a 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 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.

What it looks like

The rendering style of the dynamic addition is preset, but you can customize it.

Mobile app ad design

Contact support

Send an email

Write to chat