Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Adding a background image to a portal header

Updated on May 3, 2020

Custom applications must often reflect organization-specific branding, which may involve adding images, textures, and corporate colors to the application. One of the easiest ways to incorporate corporate branding into an application is to add a background color and image to the portal header.

Skin rules and the Header background mixin

Header background mixin in a skin rule

Pega 7 Platform applications use skin rules to collect application formatting instructions, such as font and size information for menu items and labels for UI controls. Within a skin rule, mixins represent reusable style patterns that allow UI developers to apply text, border, and background formatting throughout an application. The Header background mixin allows UI developers to add a background image and color to the portal header and address corporate branding needs. By adjusting the attributes for this mixin, a UI developer can replicate corporate branding that is already in use on a company's website.

The Header background mixin does not allow you to replace the Pega 7 logo that is displayed on the header bar. To replace this logo, you must override the pyPortalHeader section in your application.

Remember that mixins are reusable style patterns. Changes to the Header background mixin can affect other elements of your UI, such as the appearance of inactive drop-down lists in the portal header. If your changes have unintended effects on other elements of the portal UI, you might need to remove the mixin from those elements and apply any styling configuration directly to the element.

Select a background color

By default, the Header background mixin provides a Type attribute to configure a background fill. You can select one of the following options to generate the background fill:

  • None: No fill is used.
  • solid: A single color is applied uniformly to the background.
  • gradient: The background fill progresses from the start color to the end color, in the specified direction. If the browser cannot render the gradient, the backup color is applied as a solid fill.

Add a background image to the header

You can apply background images to a solid fill. These images can be used to provide a textured effect to the header, or to display a background graphic. The Header background mixin supports three optional attributes that allow UI developers to apply and position a background image on the header. These options are available by expanding the Additional Styles area.

Specify the image

Use the attribute background-image to specify the image file to display. Enter the file name by using the format url(filename.ext), where filename and ext are from the binary file rule that contains the image. The image must be saved to the webwb directory.

When adding an image to the header bar, use an image with a semi-transparent background. This allows the background color to display through the image for a more natural, seamless appearance.

Position the image

Use the attribute​ background-position to specify horizontal and vertical positioning information for the image. The position can be described by using one of the following methods:

  • As a percentage of the header width and height. 0% 0% represents the upper-left corner of the container, while 100% 100% represents the bottom-right corner.
  • By using pixel positioning. Use pixel positioning when an image must appear on-screen at a specific position. Unlike percentage coordinates, pixel coordinates do not react to changes in the display area, and might cause the image to appear off-screen if one or both coordinates exceed the dimensions of the container.
  • By using positioning keywords. Use the keywords left, center, or right for horizontal positioning. Use the keywords top, center, or bottom for vertical positioning.
  • By inheriting the positioning. Use the keyword inherit to inherit positioning from a parent element.

The default value for the image position is 0% 0%. If you provide only a horizontal position value, the vertical position is assumed to be 50%, or center.

Repeat the image

Use the attribute​ background-repeat to specify whether the image repeats on the background.

  • repeat: The image repeats both horizontally and vertically within the header. This is the default option, so if you omit the background-repeat attribute, the skin rule assumes that your image should repeat both horizontally and vertically.
  • repeat-x: The image only repeats horizontally within the header.
  • repeat-y: The image only repeats vertically within the header.
  • no-repeat: The image does not repeat within the header.
  • inherit: The repeat setting is inherited from a parent element.


The following examples illustrate how UI developers can customize the header for the Case Manager portal.

First, start with a solid color applied to the header bar.


A plain blue background

A header with solid color #006E91 applied.

Now, apply an image to the header bar to add a texture effect.


A pebbled background

A pebbled pattern applied to a header with solid color #006E91.

Instead of a repeating image, apply an image with no repeat, and position the image on the right side of the header.

background-positionright center

A header with right-center positioning

A header with solid color #006E91 applied, overlaid with a non-repeating image with right-center positioning.

Apply a non-repeating image to a solid background with an offset.

background-position12% 25%

A red background with hexagonal shapes

A header with solid color #A9071E applied, overlaid with a non-repeating image positioned at 12% 25%.


To add an image to the header background by using a skin rule:

  1. Create a binary file rule for the image and upload the background image to the webwb directory.
  2. Open the skin rule that you want to customize, such as pyEndUser71.
  3. If the skin rule is a standard skin, save the skin to an application ruleset before customizing the header.
  4. Select the Header background mixin.
  5. From the Type drop-down list, select solid to set the background color.
  6. Expand the Additional Styles area.
  7. Specify and position your background image on the header bar by adding and configuring the background-image, background-position, and background-repeat attributes.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us