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.

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 headline</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-units-grid>
  <ya-recommendation-label />
</div>

You can use this for:

  • 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. However, you cannot delete <ya-units-grid> as it's 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
  • 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.

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:
HTML
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>
Or
<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
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 */
}
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:
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 */
}
Customizing the grid appearance

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.
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:
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 */
}
Configuring cell design

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

CSS
.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:
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 borderer'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:
HTML
<ya-unit-image ratio="0.5" enable-video src="https://example.com/image/image.png">
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:
CSS
.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:
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 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> tag. For example:

<ya-units-grid target-blank cols="${grid_columns}" rows="${grid_rows}">
Setting up the X button to close the ad

The closing X 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 />.

Disabling the tooltip

When you hover your mouse over the closing X, 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-unit-close>
  </ya-units-grid>
  <ya-recommendation-label />
</div>
Customizing the design of the closing X and the tooltip

You can customize the appearance of the X and the tooltip with CSS.

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

If you want the X 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 X is hovered over */
.ya-ad-close-hovered .super-tooltip {
  display: block; /* block element is displayed */
  position: absolute; /* absolute position */
  width: 45%; /* width — 45% */
  height: 8%; /* height — 8% */
  top: 14%; /* location relative to top border — 14% */
  left: 20%; /* location relative to left border — 20% */
  background-color: black; /* background color — black */
  color: white; /* text color — white */
}
/* the close X pops up when hovering over the ad */
.ya-unit-item-hovered .ya-ad-close {
  display: block; /* block element displayed */
}
.ya-ad-close {
  display: none; 
  /* a 7px clickable space around the X image */
  padding: 7px; /* padding inside the border from all sides — 7 px */
  border-radius: 5px; /* round the border edges after 5px */
  background-color: red; /* background color — red */
  width: 40px; /* width — 40 px */
  height: 40px; /* height — 40 px */
  top: 10%; /* location relative to top border — 10% */
  right: 10%; /* location relative to right border — 10% */
 }

In addition, you can change the system image for the X: 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="https://yandex.ru"/>
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:

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

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

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

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

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="https://example.com/image/image.png" />
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.
Sitelinks

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.