Create a rendering variant

Current version: 10.3

SXA comes with a set of default renderings and rendering variants. Rendering variants are configurable adaptations of the default renderings. To encourage reusability, designers and front-end developers can also create new rendering variants. This gives authors more options in the way they present their content.

You can create your own variation of a rendering by adding a variant in the Content Editor.

To create a rendering variant:

  1. In the Content Editor, click the site and open the Presentation/Rendering Variants folder. This folder lists all the renderings that allow variants.

    Note

    To add a rendering to the folder, contact your Administrator.

  2. Right-click the rendering that you want to add the variant to, and then click Insert, Variant Definition.

    Insert a variant definition
  3. Enter a name and click OK.

  4. In the Variant Details section, specify information in the following fields:

    • Field used as link target - provide the field name of the target item. This class is added to the list and navigation items markup (li HTML element). This link is used to override all links when the Is link, Is prefix link, or Is suffix link check boxes are selected.

    • Allowed in templates - specifies the pages that the variant is available for. Click the relevant page template, click the right arrow to move it to the list of selected items, and then click Save. If there are no templates selected, the variant is available for all pages.

    • Compatible renderings - makes rendering variant available for other renderings. For example, if for a Page Content rendering variant, in the Compatible Renderings field, you specify Title, you can use the rendering variant for the Title rendering as well..

    • Css Class: Specifies class to render into rendering content element. For example:

      RequestResponse
      <div class="component title customClass col-xs-12">
          <div class="component-content">
      <div class="field-title">S</div>    
      </div>
      </div>
    • Item Css class field: Specifies field name of the rendered item from which the CSS class will be taken and rendered into class attribute. Supported for Navigation rendering only

  5. Optionally, in the Appearance section, you can add a thumbnail image for the variant. This image appears in the Variant drop-down box and can help content editor select the best variant for their purpose.

    Content Editor

    Experience Editor

    In the Appearance section add a thumbnail for the variant
    Choose a rendering variant after viewing thumbnails.

    Rendering variants without a thumbnail display with their name only.

    If no thumbnail is specified, the variant displays the name only.
  6. To display the fields, you can add child items to the rendering variant, right-click the variant, click Insert, and then click the relevant item.

    These are the child items available for a rendering variant:

    • Field - displays field name and other field values.

    • Date - displays data and time in custom format. To be able to display date and time in custom format you have to use the Date item. This item is similar to the Field item but has an additional field: Date format that allows you to choose a date and time format. Like the Field item, the Date item can be used as fallback item and can have its own fall back items defined.

      Note

      The fields and variant details are described in a table below.

    • Edit Frame - variant item that can be used in the edit mode.

    • HTML Tag - enables users to render HTML self-closing tags.

    • Model - displays properties from the current model. The SXA renderings model inherits from Sitecore.XA.Foundation.Mvc.Models.RenderingModelBase. In the Property path field, you can enter the path to the property that you want to display.

    • Model Iterator - displays properties from list of models.

    • Placeholder - renders a placeholder that enables users to add additional renderings. If you want the user to be able to switch context for the renderings inside this placeholder, go to the VariantDetails section and select the Switch component context to currently rendered item check box.

      Enable switching context for renderings within the placeholder.
    • Reference - displays field from referenced item. If you want to display a field from a referenced item, you can define this field in the PassThroughField. You can use this variant field for the following fields: LinkField (GeneralLink, DropLink), FileField (File), ImageField (Image), and ReferenceField (Droptree). Reference items can contain have another reference item as its child item. This can be convenient when you want to create a tree of reference items and display fields from items which are referenced in referenced items.

    • Responsive Image - enables you to define the default size as well as the allowed sizes and width of images. Making your images responsive means that your browser serves a different sized version of that image based on the size of the image on your page and the screen resolution. The values entered in the Variant Details section are combined in a srcset attribute. The values in the following screenshot will generate the following img tag:

      Variant details will be combined in a srcset attribute.
    RequestResponse
    <img src="/-/media/Project/Tenant/Site/26056130_2115225655366272_5152181870065454436_n/MyImage.JPEG?w=400&amp;hash=C54AFF8A74289E7B0A776137DFF1D4F89DDEFF93" alt="Simple description of the image" sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px" srcset="/-/media/Project/Tenant/Site/26056130_2115225655366272_5152181870065454436_n/MyImage.JPEG?w=280&amp;hash=DB3A5BEB52094FC6C547F04211070DE715F458D3 280w,/-/media/Project/Tenant/Site/26056130_2115225655366272_5152181870065454436_n/MyImage.JPEG?w=440&amp;hash=247F0C11B22A5339E5913F9C4EC52361D1D2A1F2 440w,/-/media/Project/Tenant/Site/26056130_2115225655366272_5152181870065454436_n/MyImage.JPEG?w=800&amp;hash=D10309E3D24FF417E3194419240075419EF353B8 800w">
    • Query - allows you to specify a query to run on current context item. This enables you to query child items or use SXA tokens. For example, if you want the rendering variant to display only for the child items of a certain template. You must start your query with query and then use standard Sitecore query syntax. You can combine Sitecore queries with SXA tokens such as $home and $site.

    • Section - used to create groups. Section contains fields such as Tag (to create wrapping element for the section, for example "div") and CssClass (to add a css class to the wrapping tag). You can nest Section items to create more complex variant structure.

    • Template - allows user to define a template to use to render part of the HTML.

    • Text - displays text. Used to render custom string of for example a description. You can use the following fields: Text, Tag (define additional tag to wrap text), CssClass (the CSS class that will be added to the tag), IsLink (if selected, then the custom text is additionally wrapped by hyper link to the current item).

    • Token - SXA supports tokens $id (renders ID of the item), $size (formats size of attached asset), $name (renders name if the item), and $FileTypeIcon (renders span with CSS classed equal to the file extension). The custom pipeline resolveVariantTokens can be used to extend the set of variant tokens.

    • Component - allows you to embed a component. For example, for a News heading you can create a variant that includes the Breadcrumb and tag renderings. Does not support embedding the Pagination component.

      In the Rendering item field, you can select the rendering. In the Rendering parameters field, you can select the datasource. If you leave the datasource empty, the item that is normally used to render fields is provided to the component as its datasource. Before you can configure the rendering parameters, you must specify the Rendering Item and save it.

    • Scriban - allows user to define Scriban template that is used to render part of the HTML.

    Note

    If you use the Component variant under a Scriban item, you cannot use composite or pagination components in the Component. We recommend that you do not use components with placeholders under Scriban templates either, because these components might not be rendered correctly on the page.

    Depending on the item you add, you can set the following fields:

    Field

    Variant details

    Tag

    HTML tag used to wrap rendered field content. For example: div 

    If left empty, field content remains unwrapped.

    You must make sure that the tag you choose does not lead to invalid HTML markup. If the HTML markup is invalid, Experience Editor stops working correctly and it is impossible for an editor to edit the item field on content pages. For example, an item presentation that contains nested components that both render <p> tags.

    <p>My <p>text</p> which gives trouble</p>

    Field name

    Name of the field from the item used for rendering content.

    Prefix

    Adds string value as a prefix.

    Suffix

    Adds string value as a suffix.

    Is link

    Select whether to have hyperlinks that wrap the field content:

    Unwrapped – the field is not wrapped with the link (<a href="" … /> HTML element)

    Wrapped – the field is always be wrapped with the link (<a href="" … />; HTML element)

    Wrapped If Not Empty – the field is wrapped with the link (<a href="" … /> HTML element) only when it is not empty.

    Is prefix link

    Select whether to have hyperlinks that wrap the field content:

    Unwrapped – the field is not wrapped with the link (<a href="" … /> HTML element)

    Wrapped – the field is always wrapped with the link (<a href="" … />; HTML element)

    Wrapped If Not Empty – the field is wrapped with the link (<a href="" … /> HTML element) only when it is not empty.

    Is suffix link

    Select whether to have hyperlinks that wrap the field content:

    Unwrapped – the field is not wrapped with the link (<a href="" … /> HTML element)

    Wrapped – the field is always wrapped with the link (<a href="" … />; HTML element)

    Wrapped If Not Empty – the field is wrapped with the link (<a href="" … /> HTML element) only when it is not empty.

    Is download link

    Select to have a hyperlink with a download attribute.

    Css class

    Adds CSS class to the tag. If Tag field is not specified, the CSS class will not be rendered.

    Is editable

    Select to edit rendered field.

    Date format

    Determines the date format.

    Render if empty

    Select to render empty element when the field is empty.

    Pass through field

    Defines the name of the field from the nested item.

    Text

    The text to render.

    Template

    Define the Scriban template that renders part of the component variant HTML.

    Token

    Use special tokens to format certain field values. Supported tokens are:

    $Size: displays size of a file depending on size unit.

    $FileTypeIcon: displays icon depending on file extension.

    Query

    Determines the query that will be run on the current context item. For example:

    To get all child items:

    query:./*

    To get all items of Page template from under the current item:

    query:..//*[@@templatename='Page']

    To get all items of Page template from under Home item of the current site:

    query:$site/*[@@name='Home']//*[@@templatename='Page']

    Maximum number of results

    Enter a number to limit the number of items returned.

    Property path

    In the Property path field, you can enter the path to the property that you want to display. For example, Item.Paths.Path accesses first the Item property from Model, then dig deeper and access the Paths property and then the Path string.

    The Property path field
    Item.Paths.Path example

    Data attributes

    Adds a data attribute to the HTML element generated by the rendering variant item.

    Link attributes

    Adds a link attribute to the link element generated by the rendering variant.

    Buttons

    Edits frame buttons. Go to:/sitecore/content/Applications/WebEdit/Edit Frame Buttons to select a button.

    Placeholder Key

    Defines placeholder key used for rendering placeholder.

    RenderingItem

    Selects rendering used by rendering variant renderer.

    RenderingParameter

    Specifies rendering parameters for rendering variant renderer.

    DefaultSize

    Determines the default size of a responsive image. Used to generate responsive image syntax. For example,

    RequestResponse
    img srcset="photo-author1-320w.jpg 320w,
                photo-author1-480w.jpg 480w,
                photo-author1-800w.jpg 800w"
    sizes="(max-width: 320px) 280px,
            (max-width: 480px) 440px,800px"
    src="photo-author1-800w.jpg" alt="Blog author 1"

    Sizes

    Defines media conditions for a responsive image and indicates the best image size to choose. Used to generate responsive image syntax. For example,

    RequestResponse
    img srcset="photo-author1-320w.jpg 320w,
                photo-author1-480w.jpg 480w,
                photo-author1-800w.jpg 800w"
    sizes="(max-width: 320px) 280px,
            (max-width: 480px) 440px,800px"
    src="photo-author1-800w.jpg" alt="Blog author 1"

    Width

    Determines available widths for a responsive image. Used to generate responsive image syntax. For example,

    RequestResponse
    img srcset="photo-author1-320w.jpg 320w,
                photo-author1-480w.jpg 480w,
                photo-author1-800w.jpg 800w"
    sizes="(max-width: 320px) 280px,
            (max-width: 480px) 440px,800px"
    src="photo-author1-800w.jpg" alt="Blog author 1"

Do you have some feedback for us?

If you have suggestions for improving this article,