Additional ad elements

Additional ad elements can make the ad more attractive and increase the ad unit conversion rate.

  1. Image or video
  2. Advertiser information
  3. Callouts
  4. Price
  5. Discounts
  6. Description
  7. Action button

Image or video

You can add an image or video to the ad using the <ya-unit-image> element:

  • If you receive a video from the advertiser via the <ya-unit-image> tag, it will be displayed in the ad. If there is no video, a picture will be displayed instead.
  • If there is no picture in the ad, you can insert a placeholder image. To specify the path to the placeholder image, find the <ya-unit-image> tag and add the src parameter.
Editing an image or video
  • To set the aspect ratio, use the ratio parameter (sets the height to width ratio). You can set the aspect ratio between 9:16 and 2:1.

    What it looks like
  • To enable adaptive aspect ratio for ad units with adaptive height, use 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 viewable browser window area (without scrolling).

  • You can limit the height of adaptive images or videos by using the max-height parameter. The maximum height is set in pixels or as a percentage of the viewable area of the browser window, such as max-height="140" or max-height=40vh.

  • To fit a picture or video into a specified area without cropping, use the variant="contain" attribute (example: <ya-unit-image ratio="0.5625" variant="contain" />).

Recommendations for using images and videos in ads
  • Keep in mind that images can use different colors and formats: the design of the ad should look good and work well with various image types (illustrations, professional or amateur photography, and so on).
    What it looks like
  • The image can use a solid white or colored background around the edges. The design should look right when the color matches the background of the ad.
  • The ad text should not conflict with the picture and negatively impact the design of the ad.
  • If the width of the container is more than 150 pixels, make sure that videos can be played inside it. The ad should look attractive in all cases, even if you fit videos to width using the variant="contain" attribute.
  • Make sure that the container for the image or video isn't cropped and doesn't overlap other elements that take up more than 5% of its area. The only exceptions are mandatory disclaimers, menus, age labels, and the “Ad” label.

Advertiser information

The website's favicon

You can add a favicon for the advertiser's website using the <ya-unit-favicon /> element. In this case, place a solid white background under the favicon in order to avoid problems that arise when placing semi-transparent favicons against dark and complex backgrounds.

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>

You can add the advertiser's logo to be displayed on your unit'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="" />
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 image: the logo is replaced with a favicon or a placeholder if no favicon is found.
You can add sitelinks using the <ya-unit-sitelinks /> element. Ads can contain up to 8 sitelinks. You can limit their number using the limit parameter.
<ya-unit-sitelinks limit="2" />

When configuring ad design, keep in mind that the maximum length of a sitelink is 22 characters, and the total length of all sitelinks can't exceed 66 characters.

Sitelink design should clearly stand out from other elements of the ad: it should be clear to the user that this is an extra way to get to the advertiser's website. The user should be able to clearly distinguish sitelinks from each other.

Physical address

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


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

You can display only the first few callouts if you want: their number can be limited using the limit parameter.

Callouts can affect ad conversion. Make sure that the ad looks right with different callout numbers and lengths.

Ads located next to each other with a different callout length, number of callouts, or with no callouts at all, should not differ much in design.

Callouts are not clickable.


The <ya-unit-price /> element is used for rendering prices: it displays the old price, the new price, and the currency symbol (rubles, Belarusian rubles, tenge, lira, dollars, euros, and more). If you don't want to display the old price, add the disable-old-price attribute to the element.

You can customize individual subelements (new or old price) using the .ya-unit-price-current and .ya-unit-price-old classes accordingly.

When customizing your design, make sure that the old price is clearly discernible, and its design indicates that it is no longer applicable. The ad should look correct with different values of the new and old prices (from ₽10 to ₽100,000,000).


The ad may display a discount on the advertised product: to do this, add the <ya-unit-discount /> element.

To set the minimum discount value, use the minDiscount parameter with the required discount amount as a percentage, for example: minDiscount="20". If the discount is less than the specified minimum value, it will not be displayed in the ad. If you added a parameter but haven't set the minimum discount amount, the default value will be set to 5%.

The discount design should not clash with other ad formats used on the Yandex Advertising Network.

Stick to the following rendering priority order for prices and discounts: new price (price), old price, discount.

Example of price and discount display


To add a description to the ad, use the <ya-unit-desc> tag. Your description affects ad conversion. Make sure that the ad looks right with both a short description (10-12 characters) and with a description of the maximum length (75 characters).

Ads located next to each other with descriptions of a different length (or none at all), should not differ much in design.

Action button

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 website", 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:


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

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

Contact support

Send an email