Geometrical patterns of points representing genes and lines indicating degree of similarity.
Hero image with Headline style "Text in white box"

Page building: Component demo

This page is a work in progress documenting available components content authors can use when building pages with Layout Builder. Where possible, guidance is included to support usage of these components.


The CMS provides two main types of components for displaying images: Image and Hero. This section describes best practices for images, and also has special recommendations for Hero images used on landing pages. 

The Image component is versatile and allows for images to display in different types of sections, at different sizes, and aligned in different ways. The vast majority of images in our CMS use the image component.

IceCube rendering

Credit: IceCube Collaboration

When to use an Image component

  • When it's important to display your visual content entirely without cropping. 
    • Certain types of visual content are important to display in full without cropping.
    • Example: display a chart in full. A chart is a carefully constructed image used in a data analysis; display it fully to prevent confusion. 
  • When you want to experiment with different positions of the image, sizes, or alignments. 
    • Once an image is placed on a page, the CMS provides tools for quickly moving images around.
    • As you move images around on a page, the image is resized based on the dimensions of the section containing the image. 
  • While using the Text editor WYSIWYG (What You See Is What You Get) features
    • The image component is also accessed in the WYSIWYG toolbar.

When to use a Hero image component

  • When a high-impact landing page is desired, and the authors and editors follow the best practices detailed below. 

  • Keep images under 1MB in file size.
    This size limit balances the need for faster load times with the equally important requirements of image quality and size. If needed, compress images prior to upload using a tool such as Compress JPEG. An exception to the 1MB file size is if you are uploading a hi-res image for users to download.

  • Use JPEG files over PNG’s.
    JPEG (.jpeg) images commonly have a smaller file size than PNG’s (.png), which will optimize the page load time. Additionally, uploading a JPEG ensures the image does not contain any unwanted transparency.

  • Don't use imagery that contains text.
    This is a WCAG accessibility violation (WCAG 1.4.5) which states that text should be used to convey information, rather than images of text. If this is unavoidable, make sure the text is represented in the alt text field.

  • Write descriptive alt text.
    This is brief, meaningful text used by screen readers, search engines, or when the image cannot be loaded. It is also the link text used if the image is linked. 
    NOTE: If the image is decorative or redundant to text near it, then use two quote marks to indicate empty alt text: "". View this decision tree for more about when to use alt text or not.
    More information on authoring effective alt text.

Hero image usage and best practices

Hero components fill the entire width of the window and contain a large image ("Hero Image") that "help set the tone for the content of your site," according to the US Web Design System. Hero components optionally may contain the page title or headline, a small amount of text in an overlay, and a single link or a button in an overlay.

The NSF Hero component is designed for high visual impact, and is popular for landing pages. Because the high visual impact would be diminished through overuse, the hero component is limited to one per page, and is not available for all page types.

Will my image work as a hero?

The Hero component takes some practice to use well, but results can be rewarding with careful image selection.

In general, a good hero image:

  • Functions more as wallpaper than a detail image. The Hero sets mood and tone and is not intended for accurate infographics, charts, maps, diagrams, group photo, portraits, or any other visual content where detail is important.
  • Has no text. Text in an image, except for pure decoration, creates accessibility issues. The large Hero component will pixellate, crop, and/or obscure the text. Use the Hero component's Headline Text to create an accessible text layer on top of your image. 
  • Is high resolution, such that the main visual content will not pixellate at larger sizes. 
  • Does not need an NSF logo. The logo is prominent in other parts of the page.

What will my image look like at different cropped sizes? Will important content be lost?

In the NSF CMS, hero images crop and resize when displayed on different sized screens. This cropping is especially hard to control, and it looks very different at different screen sizes.

In the image below, the building appears at small window sizes, but disappears at larger sizes. Often the decision to use an image in a Hero component will be an editorial decision based on what is the important content. If the building is not highly relevant to your content, this image works well as a Hero. 

Screen capture of Hero image at small screen size
In this screen capture simulating a small screen size, the building is visible. The colorful Northern Lights are largely covered by the Headline. At larger screen sizes, the building is not visible, but more of the Northern Lights are visible.

Will Headline text or Page Title obscure important details of my image? 

Headline Text or Page Title is encouraged for Hero components. The Hero is an eye catching region at the top of the page, and it is a great place to put large text that describes the page.  Keep in mind the headline or title will display on top of your image, potentially obscuring parts of the image below.

As with cropping of images, consider whether important details are lost. If you determine important details are not lost, go for a Hero! 

In summary: The cropping of the hero image and the priority given to a headline and associated text create important considerations for choosing an image for a hero feature. Depending on the specific visual elements in your image, consider carefully whether the meaning of the image changes if a certain visual element is cropped or obscured. 

To use a hero image effectively without losing important visual content, consider the following special criteria (in addition to the considerations for images above).   

A Hero image is principally a wide format, so wide aspect ratio is better. Aim for at least 1.7 times wider than the height (expressed as 1.7:1). 




Aspect ratio


Hero, aka Full-Width Image



16:9, also measured as 1.78:1 

This is the preferred full size of a Hero image; it displays at high quality on large monitors.
Hero, aka Full-Width Image 1366px 768px 16:9, also measured as 1.78:1  This size works well also but will be less detailed than 1920px. Note the aspect ratio is the same as 1920px X 1080px.

Pro tip: the 1366px size is very useful when you have a larger image that you want to change the location of a focal point. By making a larger image smaller you can crop out extraneous visual elements and to bring attention to particular visual elements that remain. 

    Images in the Hero component change greatly at different window sizes

    One of the more noticeable effects of the Hero component is that images adjust in several ways to fit different size displays. You can see this in action by opening a page in with a Hero component and adjusting the window size.

    This can make Hero images somewhat difficult to use - it can even crop out or obscure important visual content.

    Above in this page, we reviewed what makes a good Hero image. If you've made it this far, you probably want to see what happens to an image at different sizes. 

    Hero image example at 1920px width, a common desktop window size

    User interface of the top of a web page with colorful microscopic image
    Credit: National Science Foundation screen capture, adapted from M.F. Crommie, UC Berkeley Physics Department and Materials Sciences Division, LBNL


    In the large example, the window is 1920px wide, a common desktop window size. The superlattice image is ideally placed, with the focal point slightly right-aligned to avoid being obscured by the white text box, which is slightly left-aligned. 

    Hero image example at 456px, a common mobile window size 

    User interface of the top of a web page with colorful microscopic image, small version
    Photo Credit: National Science Foundation screen capture, adapted from M.F. Crommie, UC Berkeley Physics Department and Materials Sciences Division, LBNL

    In the smaller example, the same hero image is shown at a common mobile window size. There is certainly less detail than in the larger desktop example, but the bright colors and the lattice pattern are still visible. 

    Although both examples use the "Text in white box" style. at this size the text box obscures much of the image.  The example also uses long words in the headline, which make the text box larger. The other style, "Text over image" may be less obstructive, as may using shorter words in the headline, if that is an option. 

    Responsive Design causes the Hero images to resize (and all text and images, too)

    Responsive refers to responding on-the-fly to make adjustments to fit the user's device. 

    Responsive Design applies to many aspects of a web page, such as images, text, buttons, and menus. Most are not noticeable as much as the Hero component.

    For example a change in text size happens more quickly because the rendering speed of text is much faster than images.

    US Web Design System requires Responsive Design, is based on the US Web Design System, which currently requires Responsive Design. 

    Do: Select a relevant image that conveys a consistent meaning, even when cropped

    You've selected a great looking image relevant to your page content.  The Hero component will crop your image unpredictably at different sizes. Consider whether your image has consistent meaning when parts of the image are cropped out, and the center of the image is zoomed in or zoomed out.

    If you have any concern your image will lose meaning if the whole image is not displayed, consider using a different image component that will display the whole image. 

    Pro tip: NSF’s Virtual Backgrounds provide excellent examples of stunning science images that work well as widescreen backgrounds.


    Group photo people, with some people cropped out due to putting image in Hero component
    People's faces are an important detail when their work is directly related to your content.  This group photo is added to a Hero component, which obscures people's faces at this size.At other sizes, faces or entire persons will be cropped out. Probably best not to use this image in a Hero feature.
    Credit: National Science Foundation screen capture, adapted from Center for Astrophysics | Harvard & Smithsonian
    Team members of the Event Horizon Telescope hold up newspapers displaying the history-making black hole image on the front page.
    The same group photo used in a standard Image component. This layout makes all group members visible, and does not crop or otherwise obscure people. Photo Credit: Center for Astrophysics | Harvard & Smithsonian

    Don’t: Use images in a Hero that contain an important detail in the context of your web content

    If there is an element in your image that visually communicates an important detail in the context of your content, it's best not to risk the cropping and overlays that occur with the Hero component. The same image will almost certainly look great in a standard image component, and your audience will be able to view all of the image as intended. 

    The first example above obscures peoples' faces in the group photo when displayed at 1920px width, a common desktop window size. At other sizes (not shown), people can get cropped out of the photo or appear headless. All these issues can be avoided by using a standard image component. 

    The second example shows the same image in a standard Image component. This technique removes the Headline that obscures faces and allows the full image to display at different sizes - without cropping. Other benefits of the standard image are simplicity, ease of use, multiple layouts available, and it's available on more types of pages. 

    Pro tip:  NSF’s Science Matters has many examples of compelling visual communications in different shapes and sizes, and does not use the Hero component.

    Do: Use high-definition visuals that are not pixelated or low quality

    The hero image is the largest image found on your page and creates a strong impression on site visitors. Images that are too small or do not follow the above sizing recommendations may display illegibly.

    User interface of the top of a web page with colorful microscopic image
    This image has a focal point slightly right-aligned, and it works well with the Headline. If the focal point were left-aligned, the Headline would obscure more of the image. Credit: National Science Foundation screen capture, adapted from M.F. Crommie, UC Berkeley Physics Department and Materials Sciences Division, LBNL

    Don’t: Use images with left-aligned focal points.

    Focal points in an image usually contain the most important visual content. A left-aligned focal point will be overlaid by a Headline or Page Title. A focal point more than 1/4 left or right-aligned will be cropped at different screen sizes. 

    Pro tip: Adjust images to be uploaded as Hero images with a focal point in the center, or less than 1/4 right-aligned.  


    Videos can be selected from Brightcove, Youtube or Vimeo. Brightcove titles and captions will display automatically above and below the video. If you'd like to add titles or captions for Youtube or Vimeo videos beyond what's in the videos themselves, they'll need to be added manually with Text components.

    Here is a Brightcove video, and a Youtube video example is shown below that.

    Vera C. Rubin Observatory: Opening a Window of Discovery on the Dynamic Universe

    Image links work best with iconography rather than photos. Below, three icons are shown and "Display a round image thumbnail" was selected for "Image display type".

    If you'd like to include more context with links, use the CTA ("Call to action") Component instead.

    Image sizing (width x height)

    • Round thumbnails: 100px x 100px
    • Round icon: 80px x 80px
    • Rectangular (no selection for "Image display type"): 220px x 142px

    About background colors

    • If you'd like to add a background color like this to a section: When you're adding a section, choose a background color in the "Section background color" dropdown and select the "Display section at full browser width" checkbox. Full-width background colors look best on pages without sidebar menus.

    The Featured File component provides download links for files, along with metadata like thumbnail, short description and date.

    When to use Featured File

    • If the files you are sharing deserve emphasis or attention
    • When you'd like the thumbnail, short description and/or publish date to display with the file download link

    When to use something different

    • If a large number of files are being shared (try the Related links w/ Files or Text components)

    Thumbnails, short descriptions and publish date are all optional. It is possible to display or not display publish dates (via a checkbox on the Drupal form).

    Optional headline to introduce Featured Files


    An accordion is a list of headers that hide or reveal additional content when selected.

    When to use the accordion component 

    • If you have only a small space to display a lot of content.
    • If the content within the accordion item might not be necessary to all users.
    • If you can summarize the content within in approximately one line of text for the heading.

    When to consider something else

    • If users need to see most or all of the information on a page. Use well-formatted text instead.
    • If there is not enough content to warrant condensing. Accordions increase cognitive load and interaction cost, as users have to make decisions about what headers to click on.

    View USWDS Accordion guidelines

    The Accordion item "Body" field is a WYSIWYG, so it can accommodate text, images and other media.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

    Allosaurs attack a sauropod along a beach in what is now Utah, 150 million years ago. Photo Credit: Todd Marshall

    Text ("Section Heading"/h2)

    This is "Lead text", which is available as part of the Text component. Its use should be limited to the top of pages, to bring more emphasis to introductory content.

    This is normal body copy, which is part of the "Main text" field in the Text component. Because this field is a WYSIWYG ("what you see is what you get"), you can also embed images, video and files in it.

    A view of WYSIWYG controls that calls out which icons perform certain tasks.
    Where to find particular items in the WYSIWYG menu. Photo Credit: NSF


    Tabs provide a way to progressively disclose information on a page. Like Accordions, they contain WYSIWYGs, so content within can be customized.

    When to use Tabs

    • If the content within the tab might not be necessary to all users. 
    • If content within a tab is complementary or about a similar topic.
    • If you can present a succinct title for the tab; aim for 3 words or less.

    When to consider using something else

    • If you need more than three or four sections of content (an Accordion might work)
    • If the information is critical to the page and shouldn't be hidden on load

    Example tab content.

    CTA (Call to Action)

    A CTA (“call-to-action”) is an image and/or line of text and link that prompts your website visitors to take some specific action. Use it:

    • If you have a set of key pages you want to highlight on a landing page.
    • If you want to call attention to a specific action, such as “Register now” or “Learn more about this event.”

    Consider using something else (like the "Related links" component) if you have a long list of links.

    Images are optional in CTAs. If you choose to include an image, there are two image styles to choose from:

    • Full: crops the image to 220 x 142 pixels (horizontal format) 
    • Thumbnail: crops the image to 80 x 80 pixels (square format)

    Full is best used for photographs while the Thumbnail format is better for icons, as shown below.

    This is a CTA (Call to Action) in a two-column section

    The images here use the "Full" Image Style. This is a short description for a CTA. This can be used to add context for what you are linking to. The link below can display as a text link or a button.

    This is another CTA headline in a two-column section

    CTAs will look better side-by-side when they are matching in height. Additionally, you'll want to use the same kind of link or button style when using them next to each other. 

    This is a CTA in a three-column section

    Images are optional for CTAs.

    Lorem ipsum dolor sit amet

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

    Lorem ipsum dolor

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore.

    This is a CTA on a full-width background

    The icon is a PNG using the "Thumbnail" Image Style.

    This is another CTA headline

    This is the short description.


    When to use the quote component: 

    • To draw attention to a particular passage in a news story.
    • To share a testimonial related to other content on the page.

    Because the same Quote can be added to multiple pages, they are uploaded and managed outside the Layout Builder. To add a Quote, go to "Add content > Quote", add the Quote, and then return to the Layout Builder page and select the "Quote" component, and search for the added quote.

    Important note: When adding a quote to a page, check the Published checkbox before Update Quote. If you forget to do this, your quote will be hidden from users not logged into the CMS.

    Quote images are 220px x 220px.

    A bearded man works in a greenhouse

    [Merit Review] is a painstaking endeavor but the result is clear: basic research selected for funding by the NSF has led directly to cell-phone technology, MRI scanners, and the Google search engine, to name just a few outcomes that today are valued in the billions of dollars.

    John P. Holdren
    former Director of the White House Office of Science and Technology Policy

    The Related Links (with Files) component includes a heading and a list on a light gray background. The list can include links, files, or a combination of both. External links are automatically styled to include an icon that lets users know they will be leaving the NSF website when they click on the link. There is no limit on the number of links and files you can add to your list.

    When to use the Related Links (with Files) component 

    • If you want to call attention to two or more links or resources, and can summarize each item in approximately one line of text. 

    When to consider something else

    • If you have a small number of important actions you want to call attention to, especially if you are using an image or button to call attention to an action. Consider instead using the CTA component, Featured File component, or even dedicate a whole section of your page to calling attention to the important action. 

    There are two available component styles, as shown below. 

    Important note: When using this component, be sure to use "Related Links with Files" component (even if you are only adding links, and no files), because the legacy "Related Links" component will soon be retired.


    The divider component is a blue horizontal line. Use it when you want to break up two sections on a page.

    Recent Science Matters Posts

    This component dynamically displays the most recent Science Matters blog posts. You can select how many posts to display, and filter to show a particular campaign.


    NSF 101: GRANTED

    November 9, 2023
    The Growing Research Access for Nationally Transformative Equity and Diversity (GRANTED) initiative differs from other U.S. National Science Foundation programs. Instead of funding scientific research...